子智能体委派桥 mbj733/dsh-subagent-mcp

dsh-subagent-mcp

给 Codex 配一支 DeepSeek 小队。 一次工具调用，就能把任务交给一个全新的 DeepSeek Harness 智能体。它已经带着你的技能、你的 AGENTS.md 和你的登录状态，在你指定的项目目录里干活，干完把答案交回来。

| 你能得到什么 | 为什么重要 |
| 每次委派约 9k token | 一次轻量运行的开销差不多等于读一个文件，而不是再开一场对话。 |
| V4.1-Flash，推理档位 max | 默认就是最强预设，不用调。 |
| 你的技能和 AGENTS.md | 它用你的 DSH_HOME，所以行为跟你配置好的 DSH 一致。 |
| 长任务不会被超时杀掉 | 它先等 wait_sec，然后返回一个任务 id，你稍后再取结果。 |
| 零运行时依赖 | 约 600 行，JSON-RPC 循环是手写的。除了这层桥接，没有别的东西要审。 |
| 一个进程，一个回合 | 没有常驻进程，任务之间不会串状态，也不会改你的 DSH 配置档。 |

Codex / Claude Code / any MCP client
│ MCP over stdio
▼
dsh-subagent-mcp ← this package, zero deps
│ spawn: dsh --profile --patch <overlay> --json
▼
DeepSeek Harness (headless) ← inherits DSH_HOME: AGENTS.md, skills, sign-in
▼
your project directory · one turn · final answer

与同类桥接方案的对比

智能体宿主和 DeepSeek Harness 之间的桥接方案有三种形态：常驻守护进程，让智能体一直活着并回调宿主；SDK 桥接，在 git worktree 里跑 worker；中继，把已经在跑的 DSH 实例暴露出来。这个包是第四种：无状态一次性桥接。它在哪些地方更强，又在哪些地方故意示弱：

| 维度 | 这个包 | 常见替代方案 | 为什么重要 |
| 运行时依赖 | 零 —— 只需要 dsh 本身 | ws + @modelcontextprotocol/sdk + zod，或者一串 SDK 包 | 约 600 行的单文件，坐下来一遍就能审完；也不会因为某个传递依赖变了就挂掉 |
| 你的 DSH 配置档 | 绝不触碰 —— 配置以 --patch 覆盖层的形式传入 | 写进配置档，或者要求 DSH 侧装插件 | 升级 DSH 时，不会跟一个把自己写进你配置的桥接撞车 |
| 单次调用成本 | 两档，明码标价：约 9k 或约 300k token | 一个隐式档位，等账单来了才知道 | 跑之前你就知道要花多少 |
| 生命周期 | 每个任务一个进程，跑完就退出 | 常驻守护进程 / worker 池 | 后台不跑任何东西；一次崩溃不会污染下一个任务 |
| 孤儿进程 | 取消和关闭时按进程树杀 | 有时会留下 dsh 拉起的 MCP 子进程 | 几次取消之后不会慢慢漏内存 |
| 配置继承 | 真实 DSH_HOME → 你的技能、AGENTS.md、登录状态 | 有些运行时拿到隔离的临时 DSH_HOME（空壳） | 子进程的行为确实和你配置的 DSH 一致 |
| 安装 | npx -y github:…，不需要 registry 账号 | 只能 npm publish | 一段配置，今天就能用 |
| 冷启动 | 每次委派约 1.7 s ⚠️ | 热守护进程更快 | 无状态要付的实价 |
| 原生回调 / 会话挂接 | 不提供 —— 需要宿主钩子 ⚠️ | 守护进程能原生回调，也能挂到运行中的会话 | 这两样你都要，就该选守护进程形态的桥 |

一句话：想要便宜、可审计、没有活动部件的方式把活交给 DSH，选这个；想要长期存活的智能体自己唤醒宿主，选守护进程形态的桥。

- 默认预设： DeepSeek-V4.1-Flash（id deepseek-flash），推理强度 max。
- 无需配置： 第一次调用会用随包提供的 headless 模板，创建自己的 dsh-subagent 配置档。

安装

需要 Node.js ≥ 22.19。随包依赖自带 dsh 命令行。

A · 直接从 GitHub 装 —— 不用 clone，不用构建，不用 npm 账号：

~/.codex/config.toml
[mcp_servers.dsh_subagent]
command = 'npx'
args = ['-y', 'github:mbj733/dsh-subagent-mcp']
startup_timeout_sec = 60

B · 固定版本的 tarball

npm i -g https://github.com/mbj733/dsh-subagent-mcp/releases/download/v0.5.0/mbj733-dsh-subagent-mcp-0.5.0.tgz

C · clone（想读代码或打补丁时用）

git clone https://github.com/mbj733/dsh-subagent-mcp
cd dsh-subagent-mcp && npm install

[mcp_servers.dsh_subagent]
command = 'node'
args = ['/absolute/path/to/dsh-subagent-mcp/index.mjs']
startup_timeout_sec = 30

之后重启宿主。然后直接说：

Delegate to DSH: summarise src/ and list the files that look unused. Work in /path/to/project.

工具

| 工具 | 覆盖层 | 做什么 |
| subagent_dsh | lite | 委派任务：技能、shell、文件编辑、网页搜索 —— 不含 MCP 工具。约 9k 输入 token。 |
| subagent_dsh_full | full | 同上，外加 overlay.yml 里声明的每个 MCP 服务器。十几个服务器时约 300k 输入 token。 |
| subagent_dsh_status | — | 收取任务结果。接受任务 id（t-…）或 dsh 会话 id。 |
| subagent_dsh_continue | — | 在同一个 dsh 会话里追问；cwd/overlay 默认沿用记住的值。 |
| subagent_dsh_cancel | — | 杀掉运行中或排队中的任务，连同整棵进程树。 |

| 参数 | 默认值 | 含义 |
| prompt | — | 必填。子代理看不到宿主对话，需要的东西都要写进去。 |
| cwd | — | 必填。项目目录的绝对路径。不是沙箱（见「安全」一节）。 |
| wait_sec | 120 | 返回任务 id 之前等待的秒数。设为 0 立即返回。 |
| timeout_sec | 1800 | 硬性上限；超时后整棵任务树被杀掉，返回已产出的部分输出。 |
| read_only | false | 要求子代理不改动文件系统（靠指令加检测，不是内核级沙箱）。 |
| format | text | 设为 json 时返回 {ok, state, answer, usage, meta}。 |

长任务在设计上就是安全的：调用先等 wait_sec，然后返回任务 id，所以宿主侧的工具超时永远不会杀掉任务。

模型与成本

子代理运行 DeepSeek-V4.1-Flash，模型 id 为 deepseek-flash，推理强度为 max。
两个 overlay 都是这么配的，你可以自己验证：

dsh --profile dsh-subagent --patch overlay.lite.yml --dump-config | grep -A4 agent-default-model

账号下有两个 id（已对照 GET https://api.deepseek.com/models 核对）：

| id | 显示名 |
| deepseek-flash | DeepSeek-V4.1-Flash · 默认 |
| deepseek-v4-pro | DeepSeek-V4-Pro |

不用改文件，按机器切换：export DSH_SUBAGENT_MODEL=deepseek-v4-pro。

要固定 id，不要固定显示名。其他产品线的服务商专属 id（比如 opencode 的 deepseek-v4.1-flash）在这里无效；用它们需要在 dsh-subagent 配置档上配好对应服务商的 key 和 base_url。

| Overlay | 挂载内容 | 典型输入 token | 适用场景 |
| lite | 凭证 + 技能 | ~9,000 | 写作、重构、分析——凡是用 shell 和文件就能完成的事 |
| full | 再加 11 个 MCP 服务器 | ~300,000 | 确实需要 PDF/office/浏览器/GitHub/地图工具的任务 |

一次简短的 lite 回复，端到端实测：startup 1.67s · work 1.19s · tokens in 9073 / out 2。

不借助宿主验证安装

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| npx -y github:mbj733/dsh-subagent-mcp

预期输出 serverInfo.name = dsh-subagent-mcp，且恰好五个工具。

要替别人装，或者让智能体来装？ 读 llms.txt 拿机器可读指南，读 AGENTS.md 了解注册规则和仓库约定。通用客户端配置：

{"mcpServers":{"dsh_subagent":{"command":"npx","args":["-y","github:mbj733/dsh-subagent-mcp"]}}}

可选：把完成的任务回报给宿主

MCP 没有传递迟到结果的通道，所以长任务会返回任务 id。在支持钩子的宿主上，notify-hook.mjs 会把已完成的任务注入下一轮对话。

Codex. type = "command" is mandatory — a missing type breaks the whole config file.
[[hooks.PostToolUse]]

[[hooks.PostToolUse.hooks]]
type = "command"
command = "'node' '/absolute/path/to/dsh-subagent-mcp/notify-hook.mjs' PostToolUse"
timeout = 5

它读取 state/tasks.json，每个已完成任务只上报一次，其余情况保持静默。

行为特点

- 每次调用无状态 —— 新进程、只跑一轮；没有需要监管的东西，任务之间也不会互相泄漏。
- 叠加配置，不动配置档 —— 配置以 dsh --patch 层的形式传入，你现有的配置档永远不会被改写。
- 并发有上限 —— DSH_SUBAGENT_MAX_CONCURRENCY（默认 2）配合 FIFO 队列；超出的调用返回 queued 及其排队位置。
- 用量上报 —— token、工具调用及名称、startup_ms / work_ms、exit_code、error_code（TIMEOUT、CANCELLED、SPAWN_FAILED、EMPTY_ANSWER、CHILD_EXIT、RATE_LIMIT）。
- 超长回答 —— 超过 DSH_SUBAGENT_INLINE_LIMIT（默认 24000 字符）时，全文写入 state/results/<task>.md；回复中会说明展示了百分之多少。
- 不留孤儿进程 —— 取消和关闭都会杀掉整棵进程树。

安全

- cwd 不是沙箱。 它只选择工作目录；子进程继承宿主用户的文件系统和网络权限。
- read_only 只是建议性的。 靠指令约束、靠检测上报，不是内核强制。
- 子进程继承 DSH_HOME，因此会读取你的 AGENTS.md、技能和已保存的凭据。
- 除了你配置的模型服务商，不会向任何地方发送数据。

差异与限制

刻意做成无状态：每个任务一个进程，跑一轮就退出。这样失败面小、计费可预测，也意味着：

- 没有守护进程，除了进程内 FIFO 之外没有别的队列；
- 没有原生的「完成后唤醒父进程」回调 —— 那需要宿主钩子，见上文；
- 无法接入别处已在运行的 DSH 会话；
- 没有流式输出，也不能中途提问 —— 追问请用 subagent_dsh_continue；
- 宿主看不到子进程的对话，只有最终回答会传回来。

多个宿主窗口各自运行自己的服务器实例，共享 state/tasks.json，所以钩子通知可能重复。

基于

DeepSeek Harness。本项目和 @deepseek-ai/dsh-subagent-codex 方向相反，后者让 DSH 驱动 Codex 线程。

作者

由 @mbj733 构建和维护。MIT 协议。

故障排查

failed to parse overlay … YAMLException: end of the stream or a document separator is expected

dsh-subagent 配置档补丁坏了。该文件开头是 [] 占位符，所以后面追加任何块都会让整个文件变成非法 YAML —— 通常是从别的配置档复制进来的 persona/插件块。桥接层每次运行都会检测到这一点，保留备份并自动重置文件，所以一个任务仍会成功（页脚随后显示 profile-patch auto-reset）。手动操作：

node repair-profile.mjs # backs the file up, then writes the clean template

unknown prompt variable "{{cwd}}"

配置档补丁把 personaSuffix 设成一段文本，其中含有 {{cwd}}，而无人值守配置档没有注册这个变量（那里只有 provider 和 model）。要么删掉 personaSuffix 这一行，要么把人格设定放进 personaPrefix，它不接受任何变量。

重启宿主后报 unknown task id

任务 id 存放在服务器进程里。重启之后，改用 dsh 会话 id 继续：subagent_dsh_continue(session_id="session-…", prompt="…")。