ce-proof

通过 Every 的协作 Markdown 编辑器 Proof 创建、共享、查看、评论和运行人机交互审阅循环。

ce-proof 是 协作文档 技能。 Proof 是一个实时 Markdown 编辑器，人类和代理都在同一个文档上工作——用户在浏览器中用评论和建议进行注释；代理获取这些线程，应用商定的编辑，并就地回复。该技能公开了 Proof 的 Web API（无需安装；通过 HTTP 创建、读取、编辑共享文档）和本地桥（驱动位于 localhost:9847 的 macOS Proof 应用程序）。大多数连锁技能都使用它来进行 HITL 审查交接。

最常见的用途是 HITL 审阅模式：上传本地 Markdown 文件（头脑风暴、计划、学习），让用户在 Proof 的 UI 中进行注释，提取每个评论线程，应用商定的编辑，然后自动将审阅的文档同步回磁盘。

TL;DR

＃＃ 问题

协作审阅 Markdown 草稿比看起来更困难：

• 聊天是错误的界面 — 将 2,000 行计划粘贴到聊天中以获取“反馈”会失去结构
• 粘贴评论是有损的 - “参见第 47 行的项目符号”不会锚定；一周后没人记得是什么子弹
• 跟踪更改需要基础设施 - 仅当存在真正的接受/拒绝可供性时，“建议此编辑”才有意义
• 身份漂移 - 当代理编辑时，谁编辑？如果没有一致的归属，渲染文档中的评论作者身份是错误的
• 状态管理很脆弱 - 并发编辑发生冲突；突变需要基础令牌；重试逻辑充满了枪声
• PII / 传输中的秘密 — 将内容上传到第三方编辑器是一个真正值得关注的问题；用户需要知道什么离开了本地

解决方案

ce-proof 通过 Proof 的结构化 API 运行协作：

• Web API 用于共享文档 - 无需安装；通过 HTTP 创建、读取、编辑；用户获取带有访问令牌的可共享 URL
• 直接共享链接读取 - 代理可以使用 Accept: application/json 或 Accept: text/markdown 获取证明 URL，无需浏览器自动化
• 本地桥 当 macOS Proof 应用程序运行时 - 通过 localhost:9847 直接驱动打开的文档
• HITL审查模式作为主链集成 - 原子上传+迭代摄取+原子最终同步到磁盘
• 一致的身份 — 每个操作上的 by: "ai:compound-engineering"； name: "Compound Engineering" 通过 /presence 绑定一次
• 高效的摄取过程 - 过滤评论读取、一批内容更改的块编辑、一批回复/解决方案的评论
• 重写最后编辑策略 - 首先精确替换和块编辑；仅在确实不可避免时才进行整个文档替换
• baseToken纪律 - 来自读取的种子，链接来自突变响应的下一个标记；在 STALE_BASE 上重新读取并重试一次；在重试可能应用的突变之前进行验证
• 幂等键用于安全精确请求重试，无需重复写入

是什么让它如此新颖

1. Web API + Local Bridge — 两者都支持，相同的身份模型

证明暴露了两个表面：

• Web API 位于 proofeditor.ai — 任何知道共享 URL 的人都可以阅读/编辑；非常适合共享评论
• Local Bridge at localhost:9847 — 直接驱动 macOS 上打开的 Proof.app；非常适合单机工作流程

该技能记录了两者。标识保持一致：ai:compound-engineering 计算机 ID、Compound Engineering 显示名称。如果不同的子代理应该拥有该文档，则在不同子代理上下文中运行 HITL 审核的调用者可以覆盖身份对。

2. HITL复习作为一种结构化模式

人机交互审查路径（从 references/hitl-review.md 加载）是该链的主要用例：

• 上传本地markdown文件到Proof；用户获取一个 URL
• 用户在 Proof 的 Web UI 中进行注释（评论、建议编辑）
• 技能摄取线程 - 读取过滤的评论状态，使用 /edit/v2 应用商定的编辑，在线程内回复，并解析批量评论突变中已处理的线程
• 在结束同步时，将最终的降价同步回本地文件原子（写入临时同级文件，然后 mv）

两个入口点，相同的机制：

• 直接用户请求 - 简单的短语，例如“共享此证明，以便我们可以迭代”或“HITL此文档”
• 上游技能交接 — ce-brainstorm / ce-ideate / ce-plan 完成草稿并通过审核

3. 变异规则——令牌链+重试前验证

每个证明突变都需要 baseToken。该技能教授正确的模式：

• 读取一次，链令牌 — 来自 /state 或 /snapshot 的种子，然后重用成功突变返回的下一个 mutationBase.token
• 在 STALE_BASE / BASE_TOKEN_REQUIRED / MISSING_BASE / INVALID_BASE_TOKEN 上 — 重新读取 /state，使用新令牌重建主体，使用新的幂等密钥重试一次
• 关于 INVALID_OPERATIONS / INVALID_REQUEST / 422 错误 — 首先修复有效负载，不要盲目重试
• 关于 COLLAB_SYNC_FAILED / 5xx / 网络超时 / 202 with collab.status: "pending" — 规范文档 可能 已编写；重新读取 /state 并检查预期的标记/编辑是否已经存在在重试之前
• Idempotency-Key 建议在每个突变上使用；合同要求时需要。重复使用相同的密钥仅用于完全相同的主体重新发送；如果主体发生变化（包括新的 baseToken），则铸造一个新密钥

重复标记事件通常来自超时后未经验证而重试 comment.add 或 suggestion.add 。如有疑问：重新阅读、比较，然后决定。

4. 两个端点形状 — /ops 和 /edit/v2

证明有两个具有承载差异的书写表面，该技能教导：

• /api/agent/{slug}/ops — 用于单个标记操作的顶级 type，或用于批量注释线程突变的顶级 operations。最适合评论、建议、回复和解决。
• /api/agent/{slug}/edit/v2 — operations 数组，其中每个条目都有 op。原子批次——每个操作要么落地，要么没有。最适合块级编辑和批量扫描（replace_block、insert_after、find_replace_in_doc 等）

向 /ops 发送 op 型操作返回 422；有线格式不可互换。该技能记录了两者。

5. 快速 HITL 通过 — 编辑批次，然后评论批次

对于正常的 HITL 反馈，评论线程是审计跟踪。有效的通道形状为：

• 阅读GET /state?kinds=comment，这样来源/作者标记就不会污染需求回复列表
• 在可能的情况下，通过一批 /edit/v2 应用商定的内容编辑
• 使用 find_replace_in_doc 进行文档范围内的字面替换，例如术语或标点符号扫描
• 使用 comment.reply 和 resolve: true 在一批 /ops 中回复并解决已处理的线程

这将 8 条评论的评论从数十个连续回复/解决/状态读取请求转变为少量的权威突变。

6.重写是最后的手段

代理不应从替换完整文档开始。首选的编辑阶梯是：

• find_replace_in_doc 用于精确的重复替换
• /edit/v2 阻止已知段落、列表项、节、插入和删除操作
• suggestion.add 当可见的轨道变化是所需的检查表面时
• rewrite.apply 仅当用户明确想要替换整个文档或者无法使用更窄的操作安全地表达更改时

这可以保持人类评论的稳定，避免破坏实时协作者，并使重试更容易推理。

7. 使用 status: "accepted" 跟踪建议

suggestion.add 默认创建用户必须接受/拒绝的待处理建议。该技能还公开了 status: "accepted" — 创建建议标记 ** 并** 在一次调用中提交更改。该标记作为审计跟踪持续存在，并带有每次编辑的归属；用户仍然可以拒绝恢复。当代理有信心并且用户希望在没有明确接受步骤的情况下查看落地内容时很有用。

HITL 默认值现在是 /edit/v2 加上线程内回复；当可见的轨道更改标记本身就是所需审阅体验的一部分时，请使用已接受的建议。

8. LIVE_CLIENTS_PRESENT 意识

当客户连接到证明文档时，技能知道什么是安全的：

• /edit/v2 — 在活动协作期间工作
• suggestion.add （包括 status: "accepted"） — 在活动协作期间工作
• 所有评论操作 — 在活跃协作期间工作
• rewrite.apply — 被 LIVE_CLIENTS_PRESENT 阻止；会破坏正在进行的 Yjs 编辑

该技能告诉调用者为无客户端场景保留 rewrite.apply ，并在活动会话期间使用精细操作或 /edit/v2 。

9. 原子结束同步到本地文件

当源是本地 Markdown 文件时，end-sync 将审阅的 Proof 状态自动写回磁盘：

# Stream .markdown bytes directly to a temp sibling, then rename.
TMP="${LOCAL}.proof-sync.$$"
jq -jr '.markdown' "$STATE_TMP" > "$TMP" && mv "$TMP" "$LOCAL"

jq -jr（无尾随换行符，原始字符串）保留逐字节内容，包括尾随换行符。同一文件系统中的 mv 是原子的——崩溃的写入不会影响原始文件，永远不会写一半。

当未直接请求拉取时（例如，作为 HITL 完成的副作用），该技能还要求用户在写入之前进行确认 - 无声覆盖令人惊讶。

10. 一致的代理身份

该技能在每个操作上强制执行 by: "ai:compound-engineering" ，并在标头中强制执行 X-Agent-Id: ai:compound-engineering 。显示名称 Compound Engineering 通过 /presence 在每个会话中绑定一次。 不要使用 ai:compound 或其他临时变体 - 身份保持统一，除非调用者显式覆盖子代理上下文。

简单示例

/ce-plan 完成通知静音计划，用户在阶段 5.4 菜单中选择“在 Proof 中打开”。计划在 HITL 审核模式下使用计划路径和标题调用 ce-proof。

该技能通过 POST /share/markdown 创建包含计划内容的证明文档。返回带有令牌的 URL。通过 POST /presence 绑定显示名称。向用户显示 URL。

用户在浏览器中打开 URL。在 10 分钟内添加 4 条内联评论和 2 条建议编辑。在聊天中说“准备好”。

该技能读取 /state，发现 6 个新标记。对于每个评论线程：

• 新鲜地阅读线程
• 通过 /edit/v2 小批量应用商定的内容编辑
• 使用一批 /ops 评论发布线程回复并解决已处理的评论

所有线程处理完毕后，技能会要求用户确认结束同步。用户确认。该技能自动将审阅的降价写回 docs/plans/2026-05-04-001-feat-notification-mute-plan.md。使用 status: proceeded 和 localSynced: true 将控制返回到 ce-plan 阶段 5.4。

何时去实现它

在以下情况下使用 ce-proof：

• 您想要一个 Markdown 文档的可共享 URL（头脑风暴、计划、学习、草稿）
• 您希望在最后进行 HITL 审查，包括评论线程、代理应用的编辑和原子磁盘同步
• 链技能（ce-brainstorm、ce-plan、ce-ideate）已移交给人工审核
• 您正在使用证明 URL 进行工作并希望代理参与

在以下情况下跳过 ce-proof：

• 该文档足够小，聊天粘贴和讨论工作正常
• 您没有网络访问权限（Web API 需要 proofeditor.ai）；本地网桥仅适用于 macOS
• 内容过于敏感，无法上传到第三方编辑器 - 将其保留在本地

用作工作流程的一部分

ce-proof 在多个 HITL 接触点与链集成：

• /ce-brainstorm 第 4 阶段 — “在证明中打开”交接，以对需求文档进行协作迭代
• /ce-plan 阶段 5.4 — “开放证明”移交以供 HITL 审查计划
• /ce-ideate 第 6 阶段 — “在 Proof 中打开并迭代”选项（非软件主题的默认保存目的地）
• /ce-compound — 在承诺 docs/solutions/ 之前分享学习成果

HITL 审核完成后，原始技能将重新获得控制权并处于以下四种状态之一：

• proceeded 和 localSynced: true — 磁盘已同步；继续
• proceeded 和 localSynced: false — 证明有新版本，本地版本已过时；提出拉动
• done_for_now — 用户暂停；提供拉当前 Proof 状态
• aborted — 回退到菜单而不进行任何更改

使用独立版

直接调用临时证明工作：

• 上传本地 markdown — /ce-proof "share docs/plans/foo.md to Proof for iteration"
• 来自证明 URL — /ce-proof https://www.proofeditor.ai/d/abc123?token=xxx（阅读状态、添加评论、建议编辑）
• 刚刚编辑的文件上的 HITL —“共享此内容以进行证明，以便我们可以迭代”会选择刚刚触及的降价
• 将 Proof 文档拉到本地 — 将当前 Proof 状态同步到 Markdown 文件（原子写入）

＃＃ 参考

标识默认值：by: "ai:compound-engineering"、X-Agent-Id: ai:compound-engineering、name: "Compound Engineering"。 Idempotency-Key 建议在每个突变上使用，并且在合同规定时需要使用。

＃＃ 常问问题

为什么有两个端点形状？ 不同的顾虑。 /ops 处理标记突变，包括批量现有线程评论回复/解决。 /edit/v2 处理块级编辑和文档范围文字替换的原子批次。线路格式不同 — 将 op 形状发送到 /ops 返回 422。

我应该重写整个文档吗？ 几乎从来没有作为第一步。使用 find_replace_in_doc 进行文字扫描，使用块级 /edit/v2 进行范围编辑。仅当用户要求完全替换或更改无法用更窄的操作表示时才使用 rewrite.apply 。

正确的突变模式是什么？ 读取 /state?kinds=comment 以获取评论，或读取 /snapshot 以获取块引用，捕获 mutationBase.token，然后从成功的突变响应中更新缓存的令牌。在 STALE_BASE 上，使用新令牌重新读取并重试一次。对于潜在应用的错误（5xx、超时、202 pending），在重试之前重新读取并检查更改是否已存在 - 重复标记来自于未经验证的重试。

为什么是 ai:compound-engineering 身份？ 为了一致的归因。在渲染的文档中标记作者身份，显示编辑者；如果代理某一天使用 ai:compound ，第二天使用 ai:compound-engineering ，则审计跟踪看起来会支离破碎。该技能强制执行一个身份，除非调用者明确覆盖。

HITL 审核模式有什么作用？ 将本地 Markdown 文件上传到 Proof，让用户通过 Web UI 中的评论和建议进行注释，通过过滤的评论读取提取每个线程，通过 Proof 的编辑 API 应用商定的编辑，在线程内回复/解决，然后自动将审阅的 Markdown 同步回本地文件。完整的循环规范位于 references/hitl-review.md 中。

我可以在用户连接时编辑文档吗？ 对于 /edit/v2、suggestion.add（包括 status: "accepted"）和所有注释操作，是的。 rewrite.apply 不可以——它被 LIVE_CLIENTS_PRESENT 阻止，因为它会破坏正在进行的 Yjs 编辑。

如果上传失败怎么办？ 该技能会重试一次。如果仍然失败，调用者会收到一个明显的错误，并可以决定要做什么（通常：留在链技能的菜单中而不进行证明切换，或者退回到仅限本地）。持续故障通过 POST /api/bridge/report_bug 报告给 Proof 进行诊断。

另请参阅

• /ce-brainstorm — 第 4 阶段“开放证明”交接
• /ce-plan — 第 5.4 阶段“在证明中打开”移交
• /ce-ideate — 第 6 阶段“打开并迭代证明”选项
• 证明 — 编辑器本身；这个技能是代理客户端