Proof 是一个面向人类与智能体协作的 Markdown 文档编辑器，支持两种工作方式：Web API（通过 HTTP 创建和编辑共享文档，无需安装），以及本地桥接（通过 localhost:9847 驱动 macOS 版 Proof 应用）。
主要能力：创建共享文档并返回可分享的 tokenUrl；读取文档状态（/api/agent/{slug}/state）；通过 /api/agent/{slug}/ops 对文本添加评论、回复、解决/取消解决评论；添加待处理建议（suggestion.add，需用户接受或拒绝）或标记为 accepted 的建议（立即应用但保留可回退的审计标记）；通过 suggestion.accept / suggestion.reject 处理建议；使用 rewrite.apply 做整篇重写。另有 /edit/v2 端点支持块级编辑，操作类型包括 replace_block、insert_before、insert_after、delete_block、replace_range、find_replace_in_block。
身份与归属：每次写入都需携带 by 字段与 X-Agent-Id 头，默认值为 ai:compound-engineering，显示名默认为 Compound Engineering，通过 POST /presence 绑定到该 agent ID。评审模式见 references/hitl-review.md，涵盖标记分类（change / question / objection / ambiguous）、幂等摄入、异常终止报告与结束同步的原子写入。
使用方式：所有变更都需先读取最新的 baseToken（来自 /state.mutationBase.token），随请求体提交；遇到 BASE_TOKEN_REQUIRED 或 STALE_BASE 时重新读取并重试一次；建议使用 Idempotency-Key 头。评论示例：{"type":"comment.add","quote":"...","by":"ai:compound-engineering","text":"...","baseToken":"<token>"}。读取与同步文档可用 jq -jr '.markdown' 流式写入临时文件后 mv 原子替换，避免尾随换行丢失；若拉取是其他操作的副作用，应先确认再写入。
限制：桥接端点 /d/{slug}/bridge/* 需要客户端版本头，缺失时返回 426；活动协作期间 rewrite.apply 会被 LIVE_CLIENTS_PRESENT 阻止，此时改用 edit/v2 或 suggestion.add；不要在同一 replace 中跨表格单元格；不支持 suggestion.resolve，应使用 accept 或 reject；/ops 与 /edit/v2 的载荷结构不同，混用会返回 422。收费、价格与平台支持范围：暂未提供。