本文档由调研结论沉淀而来，是子代理团队接手项目的上下文基线。日期：2026-08-06。
大量开发者把 Codex CLI/Desktop 通过自定义 provider 接入 DeepSeek API 省钱，但发现缓存命中率不高，成本反而上去了。
根因是 DeepSeek 自动前缀缓存的硬约束 + Codex 的 agent 循环天然破坏缓存：
- 字节级精确匹配：只有本次请求前缀与上一次请求完全一致才命中；任何重排/注入/改写都会从字节 0 失效。
- 动态注入：Codex 每轮注入时间戳、随机 nonce、cwd/git 状态等 → 实践中命中率 <20%。
- 工具列表位置：工具渲染在缓存前缀最前面，MCP 服务器连接/重排一次，整个前缀作废。
- 协议转换漂移：Codex 走 Responses API，本地代理转 Chat Completions 时序列化漂移也会破坏前缀。
- 配置变动：SKILL.md / AGENTS.md 频繁修改 = 系统提示词频繁换缓存身份。
- 并行冷启动：多个子代理共享冷前缀，各自独立付一遍 miss 价格。
- 空闲 eviction：长时间思考间隙缓存被踢掉，恢复后重新冷启动。
| 手段 | 原理 | 代表项目 |
|---|---|---|
| 冻结稳定前缀 | system/AGENTS/skill 文件写定不修改，动态内容放尾部 | codex-token-skills |
| 确定性工具排序 | 固定工具渲染顺序，防重排炸 byte 0 | permafrost（33%→71%） |
| env 冻结 + delta | 首轮钉入 cwd/日期/git 状态，后续只发变化行 | permafrost |
| 易变字节剥离 | 去时间戳、nonce、TodoWrite 提醒等无语义字节 | permafrost / popt |
| L0/L1 分层 | 稳定内容置前、动态历史置后 | deepseek-cache-gateway |
| keepalive / 预热 | 空闲原样重放最后请求；启动预发一枪 | deepseek-cache-gateway（首请求 0%→70%） |
| 冷锚点合并 | 并行共享冷前缀时 leader 预热、follower 等待 | permafrost（0%→73%） |
| 严格统计口径 | 分母含 cache_creation，拆分冷启动/复活 | popt |
| 项目 | 定位 | 命中率成果 |
|---|---|---|
| DeepSeek-Reasonix | DeepSeek 原生终端 agent，缓存稳定为硬约束 | 85-99%+ |
| deepseek-cache-gateway | L0/L1 重排 + Responses/Anthropic 适配 + 监控 + 预热 | 99%+ |
| codex-token-skills | Codex skill 层：冻结 skill + 省 token + 文件记忆 | 103 stars |
| codex_with_cc | Codex leader + Claude Code 子代理 + session 复用池 | 98.5% |
| permafrost | Claude Code 代理：冻结前缀 + 合并 + keepalive | 工具重排 33%→71% |
| popt | 透明代理重写 system prompt | 0%→94%，成本降 86% |
| headroom | 压缩代理 + CacheAligner | 60-95% token 削减 |
现状空白：Codex 专属 + 命中率遥测 + 自动修复的闭环。
- 竞品要么是 Claude Code 生态（permafrost/headroom），要么是 skill 层打补丁（codex-token-skills），要么是通用代理（gateway/popt）。没有针对 Codex CLI/Desktop 的完整方案。
- 主打"缓存医生"心智：装上后自动检测哪些东西在破坏缓存（工具重排、动态 env、skill 改动），给出字节级 diff，一键修复，配命中率与省钱可视化。
- 中文社区是主战场（竞品几乎全是中文开发者），运营与口碑比代码本身更值钱。
- 成本仪表盘做钩子：让用户先看到账单，再装优化。
- 绝对金额不大：DeepSeek 本身便宜，个人用户日省几元，付费意愿低 → 走开源 + Star 路线。
- 同质化严重：通用代理/L0-L1/keepalive 手段已被做遍，纯复刻无意义。
- 官方收编风险：DeepSeek 若放宽缓存匹配策略，赛道价值缩水。
- Codex 版本漂移：Responses API 字段、工具格式随版本变化，需持续跟进（maintainer 职责）。
- MVP：透明代理（前缀冻结 + 工具确定性排序 + env delta）+ 严格口径命中率遥测（TUI 状态栏）+ 一键安装/回滚。
- v1：易变字节剥离、L0/L1 分层、字节级破坏点诊断报告、Web 仪表盘。
- v2：keepalive、冷锚点合并、离线缓存模拟器进 CI、多 Codex 版本兼容矩阵。
- 核心代理：零依赖 stdlib Python（便于分发，参照 permafrost）。
- 协议：Responses 透传（2026-08-06 调研确认：DeepSeek 官方原生支持 OpenAI Responses API，
base_url = https://api.deepseek.com+wire_api = "responses"即可直连，无需协议转换）。cache-doctor 是 Codex 与官方接口之间的透明中间层：做前缀稳定化改写后原样转发，保留 tool call / streaming / reasoning。 - 遥测：本地 SQLite/JSONL，不上传任何请求内容。
- 安全：仅监听 127.0.0.1，key 只走环境变量，上游白名单 api.deepseek.com。