DeepSeek MCP Worker and Codex Responses Bridge

本项目包含两个相互独立的本地入口：

• deepseek-mcp：保留原有候选补丁工具，并提供由 Sol 调度的并发 DeepSeek 自主代理池。自主代理只在隔离 Git worktree 中修改和测试，不自动合并到主工作区。

• deepseek-bridge：把 Codex Responses API 转换为 DeepSeek Chat Completions，使 DeepSeek 可以作为原生 Codex custom agent 的模型 provider。

非 DeepSeek 官方项目。调用 DeepSeek API 会发送数据并产生费用，请先阅读 SECURITY.md。

功能

• 同步生成或审查候选补丁：generate_patch、review_patch

• 后台长任务：submit_patch_job、get_patch_job、get_patch_result、cancel_patch_job

• 本地能力查询：get_capabilities（不调用 API）

• Bridge 查询：bridge_health、get_bridge_capabilities

• 自主代理：单任务/批量提交、状态面板、长轮询、结果获取、follow-up、取消和释放

• 严格限制补丁只能修改 allowed_paths 中的路径

• 拒绝二进制补丁、越权路径和超限响应

• 只持久化任务摘要、哈希、聚合进度和已校验结果，不持久化完整提示词、文件上下文或推理内容

• Responses Bridge 支持文本流、串行函数/custom 工具调用、稳定工具别名和 token usage

• Bridge 明确拒绝非流式请求、超过 128 个工具以及 web/image/file-search/computer hosted 工具

• 每个自主写任务使用独立 detached Git worktree，最终补丁再次接受写入范围和完整性校验

Related MCP server: CodePeel MCP Server

Sol 调度并发 DeepSeek 代理

自主代理使用以下调用链：

GPT-5.6 Sol → deepseek-mcp → codex exec → DeepSeek Bridge → DeepSeek
                                     ↓
                              Shell/apply_patch/tests

主仓库必须是干净的 Git 工作区，并位于 DEEPSEEK_AGENT_ROOTS 下。MCP 为每个任务从 当前 HEAD 创建独立 worktree；DeepSeek 可以在其中检查代码、修改文件和运行测试，MCP 不会把结果自动合并到主工作区。

Sol 应先调用 submit_agent_batch，一次提交最多八个任务。批次通过 task_size 明确指定 small（小任务）或 large（大任务）。每个任务提供 task、 write_scope，以及可选的 task_name、constraints 和 model。write_scope 支持仓库 相对文件和 src/** 形式的 glob。提交立即返回 batch_id 和 task_id。

随后调用：

wait_agent_events(batch_id, after_event_id)

任务结束时调用立即返回；否则会聚合期间的进度事件，小任务每 60 秒轮询一次、最多 10 次， 大任务每 180 秒轮询一次、最多 15 次。把返回的 next_event_id 传入下一次调用，直到 all_terminal=true；响应中的 polling 会按任务给出当前次数、剩余次数和是否耗尽。预算由 服务端 scheduler 在任务真正开始执行后逐项计数；排队时间和所有状态查询都不消耗预算，也不会 仅因查询而创建 revision。语义检查点和 scheduler tick 会保存可查询的阶段结果。预算耗尽时， MCP 会停止尚未完成的执行回合，并 使用同一 session 启动只读总结回合；总结时间为普通轮询间隔的 3 倍，即小任务最多 180 秒、 大任务最多 540 秒。总结完成后返回 partial_completed 和经过校验的部分补丁。返回值包含结构化事件、完成结果和 get_agent_dashboard 使用的紧凑状态面板。普通 MCP notification 不负责唤醒模型；长轮询 工具返回本身就是结果进入 Sol 上下文的交接点。

完成后由 Sol 调用 get_agent_result 审查完整或部分补丁、处理多个任务间的冲突、应用补丁并在 主工作区重新测试。不完整的任务可通过 send_agent_followup 恢复同一 Codex session 和 worktree。list_agent_result_revisions 和 get_agent_stage_result 可读取历史阶段；Sol 应在 写入主工作区并验证后调用 record_agent_review，以 revision 和 patch_sha256 记录审核结果。 验收完成后调用 release_agent_task 清理隔离 worktree。

MCP 服务重启后，启动对账会把未完成的任务转成带可审核局部补丁的 partial_completed revision（stop_reason=server_restarted），并保留可恢复的 Codex session 与 worktree； 服务不会在启动时自动续跑或应用任何补丁。Sol 审核后如需继续，调用 resume_agent_task(task_id, prompt) 显式恢复：它只允许恢复 interrupted 或 partial_completed 任务，要求 worktree、base commit、session 与 rollout 文件均存在，复用 原 session、worktree 和模型，并且只重置该任务自身的预算，不影响同批其他任务。多个 MCP 实例共享同一状态目录时，批次的 scheduler lease 保证同一 tick 只被一个实例推进； 实例退出后，另一个实例在 lease 过期后接管并把孤儿任务转为可审核的 partial checkpoint。

结构化编辑（第三阶段）

小任务默认使用确定性结构化编辑（roadmap 6.1）：submit_agent_task / submit_agent_batch 接受 prefer_structured_edits（auto 启发式、on 强制、 off 禁用）。启发式规则：small 任务 + 不超过 3 个 write_scope 模式 + 任务描述 不含重构/跨文件信号时，agent 只读分析 worktree 并在最终消息中输出结构化 edits JSON（path / expected_file_sha256 / operation="replace" / expected_text / replacement / occurrence）；Worker 校验 SHA-256、精确文本 匹配与 occurrence 后确定性应用，再走与直接编辑相同的 git diff 收集与安全校验管线。 校验失败（VALIDATION_FAILED）返回同 session 修复一次；安全拒绝（scope 越界、 symlink、敏感路径等，PATCH_INVALID）不重试。结果 revision 附带 edits_applied 审计字段。能力响应中 structured_edits_supported=true、 structured_edits_routing="auto"。

确定性安全验证（roadmap 6.3）在收集与写回双路径执行：write_scope、symlink 逃逸、 git diff --check、补丁大小、二进制、敏感路径（.env/密钥/凭据文件名与私钥块 内容）、变更文件数（≤50）与 diff 行数（≤20,000）上限；apply_reviewed_result 写回前还会解析补丁目标路径复检 symlink 逃逸。所有校验失败统一为 PATCH_INVALID 错误码。

安装

需要 Python 3.10 或更高版本。

git clone https://github.com/prelearn-code/deepseek-mcp.git
cd deepseek-mcp
python -m venv .venv

Linux/macOS：

.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .
export DEEPSEEK_API_KEY="your-key"

Windows PowerShell：

.venv\Scripts\python.exe -m pip install -U pip
.venv\Scripts\python.exe -m pip install -e .
$env:DEEPSEEK_API_KEY = "your-key"

不要把真实密钥写进 Git、TOML 示例或命令历史。除环境变量外，Bridge 和 MCP worker 会自动读取 Codex 用户配置目录下的 mcp-secrets.env。Linux/WSL 默认路径是 ~/.config/codex/mcp-secrets.env，文件权限必须为 0600：

install -d -m 700 ~/.config/codex
printf 'export DEEPSEEK_API_KEY=%s\n' 'your-key' > ~/.config/codex/mcp-secrets.env
chmod 600 ~/.config/codex/mcp-secrets.env

环境变量优先于文件内容；可通过 DEEPSEEK_SECRETS_FILE 指定其他文件。加载器不会执行 文件中的 Shell，只解析允许的 DeepSeek 配置项，因此同一文件中的其他 MCP key 会被忽略。

启动 Responses Bridge

Bridge 默认只监听本机 127.0.0.1:8787：

.venv/bin/deepseek-bridge

若 key 已写入上述持久化文件，无需先运行 source。

健康检查无需认证：

curl http://127.0.0.1:8787/healthz

本机默认配置只需要 DEEPSEEK_API_KEY。Bridge 仅监听 127.0.0.1，因此 Codex provider 不需要额外认证。若确实需要监听非回环地址，必须另外设置 DEEPSEEK_BRIDGE_TOKEN，Codex 也需用该 token 发送 Bearer 认证；Bridge 会拒绝在无 token 时绑定非回环地址。可通过 --host、--port 或对应的环境变量调整监听地址。

接入 Codex

将 config.example.toml 中的 provider 和 MCP 表复制到用户级 ~/.codex/config.toml，并替换 Python 的绝对路径。Codex 会忽略项目级 .codex/config.toml 中的 model provider，因此 provider 必须配置在用户级文件。

将 deepseek_worker.agent.toml.example 复制为：

~/.codex/agents/deepseek_worker.toml

把模板中的 model_catalog_json 替换为仓库内 deepseek-model-catalog.json 的绝对路径。该目录为 Codex 提供 DeepSeek 的上下文窗口、串行工具和 apply_patch 能力；没有它时未知模型会使用降级元数据，核心编码工具可能不完整。

重启 Codex 后，要求父代理使用 agent_type="deepseek_worker" 创建子代理。使用 fork_turns="none" 或有限的最近轮次，不要复制完整长对话。子代理会出现在 /agent 中，其工具仍由 Codex 执行，Bridge 只负责模型协议转换。模板关闭 hosted web search；如果继承的 MCP、插件或 connector 展开后超过 DeepSeek 的 128 工具限制，需要在该 agent 配置中禁用无关工具。

Codex 0.146 的 Multi-Agent V2 会把子任务正文放入 OpenAI 专用的 encrypted_content，第三方 provider 无法解密。使用 DeepSeek custom agent 时，当前需要由 Multi-Agent V1 父线程调度。例如：

codex -m gpt-5.4 -c 'features.multi_agent_v2=false'

然后要求父线程创建 deepseek_worker。已验证同一 DeepSeek 子线程可以完成代码修改、运行 测试并接受 follow-up。GPT-5.6 父线程当前会强制选择 V2，不适合作为 DeepSeek custom agent 的调度父线程；DeepSeek 作为直接根 provider 不受该限制。

本项目新增的 MCP 自主代理池不使用 Codex Multi-Agent handoff，因此 GPT-5.6 Sol 可以直接 调用 submit_agent_task 或 submit_agent_batch 调度 DeepSeek；这些任务显示在 get_agent_dashboard 中，而不是 CLI 的 /agent 原生线程列表中。

Windows 的 MCP command 应改为类似：

command = "C:/absolute/path/deepseek-mcp/.venv/Scripts/python.exe"

重启 Codex 后运行 codex mcp list，或在 Codex 中输入 /mcp。示例使用 env_vars 转发已存在的环境变量，并将工具审批设为 prompt，因为每次模型调用都可能发送代码并产生费用。

其他支持 STDIO 的 MCP 客户端可用相同入口启动：

/absolute/path/.venv/bin/python -m deepseek_worker.server

配置

默认模型为 deepseek-v4-flash，也支持 deepseek-v4-pro。官方 API 当前使用 POST /chat/completions、JSON Output 和流式响应。

Bridge v2 限制

Bridge v2 默认启用 DeepSeek thinking，并要求串行工具调用。工具轮次的 reasoning_content 会经过带认证加密，以 Responses reasoning item 的不透明内容交给 Codex 保存并在下一轮回传；Bridge 重启后使用持久化密钥恢复。Bridge 不把原始 reasoning 写入普通 日志或任务结果；请求账本只保存状态、终止原因、用量和字符/工具计数。当前仍不支持并行 tool calls、hosted 工具或 Codex Multi-Agent V2 的 OpenAI 专用加密 handoff。Codex 继续负责 thread、上下文压缩、工作区权限和工具执行。

自主代理并发发生在 MCP 任务池层，而不是单个 DeepSeek response 内。内部 Codex worker 关闭 MCP、apps 和继续创建子代理的能力，避免递归调用。MCP重启时仍处于活动状态的任务会 标记为 interrupted；其 worktree 会保留供检查和显式释放，第一版不会自动恢复进程。

finish_reason=length 会映射为 response.incomplete，Agent Job 会从已有 Codex session 和 worktree 做一次同模型恢复；再次耗尽时使用同一已选模型生成只读阶段总结并返回 partial_completed，不会自动把 Flash 升级到 Pro。只有调用方明确指定时才使用 Pro。旧的一次性 Patch Job 仍是兼容接口，长审阅和跨文件修改应使用 Agent Job。

任务执行预算由服务端 scheduler 按墙钟时间推进：小任务保持 60 秒/10 ticks，大任务保持 180 秒/15 ticks。wait_agent_events、dashboard 和结果查询不增加 tick，多客户端查询不会提前 耗尽预算。session、工具/命令完成、文件变化、测试和 agent message 会保存语义 checkpoint； 传输和 reasoning 活动只更新时间。MCP 重启后会从残留隔离 worktree 保存可审核的 partial revision。

测试结果使用 passed、failed、inconclusive 和 not_run。当测试命令的退出码缺失，或 未启用 pipefail 的输出管道可能掩盖真实失败时，结果为 inconclusive，不能作为通过依据。

Sol 使用 record_agent_review 接受精确的 task_id + revision + patch_sha256 后，可显式调用 apply_reviewed_agent_result 写回。写回要求主仓库 HEAD 未变化、工作区干净、scope/hash 匹配 且 git apply --check 通过；同一 revision 不能重复应用。

开发与验证

测试不会调用真实 API：

.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python -m build
.venv/bin/deepseek-bridge --help
.venv/bin/python tests/codex_bridge_smoke.py

真实 DeepSeek 自主代理验收是显式 smoke，不进入默认测试：

.venv/bin/python tests/agent_pool_live_smoke.py
.venv/bin/python tests/agent_pool_live_smoke.py --model deepseek-v4-pro

实网 smoke 会为当前源码启动独立随机端口 Bridge，避免误用机器上仍在运行的旧协议进程。

GitHub Actions 会在 Linux、Windows 和 macOS 的 Python 3.10/3.13 上运行相同验证。

安全模型

返回的补丁和原生子代理生成的修改始终是不可信候选内容。父 Codex 仍需审查完整 diff 并重新运行测试。allowed_paths 只能约束补丁 worker 的输出路径，不能约束原生子代理，也不能识别输入中是否包含敏感数据。