dsh-custom-subagents

为 DeepSeek Harness(DSH)提供的自定义子 Agent 插件:把常用的专业角色——比如「代码审查员」「文档撰写」「网络调研」——保存成一份可复用的子 Agent 定义,之后主 Agent 随时可以用一个 delegate_agent 工具把它们叫出来干活。

不需要写代码,也不需要了解 DSH 的内部机制:所有操作都在 设置 → 子 Agent 页面完成,创建专业子 Agent 的感觉就像填写一张简短的表单。

它能做什么

• 一次定义,反复使用。为每个角色设置名称、描述、系统 Prompt、模型、上下文和工具,保存后主 Agent 可以反复委派同一个角色。
• 直接勾选工具,所见即所得。勾选 read、glob/grep、write/edit、Shell (bash / pwsh)、web_search、skill 等原始工具名,勾什么给什么,不会配错;或选择「继承父 Agent 工具」直接用父会话的工具。
• 和 DSH 原生子 Agent 一模一样。委派出来的实例出现在现有的子 Agent 树里,照常查看转录、继续执行、中断,行为和内置子 Agent 一致。
• 安全边界清晰。子 Agent 能用的工具永远不会超出主 Agent 自己有的工具;平台的安全、沙箱、审批保护也不会被自定义 Prompt 移除。
• 改配置不影响运行中的任务。编辑或删除定义只影响未来的委派,正在运行和已经完成的子 Agent 不受影响。

安装要求

• DeepSeek Harness 0.1.0-rc.7(npm latest 默认版本)
• Node.js 20 或更高版本

版本说明:本项目当前正式支持 DSH 0.1.0-rc.7(npm latest 默认版本)。0.1.0-rc.8 目前位于 npm next 通道,官方安装链(缺少 cordis-plugin-group 依赖)尚未稳定,待官方修复并完成验证后会另行支持。npm 上已发布的 dsh-custom-subagents@0.1.0 仍依赖 rc.8,在 rc.7 环境下请勿直接安装,改用下方的 tarball 方式。

安装

当前建议用 tarball 安装。 npm 上已发布的 0.1.0 仍依赖 DSH rc.8,与 rc.7 宿主混装会出问题;含 rc.7 适配的新版本尚未发布。等新版本发布后,可直接用下方的 registry 命令。

web 是什么? 它是 DSH 的配置档案(profile)名,dsh web 就是 dsh --profile web 的别名。如果你平时用 dsh web 启动,这里就是 web;其他可用名字可在 ~/.dsh/profiles/ 目录下查看。

从本地安装包安装(当前推荐)

dsh plugin --profile web add ./dsh-custom-subagents-<版本>.tgz

从 npm registry 安装(新版本发布后可用)

dsh plugin --profile web add dsh-custom-subagents

安装后开箱即用:根 Agent 立刻获得 delegate_agent 工具,不需要手工配置、软链或复制任何文件,你的默认 Agent Preset 也不会被改动。从 Git 源安装需要额外允许包的构建脚本,建议优先使用 tarball。

快速上手

1. 打开 设置 → 子 Agent,点击 新建。

2. 填写表单:名称、描述和系统 Prompt 是必填项;模型、上下文、工具都有安全的默认值,可以先不改。

3. 点击 保存,然后在对话里直接吩咐主 Agent,例如:

   用「代码审查员」检查一下 src/ 最近改动的代码。

   主 Agent 会通过 delegate_agent 工具找到你保存的定义,创建一个对应的子 Agent 来执行任务。

表单字段说明

字段	含义
名称	角色的名字,主 Agent 靠它来认人。必须唯一。
描述	写给主 Agent 看的「什么时候该用我」。例如:「在需要检查代码正确性、安全性和可维护性时使用」。
系统 Prompt	角色的身份与工作方式,例如「你是一名细心的代码审查员」。DSH 的安全指令不受影响。
模型	默认 父模型:和主 Agent 用同一个模型,无需额外配置;也可以指定 DSH 里其他已配置的模型。
上下文来源	全新上下文:子 Agent 从空白开始,互不干扰;继承对话:子 Agent 能看到父对话中已完成的内容,适合接着之前的讨论往下做。
可用模式	标准模式始终可用(不可取消);高级用户可额外勾选 PTC 模式、创造模式。
工具	二选一:继承父 Agent 工具(默认),或自定义可用工具(按需勾选下面的能力)。

工具能力一览

勾选项	含义
read	读取文件
glob / grep	查找文件、搜索文件内容
write / edit	创建和修改文件
Shell (bash / pwsh)	运行命令(Windows 上自动使用 PowerShell)
web_search	联网搜索
skill	使用技能

小提示:子 Agent 能用的工具永远不会超过主 Agent 自己拥有的工具;如果父会话里没有定义勾选的某个工具,委派会明确失败,而不是偷偷少给。

列表页的常用操作

• 禁止嵌套委派(页面顶部的全局开关,默认关闭):开启后,子 Agent 不能再创建新的子 Agent,只有根 Agent 可以。改动即时生效,重启后保持。
• 每行右侧的开关可以单独启用/禁用某个定义:被禁用的定义仍保留在列表里,但主 Agent 不会再拿它来委派。
• 每行的 复制 可以基于已有定义快速创建变体,会自动给出一个不冲突的新名称。

升级与卸载

# 升级(tarball:再次 add 新版本即可,已保存的定义和「禁止嵌套委派」设置都会保留)
dsh plugin --profile web add ./dsh-custom-subagents-<新版本>.tgz

# 卸载(清理插件产生的全部内容,不影响其他插件)
dsh plugin --profile web remove dsh-custom-subagents

常见问题

• 保存时提示「重新加载后重试」? 页面上的数据已过期(例如另一个浏览器标签页改过配置),点击列表页的刷新入口重试即可,不需要重启 DSH。
• 委派失败,提示某个工具不可用? 自定义工具是「全有或全无」:父 Agent 当前会话缺少定义里勾选的某个工具时,这次委派会明确失败。
• 后台执行不可用? 后台运行只支持标准模式,其他模式下请使用前台委派。
• 删除定义会破坏历史记录吗? 不会。已创建的实例继续正常运行,删除只影响未来的委派,而且删除前会弹窗确认。
• 改名会丢引用吗? 不会。每个定义都有稳定的隐藏身份,改名只影响显示,不影响已保存的引用。
• 装完发现环境里混了 rc.8 的依赖? 通常是因为装到了 npm 上的旧版 0.1.0(依赖 DSH rc.8)。先用 dsh plugin --profile web remove dsh-custom-subagents 卸载清理,再按本文档改用 tarball 安装 rc.7 版。

面向开发者

架构、设计决策与测试说明见 docs/specs/ 与 CONTEXT.md。