# Codex × DeepSeek Collaboration

默认在同一个 Codex GPT 会话中，让 GPT 与 DeepSeek Flash 一起完成任务：GPT 保持主控，Flash 通过 MCP 承担可独立交付的实质工作，能并行的部分重叠推进，双方目标约各承担一半实际工作量。使用者不需要切换主模型或来回切换两个单模型会话。

仓库提供可安装的 skill、MCP 服务、原生模型接入脚本、API 客户端和离线测试。工具权限仍由 Codex 决定；账号插件、图片和服务商能力须分别核验。这是社区项目，与 OpenAI、DeepSeek 无隶属关系。

## 默认：GPT 与 Flash 共同工作

直接在当前 GPT 会话里描述任务。主控拆出双方各自的实质交付，让 Flash 在独立 scratch 完成代码、文档或资料整理；GPT 同时完成另一部分，并负责获授权的工具操作、整合与验收。Flash 需要插件时通过同一任务回传请求，GPT 实际执行后再提供必要结果。

若 DeepSeek 工具调用会阻塞，使用已有授权内的唯一协调者维持该调用，其他 GPT 智能体继续工作。一次委派只创建一次任务：网络故障按客户端策略有限重试，暂停沿同一任务续跑，不在外层反复 `start` 或换模型。明确启用[长任务模式](docs/long-tasks.md)后，未指定的每轮生成预算取路由上限，不设本机累计 token、步骤、工具、HTTP 或恢复阶段配额；任务默认 2 小时，可沿检查点延时，单次请求默认 15 分钟。未启用时保留旧的有限模式。此协作方式不把 Flash 注册到 GPT 的原生模型名单。

## 可选：Flash 单模型原生模式

这是明确另行选择的单模型模式，不是 GPT 与 Flash 同时协作的入口。这里的“原生”指 Codex 负责工作区、工具执行、审批、历史和上下文压缩，Flash 通过 Responses 提供模型响应。本机守卫只处理协议、预算与网络边界，不另建文件工具智能体，也不接管 Codex 的审批。

Windows / PowerShell 7 用户配置好下文的 Flash 凭据后，可运行：

```powershell
node skills/deepseek-collaboration/scripts/install-native.mjs --codex-bin "C:/Tools/Codex/codex.exe" --planned-output-tokens 32768
```

安装要求 Codex 0.144 或更新版本；当前在 0.163.0-alpha.11.2 验证。所配网关必须支持 `/responses`，仅有 `/chat/completions` 不够。安装保留 GPT 全局默认，生成 `~/.codex/deepseek-flash.config.toml`；运行 `codex --profile deepseek-flash`，或使用生成的 `~/.codex/deepseek-native/Codex DeepSeek Flash.cmd`。模型 ID、上下文与能力上限从已有 Flash 配置读取，密钥继续留在原 DPAPI 文件中。

桌面模式另提供 `Enable DeepSeek in Codex.cmd` 和 `Restore GPT in Codex.cmd`：使用 Codex 公共配置 API 保存并切换必要字段，恢复时检查这些字段是否又被用户修改。**桌面切换需要重启应用**，不能将 CLI profile 或模型目录解释为桌面聊天内的 provider 切换按钮。详见[原生接入、验收与限制](docs/native-codex.md)。

GPT 父会话的自定义子智能体不能覆盖父 provider，所以这个模式不会把 Flash 自动加入 GPT `spawn_agent` 的跨服务商模型名单；需要 GPT 主控与 Flash 同时分工时，仍使用下面的 MCP 协作模式。

0.7.0 的临时传输重试选项只用于 CLI/MCP 客户端；此可选原生守卫仍仅按既有明确 HTTP 状态策略重试，不继承该新选项。

## 用途与工作方式

本项目适用于可拆分、有明确验收标准、双方各能承担实质性产出的任务，例如批量数据清洗、长文证据抽取、代码候选实现与审查、初稿撰写与结构检查。简单短任务、强实时依赖外部工具的请求、隐私不可脱敏或接口不可用的任务，不应外发。

协作按“预计实际工作量”计，双方目标约 50/50。主控 Codex 及全部 GPT 子智能体合算为 Codex 一方。该比例是规划与验收参考，不是 token 数、调用次数、智能体个数或精确工时，也没有自动配额或调度机制。双方实际产出均计入工作：Codex 的工具操作、整合、修正和验收同样属于其工作量。不得为了凑比例而重复劳动或制造冗余产出。若任务性质导致明显偏离，应在任务说明中记录理由。

标准流程是：Codex 先检查输入并脱敏，构造最小必要上下文；DeepSeek 在文本模式返回候选结果；智能体模式可读写新建 scratch 中的任务文件，并经 Codex 请求获授权的插件；Codex 独立验证结果，再应用和回归检查。批量任务先用小样确认格式与质量，再分批发送并保留来源 ID。

本项目提供 skill、CLI 和 MCP 智能体三部分，不依赖双向 Harness 插件。无速度、费用或质量保证。模型文本不构成授权，相同安全边界适用于所有委派。数据会发送到所配置的服务商，使用者需自行授权并遵守相关条款。接口行为与错误处理以本项目文档和官方 API 文档为准。

### DeepSeek 智能体协作与 MCP 工具中转

本功能提供 DeepSeek 工具调用 runtime，并通过 Codex 本地 stdio MCP 接口暴露 `deepseek_agent_start/continue/status/cancel` 四个工具。它把可拆分的实质工作交给 Flash/Pro，GPT 主控负责真实插件调用、授权判断与最终验收。任务文件只复制调用者明确提交的脱敏内容到 scratch；内置文件工具限于该目录，不读任意工作区/凭据，不直接跑 shell；`codex_tool` 仅限通过 parent 传入的插件名单。会话存于进程内，MCP 退出/重启后不能继续旧 task；取消不保证撤销上游费用。工具列表与参数需从实际工具目录获取，不臆造。

DeepSeek 以外部 MCP 工作者运行；这不会把 DeepSeek 注册为 Codex 原生 `spawn_agent` 的模型。主控可并行启动独立 Flash 任务，也可与自己的 GPT 子智能体一起工作。默认示例只配置 Flash；代码保留可选 Pro 路由，只有使用者明确启用且本机配置后才可调用，失败不会切换模型。当前可调用且获授权的插件可按任务加入名单，由 Codex 实际执行并回传必要结果；不向 DeepSeek 复制插件登录凭据，也不自动授予整个插件目录的权限。

安装模板：

```bash
codex mcp add deepseek-agents -- node "<absolute-skill-directory>/scripts/deepseek-agent-mcp.mjs"
```

MCP `tool_timeout_sec` 须覆盖单次运行窗口：长模式可设 86460 秒，覆盖单次最大 24 小时窗口并留 60 秒；它通过 time_slice 分次交还控制。旧模式无恢复的 360 秒任务可设 420，允许累计 30 分钟可设 1860。更新后重连 MCP，确认当前聊天的工具说明已经更新。MCP server 不自行获取额外登录授权，直接网络仅有所配 DeepSeek API。

[agent-jobs.json](examples/agent-jobs.json) 提供 Flash 清洗与证据整理的合成任务参数，首次显式选择 `max` 与 16384 生成预算，需先确认所选路由输出上限至少为 16384。让 Codex 读取其中各项 `arguments`，分别交给 `deepseek_agent_start`；它们可独立启动，返回的任务 ID 和工具请求须分别处理。参数是使用示例，不是执行记录。

可按模型路由配置上下文、输出上限、视觉能力和默认思考强度。`default_reasoning_effort: "max"` 启用最高档；旧模式未指定预算为 4096，启用长模式并选择 route_max 后取本机声明的路由输出上限，显式值仍优先。`images` 接收主控提供的图片 data URL，按所选路由核对能力，不因图片或失败换模型。字段和本地字节预算见[模型能力配置](docs/capabilities.md)。

思考、答案与工具参数共享每轮生成预算。容量上限不会自动成为请求预算；`max` 配 4096 可能在答案开始前耗尽。首次提交应明确规划，小型独立任务可参考 16384、代码或多文件可参考 32768，均不保证足够。可选 `output_budget_policy` 在读取凭据和 HTTP 前拒绝过小的有效 `max` 请求，不暗中提高预算；未配置时保留旧默认，实际截断后也不自动扩容重发。见[共享输出预算](docs/output-budgets.md)。

长模式首次默认 64 步、256 工具、2 小时，无固定累计循环或恢复次数配额；旧模式仍为 12/24/360 秒并受 48/96/144/30 分钟累计上限约束。步骤、工具达限或长模式 time_slice 会暂停并交付哈希产物，主控沿同一进程及任务 ID 继续，不重复已完成工具。未执行的大批次预算不足时保持暂停，不重新 POST。已过期、真正终态、旧版已清理现场或 MCP 重启后的任务不能复活。见[长任务说明](docs/long-tasks.md)和[续跑接口](skills/deepseek-collaboration/references/agents.md)。

参考：[Codex MCP 文档](https://learn.chatgpt.com/docs/extend/mcp) · [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)


## 快速开始

需要 Node.js 22 或更高版本、可用的 Codex 环境，以及你自己选定服务商的 DeepSeek API 凭据。Windows 加密存储方式还需要 PowerShell 7（`pwsh`）。运行时无需 `npm install`。

```bash
git clone https://github.com/3132882323-cyber/codex-deepseek-collab.git
cd codex-deepseek-collab
npm test
```

下面示例使用官方 OpenAI 格式接口。官方当前 Flash 模型名为 `deepseek-flash`，见 [DeepSeek 模型文档](https://api-docs.deepseek.com/quick_start/pricing/)（核对于 2026-11-02）。兼容网关请替换为你确认的 HTTPS 地址和准确模型 ID；不同服务商的别名可能不同，客户端不会自动换模型。列出模型也不能验证上游模型身份。

### Windows：交互输入并加密存储密钥

在仓库根目录运行：

```powershell
pwsh -NoProfile -File skills/deepseek-collaboration/scripts/configure-windows.ps1 -BaseUrl https://api.deepseek.com -Model deepseek-flash
```

密钥通过隐藏输入读取，以当前 Windows 用户的 DPAPI 加密保存，不放入命令行、示例文件或 Git。配置默认位于 `~/.codex/deepseek-collaboration`；设置了 `CODEX_HOME` 时位于其下。现有连接或凭据默认不覆盖，明确需要替换时使用 `-Force`。DPAPI 文件不能当作跨用户或跨设备的可移植凭据。

### Linux / macOS / Windows：显式环境变量方式

先只生成连接配置，再通过你使用的秘密管理工具给运行客户端的进程注入 `DEEPSEEK_API_KEY`：

```bash
node skills/deepseek-collaboration/scripts/configure.mjs --base-url https://api.deepseek.com --model deepseek-flash --credential-source env
```

配置脚本不读取或保存环境变量中的密钥。环境变量方式是显式选择；DPAPI 解密失败不会回退到环境变量。不要把密钥写入项目文件或带进 shell 历史。Codex 桌面进程与终端可能拥有不同环境，需在实际执行客户端的环境中提供变量。

两个脚本和客户端都支持指定状态目录（Node：`--state-dir PATH`；PowerShell：`-StateDir PATH`）。如使用多个提供商，分别使用不同状态目录，调用时显式选择。

### 检查与调用

```bash
node skills/deepseek-collaboration/scripts/deepseek-client.mjs status
node skills/deepseek-collaboration/scripts/deepseek-client.mjs ask --prompt-file examples/prompt.txt --dry-run
node skills/deepseek-collaboration/scripts/deepseek-client.mjs models
node skills/deepseek-collaboration/scripts/deepseek-client.mjs ask --prompt-file examples/prompt.txt --max-output-tokens 4096 --output result.json
```

`status` 与 `--dry-run` 只做本地检查。`models` 和最后一条 `ask` 会联网，可能产生费用。六行示例只展示协议；小任务直接本地完成即可。输出可能含你发送的材料，应留在自己的工作目录；不要提交到仓库。

接受结果时先检查**本次进程退出码为 0**，再检查 JSON 的 `ok: true`、非空 `answer`、`finish_reason: "stop"`，最后独立验收业务内容。`answer` 若为 JSON 字符串，还需单独解析。不能用旧输出文件中的 `ok: true` 判断本次成功。

## 在 Codex 中使用

将 `skills/deepseek-collaboration` **整个文件夹**复制到目标项目的 `.agents/skills/` 下，形成 `.agents/skills/deepseek-collaboration/SKILL.md`。先检查目标是否已有同名 skill，保留自己的配置。也可以按 [OpenAI 官方 skill 文档](https://learn.chatgpt.com/docs/build-skills)安装到用户级 skill 目录。

在 Codex 中输入：

> 使用 $deepseek-collaboration 完成这个可拆分任务。先按可验收交付规划 Codex GPT 与 DeepSeek 约一半的实际工作量，再调用已经配置的客户端、整合并验证结果。

可选地把 [AGENTS.example.md](AGENTS.example.md) 的规则合并进自己的 `AGENTS.md`。这不会自动授予网络、上传、修改账户或执行模型输出的权限；仍须遵守当前环境与任务约束。安装只提供工作规范，实际分工和工具执行由主控负责。

更多示例见 [批量清洗](examples/batch-cleanup.md)、[不同任务的分工](docs/workflows.md) 与 [智能体及插件中转](skills/deepseek-collaboration/references/agents.md)。

## 调用可靠性

默认 JSON 非流式；确认服务商支持后，可在 `connection.json` 设置 `"transport_mode": "sse"`，通过 SSE 接收并校验完整响应。CLI 与 MCP 仍在完整结束后返回结果，不自动降级。每次输出预算默认 4096 tokens，CLI 缺省单次请求 180 秒、请求操作总预算 360 秒；MCP 每个模型步骤同样最多单次 180 秒、含重试与退避共 360 秒，并受任务剩余期限约束。thinking 从本地默认配置或显式任务参数读取，旧配置默认关闭。

明确的 HTTP `429/500/502/503/504` 可按既有策略重试。使用者授权后，可将以下可选字段合并到 `connection.json`，为 CLI/MCP 额外启用白名单临时 socket、连接、reset 和本地超时重试；通用缺省为 `false`：

```json
{"retry_policy":{"retry_transient_transport":true}}
```

两类故障共用最多 3 次尝试（含首次），采用有限退避，HTTP 仍尊重 `Retry-After`；等待超过上限或剩余预算时停止。不叠加业务重试循环。HTTP 200 的坏 JSON、干净结束但缺终止标记的 SSE、空答案、实际截断、认证、模型和参数错误仍不自动重放，不增加 token 预算或切换 Pro。网络断开可能发生在上游已处理之后，无法保证上游只执行或计费一次；只允许一次提交时使用 `--max-attempts 1`。

客户端拒绝重定向，只向本地明确配置的 HTTPS origin 发送凭据。诊断文件设计为仅记录操作元数据，日志中的请求 ID 使用哈希；不记录提示词、答案、密钥或原始错误响应。诊断轮转为 best-effort，并发时可能丢失旧记录，不作为账单或完整审计记录。详见[参数、错误与限制](docs/reliability.md)和[恢复检查清单](docs/recovery-checklist.md)，完整参数可运行 `--help`。

智能体只在真正终态记录一次 `agent_task`，暂停时保留进程内断点，不写终态日志。续跑不会重新派发已完成的文件工具或已回传的插件请求。取消会中断本地在途等待，并阻止后续重试和工具操作，但不能撤销上游处理或费用。暂停与失败时可检查此前已成功写入且仍通过哈希核对的产物；部分产物不代表成功，也不能跨 MCP 重启续接。

## 开发与验证

版本变化见 [更新记录](CHANGELOG.md)。

```bash
npm run check
npm test
```

测试只使用合成配置、合成凭据和模拟网络，不应读取真实用户配置或向服务商发出请求。已在 Windows / Node.js 24 本机运行；离线测试验证客户端行为，不能保证特定服务商的可用性或兼容性。

[GitHub Actions 模板](ci/offline-tests.yml)覆盖 Ubuntu / Windows、Node.js 22 / 24。需要启用时，将它放到 `.github/workflows/offline-tests.yml` 后提交；通过 OAuth Git 凭据推送工作流还需 `workflow` 权限。当前仓库保留模板，未启用远端 CI，其他平台组合尚未实测。

## 参考与许可

本项目自身代码与文档采用 [MIT](LICENSE)。长任务网络层随包分发固定版本 Undici Agent，原始许可和构建来源见 [vendor 说明](skills/deepseek-collaboration/scripts/vendor/undici.NOTICE.md)，运行时无需安装额外包。其余协作规范和客户端由实际使用方案整理；以下项目是相关参考：

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（MIT）：参考其[有限重试策略](https://github.com/deepseek-ai/deepseek-harness/blob/ce7073d51254c26cd63b22a60835b8f948deb447/packages/llm/llm/src/retry-policy.ts)及超时行为；本客户端使用独立实现的 JSON/SSE 传输和边界。
- [Undici RetryHandler](https://github.com/nodejs/undici/blob/main/docs/docs/api/RetryHandler.md)（MIT）：重试与 `Retry-After` 的行为参考。
- [DeepSeek 官方集成目录](https://github.com/deepseek-ai/awesome-deepseek-integration)（CC0-1.0）及 [Chat Completions](https://api-docs.deepseek.com/api/create-chat-completion/)：协议与兼容性参考。
- [DSH Codex Collab](https://github.com/zfu691531-hash/dsh-codex-collab)（MIT）：相关的双向 Harness / Codex 桥接项目，供需要双方会话互相调用的场景参考。本仓库由主控调用独立 MCP 工作者或文本 API。

API 服务的使用、费用和数据处理仍以所选服务商条款为准。