D5：協調多代理協作
D5-O1 操作與管理多代理工作流程
多代理適合拆分責任與驗收清楚的工作。若下一步必須等上一個決策，就無法藉由平行執行縮短這段等待；仍可因專業分工採用管線，但要評估交接成本。匯出修正很小時，一個代理即可完成；若同時需要整理格式規格與盤點跨平台測試，可以先讓兩個唯讀工作平行，再由一位實作者整合。
按依賴選擇編排方式
| 模式 | 適合的關係 | 要付出的管理成本 |
|---|---|---|
| 主管／工作者 | 任務可切分，但需要集中裁決 | 主管必須掌握驗收與衝突 |
| 管線 | 後一階段依賴前一階段產物 | 每次交接都要驗證版本與完整性 |
| 平行後整合 | 輸入固定、子任務互相獨立 | 必須處理重疊修改與語意衝突 |
任務分派要寫明負責範圍、可用工具、輸出契約及整合者。讓兩位代理同時「改善匯出模組」，即使各自建 branch，也仍會產生重複工作；先約定誰修改實作、誰唯讀檢查邊界案例，才是在切分責任。
Branch 區分版本線；獨立 worktree 或 checkout 才提供不同工作目錄。同一目錄中的兩個代理，不會因為各自有分支名稱就隔離未提交修改。這些安排也不會自動隔離共用資料庫、同一個遠端 issue 或執行身分。若兩個工作都會寫入測試服務，還需要獨立資料或其他並行控制。沒有文字 merge conflict，也可能有語意衝突，例如一方改成保留空字串，另一方仍以空值作為驗收。
判斷練習： 兩位代理各自測試全綠，合併後就能直接交付嗎？
解析： 必須對整合後的版本重跑共同驗收，因為兩份結果分別證明的是不同產物。整合者應先確認格式契約一致，再處理差異，不能只挑較新或篇幅較長的答案。
技能範圍：GH600-SG；角色與工具設定延伸閱讀：GH-DOC-05、GH-DOC-06。本節為編排設計，不宣稱 custom agent 設定本身就是完整排程系統。
D5-O2 設定多代理可觀測性
多代理日誌最重要的用途，是重建各項決策與產物之間的關係。只有「A 完成、B 完成」無法回答它們是否讀到同一版規格、誰接手了失敗工作，或哪份測試對應最後合併結果。
用穩定識別串起交接
任務紀錄可以包含 task ID、agent ID、attempt ID、輸入版本、產物位置與狀態。相同任務重試時保留 task ID，使用新的 attempt ID 區分執行次數，並記錄前次執行關聯與重派原因，才有依據分辨預定重試和誤重複分派。這些是教學用欄位，可用現有 issue、workflow run 與 artifact 識別表達，不必為此另造平台。
| 事件 | 應留下的證據 |
|---|---|
| 分派規格盤點 | 任務範圍、輸入版本與負責代理 |
| 交給實作者 | 已確認規格、仍有疑義的項目與來源 |
| 整合修改 | 採用哪份產物，捨棄哪個方案及理由 |
| 執行驗收 | 受測版本、實際案例、結果與未測範圍 |
時間戳可協助排序，但跨機器時鐘可能不同，不能只用時間先後推定因果。交接關聯與產物版本提供更直接的線索。監控也不只看代理是否在線；要看可驗證產物是否前進、失敗是否重複，以及是否有人在等待不存在的輸入。
判斷練習： 日誌持續增加，但 20 分鐘沒有新差異或測試結果，能判定代理正常前進嗎？
解析： 不能。它可能在重複讀取相同檔案，也可能等待外部回應。核對預期步驟、工具狀態與產物進度；尚未查清前，將狀態記為待診斷，而不是僅憑日誌流量推定健康。
技能範圍：GH600-SG。GitHub checks（GH-DOC-17）可承載部分結果，但跨代理關聯仍需由工作流程保存。
D5-O3 回應失敗與效能退化
不同失敗狀態需要不同恢復動作。已經失敗的工作可以處理原因後重派；尚在執行但沒有進度的工作，必須先確認是否仍會產生副作用。過早啟動替代者，可能讓兩個代理同時修改遠端資源。
| 狀態 | 可觀察的例子 | 優先處理 |
|---|---|---|
| Failed | 工具明確失敗，沒有合格產物 | 保留輸入與錯誤，定位原因 |
| Partial | 實作完成，但只跑過部分驗收 | 保存可驗證產物，補足缺口 |
| Stalled | 超出預定等待界線，沒有進度 | 確認等待來源與執行是否仍存活 |
| Degraded | 持續產出但品質、延遲或衝突率惡化 | 比對基線，限制影響並調整策略 |
這些分類是工作流程的判讀方式，不是所有平台都有相同狀態列舉。重點在於觀察證據，而非狀態名稱。
匯出案例中，規格整理完成、實作代理中斷時，不必把已核對的規格重新產生。先檢查其適用版本，再從 checkpoint 恢復實作。若中斷前已送出寫入但結果未知，先核對遠端，不能直接交給另一個代理重送。
判斷練習： 兩位代理對空值的處理提出相反方案，應讓第三位代理投票嗎？
解析： 先回到格式契約、既有行為與使用者需求。多數意見不能補足缺少的規格；若資料仍不足，由權責者決定並更新共同契約。整合者的任務是解決依據上的衝突，不只是累積更多意見。
技能範圍：GH600-SG；個別代理工具的診斷入口另見 GH-DOC-22。
D5-O4 管理代理生命週期
更換代理的模型、指令或工具設定，可能改變輸出契約與權限需求。把新版設定覆蓋到進行中的工作，會讓同一任務前後使用不同假設，卻沒有清楚分界。因此代理設定也應有可辨識版本，更新要有驗證與切換條件。
一次可追溯的替換
先停止對舊代理分派新工作，確認它正在做的操作與可能副作用；能安全完成的工作可以完成，必須中斷的工作則保存 checkpoint。接著由新代理核對狀態與產物，再明確移轉任務責任，避免兩個執行者同時認為自己仍擁有寫入權。
新版本先在代表性任務驗證輸出格式、工具權限與失敗處理。若要回復舊版，不只回復模型名稱，也要恢復相容的指令與狀態解讀方式。已經改變的外部資料不會隨設定回復而自動還原。
退役代理時保留必要的任務、版本與決策關聯，並依資料保存政策處理紀錄；保留可稽核性不等於永久保存所有原始輸出。執行身分若不再需要，應透過既定管理程序收回權限。
判斷練習： 新代理的結果較好，能直接接手舊代理正在建立的 PR 嗎？
解析： 先確認舊操作是否完成、PR 是否存在、目前 commit 與責任歸屬，再交接。品質提升不會消除重複寫入風險。交接完成的判準，是新代理能指出從哪個狀態續作，而舊代理不再對該任務產生競爭操作。
技能範圍：GH600-SG；custom agent 角色設計延伸閱讀：GH-DOC-05。上述切換流程是工程設計範例，不是 GitHub 自動提供的生命週期保證。