Skip to content

PLAN.md

Latest commit

 

History

History
144 lines (109 loc) · 10.7 KB

PLAN.md

File metadata and controls

144 lines (109 loc) · 10.7 KB
Raw

cache-doctor 执行计划（PLAN.md）

编制：cache-doctor-planner｜日期：2026-08-06 基线：docs/RESEARCH.md（2026-08-06 调研）+ docs/PRODUCT.md（已按调研修正） 原则：任务粒度 = 子代理拿到可直接开工；每项含负责角色、依赖、交付物、验收标准、预估工作量。

一、MVP 范围界定

一句话：一个本地透明代理，让 Codex → DeepSeek 的请求前缀稳定，从而把缓存命中率从 <20% 拉到 80%+，并让用户看到命中率和省了多少钱。

MVP 必做（In Scope）

  1. Responses 透传代理（非协议转换）：Codex 的 base_url 指向本地代理，代理改写请求后原样转发官方 https://api.deepseek.com/v1/responses，完整保留 streaming / tool call / reasoning。
  2. 前缀稳定化管线：工具确定性排序、instructions 冻结检测、动态字节后置（L0/L1 分层）。
  3. 严格口径遥测：解析 prompt_cache_hit_tokens / prompt_cache_miss_tokens / cache_creation_tokens，本地存储（SQLite/JSONL），CLI 展示命中率、成本、节省估算。
  4. 一键安装/回滚：备份并改写 Codex config.toml（base_url → 127.0.0.1 代理），提供回滚。
  5. 字节级诊断（基础版）：相邻请求前缀 diff，定位动态字节破坏点。

MVP 不做（Out of Scope，标记 v1/v2）

  • keepalive / 冷锚点合并（v2，依赖遥测数据积累）
  • Web 仪表盘（v1，MVP 用 CLI）
  • 自动修复的深度模式（MVP 只做诊断 + 手动一键修复）
  • 离线缓存模拟器进 CI（v2，MVP 只做本地模拟器供开发自测）
  • 多 Codex 版本兼容矩阵（v2）

MVP 成功标准（可测量）

  • 在真实 Codex 工作流中，连续 3 轮以上请求命中率 ≥ 80%（以本代理遥测口径为准）。
  • 代理本身不改变 Codex 功能：tool call、streaming、reasoning 全链路可用。
  • 安装/回滚 5 分钟内可完成，回滚后配置与安装前逐字节一致。
  • 全部核心逻辑有离线单测；e2e 真实 API 成本 < $0.10。

二、架构概览（供 architect 细化，不冻结细节）

Codex CLI / Desktop
   │  base_url = http://127.0.0.1:8688/v1/responses
   ▼
cache-doctor proxy（零依赖 stdlib Python，asyncio）
   ├─ RequestPipeline
   │    ├─ prefix_stabilizer：工具排序 / instructions 冻结 / 动态字节后置
   │    ├─ request_fingerprint：稳定前缀哈希 + 动态字节记录（供诊断）
   │    └─ forwarder：透传上游 /v1/responses（streaming SSE 逐事件转发）
   ├─ ResponsePipeline
   │    └─ usage_extractor：从 response.completed 提取 hit/miss/creation tokens
   ├─ TelemetryStore：SQLite（或 JSONL）本地落盘，不记录 key 与完整 prompt
   ├─ DiagnosticEngine：相邻请求前缀 diff → 定位破坏点
   └─ CLI：install / uninstall / status / diagnose / doctor

接口约定：

  • 监听 127.0.0.1:8688（可配置）；上游默认白名单 api.deepseek.com。
  • API key 只走环境变量或用户配置文件，绝不写入日志/遥测。
  • 代理日志默认不含完整 prompt；遥测只存 token 计数与哈希摘要。

三、任务清单（按依赖排序）

工作量符号：S = ≤0.5 人天，M = 1 人天，L = 2+ 人天。

Phase 0：架构基线（无代码）

ID 任务 负责 依赖 交付物 验收标准 量
P0.1 架构设计：组件/接口/数据流/SSE 处理/配置 schema cache-doctor-architect RESEARCH.md docs/ARCHITECTURE.md 每个组件有输入输出定义；SSE 事件流转完整；配置项有默认值与边界说明；Reviewer 能按此开工 M
P0.2 仓库骨架：目录结构、README 占位、.gitignore、LICENSE cache-doctor-maintainer — 仓库结构 rg --files 可读；README 含项目一句话定位 S

Phase 1：代理骨架（先通后优）

ID 任务 负责 依赖 交付物 验收标准 量
P1.1 配置加载 + 日志模块 cache-doctor-proxy-engineer P0.1 src/cache_doctor/config.py, logging.py 配置缺失/非法时给出可读错误；日志不输出 key S
P1.2 HTTP 服务 + Responses 透传（非 streaming 先通） cache-doctor-proxy-engineer P1.1 proxy 服务器核心 curl 发一个真实 responses 请求能拿到完整响应（e2e 冒烟，成本 < $0.05） M
P1.3 SSE streaming 逐事件透传 cache-doctor-proxy-engineer P1.2 streaming 转发 长响应流式到达不缓冲、不丢事件；tool call 事件完整 M
P1.4 遥测埋点骨架（usage 提取 + 本地存储） cache-doctor-telemetry-engineer P1.2 usage 提取 + SQLite 表 response.completed 的 hit/miss/creation 正确入库；无 usage 时不崩 M

Phase 2：缓存优化管线

ID 任务 负责 依赖 交付物 验收标准 量
P2.1 工具确定性排序 cache-doctor-proxy-engineer P1.2 prefix_stabilizer 排序模块 tools 数组按 type+name 稳定排序，幂等（两次排序结果一致）；函数参数内 key 可选排序；有单测 S
P2.2 instructions 冻结检测 cache-doctor-proxy-engineer P1.2 冻结检测模块 能识别 instructions 是否随请求变化；变化时告警并记录（不阻断） S
P2.3 动态字节后置 / L0-L1 分层 cache-doctor-proxy-engineer P1.2 input 重排模块 稳定内容（instructions、工具、固定上下文）置前，动态内容（时间戳、env diff、历史）置后；默认开启、可配置关闭；有单测 M
P2.4 config.toml 安装器 + 回滚 cache-doctor-codex-engineer P1.1 install/uninstall CLI 安装前备份原始 config.toml；改写 base_url 指向 127.0.0.1:8688；回滚后文件与备份逐字节一致；dry-run 模式 M

Phase 3：遥测与诊断

ID 任务 负责 依赖 交付物 验收标准 量
P3.1 严格口径命中率计算 cache-doctor-telemetry-engineer P1.4 指标模块 分母 = hit + miss + cache_creation；拆分冷启动/复活命中；滑动平均（最近 N 次）；口径有单测覆盖边界 M
P3.2 CLI status（命中率/成本/节省估算） cache-doctor-telemetry-engineer P3.1 status 命令 表格输出：总请求、命中率、今日成本、估算节省；无数据时有提示 S
P3.3 请求指纹 + 相邻前缀 diff cache-doctor-proxy-engineer P1.2 diagnostic 模块 每请求记录稳定前缀哈希与动态字节；相邻请求 diff 能定位动态字节来源（如时间戳字段）；有单测 M
P3.4 doctor 命令（诊断 → 建议 → 一键修复） cache-doctor-codex-engineer P3.3, P2.4 doctor 命令 对构造的「动态污染」用例，diagnose 能指出破坏点，doctor 应用修复并验证 M

Phase 4：测试、审查、发布

ID 任务 负责 依赖 交付物 验收标准 量
P4.1 离线缓存模拟器（本地自测用） cache-doctor-tester P2.3 tests/cache_simulator.py 模拟 DeepSeek 前缀缓存语义（单元匹配/公共前缀持久化/eviction）；可复现「工具重排 → miss」用例 M
P4.2 全量离线单测 + e2e 脚本 cache-doctor-tester P4.1, P2.x 测试套件 + e2e 脚本 python -m pytest 全绿；e2e 脚本真实 API 验证透传 + streaming + 命中率提升（< $0.10） M
P4.3 代码审查（正确性 + 回归） cache-doctor-reviewer P4.2 审查报告 无 P1 级问题；P2 级问题全部修复或有明确处置 S
P4.4 安全审查（密钥/本地服务/SSE 注入） cache-doctor-security-reviewer P4.2 安全审查报告 无密钥泄漏路径；仅监听 127.0.0.1；无命令注入/SSE 注入面；白名单上游 S
P4.5 文档：README + 安装教程 + 缓存杀手清单 cache-doctor-docs-writer P4.2 README.md / docs/INSTALL.md / docs/CACHE_KILLERS.md 新人 10 分钟可安装运行；杀手清单与实现一致 M
P4.6 MVP 版本标签 + CHANGELOG cache-doctor-maintainer P4.3, P4.4, P4.5 v0.1.0 tag + CHANGELOG.md 发布门槛全部满足（测试全量 + 双审查 + 文档） S

四、执行顺序与并行策略

P0.1 → P0.2
  P1.1 → P1.2 → P1.3 ──────────────→ P4.1/P4.2
      ↘ P1.4 → P3.1 → P3.2
  P2.1/P2.2/P2.3 → P3.3 → P3.4
  P2.4 ────────────────────────────→ P3.4
                  → P4.3 + P4.4（双审查并行）→ P4.5 → P4.6
  • Phase 1 串行（骨架必须先通）；Phase 2 的 P2.1/P2.2/P2.3 可并行（同一模块内不同纯函数）。
  • P3.1/P3.2 与 P2.x 无强依赖，可在 P1.4 后立即并行。
  • P4.3 与 P4.4 并行，然后合并处置审查意见。
  • 建议启用 6 并发槽位后，按「P2.1 + P2.2 + P2.3 + P1.4」四路并行推进。

五、风险与回滚点

风险 概率/影响 应对 回滚点
DeepSeek Responses API 实际行为与调研不符（字段/SSE 事件差异） 低/高 P1.2/P1.3 先用真实 API 冒烟验证；若发现协议差异，回到 codex-helper 式转译兜底（保留调研中的转译方案作 fallback） P1.2 验收失败即停，返回 P0.1 重设计
工具排序/重排改变 Codex 行为（工具调用异常） 中/中 排序只改变顺序不改变语义；P4.1 模拟器 + P4.2 e2e 覆盖 tool call 链路；提供开关一键关闭 P2.1/P2.3 有配置开关，可单模块回滚
官方涨价或放宽缓存策略 中/高 MVP 快出（窗口期）；架构保持轻量；涨价反而放大省钱价值，放宽则降级为「可观测工具」 不阻塞，调整宣传定位
Codex 版本漂移（config schema / 请求形状变化） 中/中 安装器带兼容检测；P0.1 配置 schema 版本化 P2.4 回滚命令始终可用
命中率口径被质疑 中/中 严格口径写进 AGENTS.md 与文档，分母含 cache_creation；拆分冷启动/复活 无

六、首个里程碑定义

M1（Phase 1+2 完成）：代理可跑，透传 + 前缀稳定化生效，安装器可用。验证方式：真实 Codex 会话跑 3 轮，遥测显示命中率较基线提升。

M2（Phase 3 完成）：status/diagnose/doctor 三命令可用，用户能"看到病、知道病因、一键治"。

M3（Phase 4 完成 = MVP v0.1.0 发布）：测试全绿 + 双审查通过 + 文档齐备 + 打 tag。

七、下一步（首个执行批次）

  1. orchestrator 或根代理：spawn cache-doctor-architect 执行 P0.1（输入：本计划 + RESEARCH.md）。
  2. 并行 spawn cache-doctor-maintainer 执行 P0.2（仓库骨架）。
  3. P0 验收后进入 Phase 1，spawn proxy-engineer 执行 P1.1→P1.2（真实 API 冒烟）。