shaokeyibb/dsh-plugin-product-subagents

dsh-plugin-product-subagents

面向 DeepSeek Harness 的基于角色的 Codex / Claude Code / ACP 子代理插件。把外部 Agent CLI 变成持久、可续聊的子代理:声明式角色库、按角色的产品权限、带权限天花板的委派、跨平台进程启动。

功能

- 可续聊子代理 — 同步 one-shot 或异步连续式(用 send_message / list_agents / interrupt_agent 控制;用 product_wait 同步 attach)。
- 会话连续性 — 子代理的远程产品会话在空闲释放与进程重启后仍可恢复(持久注册表 + 日志标记;claude/codex 按 id 恢复,ACP 重连)。
- 声明式角色(roles/*.json)— general(默认)、code-review、explore(禁派)、debug。委派默认开启,角色可显式禁止;未知角色回退 general。
- 两层权限模型 — 中继模型永远是只读传话筒;permissionMode(readonly / default / full)作用于远程产品,映射到各产品自己的 CLI 标志。
- 权限天花板 — 子代理不能派生出比自己权限更高的后代。
- 任意 ACP Agent — 通过 config.providers 加 Cursor(agent acp)、CodeBuddy(cbc --acp)、Gemini(gemini --acp)等,零代码。
- 资源管理 — 空闲释放、可配超时、并发上限。
- 跨平台 — Windows .cmd 垫片、Windows 安全路径转义;CI 覆盖 macOS / Ubuntu / Windows。

环境要求

- DeepSeek Harness 部署(web profile)。从 0.0.1-rc.5 到当前 0.1.5-rc.1 之间
每一个可安装的 @deepseek-ai/dsh 发行版都已验证 —— 见兼容性。
- 至少一个产品 CLI 在 PATH 且已登录:claude、codex,或某个 ACP CLI(opencode、agent、cbc…)。
- Node ≥ 18。

安装

推荐方式 — dsh plugin add

dsh plugin --profile web add dsh-plugin-product-subagents

这一条命令同时完成装包与接线:插件通过 package.json 里的 dsh.bundle
声明自带 cordis.patch.yml,dsh plugin add 会自动将其注册为 profile 层
(无需手动编辑 cordis.patch.yml)。装完后重启 harness 即可生效。

如需自定义插件配置(例如加 ACP provider),在 profile 自己的
cordis.patch.yml(~/.dsh/profiles/web/cordis.patch.yml)里按
product-subagents id 覆盖:

- id: product-subagents
config:
idleTimeoutMs: 600000
providers:
cursor:    { type: acp, command: agent, args: [acp] }
codebuddy: { type: acp, command: cbc, args: [--acp] }

注意: config 覆盖会替换整行 config 对象,请把要保留的字段一并写上
(如上面的 idleTimeoutMs)。

让 Agent 安装(一句话)

把这句粘贴给你的 DeepSeek Harness Agent(或任何有 shell 权限的编码 Agent),
它会自己完成所有步骤:

请把 dsh-plugin-product-subagents 插件装进我的 DeepSeek Harness
web profile:执行 dsh plugin --profile web add dsh-plugin-product-subagents,
然后提醒我重启 harness 让插件生效。

手动安装(进阶)

如果你希望自己管理 profile,请在 profile 目录内使用 pnpm(不要用 npm),
以避免 peer 依赖被自动安装:

cd ~/.dsh/profiles/web
pnpm add dsh-plugin-product-subagents

然后在 profile 的 cordis.patch.yml 加一行宿主层:

- insert:
- id: product-subagents
name: 'dsh-plugin-product-subagents'
config:
idleTimeoutMs: 600000
providers:
cursor:    { type: acp, command: agent, args: [acp] }
codebuddy: { type: acp, command: cbc, args: [--acp] }

快速开始

会话中的模型有六个工具:

| 工具 | 用途 |
|---|---|
| product_delegate | 按角色委派任务(同步或连续式) |
| product_roles | 列出角色库 |
| product_submit | 子代理内部桥(仅连续式子代理) |
| subagent_progress | 单个子代理的状态 + 内部 trace |
| product_wait | 阻塞直到子代理结算,返回答案 |
| product_agents | Provider 可用性 + 活跃子代理 |

product_delegate role=general task="重构 demo-project/calc.js 并运行测试"
product_wait subagent_id=

配置

config:
providers: { cursor: { type: acp, command: agent, args: [acp] } }
idleTimeoutMs: 600000       # 结算后的子代理闲置超过此时长则释放远程会话(0 禁用)
maxConcurrentChildren: 8    # 同时存在的连续式子代理上限
rolesDir:             # 声明式角色库目录(默认 roles/)
registryPath:         # 持久化远程会话注册表
providerNamespace: product-subagents
注册到 ctx.subagents 的 id 命名空间;
设为 '' 则注册裸 key

Provider id

claude-code、codex、acp(以及任何 config.providers 的 key)仍然是你在角色和
product_delegate 里使用的名字 —— 但它们同时也是官方
@deepseek-ai/dsh-subagent-claude-code / -codex / -acp 插件注册用的 id,而 harness 对重复的
provider id 会直接报错,并且这个报错会让整个 Profile 的插件树在启动时加载失败。

因此本插件注册到 ctx.subagents 上的是带命名空间的、插件自有的 id ——
product-subagents:claude-code 等 —— 两个插件可以共存于同一个 Profile。这只改变 harness 全局
subagent 工具里看到的 provider 名字,本插件自己的接口没有任何变化。若要恢复裸 key,设置
providerNamespace: ''(仅在没有加载官方产品子代理插件时才安全)。

角色与权限

每个角色文件:

{
"id": "code-review",
"description": "审查代码的缺陷、安全与可维护性(只读)。",
"provider": "claude-code",
"permissionMode": "readonly",
"allowDelegation": true,
"instructions": "你是代码审查员。只读:绝不修改文件。…"
}

- permissionMode 映射到产品标志:readonly(claude --permission-mode plan / codex --sandbox read-only)、full(claude --dangerously-skip-permissions / codex --dangerously-bypass-approvals-and-sandbox)。
- 中继模型任何角色都拿不到可写工具。
- 委派有天花板:readonly < default < full;子代理不能派生出权限更高的后代。

自定义 ACP Provider

config.providers 接受任意讲 ACP 的 CLI —— 通用桥负责持久进程、session/load 恢复与死进程重连:

providers:
cursor:    { type: acp, command: agent, args: [acp] }    # Cursor CLI
codebuddy: { type: acp, command: cbc, args: [--acp] }    # CodeBuddy
gemini:    { type: acp, command: gemini, args: [--acp] } # Gemini CLI
opencode:  { type: acp, command: opencode, args: [acp] } # opencode

只有命令在 PATH 上被检测到,Provider 才会出现在委派枚举里。内置三件套(claude-code / codex / acp)可用同名键覆盖。

开发

npm install
npm test        # node:test — 纯逻辑 + fake bridge,不需要 CLI 或密钥
npm run lint    # 语法检查所有模块

桥契约、权限模型与新增产品的方式见 docs/ARCHITECTURE.md。CI 在 macOS / Ubuntu / Windows × Node 18/20/22 上跑测试套件。

兼容性

package.json 的 dsh.compatibility 声明支持的 DSH 范围,以及 dshReleases —— 逐个发行版的
compatible / incompatible / unknown 结论。每个 compatible 都由一次一次性 Profile
的验收运行支撑,而不是只靠版本范围:

node scripts/verify-dsh-profile.mjs --dsh 0.1.5-alpha.2

对一个 DSH 发行版,它会创建一次性的 $DSH_HOME,用真实的 dsh plugin add 安装打包好的
tarball,检查组合出的 Profile 树,启动 Profile 并在运行中的 harness 内部断言:六个工具全部注册、
Provider 确实进入了真实的 SubagentRuntime、工具能执行并通过输出 schema 校验;随后卸载并确认
Bundle 层已经消失。整个过程不需要 API key,也不属于 npm test。

记录下来的矩阵、以及一次验收能证明与不能证明什么,见
docs/COMPATIBILITY.md。

安全

这是配置即信任边界的工具:它会启动你配置的任何 CLI,full 会传递产品自己的"绕过所有权限检查"标志。见 SECURITY.md。

License

MIT