dsh-plugin-product-subagents
English | 简体中文
面向 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)。
- 至少一个产品 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=<childId>配置
config:
providers: { cursor: { type: acp, command: agent, args: [acp] } }
idleTimeoutMs: 600000 # 结算后的子代理闲置超过此时长则释放远程会话(0 禁用)
maxConcurrentChildren: 8 # 同时存在的连续式子代理上限
rolesDir: <path> # 声明式角色库目录(默认 roles/)
registryPath: <path> # 持久化远程会话注册表角色与权限
每个角色文件:
{
"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](docs/ARCHITECTURE.md)。CI 在 macOS / Ubuntu / Windows × Node 18/20/22 上跑测试套件。
安全
这是配置即信任边界的工具:它会启动你配置的任何 CLI,full 会传递产品自己的"绕过所有权限检查"标志。见 [SECURITY.md](SECURITY.md)。
License
MIT