用途
Project Protocol 是一个用于协调式项目工作的运行状态管理协议。它负责规范化运行身份、快照绑定、交付与验证记账、授权连续性以及安全阶段恢复。该协议属于 acaprino/daodan 技能集，其规范契约位于 ${CLAUDE_PLUGIN_ROOT}/contracts/work.toml 和 ${CLAUDE_PLUGIN_ROOT}/contracts/project-result.toml。
主要能力
- 运行状态接口：通过 python "${CLAUDE_PLUGIN_ROOT}/skills/project-protocol/scripts/run_state.py" 提供 init、show、update、validate、resume、snapshot 等命令。
- 状态存储：运行状态存放在项目内专用根目录，默认 .daodan/runs/<id>/，根哨兵为 .daodan-root。协调者拥有 work.json 和 result.json，每个被派发的工作者拥有一个声明的报告。
- 快照哈希：包含脏文件和未跟踪的范围内输入，但不包含运行自身的输出根目录。
- 更新机制：递归合并对象并替换数组。身份、原始范围、授权和基线项目绑定不可变。已完成的运行不可变。修订不匹配时不写入任何内容。
- 验证：validate 输出有效性和身份。validate --result 还会检查规范信封与确切工作修订、候选快照、交付账本和必需检查状态的一致性。添加 --current 可将结果作为当前项目的验证来接受。
- 恢复：resume 需要当前授权，可选提供的范围必须等于记录的范围。它验证项目/工作树/HEAD 和当前候选快照，返回记录以及待处理阶段和交付，不更改任何文件。
- 状态与完成：运行状态为 in_progress、complete；阶段状态为 pending、in_progress、complete、skipped；工作者交付为 pending、running、delivered、failed。失败的工作者可以重试，失败记录保留在其尝试历史中。
- 基线、门禁与恢复：在变更阶段前，验证工作树的独占所有权。记录 pre_phase_sha，保存足够的阶段前文件状态以精确恢复该阶段拥有的编辑。失败时仅恢复该阶段拥有的编辑到捕获的阶段前值。
使用方式
使用 run_state.py 脚本，命令格式如下：
- init --project ROOT --payload INPUT.json [--out INTERNAL_ROOT] [--run-id ID]
- show --project ROOT --run-id ID [--out INTERNAL_ROOT]
- update --project ROOT --run-id ID --expected-revision N --payload PATCH.json
- validate --project ROOT --run-id ID [--out INTERNAL_ROOT] [--current] [--result RUN_RESULT.json]
- resume --project ROOT --run-id ID --payload CONTEXT.json [--out INTERNAL_ROOT]
- snapshot --project ROOT --payload CONTEXT.json [--out INTERNAL_ROOT]
选择自定义根目录后，需一致地传递 --out。Init 需要 operation、objective、scope（路径和可选的 focus/excluded）、authorizations 和 budget。它默认将 phases、plan、deliveries 和 gates 设为空容器。在派发前需在 deliveries 中声明每个预期工作者，在执行前需在 required_gates 中声明每个已知的强制检查。
适用场景
适用于需要协调多个工作者、管理运行状态、验证交付结果和确保授权连续性的项目工作流程。特别适合需要精确快照绑定、阶段恢复和门禁验证的复杂项目。
限制
- 运行状态助手记录并验证过程，但不执行 Git 回滚、派发工作者、强制其令牌限制或限制其其他工具。
- 其自身的写入在机制上受到限制。其他工具的限制是明确的提示义务，直到适配器具有可测量的运行时机制。
- 远程检查需要非空的 Git 修订和 head_matches_snapshot 为 true。
- 比较是字节精确的。具有转换行尾的检出需要本地验证。
- 快照包含常规文件类型和可执行状态（在文件系统支持的情况下）；HEAD 符号链接 blob 无法证明常规文件。
- 新输入或更广泛的授权需要新的运行，绝不能重新绑定已完成的报告。
- 部分报告不授权将运行标记为完成。
- 在共享检出中绝不运行 git clean、广泛检出或硬重置。
- 已发布的阶段通过授权的回滚来撤销，绝不重写历史。