Codex DeepSeek Subagent Handoff

一套可直接交给 Windows 或 macOS 上的 Codex Desktop 读取并执行的交接包，用于把 deepseek-v4-flash 配置为原生自定义子代理，同时保留用户原来的 OpenAI 主模型和登录方式。

非官方社区项目，与 OpenAI 或 DeepSeek 没有隶属、合作或官方背书关系。使用 DeepSeek API 会产生相应账户费用。

如果你是 Codex 或其他 AI Agent，请从 README_FOR_AGENT.md 开始，并按平台和用户意图路由到对应手册。

目标拓扑

Codex Desktop / OpenAI 主代理（保持不变）
  -> spawn_agent(agent_type="DeepSeek", fork_turns="none")
  -> DeepSeek 官方 Responses API
  -> deepseek-v4-flash
  -> reasoning_effort = max
  -> context_window = 1,048,576
  -> effective_context_window_percent = 95

当前兼容方案会把父模型目录的 multi_agent_version 设为 v1，并设置 features.multi_agent_v2 = false，避免跨 Provider V2 加密任务正文丢失。父模型变化后需运行 repair 并重新验收。

下载

• Windows 交接包
• Windows SHA-256
• macOS 交接包
• macOS SHA-256

SHA-256 是可选的传输完整性校验；日常分享只发送对应 ZIP 即可。

使用方法

1. 下载并解压对应平台 ZIP，保持目录结构不变。
2. 在 Codex Desktop 新任务中提供 START_HERE_FOR_CODEX.md 的绝对路径，并要求 Codex 完整阅读、配置和验收。
3. API Key 不要粘贴到聊天。Windows 使用用户级 DEEPSEEK_API_KEY 或 Credential Manager 隐藏输入 fallback；macOS 使用 Keychain 隐藏输入。
4. 只有当结果为 ready，且原生 child 返回 NATIVE_DEEPSEEK_OK、SQLite 元数据匹配时，才算安装成功。
5. 完全退出并重新打开 Codex Desktop，再新建任务使用 DeepSeek 角色。

卸载时让 Codex 读取包内 UNINSTALL_FOR_CODEX.md。默认正常卸载会恢复配置、移出技能目录并保留凭据与备份；彻底删除凭据或备份必须得到用户明确授权。

$delegate-to-deepseek 编排 Skill

仓库和平台分发包还包含 delegate-to-deepseek。它只在用户显式调用 $delegate-to-deepseek 时触发：OpenAI 主代理先制定架构与计划，把边界清晰的纯文本执行工作交给 DeepSeek，随后检查实际 diff、测试证据并驱动纠正循环。

使用 $delegate-to-deepseek 完成下面任务：
<完整目标、约束、验收与禁止操作>

它依赖已经配置为 ready、重启后可见的原生 DeepSeek 角色；不负责 Provider 配置，也不允许把 Git 推送、PR、Release、生产写入或其他高风险外部动作交给子代理。完整说明见 docs/DELEGATE_TO_DEEPSEEK.md。

验收标准

原生 child 的 $CODEX_HOME/state_*.sqlite 元数据必须精确为：

model_provider = deepseek
model = deepseek-v4-flash
reasoning_effort = max
agent_role = DeepSeek

同时 child 必须精确返回：

NATIVE_DEEPSEEK_OK

不能以模型自述、静态配置或普通 HTTP 请求成功代替双证据验收。

安全边界

• API Key 不进入聊天、TOML、JSON、manifest、测试结果或仓库。
• 写入配置前创建备份；冲突、解析或实时测试失败时回滚。
• 不修改顶层 model 或顶层 model_provider。
• DeepSeek V4 Flash 按纯文本代理使用；图片、视频和截图由主代理先检查并转换为文字事实。
• 不提交真实 $CODEX_HOME、SQLite、sessions、rollout、备份、.env 或凭据导出。

发现安全问题请先阅读 SECURITY.md。

仓库结构

README_FOR_AGENT.md        # Agent 的仓库级执行入口
codex-deepseek-subagent/   # 可安装的跨平台 Codex Skill
delegate-to-deepseek/      # 显式触发的架构主导委派 Skill
docs/DELEGATE_TO_DEEPSEEK.md # 委派 Skill 使用说明
docs/windows/              # Windows 包内手册源文件
docs/macos/                # macOS 包内手册源文件
scripts/build_packages.py  # 标准库、可复现 ZIP 构建脚本
dist/                      # 可直接分发的 ZIP 与 SHA-256

重新构建分发包：

python scripts/build_packages.py

Windows 也可以使用：

python .\scripts\build_packages.py

已验证基线

• Windows：Codex Desktop 26.730.8199.0、内置 codex-cli 0.147.0-alpha.1.2、gpt-5.6-sol 主代理。
• macOS：Codex Desktop 26.730.61309、内置 codex-cli 0.147.0-alpha.1.2、gpt-5.6-sol 主代理。
• 两个平台的实际兼容性仍以目标机器上的直连、原生派发、返回口令和 SQLite 元数据为准；版本号只用于诊断。

上游与授权

管理技能基于 MIT 授权的 oil-oil/codex-deepseek-subagent，保留其原始版权声明。本仓库增加了 Windows 运行时发现、实时用户环境变量/Credential Manager 凭据路径、统一 max/1M/95%、V1 双证据验收、跨平台交接与完整卸载手册。

本项目采用 MIT License。