代理協作協議 (Agent Collaboration Protocol)

代理協作協議

使用共享資料夾作為可攜式的協調匯流排，適用於無法直接互相傳遞訊息的代理。ACP 是一個嚴謹的協議：它是一個具有結構化事件與就緒閘門的狀態機，而非鬆散的 Markdown 對話。

任何相容的代理必須能夠讀取 Markdown 和 JSON、寫入 Markdown、附加 JSONL 事件，以及執行或完全複製附帶腳本的行為。請勿依賴 Codex 執行緒 API、Claude 專用掛鉤、OpenCode 專用狀態、Kiro 專用元資料或隱藏的對話記憶來確保正確性。

必要輸入

開始之前，需要：

• collaboration_folder：共享資料夾的絕對路徑或相對於儲存庫的路徑。
• objective：協作必須決定或產出的目標。
• completion_gates：結束協作的具體閘門。
• participants：所有參與者的 ID，例如 server、reader、reviewer 或 agent-a。
• participant_id：目前代理的身份。

如果缺少任何必要輸入，請在建立檔案或寫入事件前先詢問。請勿自行發明完成閘門。

檔案

ACP 資料夾使用以下檔案：

• protocol.json：目標、參與者、完成閘門、當前階段、提案擁有者、等待中的參與者以及時間戳。
• events.jsonl：僅供附加的事件日誌。每一行是一個緊湊的 JSON 物件。
• proposal.md：僅包含當前提案。
• review.md：結構化的參與者審查。
• decisions.md：僅包含已接受的決策。
• readiness.md：開放問題分類、阻礙項、已延遲的非阻礙項目以及實作就緒狀態。
• conclusion.md：最終討論結論。說明是否進行、不進行、延遲或受阻；原因；如何實作或為何不實作；以及下一步行動。

請勿建立或使用 state.log、discussion.md 或 opinions.md。這些不是協議檔案，不得出現在完成閘門或指令中。

初始化

建議使用附帶腳本：

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

如果 protocol.json 已存在，初始化器會失敗，除非提供 --resume。重複初始化不是附加操作。

事件

使用 scripts/append_event.py 或完全複製其行為。除非執行環境無法執行腳本，否則請勿手動撰寫事件。

必要的事件欄位：

• seq：events.jsonl 中的連續整數。
• from：列在 protocol.json 中的參與者 ID。
• event：允許的事件名稱。
• at：ISO-8601 UTC 時間戳。
• summary：一個簡短的句子。

建議的欄位：

• doc：相對於協作資料夾的路徑。
• reply_to：較早事件的 seq。

允許的事件：

• initialized
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

所有回應必須在回應先前事件時使用 reply_to。reply_to 必須指向一個已存在的較早事件。事件時間戳不得隨著 seq 增加而倒退。如果發現錯誤，請附加 blocked 或一個新的修正事件；請勿改寫較早的事件。

階段

代理必須根據 protocol.json.currentPhase 和 protocol.json.waitingFor 行動：

• drafting：提案擁有者更新 proposal.md，然後附加 proposal_submitted。
• reviewing：僅有列在 waitingFor 中的參與者將結構化審查附加到 review.md，然後附加 review_submitted。
• revising：提案擁有者處理必要的變更並附加 proposal_revised。
• decision_review：提案擁有者首先將 readiness.md 中的每個開放問題分類，並附加 question_classified；只有之後，列在 waitingFor 中的參與者才能接受 decisions.md 中明確的決策，並附加 decision_accepted。
• readiness_check：參與者對每個問題進行分類，清除阻礙項，通過就緒檢查，然後提案擁有者撰寫 conclusion.md。
• completed：停止，除非使用者明確開始新的一輪。
• blocked：停止，直到阻礙項被解決。

completed 只有在先前的 readiness_passed 事件之後才有效。completed 必須引用 conclusion.md。請勿僅憑 decisions.md 就完成；決策是輸入，而 conclusion.md 才是協作目標的最終答案。

提案擁有者在 proposal_submitted 之後必須等待。當階段為 reviewing 時，擁有者可以輪詢下一步行動或為真正的超時/阻礙項附加 blocked，但不得編輯 proposal.md、decisions.md、readiness.md 或 protocol.json，且在所需的審查提交之前不得附加推進事件。

審查格式

每個 review_submitted 事件必須有一個對應的 review.md 標題，其 seq 等於該事件的 seq：

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

Context:
- 在事件 seq `<seq>` 之後讀取 `proposal.md`。

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

請勿在審查標題中使用被回覆事件的 seq。將回覆的上下文放在 Context 和 reply_to 中。

就緒閘門

在 readiness_passed 或 completed 之前：

• 每個開放問題必須被分類為 [resolved]、[deferred_nonblocking] 或 [blocking]。
• 每個 [deferred_nonblocking] 項目必須包含 Reason: ...。
• 不得遺留任何 [blocking] 或 [unresolved] 項目。
• 最終設計檢查清單必須包含並勾選 Ready to implement。
• validate_collaboration.py 必須通過。

阻礙就緒的項目也會阻止 decision_accepted。未解決的問題以及缺少 Reason: ... 的已延遲項目也會阻止 decision_accepted。

最終設計文件必須分開列出：

• 已接受的決策
• 假設
• 已延遲的後續事項
• 實作阻礙項
• 準備就緒可實作

最終結論

在 completed 之前，將 conclusion.md 撰寫為結論文件，而非日誌。它必須包含：

• 決策結果：必須是 [proceed]、[do_not_proceed] 或 [defer] 其中之一。
• 理由。
• 已接受的決策。
• 實作方式。
• 假設。
• 已延遲的後續事項。
• 實作阻礙項。
• 下一步行動。

當實作應立即開始時使用 [proceed]；當功能或計畫不應執行時使用 [do_not_proceed]；當在實作之前必須進行後續工作時使用 [defer]。當協作受阻時，可能存在 [blocked] 結果，但無法完成。

輪詢與監聽器

參與者必須在協作迴圈中保持存活，直到階段變為 completed、blocked 或達到明確的使用者/協調者截止時間。請勿因為附加了一個有效事件就停止。在每次行動後，重新讀取 protocol.json，然後採取下一個允許的行動或等待下一個事件。

如果執行環境有監聽器，它可以在 events.jsonl 或 protocol.json 變更時通知參與者。監聽器必須保持被動：它只注意變更，絕不撰寫分析或決策。

如果沒有監聽器，請使用：

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。返回後，檢查 next_action.py，如果是你的回合則行動，附加必要的事件，然後重複等待/行動迴圈。手動使用者提示（例如「檢查新意見」）僅作為備用，並非預期的協作迴圈。

啟動參與者的協調者提示應要求每個參與者執行此迴圈，而不是只做一個階段就退出。未列在 waitingFor 中的參與者可以在 wait_for_turn.py 中阻塞，但在等待期間不得編輯共享狀態。

驗證

執行：

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

驗證器會檢查必要檔案、遺失的過時檔案、事件形狀、seq 連續性、時間戳單調性、階段轉換、waitingFor 所有權、reply_to、審查標題 seq、就緒分類、結論完整性以及完成順序。

退出碼：

• 0：有效。
• 1：有效但有警告。
• 2：無效。