deepseek-subagent-mcp

为 Claude Code、Codex 或任何其他 MCP 客户端提供一个 DeepSeek Harness 代理，使其可以像委托给自身子代理一样委托工作。

MCP（模型上下文协议）是编码代理加载外部工具的标准。DeepSeek Harness 是 DeepSeek 的开源代理运行时——一个在循环中运行模型、配备文件和 shell 工具的环境，于 2026 年 8 月以 MIT 许可证发布。该服务器位于两者之间：它在独立进程中运行一个 Harness 代理，并暴露六个工具用于启动、监控、继续和停止该代理。

子代理拥有自己的上下文窗口。这正是关键所在——你将一个独立的任务交给它，它消耗自己的 token 来处理文件，最终返回结果而非对话记录。

要求

• Python 3.11 或更新版本

• 来自 platform.deepseek.com 的 DeepSeek API 密钥

• 搭载 Apple Silicon 的 macOS 14+，或运行在 x86-64 或 arm64 架构上的 Linux

无需安装 Node.js：Harness 运行时作为自包含可执行文件包含在 deepseek-harness-sdk wheel 中。该 wheel 也是平台限制——它仅发布 macosx_14_0_arm64、manylinux_2_28_x86_64 和 manylinux_2_28_aarch64，不支持 Windows、Intel 版 Mac 和 macOS 13。

安装

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

在你的项目中添加至 .mcp.json，或添加至 ~/.claude.json 以应用于所有项目：

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

添加至 ~/.codex/config.toml：

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

工具

运行默认是异步的，因为编码任务可能耗时数分钟，而 MCP 客户端会对单个工具调用设置超时。dsh_delegate 在工作排队后立即返回；dsh_await 负责等待并在过程中报告进度。对于短任务，可以向 dsh_delegate 传递 wait_seconds 参数，从而省略第二次调用。

每次 dsh_delegate 创建一个代理，持有一个运行时进程和一个持久化会话。dsh_continue 重新进入该会话，因此子代理仍能保留之前轮次的上下文。

每次委托都要说明如何验证完成

dsh_delegate 要求提供 verification 参数：一个用于证明任务完成的命令。

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

服务器会在子代理完成后，在代理的工作目录中自行运行该命令。子代理报告自己的测试结果只是声称；退出码才是事实，而代理过早宣布成功是已被充分记录的失败模式。

该命令的分类策略与子代理自身调用前的策略相同——调用者是另一个代理，可能受到提示注入，因此“调用者要求这样做”并不构成授权。当确实没有什么可检查时，请传递 verification="true"；明确的谎言比沉默的默认值更好。

返回内容

如果子代理返回完整的对话记录，就违背了其目的。当子代理的答案超过 DSA_SUMMARY_TOKENS 时，会在同一会话中（作为额外一轮）要求其用七部分的手动摘要替换：目标、约束与偏好、进展、关键决策、下一步、相关文件、关键上下文。这才是跨 MCP 边界传递的内容。

如果答案已在限制之下，则原样返回，不消耗额外轮次。原始响应始终保留：通过 dsh_transcript(run_id, raw=True) 获取。

监督执行

子代理的工具调用在运行前受到限制。运行时内部的 PreToolUse 钩子将每个提议的调用传递给该服务器，由服务器决定允许或拒绝；被拒绝的调用作为被阻止的工具结果返回给模型，并附带理由，模型会相应调整。

确定性分类器首先做出决定，并处理大多数调用。读取文件、ls、grep、版本控制读取、运行工作区自身代码和测试等操作被允许，无需模型参与。特权命令、工作区外的删除操作、将 fetch 输出管道到 shell 以及任何涉及 SSH 密钥或 .env 的操作都被直接拒绝——即使通过看似无害的动词，因为 cat ~/.ssh/id_rsa 是一个应用到秘密上的只读工具。只有分类器无法分类的情况才会升级。

升级操作以客户端支持的最佳级别运行，在启动时确定，并通过 dsh_list 报告：

每个级别都在故障时关闭。无法访问的监督者、超时、格式错误的请求或既不支持两种能力的客户端都会产生拒绝，绝不会批准。

升级顺序是逐步走的，而不是一次性选择：一个出错的级别会降级到下一个级别，因此一个丢弃了 sampling（在 2026-07-28 规范修订版中已弃用，但至今仍可工作）的客户端会降级为询问你，而不是拒绝所有请求。一个超时的级别不会降级；未回答的问题就是“否”，而在另一个渠道重新询问只会加倍等待时间。

设置 DSA_SUPERVISOR=off 可完全禁用该门控。

展示给监督者的是结构化的事实，而非子代理的叙述：工具、每个管道段中的程序，以及命令中每个路径及其是否在工作区内的标志。子代理既编写命令，也编写对其的任何理由，能够为自己辩护的子代理会这样做。无法静态解析的路径（如 $TMPDIR/out.txt）会被报告为未解析而非猜测，并视为外部路径。

examples/claude_supervisor.py 针对真实的 Claude 运行整个模式，适用于那些不自身声明 sampling 的客户端：

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

上限与成本

委托的代理在循环中消耗你的资金，因此四个独立的上限对其进行约束，每次运行都会报告使用了多少。

没有中途取消的机制，因此每次停止都是杀死进程。因上限而终止始终优先于运行本身报告的任何结果：杀死进程后的输出绝不会被视为成功。

dsh_delegate、dsh_await 和 dsh_list 都会报告 token 使用情况——包括输入、输出、缓存读取和写入，以及步数——这些数据来自提供商的报告。每步的输入是故意累加的：每次请求都会对整个重新发送的前缀计费，因此总和才是委托的实际成本。

配置

每个设置都是服务器进程上的环境变量。

在依赖此方案前应了解的局限性

以下限制来自 Harness SDK 线路协议，而非本地选项。

• 文件系统沙箱不覆盖 bash。 dsh-fs-sandbox 将模型的 write/edit 工具限制在工作区内，但 dsh-bash-sandbox 未包含在捆绑的运行时可执行文件中，因此 bash 本身不受约束。监管者弥补了这一点——它在执行前对所有工具（包括 bash）进行把关。当 DSA_SUPERVISOR=off 时，bash 完全没有边界；请将其指向一个分支或临时目录。

• 沙箱仅限制文件影响 —— 不限制网络、进程或系统调用。并且 workspace-write 模式允许访问 /tmp 以及工作区根目录。

• 取消会杀死进程。 线路上没有回合中取消机制，因此 dsh_cancel 会终止运行时。已写入的编辑内容仍保留在磁盘上，且会话无法在之后恢复。

• 被回收代理的会话已消失，但其结果不会消失。 超过 DSA_IDLE_TIMEOUT 后进程被释放；dsh_await 和 dsh_transcript 仍可在其已完成运行上工作，而 dsh_continue 则不行。

• 会话与进程生命周期相同。 没有逐会话的关闭机制，因此内存会随代理的历史记录增长。请取消你已完成操作的代理。

• 上游为开发者预览版。 deepseek-harness-sdk 固定为 ==0.1.0rc7；一周内发布了两个候选版本。预期线路协议会有变动。

开发

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

实时测试需要真实的密钥并消耗令牌；它们不被 pytest 收集：

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md 包含架构和上游约束；wiki/ 包含决策记录和测量数据。

许可证

MIT。