wyrd-scribe

wyrd-scribe

wyrd-scribe 是一个 Tier-A MCP 服务，用于在你明确授权的一个文件夹中创建带有来源记录的 Markdown 页面。Tier A 仅支持创建：它可以创建新页面并追加其血缘记录，但不能覆盖、重命名或删除页面，也不提供血缘查询工具。

安装和配置

使用 npm install -g wyrd-scribe 安装。 可执行文件为 wyrd-scribe。默认使用 Stdio，因此 MCP 客户端配置可以直接启动它：

{
  "command": "wyrd-scribe",
  "args": ["--grant", "/absolute/path/to/folder"]
}

也可以通过 WYRD_GRANT 指定授权文件夹。显式的 --grant 参数优先于 WYRD_GRANT。WYRD_SCRIBE_TIER 用于选择层级；如果未设置，默认值为 A。Tier B 增加了 overwrite_page；Tier C 可识别，但不可用。

HTTP 和 HTTPS

仅使用 --http <port> 或 --http <host>:<port> 才会启动 HTTP。仅指定端口时会绑定到 127.0.0.1；使用 --http 127.0.0.1:0 可让系统分配一个空闲的环回端口，并将实际端点打印到 stderr。具体的非环回地址还需要 --http-public 和有效的 TLS 材料；缺少任一项时，服务会在监听前拒绝启动。路由为 POST /mcp。

使用 wyrd-mcp token 生成新的 Scribe 令牌，该令牌独立于 Reader 令牌。必须且只能提供一种来源：WYRD_WRITE_TOKEN 或 --write-token-file <absolute-path>。令牌必须是 32 字节的单一规范、无填充 base64url 编码。令牌文件末尾可以有一个 LF 或 CRLF；在 POSIX 系统上，文件不得允许组或其他用户访问。Scribe 永远不会读取 WYRD_READ_TOKEN。

WYRD_WRITE_TOKEN=<Scribe-token> wyrd-scribe --grant /absolute/path/to/vault --http 127.0.0.1:8788

如需网络访问，请使用 wyrd-mcp cert --host <hostname-or-IP> 生成证书，并配置具体的接口地址。客户端必须信任该证书，且证书必须包含客户端使用的主机名或 IP。Reader README 介绍了证书生成和平台信任设置步骤。

WYRD_WRITE_TOKEN=<Scribe-token> wyrd-scribe --grant /absolute/path/to/vault --http 192.168.1.20:8788 --http-public --tls-cert /absolute/path/to/wyrd-cert.pem --tls-key /absolute/path/to/wyrd-key.pem

每个请求都需要 Authorization: Bearer <Scribe-token>。如果请求中包含 Origin，它必须与启动时公开的某个允许的 Origin 完全匹配。HTTP 请求正文上限为 1 MiB，包含编码后的 JSON 信封；Stdio 不受此限制。已获准的写入即使在客户端断开连接后也会完成，优雅关闭会等待页面和账本追加完成，且不设超时。每个被引用的来源都必须位于同一授权文件夹内。防火墙、VPN、容器和虚拟机的路由可能会暴露已绑定的地址；Scribe 只会在启动时检查一次地址。

write_page

Tier A 提供的 write_page 接受以下精确的输入格式：

{
  "path": "Notes/new-page.md",
  "content": "Page text\n",
  "derived_from": [
    {
      "source": "Sources/source.md",
      "spans": [
        { "offset": 0, "length": 9 },
        { "quote": "source text" },
        { "offset": 0, "length": 9, "quote": "source te" }
      ]
    }
  ]
}

path 和每个 derived_from[].source 都相对于授权文件夹。每个 span 必须恰好符合以下一种形式：字节 offset 加正数 length；非空且唯一出现的 quote；或包含全部三个字段，此时字节内容必须与引文一致。未知输入键将被拒绝。

授权文件夹必须已包含 .wyrd/ 目录。Scribe 不会创建此目录。首次符合条件的写入时，它会创建 .wyrd/scribe.json，格式如下：

{
  "schema": "wyrd.scribe/v1",
  "vault_id": "a server-minted UUID v4",
  "write_frontmatter": false
}

write_frontmatter 默认为 false。在保管库配置中将其设为 true，即可选择在创建的页面中加入 wyrd_lineage 键。

结果与恢复

成功调用会先创建页面，然后向 .wyrd/lineage.jsonl 追加一条以 LF 结尾的 JSON 记录。如果创建页面后追加账本失败，页面会保留。结果为 PAGE_WRITTEN_LEDGER_FAILED，包含已创建页面的信息和底层 cause，并可能报告保留的字节数。修复或重试前，请检查保留的页面和账本；在同一页面路径重试时仅允许创建，因此会因 EXISTS 而拒绝。

账本中的每一行都是一个 wyrd.lineage/v1 对象，包含 event: "page_written"、由服务端生成的 event_id、recorded_at、写入方 wyrd-scribe 及其版本、知识库 UUID、已创建页面的路径和 SHA-256 内容标识，以及一个 sources 数组。每个来源都包含相对于授权目录的路径和内容标识；每个片段都会记录字节偏移量和长度、存储的引文文本、字节数、完整引文的 SHA-256，以及存储文本是否经过截断。

启用 frontmatter 投影后，创建的页面会收到一个包含单行 JSON 的 wyrd_lineage 键。该投影包含架构、事件、事件 ID、时间戳、写入方、知识库和来源。它会刻意省略页面标识和页面内容哈希；event_id 用于将其关联到完整的账本记录。

安全边界与限制

所有对授权文件夹的读取和写入都通过 wyrd-fence 进行。路径包含保证、硬链接限制、残余文件系统竞态及恢复影响均在 Fence 的权威安全边界与限制章节中定义。Scribe 还会拒绝直接指定 Arc/ 目标。Tier A 只能创建页面；Tier B 只有在页面的 SHA-256 与预期值一致时才能替换页面。这些控制构成的是有范围的文件系统边界，而非操作系统沙箱。

隐私与数据流

服务默认使用 stdio，只有在指定 --http 时才会打开网络监听器。它会在授权文件夹内读取知识库配置和引用的源字节。Tier A 会在该目录中写入新页面、必要时生成的配置以及溯源账本；Tier B 还可以替换页面。已连接的 MCP 客户端会收到工具元数据以及结构化结果或拒绝信息，其中包含溯源和恢复信息。初始化说明也会披露授权文件夹的规范绝对路径。Scribe 不会返回未引用的源文件内容。

从源代码构建和测试

在工作区根目录执行：

npm install
npm --workspace wyrd-fence run build
npm --workspace wyrd-mcp run build
npm --workspace wyrd-scribe test

该软件包的 test 生命周期会先构建 Reader 前置依赖，然后运行 Scribe 测试套件。

发行说明

0.2.1 — 2026-10-19

将精确的 wyrd-fence 依赖项更新为 0.4.0。Scribe 工具行为没有变化。

许可证

Apache-2.0。请参阅 LICENSE。