前言¶
在 DeepSeek Harness (DSH) 的生態中，通過多個智能體協作處理複雜任務時，常面臨角色漂移、交接過程無法驗證以及死鎖等問題。dsh-swarm 是一個 DSH 插件，旨在將這些協作轉化爲嚴格的、有證據驗證的交付管線。它將一個需求轉化爲一個嚴格排序的階段鏈，由六個專職角色分別執行，並通過可視化的看板提供實時狀態與交付證據。
安裝與前置條件¶
該插件由 joekytc 維護，遵循 MIT 許可證。安裝前請確保環境滿足以下要求：
- DSH 運行時：
@deepseek-ai/*系列 - Node.js 版本：≥ 22.19
- npm 包管理器
安裝命令如下：
dsh plugin --profile web add @joekytc/dsh-swarm
如果從源碼安裝，需先執行構建：
npm install
npm run build
dsh plugin --profile web add .
核心功能¶
dsh-swarm 提供了一套完整的流程控制機制，核心特性包括：
- 蜂羣模式（推薦）：主會話轉化爲只讀的“團隊負責人”，通過自然語言接收需求、澄清、規劃和執行。
- 自動意圖識別：根據自然語言輸入判斷意圖（開發請求、復盤、羣通知或閒聊），無需記憶特定命令前綴。
- 確認門控：在管線啓動前，系統會保存檢查清單，需用戶回覆明確確認詞（如“確認”、“開幹”、“go”等）後纔會開始執行，防止誤觸。
- 可視化看板：通過 Conversation -> Trajectory -> Kanban 路徑，實時流式展示管線狀態。
- 機器驗證的證據：每個階段交接均需攜帶結構化證據，完成後的交付經過機器驗證。
- 權限隔離：編排器（Lead）爲只讀，無法直接操作倉庫源碼或執行 git 變更，代碼編寫由執行者（D）在隔離工作區完成。
角色與流程¶
系統定義了六個單職責任的角色，通過權限矩陣和工具面限制，確保職責邊界清晰。管線流程爲：p -> (pt?) -> w2 -> d -> dt -> w3 -> summary。
| 角色 | 職責 | 禁止操作 |
|---|---|---|
| V (Orchestrator) | 創建階段卡片，驅動管線，處理阻塞 | 執行 |
| P (Planner) | 讀取規範與倉庫事實，編寫實施計劃 | 寫代碼 |
| PT (Plan Reviewer) | 僅對 P 的計劃進行只讀審查 | 修改 |
| W (Knowledge Officer) | 在規劃與完成階段同步知識庫 | 觸碰代碼/Git |
| D (Executor) | 唯一編寫代碼的角色，實施、驗證、提交功能分支 | 合併到目標分支 |
| DT (Implementation Reviewer) | 依據測試、構建、類型檢查或 Diff 驗證 D 的交付 | 對倉庫只讀 |
使用方法¶
使用蜂羣模式時，交互流程如下：
- 陳述需求：直接用自然語言描述需求，例如：“爲管理後臺添加一個角色管理頁面，包含 CRUD 和權限複選框”。
- 確認執行：編排器會進行澄清（如字段定義、權限來源等），列出檢查清單。用戶回覆“確認”或“開幹”後，管線啓動。
- 實時查詢：任何時候詢問“進展如何？”，編排器會從看板中查詢真實狀態並反饋，而非編造回覆。
- 交付通知：完成後，可使用
/sms意圖進行交付（如“將當前進度發到羣裏”），系統會基於看板事實生成彙報內容。
注意事項¶
- 權限限制：主會話（Lead）角色被設計爲只讀，不能修改倉庫源碼或運行 git mutations（如 push/commit）。代碼提交由 D 角色完成。
- 完成門檻：管線完成需要經過審計確認。對於 D 鏈路，系統會自動合併功能分支，但需在 GUI 中確認所有權後纔會執行最終收尾，審計警告會阻塞最終打包。
- 環境依賴：確保 DSH 運行時、Node.js 和 npm 版本符合要求。
