iomgaa
583c012706
Add research-wiki/migrations/ (govdoc-saas, video-tree-trm5, chsanalyzer): deletion lists, component mappings, call-site inventories, config migration, stepwise rollback plans, legacy behavior audits, and reverse constraints on the library design including flagged architecture gaps.
6.9 KiB
PolyGateway 开发路线图
定位: ARCHITECTURE.md §12 里程碑表的展开——论述开发顺序及其理由、每阶段的交付物与验收出口。本文档是活文档:里程碑动工、完成、变更时更新状态;与 ARCHITECTURE.md 冲突时以后者为准(或先修订后者)。 流程约束: 每个里程碑动工前,按 SOP 产出该里程碑的功能设计文档(
designs/,≤400 行,人类门);本文档不替代设计文档,只定顺序与验收。
0. 排序的四条原则
- 每个里程碑结束都有真实接入方——排序服务于"最快让真项目用上",防止造没人用的空中楼阁(ARCHITECTURE §11 的验收哲学)。这就是 M1 先做内存后端(GovDoc/Video-Tree 可接)、M2 才做 Redis 后端(CHSAnalyzer 需要)的原因。
- 公共承诺最先冻结——types/errors/ports 是三项目要消费的公共 API,返工代价最大,放在一切实现之前设计并过人类门;
LLMResponse字段从冻结起只增不删(ARCHITECTURE §5.1)。 - 单进程能力先于分布式——内存版限流/熔断先行,语义契约先在单进程下被测试钉死,Redis 后端随后实现同一套契约(双后端 D3),避免两个后端语义漂移。
- 纯函数与叶子模块先行——看门狗、SSE 解析、错误翻译这类零依赖组件先落地先测试,为上层提供已验证的地基。
1. 总览与状态
| 阶段 | 内容 | 接入方 | 状态 |
|---|---|---|---|
| P0 奠基 | 调研、ARCHITECTURE.md、CLAUDE.md、skill Fable 5 改造、hooks 硬边界、脚手架(git/pyproject/Makefile/conda 环境/CI 绿) | — | ✅ 完成(2026-07-20) |
| M1 核心 | 内核类型 + httpx transport + 治理中间件(内存后端)+ 缓存 + SQLite 遥测 + 结构化输出 + from_env | GovDoc、Video-Tree | ⬜ 未开始(前置: M1 设计文档过人类门) |
| M2 分布式 | Redis 限流/熔断后端、多源多账号、背压、Postgres 遥测、成本 | CHSAnalyzer(治理) | ⬜ 未开始 |
| M3 OCR | OCR 端口族 + MonkeyOCR transport | CHSAnalyzer(全量)、Video-Tree(OCR 升级) | ⬜ 未开始 |
| M4 迁移验证 | 三项目逐一按 ARCHITECTURE §11 验收,缺口回补,发 v1.0 | 全部 | ⬜ 未开始 |
2. M1 核心(目标: GovDoc / Video-Tree 可试点接入)
内部开发顺序(编号即依赖顺序,同号可并行):
| 步 | 内容 | 顺序理由 |
|---|---|---|
| 1 | types.py + errors.py + ports.py 全量设计与冻结 |
原则 2:公共承诺先行;这是 M1 设计文档(人类门)的主体 |
| 2a | streaming.py 看门狗移植 |
原则 4:纯函数,零依赖,直接移植+补测 |
| 2b | providers.py 注册表 |
叶子模块;transport 的前置(thinking 注入/思考流字段声明) |
| 3 | transports/openai_compat.py(SSE 解析、非流式快路径、错误翻译 §6.2) |
依赖 1/2a/2b;错误翻译是中间件的语义地基 |
| 4a | middleware/retry.py(D13 自研,单层原则) |
依赖错误分类;先于限流接入便于独立测试 |
| 4b | backends/memory/(limiter + breaker)+ 对应中间件 |
语义契约(permit/settle、状态机)在内存版上钉死,契约测试同步交付 |
| 4c | backends/ 缓存(Redis 为主 + 内存)+ middleware/cache.py |
缓存独立于限流/熔断,可并行;key 公式 §7.5 |
| 4d | telemetry/sqlite.py + middleware/telemetry.py(单一 helper 铁律) |
可并行;18 字段 §7.8,pricing 留 M2 |
| 5 | structured/(json_repair + native_schema 双策略) |
依赖 transport 的响应形态 |
| 6 | client.py 组装 + from_env()/from_settings() + gather_bounded |
组装层最后;.env 键名清单在此定稿并回填 .env.example |
| 7 | 端到端验证: 对真实私有网关的冒烟(输出落 tests/outputs/)+ 全新上下文 verifier subagent 审查 |
Phase 2 独立验证门 |
验收出口(exit criteria): make ci 绿(含 import-linter 契约生效,门控解除);单元+集成覆盖 ≥80%;对真实网关冒烟通过;GovDoc 或 Video-Tree 任一项目完成"最小接入冒烟"——不要求全迁移,只要求用 polygateway 发起一次真实治理调用替代其 GovernedLLMClient 路径跑通。
主要风险: 端口签名一旦冻结返工代价大 → 设计文档阶段用三项目现有调用点反推签名(ARCHITECTURE §11 对接点)做纸面验证。
3. M2 分布式(目标: CHSAnalyzer 治理能力对标)
内部顺序: ① Redis 限流六道闸(移植 CHS Lua + 契约测试与内存版共用一套,原则 3)→ ② Redis 熔断(epoch fencing)→ ③ 多源多账号 + 选源策略 + 源冷却备忘 → ④ 背压 stall 判定 → ⑤ telemetry/postgres.py + pricing.py 成本入遥测 → ⑥ (若 Q3 拍板纳入)Embedding 客户端复用治理栈。
验收出口: 双后端在同一契约测试套件下全绿;多 worker 压测下全局限额真实生效(RPM 不超配);CHSAnalyzer 的 limiter/provider_gate/governance 能力对标清单逐项打钩(ARCHITECTURE §11.3);Redis 掉线时降级方向符合铁律(限流/熔断报错、缓存静默)。
主要风险: Lua 脚本移植语义漂移 → 连同 CHS 的 tests/contracts_limiter.py 一起移植并扩充。
4. M3 OCR(目标: CHSAnalyzer 全量可迁、Video-Tree OCR 免费升级)
内部顺序: ① OcrTextResult/OcrLayoutResult 类型 + 两端口(设计文档人类门,因是公共 API)→ ② transports/monkey_ocr.py(两端点:multipart→JSON 与 multipart→ZIP→_middle.json,数值防御校验下沉)→ ③ 接入既有中间件栈(OCR 无 token 计费,Usage 置 0)→ ④ ResultInvalidError 语义联调(坏结果不熔断)。
验收出口: 对真实 MonkeyOCR 服务(LAN)双端点集成测试通过;CHSAnalyzer 的 MonkeyOcrParseInvoker 路径可替换;Video-Tree 的裸调 OCR 换库后获得重试/熔断。
5. M4 迁移验证(目标: 三项目验收,发 v1.0)
顺序(按难度递增,每个项目的缺口回补后再迁下一个): ① GovDoc-SaaS → ② Video-Tree-TRM5 → ③ CHSAnalyzer。每项目按其迁移文档(research-wiki/migrations/<project>.md,含删除清单、调用点映射、配置迁移、分步回滚点、旧版行为审计)执行,原测试全绿为过关;发现的边界缺口回补进库(可能触发小版本迭代)后重验。全部通过后打 v1.0.0,分发方式按 Q1 拍板结果执行。
主要风险: 迁移中发现隐性行为依赖(参考 Video-Tree CLAUDE.md 的"前序版本对照"教训)→ 每项目迁移前先做旧版行为审计(brainstorming skill 已内置该环节)。
6. 后续储备(非承诺,按需求触发)
音频端口实现(D10)、SDK transport(openai/anthropic 原生协议,D2 预留)、GLM OCR invoker(D9 预留)、内网 pip index(Q1)、多项目共用 Redis 的 namespace 治理、harness-eval 评估流水线激活。
7. 开放决策依赖
| 决策 | 阻塞点 | 需拍板时间 |
|---|---|---|
| Q1 打包分发(git+ssh vs 内网 index) | 不阻塞开发,阻塞 M4 发布 | M4 前 |
| Q3 Embedding 是否纳入 | 影响 M2 范围 | M2 设计文档前 |