dsh-plugin-subagents

English | 简体中文

适用于 DeepSeek Harness (dsh) 0.1.0-rc.6 / 0.1.0-rc.7 · Node ≥ 18 · MIT

DeepSeek Harness 的子代理增强插件。模型继续用它已经熟悉的 subagent / subagent_fork 工具，但每一次调用都能：

• 走原生子代理，更快更省 —— 委派给 dsh 进程内子代理，并且可以按次覆盖任何参数：model、provider、persona、工具权限（toolFilter）、工作目录（cwd）。
• 借外部 Agent 的手 —— 直接把任务委派给外部 Agent CLI：Claude Code、Codex、Grok，或任何 ACP agent。桥接子代理是一个可以持续对话的长期伙伴，dsh 重启后也会重连到同一条外部会话继续干活。
• 按角色委派，不用写长篇要求 —— 带上一个具名角色（code-review、explore、codex-full……），后端、权限档、附加指令都由角色文件替你定好。

一切错误都大声报出来：不支持的参数绝不会被静默忽略；外部 CLI 返回的内容先脱敏再进入对话。

什么时候用它

• 想要一个快速、只读的代码侦察兵或审查员，不给写权限（role: "explore"、role: "code-review"）。
• 想让 Codex 或 Claude Code 干重活，但由你的 dsh 会话来调度，结果回流到对话里。
• 想让多个 agent 并行工作、各写各的目录（cwd）—— 搭配 dsh-worktrees。
• 想让一个多任务作业能规划、派发、重启后续跑 —— 搭配 dsh-dag-orchestrator。

环境要求

| 需要什么 | 说明 | | --- | --- | | dsh | 0.1.0-rc.6 或 0.1.0-rc.7 | | Node | ≥ 18 | | 桥接后端（可选） | 对应 CLI 已安装并已登录：claude、codex、grok，或任意 ACP agent（如 opencode acp）。CLI 缺失只是意味着该后端不提供 —— 只用原生子代理的话什么都不用额外装。 |

安装

# 1. 拉取仓库，并把它链接到正在运行的 dsh 的内部包上
git clone https://github.com/Luck9Star/dsh-plugin-subagents
cd dsh-plugin-subagents
npm install
npm run setup:peer        # 避免出现第二份 dsh-tools（没有这一步工具调用会崩）

# 2. 安装进 dsh profile
dsh plugin --profile web add "$(pwd)"

# 3. 应用宿主补丁 —— 这一步必须跑
./patches/install.sh      # Windows: patches\install.ps1
#    阶段 A（必须）：修复 dsh-tools 单实例软链
#    阶段 B（推荐）：为子代理打开逐次调用的 cwd 支持

# 4. （推荐）只读体检
./patches/verify.sh       # Windows: patches\verify.ps1 ；--probe 会实测 cwd 是否生效

# 5. （web 会话、standard 类预设）做预设层适配
./scripts/install-preset.sh standard

# 6. 重启并开一个新会话
dsh --profile web

预期结果： 新会话里出现 subagent、subagent_fork、subagent_submit、subagent_progress、subagent_wait、subagent_roles、subagent_agents 这组工具。subagent_agents 会显示哪些后端可用、在 PATH 上找到了哪些 CLI。

升级了 dsh？ 重跑一遍 ./patches/install.sh —— dsh 升级会落在新的 npx 缓存目录里，cwd 补丁必须重新打。

快速上手

让 agent 自己调工具，或者你亲自调：

// 原生子代理，指定目录，跑完等结果
subagent({ prompt: "运行 pwd 并只回显第一行",
           cwd: "/tmp/dsh-smoke", run_in_background: false })

// 原生子代理，仅这一次调用换个模型
subagent({ prompt: "…", model: "deepseek-v4-flash" })

// 后台委派给 Codex，然后收答案
subagent({ backend: "codex",
           prompt: "Which product/CLI are you running as? Reply with the name only.",
           run_in_background: true })   // → { kind: "background", job_id: "…" }
subagent_wait({ subagent_id: "…", timeout_ms: 60000 })   // → "Codex"

// 用角色代替自己写一堆要求
subagent({ role: "code-review", prompt: "审查暂存区的 diff。" })

后台或桥接调用会返回一个子代理 id；用 subagent_progress 看进度，用 subagent_wait 收结果。桥接子代理可续聊 —— 再次调用时，回应你的还是同一条外部会话。

内置角色

roles/ 下一个 JSON 文件一个角色 —— 放入你自己的角色文件即可自动生效（rolesDir 配置）。

| 角色 | 后端 | 权限 | 用途 | | --- | --- | --- | --- | | general | 调用方自选 | full | 默认角色，兜底处理没被其他角色匹配到的任务。 | | explore | native | 只读工具集 | 快速代码侦察 —— 只搜索和阅读，绝不写文件。 | | code-review | native | 只读工具集 | 审查 diff 的缺陷、安全性与可维护性。 | | debug | native | default | 定位 bug 与故障根因；允许派只读帮手。 | | codex-full | codex | full | 主力干将：通过 Codex 改文件、跑命令。 | | claude-readonly | claude-code | readonly | 用 Claude Code 读代码、做规划，不改文件。 | | grok-native-full | grok-native | full | Grok CLI 上的主力干将。 |

工具

| 工具 | 作用 | | --- | --- | | subagent | 委派任务。返回可续聊的子代理、后台作业，或（前台模式）最终输出。 | | subagent_fork | 同上，fork 变体（默认一次性）。 | | subagent_submit | 向运行中的桥接子代理递交工作（转发管道）。 | | subagent_progress | 子代理的实时进度 —— 包括桥接子代理真正向外转发过几次工作。 | | subagent_wait | 阻塞等待子代理回答（timeout_ms 默认 300 秒，上限 600 秒）。 | | subagent_roles | 列出可用角色。 | | subagent_agents | 可用性总览：有哪些后端、找到了哪些 CLI、登录提示。 |

内建的安全机制

• 权限天花板 —— 桥接子代理永远不能生出权限比自己高的后代。一个只读的 Codex 子代理没法靠委派给全权限的 Claude 子代理越狱 —— 任何路径都不行，包括插件间调度。未知权限档一律按只读从严处理。
• 密钥脱敏 —— 桥接输出在进入对话前先过一遍脱敏：Bearer token、sk-… 密钥、ghp_/gho_… 令牌、api_key= 赋值、JWT。默认开启（redactSecrets）。
• 传话筒诚实守卫 —— 桥接子代理是传话筒：它的职责是把任务转发给外部 CLI，而不是自己作答。如果它一次都没转发就交报告，报告会被直接打回并附明确警告 —— 偷懒的传话筒没法把自己的话冒充成 Codex 的工作成果。
• 断线可恢复 —— 每个桥接子代理的会话映射与设置记录在 ~/.dsh/subagents-registry.json（原子写入、仅所有者可读 0600、最多保留 500 条）。重启后子代理重连同一条外部会话，权限天花板原样恢复 —— 恢复依据只有这份注册表，从不信任子代理自己的日志行。

配置

全部可选 —— 下表每项都有可用默认值。配置写在 profile 的 cordis.patch.yml 中本插件的行上；写错的键会在启动时大声报错。

| 键 | 默认值 | 含义 | | --- | --- | --- | | providers | 内置后端 | 额外的桥接 CLI，如 { myagent: { type: "acp", command: "opencode", args: ["acp"] } }。类型：claude / codex / grok / acp。 | | rolesDir | 自带 roles/ | 角色 JSON 文件的加载目录。 | | idleTimeoutMs | 600000 | 桥接子代理的空闲超时（0 = 永不）。 | | maxConcurrentChildren | 8 | 在线桥接子代理数量上限。 | | redactSecrets | true | 对桥接输出脱敏。 | | relayReportGuard | true | 打回从未转发过工作的传话筒报告。 | | maxDispatchPermissionMode | full | 插件间调度的权限天花板。 | | legacyProductAliases | auto | 为从旧版注册表迁移过来的子代理保留的兼容别名。 | | provider | spawn | 原生子代理的默认 provider。 | | agentOptions | — | 原生子代理的默认 { provider, model, maxTokens }。 | | persona / toolFilter / maxDepth | — | 原生子代理的默认值；逐次调用的参数优先。 | | toolNames.delegate / toolNames.fork | subagent / subagent_fork | 必要时可改写接管的工具名。 | | register.* | true | 按工具注册开关（register.wait 等）。 | | presetRow | false | 进阶：以官方预设行形式注册，而不是接管全局工具。 |

角色文件支持字段：description（给委派方模型看）、backend、permissionMode（readonly / default / full）、allowDelegation、instructions（前置到任务文本）、overrides（仅原生子代理的按角色默认值）。完整结构见 docs/DESIGN.md。

给插件作者：调度接缝

其他插件可以通过 ctx.get('subagentsDispatch') 以纯代码方式调度桥接子代理 —— 不经过模型工具调用。有两道权限闸（委派天花板与 maxDispatchPermissionMode）。细节与示例：docs/dispatch-seam.md。

常见问题

| 症状 | 原因 → 处理 | | --- | --- | | 每次工具调用都报 Cannot read properties of undefined (reading 'prepare') | 出现了两份物理拷贝的 dsh-tools。在本仓库重跑 npm run setup:peer，再跑 ./patches/install.sh。 | | subagent: backend "codex" is not available: command "codex" not found on PATH | CLI 没装。安装并登录（codex login）后重启 dsh。subagent_agents 对每个后端都有提示。 | | dsh 升级后 cwd 好像失效了 | 重跑 ./patches/install.sh —— 每次 dsh 升级后都要重新打 cwd 补丁。 | | subagent: permission escalation blocked … | 这是设计行为：某个子代理试图生出权限更高的后代，被拦下了。 | | grok-native 只回一个字符，或每次重试都报 Session ID ... is already in use | 已修复：grok CLI 1.0.5 把 text 事件改成了分片流、且拒绝复用已存在的 -s 会话号。更新本插件即可 —— 解析器现在拼接分片、锁死会自动回退 --resume、默认超时提到 15 分钟。 | | 启动时报重复注册 provider 的错误 | 同一 profile 里有别的插件注册了同名桥接后端，或同样接管了 subagent。二选一：编辑 profile 的 cordis.patch.yml 删掉那边，pnpm remove 对应包，再重装本插件。 |

搭配使用

• dsh-worktrees —— 并行任务通过 cwd 各写各的 git worktree。
• dsh-dag-orchestrator —— 规划并可续跑多任务 DAG；其任务节点依赖本插件的 cwd 支持。

开发

npm install && npm run setup:peer   # 链接正在运行的宿主的 peers
npm test                            # node --test，全部用假对象 —— 不碰 CLI、密钥、网络
npm run lint

设计记录：docs/DESIGN.md · 验证手册：docs/VERIFY.md。

参考与致谢

• DeepSeek Harness 原生 subagent 工具族 —— 本插件扩展的对象。
• Claude Code（.claude/agents 一文件一个 agent 的设计）—— 角色库的形态来源：一文件一角色、默认允许再委托。
• Codex CLI、Claude Code CLI、Grok CLI —— 桥接后端。
• Agent Client Protocol（ACP） 及其 TypeScript SDK —— 任何讲 ACP 的 agent 零代码接入。
• task-weaver —— 密钥脱敏逻辑与 Grok 桥接的 argv/解析/分类逻辑移植自它。

安全

见 SECURITY.md。桥接 CLI 用的是你自己的凭据 —— 本插件探测可用性时只查 PATH、绝不执行 CLI；脱敏掉的密钥永远不会进入对话。

许可证

MIT