前言¶

在 DeepSeek Harness（DSH）里做复杂任务，常见做法是让主模型直接调用工具，或手写一层子代理调度。前者容易把 Codex、Claude Code 等外部产品的会话能力浪费掉；后者则要自己处理进程生命周期、会话恢复和权限边界。

dsh-plugin-product-subagents 走另一条路：把已安装并登录的外部 Agent CLI 注册为 DSH 子代理提供方，用声明式角色库描述「谁来做、能做什么、能不能再委派」，并在 Harness 会话里暴露一组统一工具。主模型始终是只读中继，写权限与委派上限落在远程产品上。

下面按安装、工具用法和权限模型说明这个插件能做什么、适合什么场景。

这是什么¶

• 插件名称：dsh-plugin-product-subagents
• 维护者：shaokeyibb
• 分类：工作流（SkillHub 目录）
• 当前版本：0.3.1（MIT）
• 仓库：github.com/shaokeyibb/dsh-plugin-product-subagents

一句话定位：面向 DSH 的基于角色的 Codex / Claude Code / ACP 子代理提供方。它把外部 Agent CLI 变成可同步、可续跑、可恢复会话的子代理，并提供按角色的产品权限与带上限的委派能力。

核心功能¶

可续跑的子代理¶

子任务可以一次性同步执行，也可以异步续跑。续跑场景下，模型通过 send_message、list_agents、interrupt_agent 控制子代理；需要同步等待结果时，用 product_wait 挂接。

会话持久与恢复¶

子代理关联的远程产品会话在空闲回收或进程重启后仍可恢复：插件用持久化注册表和日志标记跟踪会话；Claude Code / Codex 按 id resume，ACP 提供方则重连。

声明式角色库¶

角色定义在 roles/*.json，内置包括：

• general（默认）
• code-review
• explore（不委派）
• debug

委派默认开启，单个角色可关闭。未知角色回退到 general。

两层权限与委派上限¶

• 中继模型：在任何角色下都只有只读管道，不获得写能力工具。
• 远程产品：由角色的 permissionMode 控制，取值为 readonly / default / full，并映射到各产品自己的 CLI 参数。
• 委派上限：子代理不能生成权限高于自身的后代（readonly < default < full）。

任意 ACP 提供方¶

除内置的 claude-code、codex、acp 外，可在 config.providers 里声明 Cursor（agent acp）、CodeBuddy（cbc --acp）、Gemini（gemini --acp）等 ACP CLI，无需改插件代码。只有 PATH 上检测到的命令会出现在委派枚举里。

资源与跨平台¶

支持空闲回收、可配置超时、并发上限（maxConcurrentChildren）。Windows 提供 .cmd shim 与安全路径转义；CI 覆盖 macOS、Ubuntu、Windows。

环境要求¶

• 已部署 DSH（web profile）
• PATH 上至少有一个已认证的产品 CLI：claude、codex，或 ACP CLI（如 opencode、agent、cbc 等）
• Node ≥ 18

安装与启用¶

推荐用 dsh plugin add 安装。该命令会安装包并通过 package.json 里声明的 cordis.patch.yml 自动写入 host-plane 行，无需手改 profile 补丁。

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

安装后重启 Harness，插件才会加载。

若要自定义 ACP 提供方或空闲超时，在 profile 的 cordis.patch.yml（例如 ~/.dsh/profiles/web/cordis.patch.yml）里覆盖 product-subagents 这一行。注意：配置覆盖会替换整个 config 对象，需要保留的键要一并写出。

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

高级用户也可在 profile 目录用 pnpm 手动安装，再自行插入 cordis.patch.yml 行；README 建议用 pnpm 而非 npm，以避免 peer 依赖被自动安装。

典型用法¶

安装并重启后，会话里会出现六个工具：

下面是一次委派加等待的示例：

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

角色文件示例（节选）：

{
  "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 与各产品 CLI 的对应关系（来自 README）：

• readonly：Claude --permission-mode plan；Codex --sandbox read-only
• full：Claude --dangerously-skip-permissions；Codex --dangerously-bypass-approvals-and-sandbox

配置项¶

config:
  providers: { cursor: { type: acp, command: agent, args: [acp] } }
  idleTimeoutMs: 600000       # 子代理 settle 后空闲多久释放远程会话（0 表示不回收）
  maxConcurrentChildren: 8    # 同时存在的可续跑子代理上限
  rolesDir: <path>            # 角色库目录（默认 roles/）
  registryPath: <path>        # 远程会话注册表路径

适用场景与注意¶

适合谁

• 已在 DSH web profile 上跑工作流，希望把 Claude Code、Codex 或 Cursor 等 CLI 纳入统一子代理调度的人
• 需要按任务类型切换角色（代码审查只读、探索不委派、调试可写）的团队
• 希望子代理会话在空闲或重启后仍能续跑的长任务场景

使用前请确认

• 插件以当前 DSH 进程的用户权限启动你配置的 CLI；安装前建议阅读仓库源码与 SECURITY.md。
• permissionMode: full 会传递各产品自带的「跳过权限检查」类参数，属于配置即信任边界，生产环境应收紧角色与提供方列表。
• SkillHub 目录（skillhub.cn/plugins/shaokeyibb/dsh-plugin-product-subagents）是社区索引，与 DeepSeek / 幻方无官方从属关系；以 GitHub README 与发布包为准。

结尾¶

dsh-plugin-product-subagents 把「外部 Agent 产品 + 声明式角色 + 权限上限」收成 DSH 里一组可复用的子代理工具，适合需要跨 Codex、Claude Code、ACP 统一编排、又要把写权限关在远程产品一侧的场景。

• 目录页：skillhub.cn/plugins/shaokeyibb/dsh-plugin-product-subagents
• 源码与文档：github.com/shaokeyibb/dsh-plugin-product-subagents