AI Skills
ce-proof

ce-proof

热门

在 Proof 中发布、读取、评论或编辑 Markdown。适用于生成 Proof 分享链接、分享规格文档/方案/草稿，或在规划流程中发布并交接文档；请勿用于校对（proofread）、数学证明（math）、证据（evidence）或概念验证（proof-of-concept）等含义。

2.4万Star
1943Fork
更新于 2026/8/3
获取 Skill源代码

相关 Skills

notion38万network-config-validation24万agent-security-manager7.2万
SKILL.md
只读
名称
ce-proof
描述

在 Proof 中发布、读取、评论或编辑 Markdown。适用于生成 Proof 分享链接、分享规格文档/方案/草稿，或在规划流程中发布并交接文档；请勿用于校对（proofread）、数学证明（math）、证据（evidence）或概念验证（proof-of-concept）等含义。

Proof - 协作式 Markdown 编辑器

Proof 是一款面向人类与 Agent 的协作式文档编辑器。本 Skill 使用托管在 https://www.proofeditor.ai 的 Web API（通过 HTTP/Bash）。如果系统已集成强类型的 proof_* MCP 工具，请优先使用它们；否则请使用下文提供的 HTTP 操作方案。

身份标识与归属

每次对 Proof 文档的写入都必须指明操作者身份。通过以下两个字段传递 Agent 的身份信息：

  • 机器标识符 / Machine ID（每次操作中的 by 字段，以及 X-Agent-Id 请求头）： ai:compound-engineering —— 稳定、小写带连字符、可被机器解析。会出现在标记（marks）、事件（events）和 API 响应中。
  • 显示名称 / Display name（POST /presence 中的 name 字段）： Compound Engineering —— 可读文本，展示在 Proof 的在线状态气泡和评论作者标识中。

在每个文档会话开始时，附带 X-Agent-Id 请求头向 presence 接口发送一次请求即可完成显示名称设置；Proof 会在该会话期间将此名称与 Agent ID 进行绑定。这些值是调用本 Skill 时的默认配置；如果需要由不同的子 Agent（sub-agent）拥有文档，调用方也可以传入自定义的 identity 键值对。请勿使用 ai:compound 等随意变体 —— 除非调用方明确覆盖，否则身份标识应保持统一。

发布模式

本 Skill 的核心用法是单向发布：读取已有的本地 Markdown 文件（如头脑风暴记录、统一规划方案、学习总结、草稿等）完整内容，将其作为新文档的正文发布（有关源文件处理流程，详见“工作流：创建并分享新文档” —— 绝不要发布占位符内容），并将可分享的 URL 返回给用户。本地文件始终是权威源 —— 发布操作不会将任何内容同步回本地磁盘。用户可以通过链接阅读、评论并分享给他人；在拿到 URL 后，Agent 也可以通过下文提到的编辑 API 参与协作。该模式有两个入口点，底层机制完全相同（参见“工作流：创建并分享新文档”）：

  • 用户直接请求 —— 用户通过简单的口令指定本地 Markdown 文件并要求通过 Proof 分享，例如：“把这个分享到 proof”、“把这个发布到 proof”、“在 proof 编辑器里打开这个方便我审查”、“给我生成一个这个文档的 proof 链接”。对应的文件就是用户刚刚创建、编辑或引用的 Markdown 文件；如果有歧义，需先询问确认。这是一个一等入口点 —— 无需依赖上游 Skill 调用。
  • 上游 Skill 交接 —— ce-brainstorm、ce-ideate 或 ce-plan 完成草稿后，将其交接并发布以供人工审查，此时会显式传递文件路径和标题。

注意：仅发布 Markdown。如果源文件是 HTML 格式的统一方案（unified plan），请勿上传到 Proof，而是返回本地浏览器打开路径。发布统一方案时，若能确认就绪状态，请在标题中注明，例如 Plan: <title> (requirements-only) 或 Plan: <title> (implementation-ready)。

请勿静默地将仓库追踪的项目文档替换为 Proof 链接。除非用户明确批准，否则严禁将密钥、凭据、API Key、私有 Token 或敏感个人数据写入 Proof。

凭据管理

文档创建成功后会返回两个职责不同的凭据：

  • accessToken —— 日常调用的 Bearer 令牌，用于读取、编辑、发送在线状态（presence）和监听事件。所有非所有者级别的 Agent API 调用均使用此 Token。
  • ownerSecret —— 仅用于所有者权限操作（如删除文档及其他所有者级操作）。切勿将其用作日常调用的 Bearer 令牌。

请在会话级别分别存储这两个凭据（如环境变量或非仓库内存中）。严禁将 ownerSecret 或 accessToken 写入受 Git 追踪的文件、提交记录或持久化的项目日志中。严禁在面向用户的 UI 文案中暴露 ownerSecret。

向人类提供链接时，务必分发带 Token 的完整链接（tokenUrl），而不要只给一个不带参数的裸链接 /d/<slug> —— 编辑器 Token 同时兼具对无主文档的认领（claim）能力。

公开创建的文档在未登录的 Every 用户于浏览器中认领之前属于无主状态（操作路径：账户菜单 → Claim ownership）。认领文档后，ownerSecret 会被永久撤销，但 accessToken 仍可正常使用。认领之后，删除等所有者操作将归属于该用户的 Every 账号 —— 此时需联系所有者处理，或使用其 Every 会话 Token。切勿使用已撤销的 ownerSecret 重试删除。

如果收到包含 code: "DOCUMENT_DELETE_FORBIDDEN" 和 reason: "CREDENTIAL_NOT_OWNER" 的 403 错误，或者在出示创建时的 ownerSecret 时收到 401，均表明该秘钥已被撤销（通常是在认领后）。此时请停止使用该 ownerSecret，改为请求所有者进行删除或提供 Every 所有者会话。

Web API 接口说明

文档相关接口鉴权方式（首选方式排在前面）：

  • Authorization: Bearer <accessToken>
  • x-share-token: <accessToken>
  • 请求 URL 参数：?token=<accessToken>

标准的 Agent 读写接口（仅限 v3 版本 —— 请勿自行构造其他修改路径）：

  • 读取：GET /api/agent/<slug>/v3/document
  • 写入：POST /api/agent/<slug>/v3/edit

创建共享文档

公开创建接口无需身份认证，请求成功后返回带有 Token 的可分享 URL。

curl -sS -X POST https://www.proofeditor.ai/share/markdown \
  -H "Content-Type: application/json" \
  -d '{"title":"My Doc","markdown":"# Hello\n\nContent here."}'

需要保留的响应字段：

{
  "slug": "abc123",
  "tokenUrl": "https://www.proofeditor.ai/d/abc123?token=xxx",
  "accessToken": "xxx",
  "ownerSecret": "yyy",
  "shareUrl": "https://www.proofeditor.ai/d/abc123",
  "_links": {
    "read": "https://www.proofeditor.ai/api/agent/abc123/v3/document",
    "edit": { "method": "POST", "href": "/api/agent/abc123/v3/edit" },
    "delete": { "method": "DELETE", "href": "/api/documents/abc123" }
  }
}

将 tokenUrl 用作可分享链接。请立即提取并保存 slug、accessToken 和 ownerSecret —— 在文档尚未被认领之前，清理/删除文档必须使用 ownerSecret。

读取共享文档

如果你手中已有共享的 Proof URL，可以通过内容协商（Content Negotiation）或 v3 接口获取：

curl -sS -H "Accept: application/json" "https://www.proofeditor.ai/d/{slug}?token=<token>"
curl -sS -H "Accept: text/markdown" "https://www.proofeditor.ai/d/{slug}?token=<token>"

curl -sS "https://www.proofeditor.ai/api/agent/{slug}/v3/document" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering"
# -> { ok, revision, title, markdown, comments[], suggestions[], mutationReady? }

状态为 ACTIVE 的文档可以通过 v3/document 无 Token 读取。但修改、在线状态（presence）和事件仍然需要带 Token 的凭据。不带 Token 请求 GET /d/<slug> 返回的 JSON 会显示 role: null 且不包含修改链接 —— 这是对当前权限的真实反映，并非浏览器锁。

v3 读取结果中的 comments[] 和 suggestions[] 是审查状态的唯一来源。使用评论的 id 进行 reply（回复）、resolve（解决）/ unresolve（取消解决）；使用建议的 id 进行 accept（接受）/ reject（拒绝）。v3 接口支持解决和取消解决评论，但不支持删除评论。

当 mutationReady 为 false 时，revision 可能会显示为 null —— 此时请省略 baseRevision，并在短时间内重新读取。

编辑共享文档

向 POST /api/agent/{slug}/v3/edit 发送 { by, baseRevision?, operations: [...] }。操作的目标必须是 markdown 中的可见文本（而非原始 Markdown 语法或块引用 block refs）。此处不需要基础 Token。baseRevision（上次读取得到的整数）是可选的冲突保护机制 —— 若省略则直接应用于最新版本（head）。Idempotency-Key 为可选头；对于重要写入和重试操作，建议带上幂等 Key。

curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/v3/edit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "by":"ai:compound-engineering",
    "operations":[
      {"op":"replace","find":"old visible text","with":"new text"},
      {"op":"comment","on":"text to anchor on","body":"Is this still accurate?"}
    ]
  }'

内容相关操作：

op body
replace find, with（可选 occurrence / before / after）
insert after 或 before + markdown（锚点：引用文本, heading:标题, section:章节, "start", 或 "end"）
delete find
set_document markdown（将全篇替换计算为最小 diff；与在线协作人员并发时亦安全）

审查相关操作：

op body
comment on, body（可选 occurrence）
reply comment (id), body, 可选 resolve: true
resolve / unresolve comment (id)
suggest kind: "insert"|"delete"|"replace", find, with?（insert/replace 时需要 with）
accept / reject suggestion (id)

编辑策略

优先选用影响范围最小的操作：

  1. 精确的文本或特定区域改动 → 使用 replace / insert / delete
  2. 需要展示显式的修订痕迹（Track Changes） → 使用 suggest（后续按需进行 accept/reject）
  3. 全文替换 → 仅在用户明确要求全文覆盖，或者改动无法细粒度表达时使用 set_document

若 find 或锚点匹配到多处文本，服务器将拒绝请求并返回 TARGET_AMBIGUOUS 以及 error.candidates —— 此时不会对文档做任何修改。可以通过 occurrence（"first"、"last" 或从 0 开始的索引）或者 before/after 消除歧义。切勿假设系统会自动静默匹配第一处。

单次请求中的内容操作（Content ops）会原子化生效，随后依次应用审查操作（Review ops）。若内容已提交但后续审查操作失败，响应将返回 ok: false 且包含 partial: true —— 此时需重新读取文档，并仅重试失败的操作（使用相同的 Idempotency-Key 可安全重放）。

错误响应格式 为 { ok:false, error:{ code, message, retryable, opIndex?, target?, candidates?, current? } }。错误码包括：AUTH、NOT_FOUND、INVALID_REQUEST、TARGET_NOT_FOUND、TARGET_AMBIGUOUS、CONFLICT、TOO_LARGE、BUSY、PENDING、INTERNAL。

  • retryable: false —— 需修复请求内容；请勿盲目重试
  • retryable: true 且带 error.current —— 根据 current 重新定位目标文本后重试一次
  • TARGET_AMBIGUOUS —— 根据 candidates 补充 occurrence / before / after
  • BUSY —— 短暂退避后重试
  • 成功的 200 响应且 ok:true —— 检查返回的 revision / 文档内容；若返回的正文已完整，无需额外读取即可链式执行下一步
  • 202 / PENDING —— 写入可能已提交；在继续下一阶段或报告成功之前，请先重新读取 v3/document

每次编辑成功后：请确认 ok:true，确认目标文本/评论/建议无误，随后附上简明摘要并输出 Proof 链接。

在线状态（Presence）

curl -sS -X POST "https://www.proofeditor.ai/api/agent/{slug}/presence" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "X-Agent-Id: ai:compound-engineering" \
  -d '{"name":"Compound Engineering","status":"reading","summary":"Joining the doc"}'

常用状态：reading（阅读中）、thinking（思考中）、acting（执行中）、waiting（等待中）、completed（已完成）、error（异常）。

修改标题

curl -sS -X PUT "https://www.proofeditor.ai/api/documents/{slug}/title" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title":"Updated document title"}'

删除文档

仅所有者凭据（owner credentials）具备删除权限：

curl -sS -X DELETE "https://www.proofeditor.ai/api/documents/{slug}" \
  -H "Authorization: Bearer <ownerSecret>"

仅具阅读、评论或编辑权限的 accessToken 无法删除文档。删除成功后返回 shareState: "DELETED"；后续读取将返回文档已删除的响应（多数接口返回 410）。

生命周期： 请勿在每次发布交接后自动删除文档 —— 用于审查的文档需要保留供后续查阅。请在当前会话中持久化保存 ownerSecret。仅在用户明确要求删除/清理，或者完成一次性用完即丢的临时草稿时，才执行删除操作。

标记与隐私

清空 Markdown 内容（包括使用 set_document 将其替换为空白或极简内容）并不会清除评论标记。任何持有分享凭据的人仍可通过 v3/document 读取引用和评论字段。如果没有所有者删除权限，仅擦除正文内容并不能达到彻底清理隐私的目的 —— 请务必在未被认领时使用 ownerSecret 直接删除文档，或在认领后请求所有者进行删除。