# DeepSeek Subagent MCP

**Codex 负责规划和审阅，DeepSeek 负责写代码。是否委托，由你决定。**

[CI 模拟测试](https://github.com/sunyifeng11111/deepseek-subagent-mcp/actions/workflows/ci.yml) · [MIT](LICENSE) · **仅支持 macOS** · Node.js 20+ · 无 npm 运行依赖

[快速开始](#快速开始) · [工作方式](#工作方式) · [配置与本地数据](#配置与本地数据) · [工具参考](#工具参考) · [常见问题](#常见问题)

这是一个实验性的本地 MCP 服务。你明确要求使用 DeepSeek 时，它启动一个能够读文件、改代码和运行本地验证的子代理；没有明确委托时，不应调用。不是 OpenAI 或 DeepSeek 官方项目。

> [!IMPORTANT]
> **目前仅支持 macOS。** Windows、Linux 和 WSL2 暂不支持；以下安装与使用说明仅适用于 macOS。

- **手动启用**：说“用 DeepSeek MCP 实现……”即可，参数由 Codex 填写。
- **直接写入**：支持空目录和已有项目，不要求 Git，不创建开发副本或等待合并。
- **保留主模型**：主 Codex 的模型和登录不变；子代理单独使用 DeepSeek API。
- **结果可检查**：提供任务状态、文件差异、验证结果和实际委托提示词。

> [!WARNING]
> 子代理会先修改真实项目，再由 Codex 审阅。失败、取消或超时可能留下部分改动，不自动回滚。相关源码会发送给 DeepSeek，并产生 API 费用；请先备份重要文件并阅读[安全说明](SECURITY.md)。

## 快速开始

在 macOS 上准备好 Node.js 20+、可在终端运行的 Codex CLI，以及 DeepSeek API Key。当前开发验证使用 **Codex CLI 0.147.0**；其他版本的自定义模型兼容性需要另行验证。

```sh
node --version
codex --version
```

### 1. 下载源码

```sh
git clone https://github.com/sunyifeng11111/deepseek-subagent-mcp.git
cd deepseek-subagent-mcp
```

也可以在仓库首页选择 **Code → Download ZIP**，解压后进入该目录。**本 MCP 不需要运行 `npm install`。**

### 2. 保存密钥

在刚下载的 MCP 目录中运行：

```sh
node credentials.mjs set
node credentials.mjs status
```

在提示处粘贴 API Key，按回车保存。输入不会显示在屏幕上；密钥写入当前用户的配置目录，不写进源码或目标项目。

`status` 不显示密钥、不请求 API。`ready: true` 只表示本地找到了凭据，不代表已经验证密钥有效或账户余额充足。

### 3. 注册到 Codex

保持 macOS 终端位于 **MCP 源码目录**，运行：

```sh
codex mcp add deepseek_subagent -- node "$PWD/server.mjs"
```

该命令会记录当前源码的绝对路径，无需照抄别人的目录。以后移动 MCP 文件夹，需要更新注册路径。注册方式见 [Codex MCP 官方文档](https://learn.chatgpt.com/docs/extend/mcp#configure-with-the-cli)。

重新连接 MCP 或重启使用它的 Codex 客户端；可用 `codex mcp list` 查看已配置的服务。无需手动让 `server.mjs` 常驻运行，Codex 会启动它。

### 4. 在目标项目中使用

切换到**你希望修改的项目**，向 Codex 发出明确委托。例如在空目录中：

> 用 DeepSeek MCP 实现：在当前项目创建一个无需安装依赖的 Node.js Hello World 程序，提供 npm start 和中文运行说明。

已有项目也可以直接使用：

> 用 DeepSeek MCP 实现：给订单列表增加状态筛选，沿用现有接口和样式，并补充测试。

预期流程是出现 `implement_task` 的任务 ID，随后查询进度、审阅差异；文件直接出现在目标项目中，不需要初始化 Git 或另行导入。

> [!IMPORTANT]
> 只说“给订单列表增加筛选”不应触发此 MCP。安装、提及或询问 DeepSeek 不等于实施授权。这个规则由 MCP 指引及调用方的 `user_requested` 声明共同表达，不是对用户原话的独立认证。

## 工作方式

1. **Codex 准备任务**：确定本轮目标、必要背景、允许修改范围和验收条件。
2. **MCP 启动子代理**：通过独立 Codex CLI 进程连接 DeepSeek API，返回任务 ID。当前模型为 `deepseek-flash`，默认 `high` 推理。
3. **DeepSeek 实施**：按需读取项目、直接修改文件、运行已有本地验证。提示词禁止安装依赖、执行 Git 管理操作、联网操作或部署；模型 API 通信仍需网络。
4. **Codex 审阅**：查询同一个任务，分页读取实际差异，核对测试结果；有问题时，携带具体反馈发起新的修复任务。

这是 **MCP 管理的独立子代理进程**，不是把 DeepSeek 加进主 Codex 的原生子代理模型列表，也不要求把主 Codex 改成 API 计费模式。不会打开 DeepSeek 网页聊天。

**上下文不共享整段聊天：** Codex 传入任务、接口约定、文件位置、修改范围和验证要求；DeepSeek 自行读取的文件和执行过程留在子代理上下文中。返回主 Codex 的是状态、改动清单、最终摘要、验证结果及 CLI 提供的 `usage`，完整差异按需读取。新的修复任务不会自动继承上一次子代理对话，需要重新传入必要背景和修复反馈。

一次调用只启动一个子代理，不自动拆分为多个代理，也禁止子代理继续派生。同一项目及父子目录不能重叠实施；不同项目的独立委托可以分别运行。

> [!NOTE]
> `ready_for_review` 只表示可供审阅，不代表验收通过；心跳正常也不保证任务有效推进。Codex 不能只看摘要交付，失败后也不应未经用户同意悄悄改为自己代写。

### 直接写入的边界

沿用 CLI 的 `workspace-write` 沙箱，不开启跳过沙箱模式。`allowed_paths` 是提示约束和事后检查，**不是逐文件硬权限**，不能保证阻止项目内所有越界写入。MCP 额外执行的验证命令使用本地用户权限，只应在可信项目中运行。

已有未提交修改作为本轮起点。实施期间请避免其他程序同时编辑相关文件，MCP 无法可靠区分外部编辑。凭据、依赖和生成目录不在改动审计范围内，符号链接目标不跟随；完整风险说明见 [SECURITY.md](SECURITY.md)。

## 配置与本地数据

密钥属于用户，不随目标项目走。macOS 默认配置目录为 `~/Library/Application Support/deepseek-subagent-mcp`。

在 MCP 源码目录运行 `node credentials.mjs path` 可查看密钥文件的准确位置。推荐通过 `set` 写入；如需手动编辑，该文件内容为：

```dotenv
DEEPSEEK_API_KEY=your_key_here
```

macOS 的密钥文件必须限制为当前用户可读写（`0600`）。不要将真实密钥提交到 Git 或粘贴进聊天。

| 环境变量 | 用途 |
| --- | --- |
| `DEEPSEEK_API_KEY` | 优先于用户配置目录中的 `.env` |
| `DEEPSEEK_SUBAGENT_CONFIG_DIR` | 指定配置与任务记录目录；使用绝对路径，不得与目标项目互相包含 |
| `DEEPSEEK_SUBAGENT_CODEX_PATH` | 指定 Codex 可执行文件或 Node `.js` / `.mjs` / `.cjs` 入口的绝对路径 |

环境变量必须对 **MCP 进程**可见；只在某个终端设置变量，不会自动改变已启动的桌面客户端环境。使用环境变量时，可按 [Codex MCP 配置说明](https://learn.chatgpt.com/docs/extend/mcp#stdio-servers)配置 `env_vars` 转发；桌面使用不确定时，优先用上述用户密钥文件方式。

配置目录还保存以下数据，不会生成项目开发副本：

- `tasks/`：任务提示词、状态和结果。
- `direct-changes/`：本轮改动记录。开始前保留允许范围内文件的起始内容；结束后只保留真正改动文件的前后版本，用于差异审阅和必要时人工恢复。范围外变化只报告，不保证留有旧内容。
- `child-runtimes/`：子代理运行时配置和临时凭据。正常结束或取消后删除；强杀或崩溃可能残留。长期保存的 API Key 不会随任务删除。

任务与改动记录**暂不自动过期清理**，可能包含项目源码。确认任务结束且不再需要恢复资料后再手动清理，不要在运行中删除。没有自动回滚工具，人工恢复前也须核对用户后续修改。

## 工具参考

通常只需自然语言委托，不必手填参数。

| 工具 | 作用 |
| --- | --- |
| `implement_task` | 明确委托后启动一个实施任务；会产生 API 费用 |
| `get_task_result` | 查询进度、心跳、改动清单、验证结果和错误 |
| `get_task_diff` | 分页或按文件审阅差异，不再应用代码 |
| `get_task_prompt` | 排查实际传给子代理的提示词与背景 |
| `cancel_task` | 停止子代理及其验证命令，保留已经写入的代码 |
| `status` | 检查本地凭据就绪情况及活动任务，不请求模型 |

只有 `implement_task` 会启动模型。其他工具、连接和初始化不启动新的模型调用，但主 Codex 处理工具返回内容仍会消耗自己的 Token。

<details>
<summary>调用示例、重试规则与当前限制</summary>

以下参数由 Codex 根据当前项目生成：

```json
{
  "user_requested": true,
  "request_id": "orders-filter-001",
  "workspace_root": "/absolute/path/to/your-project",
  "task": "给订单列表增加状态筛选，保留原有交互。",
  "allowed_paths": ["src/orders"],
  "context": "沿用现有 Order 类型，不修改支付逻辑。",
  "acceptance_criteria": "清空筛选恢复全部订单，并补充针对性测试。",
  "test_command": ["npm", "test"]
}
```

同一请求重发须复用 `request_id` 和全部参数，即使任务已结束也不会重新启动。修复任务使用新 ID 与具体反馈；不要因为单次查询超时就重新启动代理，也不要无限高频轮询。后台任务独立于发起请求的进程运行。

| 项目 | 当前限制 |
| --- | --- |
| 初始 `context` | 最多 30,000 字符，不是模型上下文窗口上限 |
| `allowed_paths` | 1–32 个明确相对文件或目录；不接受项目根目录、通配符、凭据或符号链接路径 |
| `reasoning_effort` | `low` / `high` / `max`，默认 `high` |
| 实施超时 | 默认 1,200 秒，可设 60–3,600 秒 |
| MCP 额外验证 | 最长 120 秒；未配置 `test_command` 时为 `skipped` |
| 改动记录 | 单文件 4 MiB，本轮范围总量 32 MiB，项目元数据清单最多 20,000 项 |
| 差异分页 | 每页默认 12,000 字符，最多 24,000；`next_offset=null` 表示读完 |

改动记录超过限制会明确报错，不静默截断。`workspace_changed_since_capture` 非空表示捕获差异后文件又发生了变化，应重新核对当前文件。`usage` 只在 CLI 提供时返回，`null` 不代表零消耗，也不是完整费用账单。

</details>

## 平台支持

**目前仅支持 macOS，已进行真实项目开发验证。Windows、Linux 和 WSL2 暂不支持。** 这是本 MCP 当前的支持范围，不代表 Codex 本身不支持其他系统。

[CI](https://github.com/sunyifeng11111/deepseek-subagent-mcp/actions/workflows/ci.yml) 仍在 macOS、Linux、Windows 上分别运行 Node.js 20、22、24 的语法检查与模拟测试，仅用于开发回归检查。测试通过不代表真实 DeepSeek API 调用、子代理沙箱初始化和文件写入已完成端到端验收，也不构成对其他平台的支持承诺。

不要为了绕过运行失败关闭沙箱。

## 常见问题

**能省 Codex Token 吗？**

目标是把编码和子代理自身的文件探索移出主 Codex 上下文。规划、审阅、工具返回和返工仍有消耗，DeepSeek API 也单独计费；不保证每个任务都省钱或节省固定比例。

**为什么需要 Node.js？必须用 JavaScript 开发吗？**

Node.js 负责运行 MCP 服务、管理子进程和读写任务记录，不是模型本身。目标项目可以使用其他语言，但相关工具链和依赖需要预先准备好，子代理不会自动安装。

**代码会写到 MCP 目录吗？**

不会因为 MCP 安装在那里就写到那里。实际目标由 `workspace_root` 决定；MCP 可以放在任意固定目录，密钥与任务记录另存于用户配置目录。

| 现象 | 如何处理 |
| --- | --- |
| Codex 打开 DeepSeek 网页或找不到工具 | 检查 MCP 是否已注册并重新连接，明确使用已配置的 `deepseek_subagent`；本项目不使用网页聊天 |
| 提示缺少密钥 | 在 MCP 目录运行 `node credentials.mjs set`；检查环境变量和文件是否对 MCP 进程可见 |
| `set` 提示需要交互终端 | 在自己的终端中执行，不要把密钥作为参数交给 Agent |
| 找不到 `node` 或 `codex` | 确认客户端环境可找到它们；必要时在注册命令中填写 Node 绝对路径，并配置 `DEEPSEEK_SUBAGENT_CODEX_PATH` |
| 返回 `project_busy` | 当前项目或父子目录已有任务，继续查询返回的任务 ID，不另开代理绕过 |
| 长时间 `running` | 对照最后活动、实际文件和错误信息判断；需要停止时请求取消，并继续查询直到结束 |
| `needs_attention` / `failed` / `interrupted` | 检查验证失败、越界、审计错误或进程退出；文件可能已改变，先审阅再决定修复 |
| `cancelling` / `cancelled` | 前者尚在停止，后者已停止；两者都不撤销已写代码 |

仍有问题时，请在 [Issues](https://github.com/sunyifeng11111/deepseek-subagent-mcp/issues) 提供最小复现、平台、Node/Codex CLI 版本及脱敏错误。不要上传密钥或私有项目源码。

## 本地开发

```sh
npm run check
npm test
```

`test/` 是自动回归测试，覆盖无 Git 项目、已有修改、重复请求、后台执行、取消、差异、越界报告、凭据清理和跨平台行为。测试使用临时目录与模拟代理，**不请求付费 API**，也不会随 MCP 启动运行。

运行测试需要 Git 作为差异校验器；正常使用 MCP 不需要 Git。测试目录保留在开源仓库中，删除它不会降低日常 Token 消耗。