前言¶
DSH 的理念是「一切皆插件」，多智能體協作一開始並沒有統一的角色層。手工做法是：在宿主裏寫若干 subagent bundle，各自配好提示詞、模型和工具，再讓主代理按需 spawn。問題在於角色定義散落在各個工具配置裏，改一次模型或提示詞都要翻配置；組件之間也沒有統一的角色目錄和運行記錄。
下面介紹的插件是社區作者 Delthin 維護的 dsh-agent-roles。它在 DSH Web 左側提供「多智能體」入口，讓用戶用界面維護角色模板（職責提示詞、模型與思考強度、工具白名單、Skills），再由主代理通過原生 Agent Team 接口創建成員、分發任務和繼續對話，不需要預設固定工作流。插件配合 DSH Web 0.2.1-rc.5 及以上使用，當前版本 0.4.0。
定位¶
一句話：這是一個角色管理插件，爲 DeepSeek Harness Web 提供角色目錄界面，並基於 DSH 原生 Agent Team 接口創建成員和繼續對話。
插件裏有兩個核心概念。角色（Role） 是可複用的配置模板，保存職責提示詞、模型與思考強度、工具白名單和 Skills。成員（Member） 是主代理按角色啓動的具體運行實例。主代理在會話中能看到所有已啓用角色的職責、模型和已選 Skills，並判斷當前任務是否調用 spawn_role 創建成員。
倉庫頁還給出了遷移說明：後續源碼開發和維護遷入 Delthin/dsh-plugins monorepo 下的作用域包 @delthin/dsh-agent-roles，舊倉庫保留用於查閱歷史提交與早期版本記錄。安裝時需要注意當前源碼採用 Apache-2.0 許可證，歷史版本 <= 0.4.0 已授予的 MIT 許可不撤回。作者在社區目錄的收錄信息顯示星標爲 0，屬於早期項目。
環境與安裝¶
安裝前確認三件事：Node.js 22.18+、DSH Web 0.2.1-rc.5 及以上、至少一個已配置的模型供應商。底層 Agent Team 接口仍處於實驗階段。
安裝的 v0.4.0 通過 GitHub Release 歸檔：
dsh plugin --profile web add https://github.com/Delthin/dsh-agent-roles/releases/download/v0.4.0/dsh-agent-roles-0.4.0.tgz
如果對應版本已在 npm 發佈，也可以執行：
dsh plugin --profile web add dsh-agent-roles@0.4.0
安裝前可以先覈對 npm 可用性：
npm view dsh-agent-roles@0.4.0 version
安裝過程無需編譯，也不執行安裝腳本。裝完刷新 DSH Web 頁面，左側導航欄會出現「多智能體」入口；如果宿主沒有自動加載，重啓對應的 Web profile。插件市場收錄獨立於上面兩種安裝方式。
安裝會改到什麼¶
插件 bundle 會啓用 DSH 原生團隊服務、團隊工具與界面，並停用舊的 tool-subagent、tool-subagent-fork、tool-subagent-control、tool-subagent-list-agents 條目，切換方式與官方實驗團隊 profile 一致。如果當前環境已經有自定義團隊 bundle，需要檢查是否存在相同 ID 的配置覆蓋。
首次安裝得到空角色目錄，不包含作者的角色、提示詞或運行記錄；從舊版升級會保留本地數據。
創建角色¶
先從創建角色開始。在左側打開「多智能體 → 角色 → 新增角色」，按下面幾步填：
- 填顯示名稱、分發名稱（小寫字母、數字、連字符，如
reviewer）和職責描述。職責描述用來供主代理判斷何時選用該角色。 - 爲該角色選擇模型供應商、具體模型和思考強度。
- 在「提示詞」中寫清角色職責、工作邊界和交付標準；在「工具」中只勾選該角色必需的工具白名單。
- 在「技能」中搜索並勾選 DSH 已發現的 Skills。默認爲空，不自動繼承全局技能目錄。
- 把角色設爲啓用並保存。
任務分發與協作¶
角色啓用後，直接在主會話裏向主代理描述任務。README 給的例子是配置了只讀審閱角色 reviewer 之後，對主代理說：
請把這份改動交給 reviewer 審閱，要求指出有依據的問題；你彙總結果並決定如何處理。
運行機制有幾點值得注意。主代理通過 spawn_role({role, name, prompt}) 啓動成員，底層走原生 agentTeams.spawnTeammate。成員啓動時會保存當時的角色提示詞、模型設置和 Skills 正文快照，之後修改或刪除角色不影響已創建的成員。成員在獨立的全新會話中啓動，不繼承主代理的上下文歷史，所以任務背景和材料必須寫在 prompt 裏。需要追問時，主代理可以用原生 send_message 繼續和同一成員實例溝通。
成員的工具白名單不含遞歸委派工具，成員之間也不能主動互相通信。任務拆解、結果彙總和跨成員協調全部由主代理負責，並依靠 list_agents、send_message、interrupt_agent、wait_agent 這組接口管理。其中 list_agents 查詢的是當前已創建的成員實例，不是角色目錄。
成員狀態顯示 inactive 只代表當前沒有正在執行的回合，不代表任務成功完成，結論和錯誤要看成員輸出內容。在成員記錄的「請求詳情」中，插件會記錄實際發出的模型、思考強度與工具列表，並覈對 DSH 基礎系統提示詞、角色提示詞原文以及所選技能正文是否完整加載。DSH 0.2.1-rc.5 原生成員列表的模型字段可能保留父會話描述，實際路由以「請求詳情」爲準。
Skills 的加載與溝通成本¶
新建和已有角色默認 skills: []。勾選 Skills 後，插件在啓動成員時通過 DSH 原生技能服務讀取內容，以原生 <skill_content> 格式（含資源基目錄與字面正文）完整注入新成員的系統提示詞。即使角色不勾選任何工具，也能接收所選 Skills 的指令。
需要注意兩點。Skills 只提供文本指令，不會自動賦予工具權限，技能依賴的外部命令、軟件仍要在宿主和工具白名單裏另外配。若所選技能在啓動時不可用，成員啓動直接失敗並報告缺失的技能名稱，恢復或取消勾選後可重試。
溝通成本方面，勾選的 Skills 完整正文計入成員會話輸入，所以建議只爲角色勾選必要的 Skills。簡單直接的任務由主代理直接完成即可，不必拆成多智能體協作。
數據存儲與配置¶
默認數據目錄爲 $DSH_HOME/agent-roles，未設置 DSH_HOME 時爲 ~/.dsh/agent-roles。目錄裏兩個文件：roles.json 保存角色目錄、結構版本號和目錄修訂號；runs.json 保存成員啓動快照、所選技能正文、請求加載校驗結果，以及最多 30,000 字符的最近輸出摘要。完整對話歷史仍由 DSH 原生會話存儲保存。
自定義數據目錄或啓用可選的供應商 Fast 開關，改當前 profile 的 cordis.patch.yml：
- id: agent-roles
config:
dataDir: ~/my-dsh-data/agent-roles
fastProviders: []
dataDir 支持絕對路徑、~ 和相對當前進程工作目錄的路徑，建議用絕對路徑。當前文件存儲不提供跨進程寫鎖，多個獨立運行的 DSH 進程應配置不同的 dataDir。
公開包默認 fastProviders: []，模型選擇器旁的 Fast 按鈕不可啓用。插件只記錄 Fast/標準模式選擇，不內置特定供應商的 priority 傳輸實現；只有環境中已裝好對應傳輸適配且能讀取角色啓動快照時，才把供應商 ID 加入 fastProviders。啓用 priority 傳輸可能改變供應商側的計費標準。
限制主代理可委派的模型¶
在「多智能體 → 設置」裏可以加規則：選擇主代理模型，勾選禁止的子代理模型，保存後立即生效。模型選項來自 DSH 已配置目錄，默認沒有規則。也可以用通用 delegationRules，下面是 README 示例 ID，替換成自己的模型 ID：
- id: agent-roles
config:
delegationRules:
- leaderModel: lead-model-id
denyModels:
- blocked-member-model-id
模型 ID 精確匹配，不區分供應商。策略按主代理當前請求的模型執行，切換模型後下一輪隨之變化。角色目錄會隱藏被禁止的角色，工具調用在啓動前拒絕。受限制的主代理必須使用 spawn_role，通用委派工具也會被攔截；向已有禁止模型成員發消息同樣拒絕。已經運行的成員不會被自動中斷。
運行限制與安全邊界¶
- 單個團隊最多 32 個已創建成員、256 個共享任務。併發數和委派深度受 DSH 原生 subagent 配置約束；宿主把委派深度設爲
0時需先在宿主配置裏允許委派。插件不會越權修改全局配額或系統權限。 - 插件通過原生
agent/created鉤子在成員首個請求發出前掛載模型路由、系統提示詞與工具白名單守衛，不接管或替換 DSH 原生模型執行循環。角色管理 API 複用 DSH Web 連接服務的身份驗證，拒絕未認證請求。 - 角色工具白名單隻約束模型可調用的工具集，不是操作系統級文件或目錄沙箱，具體文件讀寫和命令執行仍受 DSH 全局權限與文件策略控制。插件代碼運行在宿主進程權限下，請勿把同一個已登錄的 DSH Web 會話暴露給不可信用戶。
runs.json中的成員快照包含提示詞、技能全文和輸出摘要，備份時按私人敏感數據保護。卸載插件不會刪除數據目錄，刪除角色也不清理已生成的運行記錄。運行記錄目前不自動過期，列表 API 默認返回最近 200 條。
適用場景與注意¶
適合需要在 DSH Web 裏管理多個具有不同模型、工具組合的協作角色（如審閱、檢索、代碼生成各一個角色），同時希望主代理按需決定調用誰的開發者和小團隊。角色目錄集中維護後，改提示詞、換模型、加技能都在界面裏完成，不必逐個編輯 bundle。
安裝前建議先讀源碼和許可證。插件以當前 DSH 進程權限運行，會禁用舊的 subagent 工具條目，也會在角色成員啓動時向系統提示詞注入 Skills 正文；請結合自己的權限與文件策略評估。也要留意倉庫遷移狀態：後續維護在 Delthin/dsh-plugins，舊倉庫不接收新開發。
小結¶
dsh-agent-roles 的價值在於把「角色」變成可維護的配置模板，並複用 DSH 原生 Agent Team 接口：角色管職責和模型，成員是按需創建的運行實例，協調仍由主代理集中承擔。對想在 Web 界面裏做多智能體分工的人來說，它比手工配 subagent 少了重複勞動。
- 社區目錄頁：https://www.skillhub.cn/plugins/Delthin/dsh-agent-roles
- GitHub：https://github.com/Delthin/dsh-agent-roles
