前言¶
在 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 / 幻方无官方从属关系。
