Skip to content
项目

PsChina/deepseek-as-subagent

在 GitHub 查看

PsChina/deepseek-as-subagent has 60 GitHub stars and 15 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 19:06 UTC. Last push 2026-11-14.

这些数字如何统计

实测星标增长

24小时
0
7天
更新延迟
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Run DeepSeek as a real sub-agent inside Claude Code / Codex CLI — with its own 7-tool agent loop, workspace-scoped file access, and bounded Bash.

人工智能

README.zh-CN.md

原文

deepseek-as-subagent

English · 简体中文

Python License: MIT GitHub stars Glama MCP server MCP Mentioned in Awesome MCP Servers Platforms

让 DeepSeek 或你自己的 OpenAI-compatible 本地模型,在 Claude Code / Codex CLI 里作为真正的 sub-agent运行。 主 Agent 保留主对话、规划、判断与验收;所选模型获得自己的工具循环,负责执行型工作。 Coding API 使用工作区受限写入和有界 trusted_host Bash;独立只读 API 提供不执行命令的纯文件分析。

完整 coding 委派

       Claude / Codex(主 Agent)
         ├─ 普通 coding → delegate_to_deepseek
         └─ 方向可能变化的 coding 任务
                           → start_deepseek → job_id
                                              ├─ send_deepseek_message(job_id, ...)
                                              ├─ get_deepseek_status(job_id)
                                              ├─ cancel_deepseek(job_id)
                                              └─ get_deepseek_result(job_id)
         ▼
       所选模型 coding sub-agent
         │  Read / Write / Edit / Bash / Glob / Grep / NotebookEdit
         │  在工作区内自主读取、修改、运行和测试
         ▼
       结果返回主 Agent
       主 Agent 抽样检查改动 / 测试后再汇报

Coding Bash 在可信宿主机上以 cwd=workspace 运行;它有时限、输出和凭证隔离, 但不是操作系统级沙箱。

只读分析委派

       Claude / Codex(主 Agent)
         ├─ 普通只读分析 → delegate_to_deepseek_readonly
         └─ 方向可能变化的只读分析任务
                           → start_deepseek_readonly → job_id
                                                       ├─ send_deepseek_message(job_id, ...)
                                                       ├─ get_deepseek_status(job_id)
                                                       ├─ cancel_deepseek(job_id)
                                                       └─ get_deepseek_result(job_id)
         ▼
       所选模型只读 sub-agent
         │  Read / Glob / Grep
         │  自主阅读、搜索、review 和静态分析
         ▼
       分析结果返回主 Agent
       主 Agent 核验结论

快速开始

git clone https://github.com/PsChina/deepseek-as-subagent.git
cd deepseek-as-subagent
# 先审查 install.sh 与 requirements.lock,再执行:
./install.sh

需要先安装 Python 3.10–3.12。安装器不会把远程 bootstrap 脚本直接 传给 shell,依赖统一从 requirements.lock 按版本和 hash 校验安装。 之后会注册 MCP server,把 skill + /ds 命令复制到受保护的 generation, 不会修改 shell 启动文件。helper 在核心注册提交后尽力部署;遇到外来目标会保留并告警。

使用 DeepSeek 官方 API 时,POSIX 在 ~/.deepseek-mcp/config.json 配置 key; Windows 设置 DEEPSEEK_API_KEY 环境变量。本地 loopback OpenAI-compatible 服务不需要 DeepSeek key。然后运行 claude,例如:

/ds 检查当前工作区并总结代码结构

升级时会先验证现有运行配置。coding 固定使用 trusted_host;只读 API 固定只使用 Read/Glob/Grep,不依赖容器运行时。

Codex 和其它 MCP 客户端见下方安装说明。

和普通 DeepSeek MCP 有什么不同?

很多 DeepSeek MCP 只暴露一次模型调用。主 Agent 仍然需要自己读文件、整理上下文、再把内容喂给模型,因此只省“思考”成本,不省“读写执行”成本。

本项目为配置的模型提供完整 agent loop:工具调度、文件 I/O、coding 时的命令执行与多轮推理都由模型自己完成。主 Agent 可以直接把一个完整逻辑单元交出去,再拿结果回来验收。

包含什么

  • MCP server(Python,stdio)
  • coding 与只读委派:delegate_to_deepseek / delegate_to_deepseek_readonly
  • 后台可控任务:start_deepseek / start_deepseek_readonly 与共用控制 API
  • Flash / Pro 模型路由:主 Agent 只选稳定档位,用户在配置里控制真实 provider 模型名
  • DeepSeek 本地 agent loop(agent_loop.py)
  • 固定 capability API:coding 为 Read / Write / Edit / Bash / Glob / Grep / NotebookEdit;只读为 Read / Glob / Grep
  • Bash 执行:通过 tool-child 边界运行有界且隔离凭证的 trusted_host
  • 工作区路径边界:文件工具拒绝指向工作区外的符号链接
  • 跨进程执行租约:多个 MCP server 也不能同时对同一工作区执行 DeepSeek
  • Write / Edit / NotebookEdit 的崩溃安全 mutation journal:恢复查询、文件核验、精确确认完成前禁止再次委派;trusted_host Bash 的改动不进入 journal
  • 显式网络重试策略:关闭 OpenAI SDK 内层重试,避免代理/TLS timeout 环境下出现重试叠加
  • Claude Code 的 skill 与 /ds 命令;临时禁用请运行 DEEPSEEK_MODE=off claude

兼容性

四个委派入口新增一个可选参数 model="flash" | "pro"。旧调用不传该参数时仍然合法, 并默认选择 Flash 档。后台任务和恢复工具仍然是增量能力。会写文件的老宿主必须接入 “恢复查询 → 文件核验 → 精确确认”流程,才能继续下一次委派;只读用法无需调整。 健康检查和错误文本包含更明确的诊断信息,不承诺逐字节不变。Provider 使用 OpenAI-compatible Chat Completions API,也包括 DeepSeek 的 兼容端点。 本地 Python 模块签名属于实现细节,不作为稳定公共 API。

安装

Claude Code(默认)

git clone https://github.com/PsChina/deepseek-as-subagent
cd deepseek-as-subagent
./install.sh

然后在 POSIX 编辑 ~/.deepseek-mcp/config.json;Windows 仅设置 DEEPSEEK_API_KEY 环境变量。

Codex CLI

git clone https://github.com/PsChina/deepseek-as-subagent
cd deepseek-as-subagent
bash adapters/codex/install.sh

详细安装、自动派工策略和后台 job 使用方式见 adapters/codex/README.md。

Claude 和 Codex 安装器都会新建隔离运行时,验证配置与 MCP 协议后才切换宿主 注册,并保留当前 generation 与一个上一代 generation 供故障恢复。手工安装时, 如果要启用文件写入工具,Python 运行时必须放在委派工作区之外;不安全的目录布局 会在启动时被拒绝。 两个安装器都会串行化 install/uninstall 事务;若进程被强杀,会故意留下 fail-closed 空锁。只有确认没有安装/卸载进程后才应人工删除该锁。

Cursor / Cline / Claude Desktop / 其它 MCP 客户端

MCP server 本身与客户端无关。先用 pip --require-hashes 安装 requirements.lock,再禁用依赖解析安装本项目,最后把客户端 MCP 配置指向生成的 deepseek-mcp 入口。

使用

先按任务的整个预期生命周期选择能力。只有任务的每一步都只是用 Read、Glob、 Grep 做静态文件分析、且不执行任何命令时,才选择只读;只要任何阶段可能需要 Bash、 测试、build、lint、Git、运行程序、依赖操作、工作区修改,或无法确定是否只读,就选择 coding。

1. 普通同步委派

任务不需要中途干预时,按能力直接使用同步 API:

delegate_to_deepseek(task, context, model="flash")
delegate_to_deepseek_readonly(task, context, model="flash")

model 是可选参数,只允许 flash / pro。普通任务省略即可,默认 Flash;复杂 debugging、 架构级推理、困难多文件推理,或 Flash 已明显不足时才显式选择 Pro。主 Agent 不直接传真实 provider 模型名。

前者用于 coding、Bash、测试或任何可能写工作区的任务;后者只用于静态文件分析。 MCP 请求会一直保持到 DeepSeek 完成。

2. 后台可控委派

对于较长、可能需要中途加指令或停止的任务,先选择对应的后台 API,随后两类 job 都使用同一组控制接口:

start_deepseek(task, context, model="flash") / start_deepseek_readonly(task, context, model="flash") -> job_id
send_deepseek_message(job_id, message)
get_deepseek_status(job_id)
cancel_deepseek(job_id)
get_deepseek_result(job_id)

两个 start_* API 都会很快返回,DeepSeek 在后台 worker 中继续执行,因此同一个 MCP session 后续还能继续发送控制请求。steering 只能更新任务指令,不能改变该 job 已冻结的工具、Bash 可用性或模型档位。

如果 readonly job 后续需要执行命令或修改工作区,应取消或结束它,再用 start_deepseek 新建 coding job;steering 不能升级既有 readonly job。

steering 会在模型 / 工具操作之间的安全点生效。cancel 会立即唤醒 API retry backoff,并及时终止正在进行的 provider 或本地工具子进程。

如果新 steering 在 DeepSeek 已经规划出 tool call、但某个旧 tool call 尚未真正执行时到达,该旧 tool call 会被跳过,DeepSeek 下一轮直接按最新指令重新规划。

每个规范化工作区同一时间只允许一个 DeepSeek execution,包括由不同 MCP server 进程启动的执行。这个租约只协调 DeepSeek MCP execution,无法阻止主 Agent、IDE、用户或其它本地进程修改工作区。coding 后台 job 运行期间,主 Agent 应优先通过 steering、status 或 cancel 控制该 job,不要同时独立修改同一工作区;等 job 进入终态后再恢复主 Agent 侧写入。后台 job ID 与结果只在当前 MCP session 内有效,关闭宿主前应先取回结果。

3. mutation 恢复

通过 Write、Edit、NotebookEdit 提交的 mutation 会在 commit 前写入持久 journal。trusted_host Bash 不经过这套事务 journal,它可以直接修改、重命名、 删除或生成工作区文件,这些变化不会出现在 get_deepseek_recovery 中。如果 coding 任务中 Bash 可能已经执行后发生取消、断连或异常中断,应先独立检查工作区状态再继续 或重试。结果报告 journal mutation,或发生取消、断连、MCP 重启后,先执行:

get_deepseek_recovery()
# 逐项核验实际文件
acknowledge_deepseek_mutations(transaction_ids)

精确确认这些 transaction ID 前,新委派会 fail closed。恢复操作不依赖有效的 DeepSeek API key,也不会删除或回滚工作区文件。

Claude Code 辅助入口

  • delegate_to_deepseek / delegate_to_deepseek_readonly —— Claude 自动选择 capability 与 Flash/Pro 档位
  • /ds <task> —— 强制同步委派
  • pure —— 本次 Claude 会话禁用 DeepSeek

网络重试

项目显式设置 connect/read/write/pool timeout,并在创建 OpenAI-compatible client 时设置:

max_retries=0

重试只由项目自己的 _call_with_retry() 负责,只对网络错误、429 和 5xx 做有限外层重试。这样可以避免“SDK 内层重试 × agent loop 外层重试”导致一次 TLS handshake timeout 被放大成多轮长等待。

委派什么时候最划算

委派决策最好发生在主 Agent 大量读源码之前,否则主 Agent 和 DeepSeek 会重复读取同一批文件。

适合:

  • ✅ 多文件实现、机械重构、补测试
  • ✅ 日志扫描、ETL、批量转换
  • ✅ 明确、可独立验收的完整逻辑单元

不适合:

  • ❌ 极小修改,派工开销反而更大
  • ❌ 跨领域架构、模糊根因分析、安全敏感判断

架构

┌─────────────────────────────────────────────────────────────────┐
│  Claude Code / Codex CLI(主 Agent)                            │
│    ↓ stdio(本地 MCP)                                         │
│  deepseek-as-subagent(Python MCP 进程)                        │
│    ├─ 同步 delegate                                             │
│    └─ 可 steering 的后台 job manager                            │
│         ↓                                                       │
│       coding agent loop + 工作区受限工具                         │
│    ↓ 配置的 OpenAI-compatible API                               │
│  DeepSeek API 或本地 endpoint                                   │
└─────────────────────────────────────────────────────────────────┘

本项目不引入第三方代理或云中转。委派任务、模型消息,以及 agent 选择读取的文件/工具输出会发送到配置的 OpenAI-compatible API;只应委派该端点获准接收的数据。

配置

~/.deepseek-mcp/config.json:

{
  "api_key": "sk-...",
  "flash": "deepseek-flash",
  "flash_reasoning_effort": "high",
  "pro": "deepseek-v4-pro",
  "pro_reasoning_effort": "high",
  "_reasoning_effort_options": ["provider-default", "none", "low", "high", "max"],
  "max_turns": 50,
  "max_run_seconds": 18000,
  "allowed_tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "NotebookEdit"]
}

flash 和 pro 配置两个 MCP 档位对应的实际模型名。Claude/Codex 仍然只传 model="flash" 或 model="pro"。

flash_reasoning_effort 和 pro_reasoning_effort 可配置为 provider-default、none、 low、high 或 max。字段缺失或设为 provider-default 时,不发送 reasoning 参数, 由 provider 使用自己的默认行为。none 表示关闭 DeepSeek thinking;其余三档会显式开启 thinking 并使用对应 effort。_reasoning_effort_options 只是配置文件里的提示字段,运行时忽略。 新安装器生成的配置会显式把两个槽位都设为 high;连接通用本地服务时,请删除这些字段 或将其设为 provider-default。

本地 / OpenAI-compatible 模型

在现有配置里设置 base_url 和模型 ID。公共的 flash、pro 仍然只是宿主侧的 profile, 两个槽位可以指向同一个模型:

{
  "base_url": "http://127.0.0.1:8080/v1",
  "flash": "your-local-model",
  "pro": "your-local-model",
  "flash_reasoning_effort": "provider-default",
  "pro_reasoning_effort": "provider-default",
  "max_output_tokens": 1024
}

支持实现 OpenAI-compatible /v1/chat/completions 接口的服务,例如 llama.cpp server、 LM Studio、vLLM、SGLang、Ollama 的兼容端点及其他兼容服务。这些是接口层面的例子;本项目 没有声称测试过每个服务版本或模型。模型服务的 base_url 接受合法的 http:// 和 https:// 地址, 也支持部署在局域网另一台机器上的服务。普通 HTTP 不加密,只应在本机或可信局域网使用; 不可信网络请优先使用 HTTPS。

修改安装器生成的配置时,要同时替换上面两个推理强度字段。通用 endpoint 不会收到 DeepSeek 专用的 thinking 扩展;显式设置推理强度时仅发送 reasoning_effort,需要服务支持。 max_output_tokens 控制每轮输出上限(1–16384,默认 16384)。本地上下文较小时应降低此值, 为提示词和累积的工具历史留出空间。

HTTP provider 和 loopback HTTPS endpoint 默认使用 dummy 凭证,不会自动继承 DEEPSEEK_API_KEY 或配置文件里的 api_key,避免把 DeepSeek 密钥误发给本地或局域网 服务(明文 HTTP 下还是明文)。这类服务需要认证时,请在启动 Claude Code 或 Codex 前 显式设置 OPENAI_API_KEY。非 loopback 的 HTTPS 自定义 endpoint 可以使用 OPENAI_API_KEY,也可在 POSIX 配置中设置 api_key;DeepSeek 官方 endpoint 继续使用 DEEPSEEK_API_KEY。Windows 凭证仍只从环境变量读取。

服务至少要支持 /v1/chat/completions 和 OpenAI-compatible tool calling,并提供足够容纳委派 任务及工具历史的上下文,且能返回格式合理的结构化 tool call。模型发出工具调用后,agent loop 会继续执行所选的 Read / Write / Edit / Bash / Glob / Grep / NotebookEdit,再把结果发回模型。 每次委派的 token 预算为 1,000,000,累计所有请求的输入和输出,包括每轮重新发送的历史。 每轮分别对输入和输出取 provider 报告值与本地估算值中的较大者;本地按每 4 个 UTF-8 JSON 字节估算 1 个 token,计入工具 schema,不计 Unicode 转义带来的膨胀。这个估算用于资源 预算兜底,并非精确的 tokenizer。对话历史另有独立的 12 MiB 编码后 JSON 大小限制。 若 endpoint 不返回 usage,这些限制仍然生效;因为 provider 未报告 token 数,返回的 token 计数可能为零。token/历史预算不足时,同步工具结果和 server 日志会显示具体原因。

使用项目已安装的 Python 环境,可以在临时工作区验收真实本地模型:

python scripts/smoke_local_model.py --base-url http://127.0.0.1:1234/v1 --model your-local-model

脚本会验证实际的 Read、Edit、Bash 调用、精确文件内容、验证命令的成功标记、 修改记录核验与确认,以及后续的只读委派; 不会下载模型或修改持久配置。

要进一步验收宿主侧 MCP stdio 调用和主代理向子代理发送消息的流程:

python scripts/smoke_local_mcp.py --base-url http://127.0.0.1:1234/v1 --model your-local-model

脚本使用临时 HOME 和工作区启动当前源码的服务,检查同步编码和只读委派, 核验并确认修改记录,再向 Pro 档后台任务发送随机口令;模型最终回复必须包含该口令。

单独使用 model 字段会同时配置两个槽位;不要与 flash 或 pro 混用。

allowed_tools 为兼容已有配置和校验而保留;它不用于为某次委派选择能力。 MCP API 会在加载配置后应用各自固定的 profile。

max_run_seconds 是单次委派的硬墙钟上限。默认 18,000 秒(5 小时), 可以显式向上调整,但配置可接受的绝对上限是 172,800 秒(48 小时)。 单次 provider 请求在总预算内仍单独限制为最多 180 秒。 同步委派时,MCP 客户端自身的 tool timeout 必须至少是运行上限再加清理 余量;Codex 安装后的默认值是 18,060 秒(5 小时加 60 秒)。

工作区根目录默认跟随启动宿主客户端时的当前目录。它是文件工具的路径边界, 也是 coding Bash 的工作目录;对 trusted_host Bash 而言它不是操作系统级沙箱。 要锁定固定路径,可加:

"workspace": "/abs/path"

运行时可用环境变量覆盖:DEEPSEEK_API_KEY、OPENAI_API_KEY、DEEPSEEK_WORKSPACE、DEEPSEEK_MODE=off。

delegate_to_deepseek 与 start_deepseek 固定使用完整 coding 工具和有界 trusted_host Bash。delegate_to_deepseek_readonly 与 start_deepseek_readonly 固定只给 Read/Glob/Grep,绝不暴露 Bash,也不依赖 Docker/Podman。能力由所选 API 固定,而不是由 task 参数或模型请求决定,整个 job 生命周期都不能改变。具体边界见 SECURITY.md。

卸载

Claude Code:./uninstall.sh。Codex:bash adapters/codex/uninstall.sh。

两个卸载器都只移除自己管理的宿主注册,不会删除项目、DeepSeek 配置/API key、日志或账户。

License

MIT