# 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](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，最终补丁再次接受写入范围和完整性校验

## Sol 调度并发 DeepSeek 代理

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

```text
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`。

随后调用：

```text
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 或更高版本。

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

Linux/macOS：

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

Windows PowerShell：

```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`：

```bash
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`：

```bash
.venv/bin/deepseek-bridge
```

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

健康检查无需认证：

```bash
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](config.example.toml) 中的 provider 和 MCP 表复制到用户级 `~/.codex/config.toml`，并替换 Python 的绝对路径。Codex 会忽略项目级 `.codex/config.toml` 中的 model provider，因此 provider 必须配置在用户级文件。

将 [deepseek_worker.agent.toml.example](deepseek_worker.agent.toml.example) 复制为：

```text
~/.codex/agents/deepseek_worker.toml
```

把模板中的 `model_catalog_json` 替换为仓库内 [deepseek-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 父线程调度。例如：

```bash
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` 应改为类似：

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

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

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

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

## 配置

| 环境变量 | 用途 | 默认值 |
| --- | --- | --- |
| `DEEPSEEK_API_KEY` | 必需的 API 密钥 | 无 |
| `DEEPSEEK_SECRETS_FILE` | 可选的持久化配置文件路径 | Codex 用户配置目录下的 `mcp-secrets.env` |
| `DEEPSEEK_BASE_URL` | OpenAI-compatible API 地址 | `https://api.deepseek.com` |
| `DEEPSEEK_DEFAULT_MODEL` | MCP 工具未显式传入 `model` 时使用的默认模型 | `deepseek-v4-flash` |
| `DEEPSEEK_BRIDGE_TOKEN` | 可选；非回环监听时必需的本地 Bearer token | 无 |
| `DEEPSEEK_BRIDGE_HOST` | Bridge 监听地址 | `127.0.0.1` |
| `DEEPSEEK_BRIDGE_PORT` | Bridge 监听端口 | `8787` |
| `DEEPSEEK_BRIDGE_TIMEOUT` | 上游请求及流读取超时（秒） | `1500` |
| `DEEPSEEK_BRIDGE_URL` | MCP `bridge_health` 使用的地址 | `http://127.0.0.1:8787` |
| `DEEPSEEK_REASONING_KEY` | 可选的 32 字节 URL-safe Base64 reasoning 加密密钥 | 自动创建持久化密钥文件 |
| `DEEPSEEK_REASONING_KEY_FILE` | reasoning 加密密钥文件 | Agent state 目录下的 `bridge-reasoning.key` |
| `DEEPSEEK_BRIDGE_LEDGER` | Bridge 请求生命周期与 token 用量账本 | reasoning 密钥同目录下的 `bridge-requests.sqlite3` |
| `DEEPSEEK_FLASH_MAX_TOKENS` | Flash 单次 completion budget | `65536` |
| `DEEPSEEK_PRO_MAX_TOKENS` | Pro 单次 completion budget | `98304` |
| `DEEPSEEK_STATE_DIR` | 后台任务数据库目录 | 操作系统的用户 state 目录 |
| `DEEPSEEK_JOB_WORKERS` | 后台并发数 | `2` |
| `DEEPSEEK_AGENT_STATE_DIR` | 自主任务数据库、Bridge日志和worktree目录 | 用户state目录 |
| `DEEPSEEK_AGENT_ROOTS` | 允许代理访问的仓库根目录，多个路径用系统路径分隔符分隔 | MCP启动目录 |
| `DEEPSEEK_AGENT_WORKERS` | 并发自主代理数 | `4` |
| `DEEPSEEK_AGENT_BATCH_LIMIT` | 单批最大任务数 | `8` |
| `DEEPSEEK_AGENT_TIMEOUT` | 单个执行回合硬上限（秒）；包含最后轮询调度余量 | `2880` |
| `DEEPSEEK_AGENT_WAIT_MAX` | 单次长轮询最大等待时间（秒） | `180` |
| `DEEPSEEK_CODEX_BIN` | 内部 `codex` 可执行文件 | 从 `PATH` 查找 |
| `DEEPSEEK_MODEL_CATALOG` | 可选的内部 Codex DeepSeek 模型目录覆盖 | 包内目录文件 |

默认模型为 `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：

```bash
.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，不进入默认测试：

```bash
.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 的输出路径，不能约束原生子代理，也不能识别输入中是否包含敏感数据。