ce-proof

Proof——协作式 Markdown 编辑器

Proof 是一款供人类和 Agent 使用的协作文档编辑器。可通过托管的 Web API https://www.proofeditor.ai，从 Bash 使用 HTTP 访问。

结果： 用户获得一个可正常使用的 Proof 链接（含令牌），或者文档中包含用户要求的读取内容、评论、建议或编辑。

完成： 操作已在相应层级得到确认，用户也已收到结果和简短摘要。创建操作通过其返回的 tokenUrl 确认。修改操作通过 ok: true 确认；对于 202 或 partial: true 响应，请重新读取 v3/document 进行确认。拉取操作通过其写入的本地文件确认，读取操作则通过其返回的内容确认。

首次通过 HTTP 或 MCP 读取或修改 Proof 前，请先阅读 references/api.md。 其中定义了各个端点：share/markdown、v3 文档和编辑端点、presence、标题，以及 DELETE /api/documents/<slug>。其中还包含操作表、错误和重试类别，以及适用于 Claude Code 的 curl 权限提示。

在审阅共享文档、创建并分享文档，以及将文档拉取到本地文件之前，请阅读 references/workflows.md。 其中提供了这些流程的精确操作步骤。

如果运行环境中已提供类型化的 proof_* MCP 工具（proof_share_markdown、proof_v3_document、proof_v3_edit、proof_presence、proof_document_title、proof_document_delete、proof_report_bug），请优先使用。否则请使用 HTTP 操作步骤。在 MCP 模式下，服务端会注入 by、X-Agent-Id 和 presence 身份。对于已登录用户不拥有的文档，编辑和 presence 操作请将 Proof URL 中的 ?token= 值作为 shareToken 传入。

在 MCP 模式下，删除权限规则不变。未认领的文档仍需要其 ownerSecret，已认领的文档则需要其所有者的会话。作为 shareToken 传入的编辑者 accessToken 不能用于删除。

身份

每次写入都会同时带上这两个字段，且二者保持不变。机器 ID 为 ai:compound-engineering，每次操作都作为 by 发送，并作为 X-Agent-Id 请求头发送。显示名称为 Compound Engineering，在 POST /presence 中作为 name 发送；每个文档会话只设置一次，以便 Proof 将其绑定到该 Agent ID。调用方可以传入不同的 identity 键值对，让不同的子 Agent 成为文档所有者。切勿擅自改用类似 ai:compound 的变体。

凭据与边界

• accessToken 是用于日常读取、编辑、在线状态和事件操作的 Bearer 凭据。ownerSecret 仅携带所有者权限——用于删除和其他所有者级操作，绝不能作为日常 Bearer 凭据。创建时同时获取两者，并将 ownerSecret 与 accessToken 分开保存，以 shell 变量或同等方式保存到会话中；文档尚未被认领时，删除操作需要它。两者都不得出现在由仓库跟踪的文件、提交或持久化日志中，且 ownerSecret 绝不能出现在面向用户的文案中。
• 将带令牌的链接（tokenUrl）交给用户，绝不要提供裸的 /d/<slug>——该链接中的令牌也能让已登录用户认领无人所有的文档。
• 公开创建的文档在已登录的 Every 用户通过浏览器认领之前都无人所有。认领会永久撤销 ownerSecret，而 accessToken 仍然有效，因此之后删除文档需要所有者的 Every 会话——请联系所有者，或使用其会话令牌。以下两种响应表示密钥已被撤销：403，且 code: "DOCUMENT_DELETE_FORBIDDEN"、reason: "CREDENTIAL_NOT_OWNER"；或者提供创建时的 ownerSecret 后收到 401。停止使用该密钥，不要重试。reason: "DOCUMENT_HAS_NO_OWNER" 则表示相反情况：文档仍未被认领，因此只有原始 ownerSecret 能删除它，Every 会话无法删除。
• 除非用户明确同意，否则绝不要在 Proof 文档中放入密钥、凭据、API 密钥、私有令牌或敏感个人数据；也绝不要在不告知用户的情况下，将由仓库跟踪的项目文档替换为 Proof 链接。
• 清空 Markdown 内容不会清除评论标记。任何持有共享凭据的人仍可读取引文和评论，因此清空内容并不等于完成隐私清理。删除文档才可以——文档尚未被认领时使用 ownerSecret，被认领后则以所有者身份删除。
• 发布交接后不要自动删除文档。评审文档必须保留。只有在用户要求删除，或完成明确标记为临时的草稿文档时，才删除文档。

发布模式

主要用途是单向发布。完整读取现有的本地 Markdown 文件，将其内容作为新文档正文发布，然后将可分享的 URL 交给用户。本地文件仍是规范版本——发布不会将任何内容同步回磁盘。

有两种入口使用相同的操作流程。一种是用户直接提出请求并指出本地 Markdown 文件（“把这个分享给 proof”“给我这个文档的 proof 链接”）；只有在文件不明确时才询问是哪一个，并且预期没有上游调用方。另一种是来自 ce-brainstorm、ce-ideate 或 ce-plan 的交接，其中会传入文件路径和标题。

只发布 Markdown。如果源文件是 HTML 格式的统一计划，则返回本地浏览器/打开路径，而不要上传。如果发布统一计划，且已知其就绪状态，应在标题中注明，例如 Plan: <title> (requirements-only) 或 Plan: <title> (implementation-ready)。

发布源文件的原始字节，绝不要使用手写内容或占位内容。references/workflows.md 提供了 jq --rawfile 用法，可正确转义换行符、引号和反引号。发布交接后，向用户展示 URL 并交还控制权。

编辑

GET /api/agent/<slug>/v3/document 和 POST /api/agent/<slug>/v3/edit 是 Agent 读取和写入内容的唯二端点。评论、回复、解决状态、建议和内容更改都是 v3 编辑请求正文中的 operations，因此，如果某个路径未在 references/api.md 中出现，那就是你臆造的。

编辑前，先将 v3/document 作为事实来源读取。然后选择能够表达更改的最精简操作：对于正文，使用限定范围的 replace、insert 或 delete；如果更改应显示为修订痕迹，则使用 suggest；仅当用户要求替换整个文档，或无法通过更精简的方式表达更改时，才使用 set_document。目标是 markdown 中可见的文本，而不是原始 Markdown 语法或块引用。

该读取结果中的 comments[] 和 suggestions[] 是审核状态。按 id 回复、解决、取消解决、接受或拒绝。v3 没有删除评论的操作。标记为 orphaned: true 的评论仍可读取和回复，但其旧引用已不再是有效锚点。

遇到以下表示应停止并检查的错误时，不要立即重试：

• TARGET_AMBIGUOUS — 锚点匹配到多个位置，且没有任何更改。使用 error.candidates 中的 occurrence / before / after 消除歧义；切勿假设系统会静默采用第一个匹配项，也不要盲目重试评论。
• retryable: false — 修正请求。若为 retryable: true 且包含 error.current，则根据 current 重新解析目标，然后重试一次。
• 202 / PENDING，或 ok: false 且 partial: true — 写入可能已提交。继续执行后续操作或报告成功前，重新读取 v3/document，并且只重试失败的操作（重复使用 Idempotency-Key 可安全重放）。
• 重新读取并安全重试一次后仍失败 — 按照 references/api.md 报告此错误，不要反复重试。

将文档拉取到本地文件会覆盖该文件。如果拉取文档只是其他操作的副作用，而不是用户要求的操作，请先确认路径。