前言¶

Agent Teams 有一批官方 README 沒寫、踩過才知道的約束：名冊只增不減，名額不可回收；interrupt 不釋放成員；寫作用域只是提示不是鎖；隊友默認是 fresh context，看不到你的歷史；沒有活躍隊友時 wait_agent 會立即返回而不是等待。這些約束的共性是：出錯時沒有報錯，只有行爲異常，堆棧裏找不到原因。

dsh-agent-team-playbook 是 elfgzp 維護的非官方插件，分類工作流。它不改運行時，而是把這些約束寫成六條守則，註冊成有序的系統提示段落注入每個 agent，讓接管 Team 的 agent 在動手前就知道哪些路走不通。下面介紹它的能力、安裝步驟和實戰細節。

這是什麼¶

一句話：一個純提示注入的 bundle，把 Agent Teams 的操作規則放進 system prompt，而不是新增工具或改變運行時行爲。事實依據上游 tag dsh-v0.2.1-rc.3 源碼覈驗；非官方，與 deepseek-ai 無隸屬關係。

插件本體很小，打包只含四個運行時文件：lib/index.js、cordis.patch.yml、locale/{zh,en}.json、icon.svg。docs/ 與 examples/ 是隨倉庫分發的文檔，不參與打包。

它做了什麼¶

插件註冊一個有序系統提示段落 team-playbook:rules，order 650，爲每個 agent 注入六條規則：

650 這個位置緊接上游 TEAM_POLICY(600) 之後、PTC_ONLY(800) 之前，讀起來是 Team 策略的延續，不會割裂後續工具段落。

它不做什麼¶

明確邊界，避免誤期待：

• 不新增任何工具，純提示注入，不改 Team 運行時行爲。
• 不強制任何流程，軟狀態標籤、寫作用域重疊仍然只是提示。
• 不做 UI，沒有 client 半邊，不加面板或按鈕。
• 不修改上游源碼，依賴 @deepseek-ai/dsh-experimental-agent-team 原樣工作。

安裝與啓用¶

環境要求¶

DeepSeek Harness >=0.2.1-rc.3 <0.3.0，已實測 0.2.1-rc.3、0.2.1-rc.5。版本約束寫在 package.json 的 peerDependencies，DSH 安裝時會據此校驗。區間寫法對 0.2.1-rc.x 與 0.2.x 正式版都成立；0.2.2-alpha.x 這類預發佈版按 semver 默認不匹配，遇到時需自行確認 API 未變再放寬。

從本地目錄安裝¶

先 clone 到持久目錄（不要用 /tmp），再 pnpm install –prod，然後自檢，最後用 plugin_manager 的 install_bundle 安裝。這幾步順序不要調換：自檢放在 install_bundle 之前，能讓「依賴沒裝上」當場暴露；跳過自檢的症狀會變成 application: failed 加 ERR_MODULE_NOT_FOUND，且不提示真實原因，容易被誤判成代碼 bug。

cd ~/Work
git clone https://github.com/elfgzp/dsh-agent-team-playbook.git
cd dsh-agent-team-playbook

pnpm install --prod

node --input-type=module -e "const m=await import('./lib/index.js'); \
  console.log('deps OK', Object.keys(m), m.inject)"

上面這段是把倉庫 clone 到持久目錄、裝依賴並自檢，期望輸出 deps OK [ ‘Config’, ‘apply’, ‘inject’ ] [ ‘systemPrompt’, ‘agents’ ]。這一步不依賴 DSH 運行時，只確認插件自己的依賴解析正常。

{
  "action": "install_bundle",
  "target": "/absolute/path/to/dsh-agent-team-playbook"
}

這一段用 plugin_manager 從本地目錄安裝。安裝後在插件詳情裏應看到標題「Agent Teams 操作守則」與對應描述（來自 locale/*.json）；已有會話的 agent 會立即生效，新創建的 teammate 也會自動獲得該段落。卸載用 remove_bundle，或在 set_bundle 裏禁用。替換已安裝包需要重啓，因爲要加載新的 JS 模塊代際。

三個容易踩的坑¶

上層目錄的 pnpm-workspace.yaml。如果 ~ 或 ~/Work 存在該文件，pnpm 會把那個目錄認作 workspace 根，在子目錄執行 install 時輸出 No projects found，什麼都不裝且退出碼是 0，&& 鏈和 CI 都不會報錯。解法之一是 pnpm install –prod –ignore-workspace。注意 –ignore-workspace-root-check 不是這個場景的選項，pnpm 會直接報 Unknown option。

源目錄不能刪。link: 協議只登記指向該目錄的鏈接，不復制文件。刪掉或移動 checkout，下次啓動插件失效，報錯是 application: failed，且不會提示「源目錄已消失」。

不要跳過 pnpm install。本地目錄通過 link: 安裝時，依賴從插件自己的目錄解析，且不會自動裝 peerDependencies，必須靠 pnpm install –prod 才能讓 lib/index.js 找到它們。

驗證是否生效¶

提示注入插件沒有按鈕可點，需要從提示內容反查：

1. 查已註冊段落：調用 Config 的 listConfigs，input.name 填 dsh-agent-team-playbook。
2. 看插件行的 application 字段：applied 纔算真正激活；overridden 表示被更高優先級層覆蓋，restart-required 表示尚未生效。
3. 會話裏端到端確認：新開會話後讓 agent 複述「Agent Teams 有幾條操作規則」，應答出上表六條。

需要說明的限制：段落已註冊不等於用戶一定看到預期文本，渲染效果取決於提示組裝，本倉庫不含自動化斷言。

實戰細節：什麼時候該用 Team¶

Agent Teams 有固定成本（名額不可回收、消息開銷、共享 cwd 的寫衝突風險），不是免費的並行，所以先做判斷，再召人。

任務能否拆成 2+ 個互不依賴、可並行的子問題？如果是，再看子問題之間是否需要共享決策或中途對齊：不需要就各自獨立跑完再彙總，Team 是好選擇；需要連續高頻對齊就消息開銷大於並行收益，改用單 agent 串行；只在關鍵節點對齊則 Team 可行，用共享任務板表達依賴，而不是消息轟炸。

額外否決條件，任一命中就不要用 Team：子任務會寫同一批文件；子任務需要跑同一份構建或測試且互相干擾；任務總量小到協調成本佔主導；已經用滿名額且無可複用的閒置成員。

名額與角色，這是最容易踩的坑。默認上限 16 個 teammate，當前 profile 配置爲 8 個；lead 不計入該上限；state.members 數組裏只有 teammate；名冊沒有刪除機制，名額不可回收；名字全會話唯一。所以先規劃 roster，再召人。

寫作用域是提示不是鎖。重疊只報 warning，不阻止寫入，沒有文件鎖，併發必須按目錄切分；多個 agent 改同一個文件必然衝突。

派活與順序。隊友默認 fresh context，所以派活必須自帶完整上下文。blocked_by 是唯一強制的順序機制，文本狀態標籤不可強制、不可篩選。

狀態解讀與報告。inactive 不等於完成，send_message 成功不等於對方已處理；只報告已驗證的結果，不能因爲隊友說成功就認爲成功。

配置¶

適用場景與注意事項¶

適合：多角度調研最後彙總成文檔、按目錄切分的大規模機械改造、一邊調研一邊實現並用任務板表達階段依賴、對抗式驗證。不適合：單個 bug 的診斷修復、需要頻繁對齊的設計工作、多個 agent 改同一個文件、需要精確順序的數據庫遷移。

插件以當前 DSH 進程權限運行，且不新增工具、不改運行時行爲。安裝前應檢查倉庫源碼與許可證：package.json 標註 license MIT，版本 0.1.0，packageManager 爲 pnpm@10.32.1。

結尾¶

這個插件的價值不在於加新能力，而在於把踩坑成本前置：在 agent 動手之前，把「名額不可回收」「寫作用域是提示不是鎖」「隊友是 fresh context」這些沒有報錯的約束說清楚。規則只有六條，約束的卻是 Agent Teams 最容易出問題的地方。

• 目錄頁：https://www.skillhub.cn/plugins/elfgzp/dsh-agent-team-playbook
• GitHub：https://github.com/elfgzp/dsh-agent-team-playbook