dsh-plugin-product-subagents

一句话定位

把 DeepSeek Harness 之外的 Agent 工具（Claude Code CLI、Codex CLI、以及任何支持 ACP 协议的客户端）接进来当"子代理"用：模型可以按角色把任务丢给它们，让它们独立完成长活，自己这边同时做别的事；中转模型本身被限制成只读，所有真正干活的是被启动起来的外部 CLI。

核心能力

• 按角色派发任务给外部 Agent：内置 general / code-review / explore / debug 四个角色，可用 product_delegate 一句话把活儿派给对应 provider 的 CLI 子代理。
• 子代理会话能续聊：派出去的子代理有持久化的远程会话 ID，多次 product_submit 走的是同一个远端 CLI 上下文，不用每次重新介绍任务背景。
• 跨进程恢复：绑定丢失或 harness 重启后，子代理能凭注册表文件（默认 ~/.dsh/product-subagents-registry.json）或会话日志里的 PRODUCT_SESSION: 标记自动接回原会话。
• 双层权限模型：远端 CLI 跑任务时的权限由角色的 permissionMode（readonly / default / full）控制，而中继模型自身永远只读，永远拿不到写工具。
• 委派权限天花板：子代理不能派生比自己权限更高的后代（readonly < default < full），并发生成时被 product_delegate 直接拒掉。
• 任意 ACP Agent 零代码接入：Cursor (agent acp)、CodeBuddy (cbc --acp)、Gemini (gemini --acp)、opencode 等只要在 PATH 上就能被自动探测并加进 provider 列表。

技术实现

• 语言: JavaScript（纯 ES Module，package.json:5 声明 "type": "module"）
• 关键依赖:
  • @deepseek-ai/dsh-tools（peer）：用 defineTool 注册 6 个 model-facing 工具
  • @deepseek-ai/dsh-subagent（peer）：注册 subagent provider 与 continuation 入口
  • @deepseek-ai/cordis（peer ^4.0.1）：宿主插件框架
  • @agentclientprotocol/sdk（^0.25.0）：通用 ACP 协议 SDK，给 Cursor / opencode / CodeBuddy / Gemini 复用
• 架构模式: 标准 Cordis 插件；通过 package.json#dsh.bundle.patch 自带 cordis.patch.yml，dsh plugin add 时自动作为 profile 层加载；apply() 内部走 provider 注册 → tool 注册 → lifecycle 钩子（subagent/end 排空闲释放、ctx.effect 卸载时全释放）三段式。
• 入口文件: lib/index.js（同时 export name = 'product-subagents'、inject = ['subagents','tools','sessions']，lib/index.js:16-17）

适用场景

希望在一个 DeepSeek Harness 会话里同时调度多个不同 CLI Agent（让 Claude Code 读代码、Codex 跑修复、Cursor 接管 UI 改动），又希望它们之间能交接上下文、不会互相写穿对方的文件；或者想给一个长期任务持续追问、但又不想每次都重新把背景解释给 CLI。普通聊天、写一次性短任务的场景用不到这个插件。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:shaokeyibb/dsh-plugin-product-subagents

配置项

常见问题

Q: 装好之后怎么开始用？

A: 重启 DeepSeek Harness 让插件加载，新会话里模型就会多出 6 个 product_* 工具，最常用的是 product_delegate（按角色派活）和 product_wait（等子代理返回）。要先在 PATH 上准备好至少一个产品 CLI（claude、codex 或 opencode / agent / cbc / gemini 之一）。

Q: 不配置也能用吗？

A: 可以。插件只检测 PATH 上已有的产品 CLI 并自动注册；只装了 Claude Code 就有 claude-code 这个 provider，三件套都不装就什么也跑不起来。要加 Cursor、CodeBuddy 这类自定义 ACP 客户端才需要写 config.providers。

Q: 远程子代理的会话能跨进程恢复吗？

A: 可以。子代理的远程会话 ID 会被三处冗余记录：内存绑定 → 默认 ~/.dsh/product-subagents-registry.json 注册表 → 子会话事件日志里的 PRODUCT_SESSION 标记；空闲释放或重启后下次 product_submit 会按这个顺序恢复，自动接上同一会话。

Q: 子代理可以再派自己的子代理吗？能突破我的权限吗？

A: 默认允许，角色 JSON 里写 allowDelegation: false 就能禁止。权限有天花板：readonly < default < full，子代理不能派生比自己权限更高的后代，调用会被 product_delegate 直接拒绝。

Q: 子代理里的中继模型（relay）会不会偷偷改我文件？

A: 不会。子代理里跑的"中继模型"只看得到 product_submit（必要时再加 product_delegate），永远拿不到 Bash、文件编辑这类写工具；所有实际改文件的工作都被丢给远端 Claude Code / Codex / ACP 进程做，受对应角色 permissionMode 控制。

Q: Windows 上能跑吗？

A: 能。插件在 Windows 下通过 cmd.exe /d /s /c 启动 .cmd 垫片（lib/run.js），任务文本里带空格或引号会自动转义；CI 在 macOS / Ubuntu / Windows × Node 18/20/22 全跑通过。

Q: 哪些 ACP 客户端可以直接用，不用写代码？

A: 任何走 Agent Client Protocol（ACP）的 CLI 都可以直接当 provider：opencode、Cursor 的 agent acp、CodeBuddy 的 cbc --acp、Gemini 的 gemini --acp，只要在 PATH 上能被探测到；不支持某个 ACP 能力（比如 setSessionConfigOption 改 model）会自动静默回退。

Q: 子代理空闲时会一直占着资源吗？

A: 不会。子代理每完成一轮会被排进空闲释放计时器（默认 600000 毫秒即 10 分钟，可在配置 idleTimeoutMs 改，0 禁用）；下一次 product_submit 调用会取消还没触发的释放，所以快速续聊不会重新建会话。

上手难度

进阶 — 不需要写代码，但要理解"角色 = 远端 CLI 权限档位"、"中继模型和远端 CLI 不是一回事"这两个关键区分；安装后还要至少装一个产品 CLI 并登录，否则什么也跑不起来；想加自定义 ACP 客户端才需要写 cordis.patch.yml 的 config 覆盖。

已知问题与限制

• pnpm 11 默认开 minimumReleaseAge，老机器可能因为 0.3.0 还"太新"被回退到 0.2.0（0.2.0 把 @deepseek-ai/dsh-tools 放在 dependencies，会和宿主 peer 冲突），必要时显式 pin @0.3.0（CHANGELOG.md:21-28）。
• 角色的 permissionMode 只能取 readonly / default / full 三个值，其它值会静默回退成 default（lib/roles.js:39）。
• 角色目录里某个 JSON 坏了会被直接跳过（lib/roles.js:46-48），插件不报警；可通过 product_roles 看到实际生效的列表。
• 通用 ACP 客户端遇到不支持的能力时静默降级：readTextFile / writeTextFile 一律抛错（lib/bridges/acp.js:36-39）；requestPermission 一律拒掉（lib/bridges/acp.js:32-34），相当于跑 unattended 模式；setSessionConfigOption 失败被吞（lib/bridges/acp.js:115-119），意味着通过 model 参数改 model 大概率不生效。
• ACP 进程意外退出后会自动重连并尝试 session/load（lib/bridges/acp.js:87-102, 145-159）；如果对端 ACP 不支持 loadSession 会回退成全新会话，原会话上下文就丢了。
• Codex 桥按 codex-cli 0.147+ 的点号事件名（thread.started / item.completed / turn.completed）实现，对老版本的 _ 下划线命名做了 fallback（lib/bridges/codex.js:11-14, 88-102）；装太老的 codex CLI 会丢文本。
• 后台子代理到达 maxConcurrentChildren 时 product_delegate 会被拒掉（lib/tools/product-delegate.js:103-105），需要先用 product_wait 或 subagent_progress 让一个子代理结束。
• 自定义 config.providers 整段 config 会被 profile 里的 patch 替换（README.md:66-67），要保留 idleTimeoutMs 之类默认必须重写一遍。

English | 简体中文

Role-based Codex / Claude Code / ACP subagent providers for the DeepSeek Harness. Turns external agent CLIs into durable, continuable subagents with a declarative role library, per-role product permissions, delegation with a permission ceiling, and cross-platform process launching.

Features

• Continuable children — one-shot sync or async continuable (control with send_message, list_agents, interrupt_agent; attach synchronously with product_wait).
• Session continuity — a child's remote product session survives idle disposal and process restarts (durable registry + log markers; claude/codex resume by id, ACP reconnects).
• Declarative roles (roles/*.json) — general (default), code-review, explore (never delegates), debug. Delegation defaults ON; a role can ban it. Unknown roles fall back to general.
• Two-layer permission model — the relay model is always a read-only pipe; permissionMode (readonly / default / full) applies to the remote product and is mapped to each product's own CLI flags.
• Permission ceiling — a child can never spawn a descendant with more permission than it has.
• Any ACP agent — add Cursor (agent acp), CodeBuddy (cbc --acp), Gemini (gemini --acp) and more via config.providers; no code needed.
• Resource management — idle disposal, configurable timeouts, concurrency cap.
• Cross-platform — Windows .cmd shims, Windows-safe path escaping; CI runs macOS / Ubuntu / Windows.

Requirements

• A DeepSeek Harness deployment (web profile).
• At least one product CLI on PATH and authenticated: claude, codex, or an ACP CLI (opencode, agent, cbc, …).
• Node ≥ 18.

Install

Recommended — dsh plugin add

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

That single command installs the package and wires the host-plane row automatically: the plugin ships a cordis.patch.yml declared via dsh.bundle in its package.json, so dsh plugin add registers it as a profile layer (no manual cordis.patch.yml editing needed). Restart the harness afterwards so the plugin loads.

To customise the plugin (e.g. add ACP providers), target the product-subagents id in your profile's own cordis.patch.yml (~/.dsh/profiles/web/cordis.patch.yml):

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

Note: a config override replaces the row's whole config object, so restate any keys you wish to keep (like idleTimeoutMs above).

Install via your agent (one line)

Paste this to your DeepSeek Harness agent (or any coding agent with shell access to the harness home) — it performs every step itself:

Install the dsh-plugin-product-subagents plugin into my DeepSeek Harness web profile: run dsh plugin --profile web add dsh-plugin-product-subagents, then tell me to restart the harness so the plugin loads.

Manual (advanced)

If you prefer to manage the profile yourself, use pnpm (not npm) inside the profile directory so peer dependencies are not auto-installed:

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

Then add a host-plane row to your profile's 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] }

Quick start

In a session, the model has six tools:

product_delegate role=general task="Refactor demo-project/calc.js and run its tests"
product_wait subagent_id=<childId>

Configuration

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # settled children release their remote session
                              # after this idle period (0 disables)
  maxConcurrentChildren: 8    # cap on simultaneous continuable children
  rolesDir: <path>            # declarative role library (default: roles/)
  registryPath: <path>        # durable remote-session registry

Roles and permissions

Each role file:

{
  "id": "code-review",
  "description": "Review code for bugs, security, maintainability (read-only).",
  "provider": "claude-code",
  "permissionMode": "readonly",
  "allowDelegation": true,
  "instructions": "You are a code reviewer. READ-ONLY: never modify files. …"
}

• permissionMode maps to product flags: readonly (claude --permission-mode plan / codex --sandbox read-only), full (claude --dangerously-skip-permissions / codex --dangerously-bypass-approvals-and-sandbox).
• The relay model never gets write-capable tools, in every role.
• Delegation is capped: readonly < default < full; a child cannot spawn a descendant with a higher mode.

Custom ACP providers

config.providers accepts any ACP-capable CLI — the generic bridge handles a persistent process, session/load resume, and dead-process reconnect:

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

Providers appear in the delegation enum only when their command is detected on PATH. Built-ins (claude-code, codex, acp) can be overridden with the same keys.

Development

npm install
npm test        # node:test — pure logic + fake bridge, no CLIs or keys
npm run lint    # syntax-check every module

See docs/ARCHITECTURE.md for the bridge contract, the permission model, and how to add products. CI runs the suite on macOS / Ubuntu / Windows × Node 18/20/22.

Security

This is a configuration-as-trust-boundary tool: it spawns whatever CLIs you configure, and full passes the products' own "bypass all permission checks" flags. See SECURITY.md.

License

MIT