agi-connect/agent-collaboration-protocol

智能体协作协议 (Agent Collaboration Protocol, ACP)

ACP 是一种基于共享文件夹的协调协议，适用于无法直接相互发送消息的智能体。它是一个状态机，包含结构化的 JSONL 事件、轮次所有权、就绪门控以及冻结的交付物。它不是松散的 Markdown 讨论。

任何兼容的智能体必须能够读写 Markdown/JSON、追加 JSONL 事件，并运行或精确复现捆绑脚本的行为。不要依赖隐藏的线程状态、供应商特定的 API 或对话记忆来保证协议的正确性。

必需输入

开始之前，需要：

• collaboration_folder：共享文件夹的绝对路径或仓库相对路径。
• objective：协作必须决定或产生的内容。
• objective_gates：目标特定的门控。协议会自动生成交付物门控。
• participants：所有参与者 ID，例如 server、reader、reviewer 或 agent-a。
• participant_id：当前智能体的身份。
• primary_deliverable_type：以下之一：adr、design-spec、implementation-plan、decision-memo、review-report、test-plan 或 custom。
• primary_deliverable_file：内置类型可选，custom 类型必需；必须是 Markdown 格式。
• primary_deliverable_checklist：仅 custom 类型需要。
• deliverables_mode：可选，默认为 internal；external 模式需要 repoRoot。
• deliverables_dir：可选，默认为 deliverables。

如果缺少任何必需输入，请在创建文件或写入事件之前询问。不要凭空编造目标门控。

文件

ACP schema v2 文件夹使用以下协议文件：

• protocol.json：包含 protocol: "acp"、schemaVersion: 2、目标、参与者、生成的和目标门控、交付物声明、当前阶段、提案所有者、等待参与者以及时间戳。
• events.jsonl：仅追加的事件日志。每行是一个紧凑的 JSON 对象。
• proposal.md：当前提案/变更摘要。
• review.md：结构化的参与者评审。
• decisions.md：包含稳定ID的简洁已接受决策索引。
• readiness.md：开放问题分类、目标门控、生成的交付物门控、交付物快照、阻塞项和就绪结果。
• conclusion.md：最终协议收据。不是主要交付物。
• deliverables/：实际的 Markdown 交付物和可选的附件。

不要创建或使用 state.log、discussion.md 或 opinions.md。它们不是协议文件，不得出现在门控或指令中。

交付物

ACP 将协议状态与交付物工件分开：

• 每个可完成的协作都需要声明一个主要的 Markdown 交付物。
• conclusion.md 是最终收据；它引用冻结的交付物和就绪结果。
• 内置交付物类型有 adr、design-spec、implementation-plan、decision-memo、review-report 和 test-plan。
• custom 类型需要明确的 Markdown 文件和清单。
• 支持性交付物为 Markdown 格式。附件可以是交付物目录下的非 Markdown 文件。
• internal 模式将交付物存储在协作文件夹内部。
• external 模式将交付物存储在仓库根目录相对路径下，并在事件、就绪检查和结论中使用 external:<file> 引用。
• 交付物必须包含 Status: Draft、Status: In Review 或 Status: Frozen。
• 提案所有者使用 deliverable_frozen 事件冻结主要交付物；冻结是严格的，没有解冻或重新冻结路径。

初始化

建议使用捆绑脚本：

python3 <skill>/scripts/init_collaboration.py \
  --folder <collaboration_folder> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --primary-deliverable-type design-spec \
  --completion "<objective gate>" \
  --completion "<another objective gate>"

对于外部交付物：

python3 <skill>/scripts/init_collaboration.py \
  --folder <repo>/.acp/<run> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<objective gate>"

初始化器会为协议文件和主要交付物创建模板。如果 protocol.json 已存在，除非提供 --resume，否则会失败。

事件

使用 scripts/append_event.py 或精确复现其行为。必需事件字段：

• seq：events.jsonl 中的连续整数。
• from：protocol.json 中列出的参与者 ID。
• event：允许的事件名称。
• at：ISO-8601 UTC 时间戳。
• summary：一个简短的句子。

允许的事件：

• initialized
• deliverable_drafted
• deliverable_revised
• deliverable_frozen
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

所有 initialized 之后的事件都需要 reply_to 指向更早的事件。doc 引用在内部模式下相对于协作文件夹，在外部模式下为 external:<file>。

所有 deliverable_* 事件都需要：

• doc：已解析的交付物引用。
• role：primary 或 supporting。

deliverable_frozen 还需要顶级的 sha256，即引用文件的 64 字符小写十六进制 SHA-256 哈希。一旦冻结，文件内容必须保持与哈希匹配。

阶段

智能体必须根据 protocol.json.currentPhase 和 protocol.json.waitingFor 行动：

• drafting：提案所有者起草主要交付物，追加 deliverable_drafted，更新 proposal.md，然后追加 proposal_submitted。
• reviewing：列出的评审者评审 proposal.md 和主要交付物，将结构化评审追加到 review.md，然后追加 review_submitted。
• revising：提案所有者根据需要更新 proposal.md 和交付物，如果交付物有更改则追加 deliverable_revised，然后追加 proposal_revised。
• decision_review：提案所有者对 readiness.md 中的每个开放问题进行分类并追加 question_classified；随后参与者通过 decision_accepted 接受 decisions.md 中的明确条目。
• readiness_check：提案所有者冻结所需的交付物，在 readiness.md 中记录快照，运行验证，然后追加 readiness_passed。
• completed：除非用户明确开始新一轮，否则停止。
• blocked：直到阻塞项解决或新一轮开始才停止。

completed 仅在 readiness_passed 之后有效，并且必须引用 conclusion.md。

评审格式

每个 review_submitted 事件必须在 review.md 中有一个匹配的标题，其 seq 等于该事件的 seq：

## <ISO-8601 UTC> - <participant_id> - seq <review_submitted event seq>

Context:
- Read `proposal.md` after event seq `<seq>`.
- Reviewed primary deliverable: `<resolved path>`
- Reviewed supporting deliverables: `<paths or none>`

Review Scope:
- Proposal coherence
- Primary deliverable completeness
- Accepted decision traceability
- Implementation readiness

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

决策

decisions.md 是已接受决策索引，不是交付物。每个已接受的决策必须使用稳定的 ID：

### D1. <short title>

- Decision: ...
- Rationale: ...
- Reflected in: `deliverables/design-spec.md#section`

ID 必须连续（D1、D2、...）。Reflected in: 必须指向声明的 primary 或 supporting 交付物。

就绪门控

在 readiness_passed 或 completed 之前：

• 每个开放问题都是 [resolved]、[deferred_nonblocking] 或 [blocking]。
• 每个 [deferred_nonblocking] 项包含 Reason: ...。
• 没有 [blocking] 或 [unresolved] 项存在。
• 目标门控已检查。
• 生成的交付物门控已检查。
• 主要交付物具有 Status: Frozen。
• 已记录主要交付物的 SHA-256 快照。
• Ready to implement 已检查。
• validate_collaboration.py 通过。

阻塞或未解决的就绪项也会阻止 decision_accepted。

最终结论

在 completed 之前，写入 conclusion.md 作为最终收据。它必须包含：

• Decision Outcome：恰好是 [proceed]、[do_not_proceed] 或 [defer] 之一。
• Rationale。
• Deliverable Receipt：主要路径、类型、SHA-256、支持性交付物和附件。
• Accepted Decisions Summary。
• Readiness Result。
• Assumptions。
• Deferred Follow-ups。
• Implementation Blockers。
• Next Action。

blocked 是一个阶段/事件，不是可完成的结果。

轮询与观察者

参与者必须保持活跃以完成协作循环，直到阶段变为 completed、blocked 或达到明确的协调截止时间。

如果没有观察者，请使用：

python3 <skill>/scripts/next_action.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

对于自主参与者，建议使用：

python3 <skill>/scripts/wait_for_turn.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

wait_for_turn.py 在参与者被列为 waitingFor 时返回，或者当协作为 completed 或 blocked 时返回。默认为 30 分钟超时；仅当外部监督者拥有取消权时才使用 --timeout 0。

验证

运行：

python3 <skill>/scripts/validate_collaboration.py --folder <collaboration_folder>

验证器检查必需的协议文件、schema v2 字段、交付物声明、路径安全性、事件形状、交付物角色和哈希、阶段转换、评审标题、决策 ID、就绪门控、冻结交付物内容、结论收据以及完成顺序。

退出码：

• 0：验证通过。
• 1：验证通过但带有警告。
• 2：验证失败。