polyphony

polyphony 技能概覽

polyphony 是一個多代理協調技能，用來在容器隔離的工作區中並行執行代理工作。每個 session 都會取得自己獨立的 Docker container 與 git branch，因此當你需要並行執行、又不想遇到 branch 衝突、共享狀態 bug 或雜亂清理時，它特別有用。

polyphony 適合做什麼

當工作比單一 prompt 更大，但仍受益於結構化分工時，就適合使用 polyphony skill：例如平行功能開發、隔離式驗證、issue 分流，或是讓幾條 agent 路徑同時對同一個 codebase 進行處理。這個技能是為那些重視乾淨執行、可重現的任務路由，以及更安全的多代理協調的使用者設計的。

polyphony 為什麼特別

polyphony 的主要差異化在於它以隔離優先的工作流設計為核心。它不是叫 agent「把所有事都做完」，而是把任務發現、路由、資源建立、執行環境與驗證分開，讓每個 worker 都在受控的工作區內運作。當你需要獨立測試與更乾淨的落地行為時，這種 polyphony for Multi-Agent Systems 的做法會更實用。

polyphony 的最佳適用情境與取捨

如果你的環境已經支援 Docker 或 OrbStack，而且你想要的是預設即啟用的協調流程，而不是一次性的 prompt 模式，polyphony 會最適合。若你只需要單次聊天回覆、無法執行 container，或想要幾乎零設定、也不需要 repository 感知型工作流，那它就比較不適合。

如何使用 polyphony 技能

安裝並載入 polyphony

先把 polyphony skill 安裝到你的 skills 目錄，接著透過支援 skill 載入的主機工作流程來使用。repository 註明它預期會在可用 container 隔離時自動載入，而且 /spawn-team 會使用它作為預設。如果你的設定不同，請先確認 Docker 存取、branch 建立與 workspace 掛載都可用，再依賴這個技能。

從正確的檔案開始讀起

使用 polyphony 時，先從 skills/polyphony/SKILL.md 開始，然後按照技能內部的使用順序閱讀其連結或提到的脈絡：任務生命週期、架構、前置條件、設定，以及檔案中嵌入的任何 repository-specific 參考。由於這個 repo 沒有 helper scripts 或額外的參考資料夾，核心行為就寫在 skill 檔本身，所以仔細讀這份檔案很重要。

把模糊目標改寫成可用的 prompt

一個好的 polyphony prompt 應該包含：目標 repo、你希望同時跑幾個 parallel agents、每個 agent 負責什麼工作、對 branch 或 PR 的預期，以及對測試、憑證或清理的任何限制。例如，與其說「修好這個專案」，不如要求「把這個 issue 拆成三個隔離的 agent 任務：重現、修補、驗證，使用各自獨立的 Docker workspaces，並回報每個 branch 的落地狀態。」

要指定哪些內容，輸出會更好

給這個技能明確的路由訊號：任務優先順序、相依性、是否必須先唯讀探索、哪些環境可以安全建立，以及什麼算驗證。這能幫助 orchestrator 挑出更好的 RunSpecs，也能減少浪費 container 啟動成本。對 polyphony 而言，最有價值的輸入不是更多篇幅，而是更清楚的任務邊界。

polyphony 技能 FAQ

polyphony 只適合 Docker 環境嗎？

是，實務上可以這麼說。polyphony skill 假設容器隔離可用，所以 Docker 或 OrbStack 支援就是主要的採用門檻。如果你無法建立 containers，這個工作流的大部分價值就會消失。

polyphony 和一般 prompt 有什麼不同？

不同。一般 prompt 是要求 agent 採取行動；polyphony 則是定義多個 agent 執行如何被認領、路由、建立環境、驗證與落地。這正是 polyphony skill 的重點，尤其當獨立 branch 與乾淨執行比速度本身更重要時。

初學者可以用 polyphony 嗎？

可以，只要你已經能執行 containers 並且看得懂 skill 檔。主要的學習曲線不在 prompt 撰寫，而在理解 polyphony 期待的是任務拆解與環境就緒。初學者通常從一個小任務和一個清楚的驗證目標開始，效果會更好。

什麼情況下不該使用 polyphony？

如果只是快速的一次性問題、輕量修改，或是沒有 Docker 的環境，就不要用 polyphony。當任務本身還很模糊、你也還沒定義每個 agent 應該負責什麼時，它也不是好選擇，因為 orchestration 的額外成本可能會高過收益。

如何改進 polyphony 技能

給 router 更清楚的任務邊界

polyphony 的最大品質提升，來自更清楚的任務拆解。請明確說出哪些工作是探索性、哪些工作會改 code、哪些工作只負責驗證。如果你想要平行化，就要把分工明確定義出來，而不是讓系統從模糊目標自行推斷。

加入會影響 workspace 行為的限制

請提到 branch 命名規則、網路限制、測試執行時間預期，以及是否需要 secrets 或已掛載的身份資訊。因為 polyphony 使用的是隔離 containers 與獨立 branches，這些限制會直接影響 provisioning，以及這次執行能不能在不需要人工介入的情況下完成。

要求驗證，不要只要求實作

常見的失敗模式，是只做到「程式碼有改」。更好的 polyphony 用法，會要求每條 agent 路徑都提供重現步驟、測試指令與落地條件。當多個 worker 可能會收斂到不同解法時，這一點尤其重要，因為你需要可靠的 merge 判斷。

第一次執行後要再迭代

如果第一次輸出太寬泛，就收窄任務，改成只有一個成功判準再重跑。如果結果太碎裂，就減少 parallel agents 的數量，並在階段之間加入更強的相依關係。對 polyphony 來說，改進通常來自更銳利的協調輸入，而不是更長的 prompt。