agi-connect/agent-collaboration-protocol

代理協作協定 (Agent Collaboration Protocol)

ACP 是一個針對無法直接相互傳遞訊息的 Agent 所設計的共享資料夾協調協定。它是一個具有結構化 JSONL 事件、輪次所有權、就緒閘門（readiness gates）以及凍結交付物（frozen deliverable）的狀態機。這不是鬆散的 Markdown 討論。

任何相容的 Agent 都必須能夠讀寫 Markdown/JSON、以附加方式寫入 JSONL 事件，並執行或完全重現捆綁腳本的行為。協定的正確性不得依賴隱藏執行緒狀態、供應商特定 API 或對話記憶體。

必要輸入

開始之前，需要以下輸入：

• collaboration_folder：共用資料夾的絕對路徑或相對於儲存庫的路徑。
• objective：協作必須決定或產出的目標。
• objective_gates：特定於目標的閘門。協定會自動產生交付物閘門。
• participants：所有參與者的 ID，例如 server、reader、reviewer 或 agent-a。
• participant_id：當前 Agent 的身分。
• 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。

如果有任何必要輸入缺失，請先詢問，不要直接建立檔案或寫入事件。請勿自行發明 objective gates。

檔案

ACP schema v2 資料夾使用以下協定檔案：

• protocol.json：包含 protocol: "acp"、schemaVersion: 2、objective、participants、產生的與 objective 的閘門、交付物宣告、當前階段、提案擁有者、等待中的參與者以及時間戳記。
• events.jsonl：僅附加的事件日誌。每行是一個緊湊的 JSON 物件。
• proposal.md：當前的提案/變更摘要。
• review.md：結構化的參與者審查意見。
• decisions.md：具有穩定 ID 的精簡已接受決策索引。
• readiness.md：開放問題分類、objective 閘門、產生的交付物閘門、交付物快照、阻礙因素與就緒結果。
• 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 雜湊，對應於被引用的檔案。一旦凍結，檔案內容必須始終與該雜湊值相符。

階段

Agent 必須根據 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 相同的標題：

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

上下文：
- 在事件 seq `<seq>` 之後閱讀 `proposal.md`。
- 審查的主要交付物：`<resolved path>`
- 審查的支援交付物：`<paths or none>`

審查範圍：
- 提案一致性
- 主要交付物完整性
- 已接受決策的可追溯性
- 實作就緒程度

立場：
- ...

疑慮：
- ...

必要變更：
- ...

問題：
- ...

決策

decisions.md 是已接受決策的索引，而非交付物本身。每個已接受的決策必須使用穩定的 ID：

### D1. <short title>

- 決策：...
- 理由：...
- 反映於：`deliverables/design-spec.md#section`

ID 必須是連續的（D1、D2……）。反映於：必須指向已宣告的主要或支援交付物。

就緒閘門

在 readiness_passed 或 completed 之前：

• 每個開放問題都是 [resolved]、[deferred_nonblocking] 或 [blocking]。
• 每個 [deferred_nonblocking] 項目都包含 Reason: ...。
• 不得遺留任何 [blocking] 或 [unresolved] 項目。
• 檢查 objective gates。
• 檢查產生的交付物閘門。
• 主要交付物具有 Status: Frozen。
• 記錄主要交付物的 SHA-256 快照。
• 勾選 Ready to implement。
• validate_collaboration.py 通過。

阻塞或未解決的就緒項目也會阻止 decision_accepted。

最終結論

在 completed 之前，將 conclusion.md 撰寫為最終收據。它必須包含：

• 決策結果：必須是 [proceed]、[do_not_proceed] 或 [defer] 其中之一。
• 理由。
• 交付物收據：主要路徑、類型、SHA-256、支援交付物與附件。
• 已接受決策摘要。
• 就緒結果。
• 假設。
• 延後的後續事項。
• 實作阻礙。
• 下一步行動。

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：驗證失敗。