前言¶
在 DSH 裏把任務拆給子代理執行後，有兩個問題經常出現：一是子代理在後臺跑，主會話裏看不到它們什麼時候啓動、什麼時候結束、進行到哪一步；二是想讓代碼審查、翻譯這類固定任務固定走某個模型和某套提示詞，只能在每次委派時手動拼 prompt。
已有的社區插件各自解決一半：dsh-subagent-monitor 提供即時監控面板，但不涉及角色與路由；dsh-plugin-subagent-director 提供角色委派，但角色只能寫在 settings 裏。本文介紹的 dsh-subagent-pro 把兩條線合併進一個插件，並補上了 Claude Code 風格的 .dsh/agents/*.md 角色定義，讓角色可以按項目放在文件裏管理。
下面按功能、安裝、典型用法的順序介紹。
這是什麼¶
dsh-subagent-pro 是 hyperion2144 維護的 DeepSeek Harness Web 擴展插件，當前版本 0.1.0，MIT 許可。一句話定位：即時子代理監控 + 角色路由委派 + agent md 角色注入。
它遵循零侵入原則：未配置任何角色與默認模型時，行爲與未安裝本插件完全一致。因此可以先裝上只用監控面板，之後再逐步加角色。
核心功能¶
即時子代理面板¶
插件監聽 subagent/start 與 subagent/end 事件，按父鏈歸因到根會話，每個根會話最多保留 200 條。瀏覽器每 1 秒輪詢一次快照接口 /api/dsh-subagent-pro/snapshot，狀態點對齊官方 StateDot 規格。
HUD 風格圖標按鈕¶
插件裝載後，會在會話輸入區左側（conversation.input.left slot）注入一枚 28×28 的線性 SVG 圖標按鈕；有運行中的子代理時，右上角以 warn-yellow 角標顯示數量。點擊圖標即可打開監控面板。
角色路由委派¶
插件註冊 subagent_role 工具，解析模型與提示詞時按四層回退：call > role > default > inherit。命中角色後，persona 與 toolFilter 會注入到 SubagentStartRequest。執行模式有三種：foreground、one-shot 後臺、continuable 後臺。
模型自省¶
插件註冊 subagent_providers 工具，主代理可以主動查詢當前 llm 服務暴露的 provider、model、reasoning-effort 列表，在不確定有哪些模型可用時先查再委派，不必硬編碼模型名。llm 服務不可用時，該工具返回空數組而不是拋錯。
默認模型兜底¶
配置 defaultProvider / defaultModel 後，所有未顯式指定 agentOptions 的子代理——包括內置的 subagent / subagent_fork 工具——都會自動應用默認模型；指定的 provider 不存在時，靜默回退到父模型。
Claude Code 風格 agent md¶
插件自動掃描 ~/.dsh/agents/*.md（全局）與 <cwd>/.dsh/agents/*.md（項目）兩處目錄，frontmatter 字段映射到 RoleTemplate，正文作爲 persona 注入子代理。角色優先級爲 project md > global md > settings.roles，三者並存時主代理指引會列出全部。
設置面板與熱更新¶
插件通過 settings.section slot 在設置面板暴露 Subagent Pro 分組：默認委派配置與 settings 角色的增刪改；md 定義的角色只讀展示，並標註 project-md / global-md 來源。settings.yaml 與設置面板的改動即時生效，無需重啓；agent md 在 settings/change 時重新掃描。
安裝與啓用¶
插件尚未發佈到 npm，dsh plugin add dsh-subagent-pro（按包名安裝）目前不可用，需要用 GitHub 路徑安裝並 tie 到 tag：
dsh plugin --profile <name> add github:hyperion2144/dsh-subagent-pro#v0.1.0
首次安裝前，先在目標 profile 的 pnpm-workspace.yaml 里加一條 allowBuilds——pnpm 11 的供應鏈保護要求 git 依賴顯式允許構建腳本，否則 prepare 鉤子不會執行。注意 key 不是包名，而是精確的 codeload URL（含 commit sha，每次發佈後都會變化），直接複製報錯提示裏的那一行即可：
# ~/.dsh/profiles/<name>/pnpm-workspace.yaml（示例；實際 key 以報錯提示爲準）
allowBuilds:
"dsh-subagent-pro@https://codeload.github.com/hyperion2144/dsh-subagent-pro/tar.gz/<commit-sha>": true
加好後再重新執行安裝命令。構建方面：lib/ 不在版本庫裏，prepare 鉤子會在安裝時自動構建，github: / npm / tgz 方式都會觸發；如果用 link:./ 引用本地倉庫，prepare 不會執行，需要先在倉庫裏手動跑 pnpm build。
插件是單一 bundle entry（dsh-subagent-pro），自動掛載 host 半 + client 半，不需要手寫 cordis.patch.yml。裝載後輸入區左側出現圖標按鈕，監控面板即可使用。
如需覆蓋默認配置，在插件清單裏按 id 覆蓋主條目：
- id: dsh-subagent-pro
name: dsh-subagent-pro
config:
subagentProvider: spawn
toolName: subagent_role
enableRunInBackground: true
backgroundMode: one-shot
maxDepth: 3
applyDefaultRoute: true
典型用法¶
用 agent md 定義角色¶
在 <project>/.dsh/agents/ 或 ~/.dsh/agents/ 下寫一個 md 文件。文件名（去掉 .md）即 role id，必須是 kebab-case；description 必填。例如 <project>/.dsh/agents/code-reviewer.md：
---
name: 代碼審查員
description: 審查代碼質量、安全、可維護性與測試覆蓋
tools: Read Grep Glob
model: sonnet
---
你是嚴謹的代碼審查員。先給結論再給證據，區分阻塞項與建議項；逐條指出問題並給出可操作的修改建議，語氣客觀直接，不吹捧也不刻薄。
保存後主代理會自動加載該角色，正文 persona 注入到子代理的 system prompt。
用 settings.roles 定義角色¶
適合在設置面板裏快速調試。在 Subagent Pro 分組下點「+ 新增角色」，填寫 displayName / description / persona / provider / model / toolFilter；對應的 settings.yaml 配置形如：
subagent-pro:
defaultProvider: opencode-go
defaultModel: minimax-m2.7
roles:
translator:
displayName: 翻譯員
description: 中英互譯技術文檔
persona: 你是專業翻譯...
provider: deepseek-official
model: deepseek-chat
toolFilter:
allow: [Read, Grep]
委派與模型查詢¶
角色就緒後，主代理會自動看到角色清單（系統提示注入），委派時調用 subagent_role：
subagent_role({ role: "code-reviewer", prompt: "審查 src/foo.ts" })
subagent_role({ role: "code-reviewer", model: "deepseek-chat", prompt: "..." })
role 既可以是 agent md 的文件名，也可以是 settings.roles 裏的角色 id。
主代理還可以隨時調用 subagent_providers 查詢可用路由：
subagent_providers({ action: "list_providers" })
subagent_providers({ action: "list_models", provider: "opencode-go" })
subagent_providers({ action: "list_reasoning_efforts", provider: "opencode-go", model: "deepseek-v4-flash" })
三個 action 分別返回 provider、model、reasoning-effort 列表。
與舊插件的關係¶
本插件在實現上深度借鑑了兩個開源項目，README 中有專門的致謝一節：
- dsh-subagent-monitor（@leetoners/dsh-ui-subagent-monitor v0.2.0）：即時面板的事件歸因、浮層面板、HUD 圖標與掛載方式均源自該項目；
- dsh-plugin-subagent-director（v0.2.1）：subagent_role 四層回退、默認模型兜底、settings 命名空間與角色 CRUD 均源自該項目。
如果從舊插件遷移，注意兩點：
1、數據路由不同：本插件的快照接口是 /api/dsh-subagent-pro/snapshot，舊 dsh-subagent-monitor 是 /api/subagent-monitor/snapshot，依賴舊路由的監控腳本需要同步更新。
2、settings 命名空間從 subagent-director 改爲 subagent-pro，遷移說明見倉庫的 ARCHITECTURE §3。
適用場景與注意¶
適合需要同時盯着多個子代理運行狀態、想把審查或翻譯等固定任務綁定到指定模型與人設、或者想在項目裏以文件形式沉澱角色定義的 DSH 用戶。只要監控、不要路由也成立：零侵入設計保證未配置角色與默認模型時與未安裝插件完全一致。
使用前注意幾點：
1、插件以當前 dsh 進程的權限運行，安裝前請先檢查源碼與許可證（MIT）。
2、npm 尚未發佈，按包名安裝不可用；allowBuilds 的 key 含 commit sha，插件每次發佈後都要按報錯提示更新。
3、agent md 文件本身的修改不會觸發 host 重掃，需要在設置面板保存一次（任意字段），或者重啓插件掛載的 DSH 會話。
結尾¶
dsh-subagent-pro 把子代理的即時監控、角色路由與默認模型兜底、agent md 角色沉澱收進一個插件，同時保持了零侵入的底線。如果你在 DSH 裏經常和子代理打交道，值得一試。
- GitHub 倉庫：https://github.com/hyperion2144/dsh-subagent-pro
- 社區目錄頁：https://www.skillhub.cn/plugins/hyperion2144/dsh-subagent-pro
最後說明：社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
