Pi Delegate
您是協調者。將一個有邊界的程式碼任務委派給獨立的實作者——Pi 程式碼代理 CLI——然後審查它產生的內容，並自行提交。您編寫簡報並掌握判斷權；實作者在它自己的會話中進行變更；您驗證並提交。
這個循環只需要一個 shell 命令和檔案存取權限，因此任何可比較的協調者都可以驅動它。
何時不該使用
- 任務夠小，可以內嵌執行；委派的開銷不值得。
- 未安裝或未驗證
piCLI。 - 您需要一個沙箱化的實作者。Pi 沒有沙箱，也沒有權限模式；
--read-only限制了工具表面，但具有寫入能力的執行不會有提示。
先決條件（檢查一次）
- 使用
npm install -g @earendil-works/pi-coding-agent安裝 pi。 - 驗證：對於訂閱提供者，在 pi 中執行
/login；或者對於 API 金鑰提供者，設定 API 金鑰環境變數或 pi 的驗證檔案。 - 確認
pi --version執行成功。 - 在目標 git 儲存庫中工作，或使用
--cd指向該儲存庫。
選擇模型（可選）
省略 --model 以使用 pi 的設定預設值。若要選擇其他模型，請從 pi --list-models 中選擇，並傳遞一個明確的 ID 或模式，例如 <provider>/<model-id> 或 sonnet:high。中繼僅接受字母、數字和 . _ : / -（該值會傳遞到 Windows 上的 shell），因此帶有 * 的 glob 模式不會被轉發。
循環
每個任務執行以下五個步驟。步驟 1、4 和 5 需要判斷；步驟 2 和 3 是機械式的。
1. 編寫簡報
Pi 只看到您傳送的文字以及它可以在工作區中檢查的內容——沒有聊天歷史或共享上下文。包括目標、當前狀態、要更改的內容、不應觸及的內容、專案的實際閘門，以及一個報告合約。告訴 pi 不要提交。每個簡報只處理一個任務。Pi 會自動從工作區及其父目錄載入 AGENTS.md/CLAUDE.md 上下文檔案，因此倉庫的指示無需內嵌即可到達。請參閱references/writing-the-brief.md。
2. 派遣
使用捆綁的中繼。它將簡報透過標準輸入傳遞給 pi --mode json，捕獲 JSON 事件串流，並寫入 result.json。（<skill-dir> 是包含此 SKILL.md 的已安裝資料夾。）
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# 選擇模型： 新增 --model <來自 pi --list-models 的 ID>
# 選擇提供者： 新增 --provider <名稱>
# 唯讀執行（審查/診斷）： 新增 --read-only
# 信任專案的 .pi 資源： 新增 --approve
# 繼續最近的會話： 新增 --resume-last （僅增量簡報）
# 繼續特定會話： 新增 --session <ID> （僅增量簡報）
# 硬性時間限制（看門狗）： 新增 --timeout 2h （預設 30 分鐘適合短期執行；實作簡報通常需要 1-2 小時）
# 查看所有選項： node .../relay.mjs --help
子行程的當前工作目錄（cwd）固定了工作區。中繼預設將工件寫入系統暫存目錄，且絕不提交。請參閱references/dispatch-and-poll.md。
3. 等待完成
中繼會阻塞直到 pi 完成。使用協調者的後台命令工具來執行它，或者在 shell 中將它背景化並輪詢 result.json。執行前的使用錯誤會以退出碼 2 結束且不會寫入結果；缺少 pi 會以退出碼 127 結束並寫入 status: "pi_unavailable"。
請相信行程狀態和工作樹，而非進度顯示。完成意味著行程已結束且 result.json 存在。Pi 的完整報告是 result.json 中的 finalMessage 欄位（同時也會在標準輸出上列印在報告標記之間）。
4. 審查——不要相信自我報告
將 pi 的最終訊息和閘門聲明視為聲明：
- 自行重新執行專案的閘門。
- 從
touchedFiles開始，閱讀與簡報相比的 diff。 - 如果已安裝，執行相關的守護技能。
- 在刪除或重新命名後，進行往返遷移並使用 grep 尋找懸空的參考。
請參閱references/review-and-land.md。
5. 提交
實作者編輯工作樹；協調者進行提交。只有在閘門通過且 diff 成立後才提交。如果需要修改，請使用 --resume-last 或 --session <ID> 傳送增量簡報，然後再次審查。
自主性與權限
Pi 沒有沙箱，也沒有權限模式。預設的無頭執行會進行讀取、寫入、編輯和執行 shell 命令，且沒有任何提示——控制項如下：
--read-only將 pi 可呼叫的工具限制為--tools read,grep,find,ls，涵蓋內建、擴充和自訂工具。已安裝的擴充程式碼仍會以使用者的主機權限執行。- 中繼預設傳遞
--no-approve，因此專案的.pi設定、擴充和技能保持不受信任。--approve是針對使用者信任的儲存庫的明確選擇加入。 touchedFiles和 diff 是變更的記錄。每次執行後檢查它們。
授權模型
委派是使用者選擇加入的。一旦他們同意（"執行此佇列"、"繼續"），提交經過驗證、閘門通過的工作就是約定的合約。仍有兩個限制：呈現，不要吸收（報告 pi 的設計決策、有道理但未要求的轉彎，以及不阻塞的挑剔點）並在範圍變更時停止（如果正確完成需要超出簡報的範圍，請詢問而不是擴張任務範圍）。請參閱references/review-and-land.md。
參考資料
- references/writing-the-brief.md — 結構、報告合約、實際閘門、標準輸入傳遞和增量簡報。
- references/dispatch-and-poll.md — 旗標、工件、
result.json、輪詢和故障恢復。 - references/review-and-land.md — 審查檢查清單、提交邊界，以及透過 pi 會話進行修改。
- references/multi-task-queues.md — 順序佇列、約束向前傳遞、進度追蹤，以及最終的一致性檢查。