iomgaa
e09362dcd1
VT migration abandoned (v1.0 scope becomes two projects), Q1 resolved to Gitea PyPI, Q6 resolved as judge exemption (unwired zero-consumer eval scaffolding), migration docs annotated with implementation errata, and the reference/ read-only rule clarified for the worktree workflow.
77 lines
9.1 KiB
Markdown
77 lines
9.1 KiB
Markdown
# PolyGateway 开发路线图
|
||
|
||
> **定位**: ARCHITECTURE.md §12 里程碑表的展开——论述开发**顺序及其理由**、每阶段的交付物与验收出口。本文档是**活文档**:里程碑动工、完成、变更时更新状态;与 ARCHITECTURE.md 冲突时以后者为准(或先修订后者)。
|
||
> **流程约束**: 每个里程碑动工前,按 SOP 产出该里程碑的功能设计文档(`designs/`,≤400 行,人类门);本文档不替代设计文档,只定顺序与验收。
|
||
|
||
## 0. 排序的四条原则
|
||
|
||
1. **每个里程碑结束都有真实接入方**——排序服务于"最快让真项目用上",防止造没人用的空中楼阁(ARCHITECTURE §11 的验收哲学)。这就是 M1 先做内存后端(GovDoc/Video-Tree 可接)、M2 才做 Redis 后端(CHSAnalyzer 需要)的原因。
|
||
2. **公共承诺最先冻结**——types/errors/ports 是三项目要消费的公共 API,返工代价最大,放在一切实现之前设计并过人类门;`LLMResponse` 字段从冻结起只增不删(ARCHITECTURE §5.1)。
|
||
3. **单进程能力先于分布式**——内存版限流/熔断先行,语义契约先在单进程下被测试钉死,Redis 后端随后实现**同一套契约**(双后端 D3),避免两个后端语义漂移。
|
||
4. **纯函数与叶子模块先行**——看门狗、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 | ✅ 完成(2026-07-20;239 测试全绿、覆盖 92%、真实网关+真实 Redis 验收通过、独立 verifier 问题清零;见 designs/2026-07-20-m1-core-design.md 状态行) |
|
||
| M2 分布式 | Redis 限流/熔断后端、多源 × Redis 联合验证、背压、Postgres 遥测、成本、Embedding(Q3)、压测 harness | CHSAnalyzer(治理) | ✅ 完成(2026-07-21;契约双后端全绿 + 时间语义真实等待变体 10/10、跨连接联合验证、CHS 对标十项打钩、P3 真实验收 300 次双进程七不变量 PASS、独立 verifier 0 Critical 且 Important 清零;见 designs/2026-07-20-m2-distributed-design.md 与 findings/m2-verifier-fixes.md。压测收官: P5 故障混编 40 次八不变量 PASS,P6 首跑 58.1% 暴露三大治理盲区(findings/2026-07-21-p6-soak-baseline.md)→ **M2.5 治理韧性**六轮迭代(双通道熔断/健康选源/AIMD/429 免预算/健康门槛降权/连败抑制)后同场景 **98.96%**、八不变量全 PASS,验收见 findings/2026-07-21-m25-acceptance.md 与 designs/2026-07-21-m25-resilience-design.md) |
|
||
| M3 OCR | OCR 端口族 + MonkeyOCR transport | CHSAnalyzer(全量)、Video-Tree(OCR 升级) | ✅ 完成(2026-07-22;真实服务双端点集成 6 用例全绿(含 Redis 熔断联调与 tables/para_blocks 一致性护栏)、P7 OCR soak 故障池 1500 调用 **99.73%** 且 13 不变量全 PASS(redis 双后端跨进程,findings/2026-07-22-p7-ocr-soak.md)、G1/R9/R10 三缺口销账;见 designs/2026-07-21-m3-ocr-design.md) |
|
||
| M4 迁移验证 | **两项目**(GovDoc→CHS)按 ARCHITECTURE §11 验收,缺口回补,发 v1.0;**Video-Tree-TRM5 项目已放弃,不迁移(2026-07-22 用户拍板)** | GovDoc、CHS | 🔶 迁移验收完成(2026-07-22;GovDoc verifier 清零、CHS 回归 50/50 + verifier 1I3M 全清,见 findings/2026-07-22-m4-acceptance.md);Gitea PyPI 发布待执行 |
|
||
|
||
## 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 自研,单层原则)+ `sources.py`(SourceConfig、round_robin/least_inflight 选源、源冷却备忘) | 依赖错误分类;先于限流接入便于独立测试。**多源完整行为(换源/冷却/多源行为测试)2026-07-20 人类拍板自 M2 提前进 M1**——重试循环每次尝试都要选源,签名与行为一并钉死 |
|
||
| 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 两个项目都完成"最小接入冒烟"**(2026-07-20 人类拍板,自"任一"升格)——不要求全迁移,只要求用 `polygateway` 发起一次真实治理调用替代其 `GovernedLLMClient` 路径跑通;多源换源/冷却行为有内存后端下的行为测试。
|
||
|
||
**环境前置(2026-07-20 拍板)**: Redis 相关集成测试使用**实验室远程 Redis**(本机无 Redis);连接串由人类在 4c 步前提供并写入 `.env`,测试必须使用独立 namespace/db 隔离,禁止触碰在用数据。
|
||
|
||
**主要风险**: 端口签名一旦冻结返工代价大 → 设计文档阶段用三项目现有调用点反推签名(ARCHITECTURE §11 对接点)做纸面验证。
|
||
|
||
## 3. M2 分布式(目标: CHSAnalyzer 治理能力对标)
|
||
|
||
**内部顺序**: ① Redis 限流六道闸(移植 CHS Lua + **契约测试与内存版共用一套**,原则 3)→ ② Redis 熔断(epoch fencing)→ ③ 多源 × Redis 后端联合验证(多 worker 下全局限额/熔断共享;多源本体已随 M1 交付)→ ④ 背压 stall 判定 → ⑤ `telemetry/postgres.py` + `pricing.py` 成本入遥测 → ⑥ Embedding 客户端复用治理栈(Q3 已拍板纳入,2026-07-20)。
|
||
|
||
**验收出口**: 双后端在同一契约测试套件下全绿;多 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`,数值防御校验下沉)→ ③ 接入治理算法件(OcrClient 独立循环,EmbeddingClient 先例;OCR 无 token 计费,Usage 置 0)→ ④ `ResultInvalidError` 语义联调(坏结果不熔断)。
|
||
|
||
**验收出口**: 对真实 MonkeyOCR 服务(LAN)双端点集成测试通过;CHSAnalyzer 的 `MonkeyOcrParseInvoker` 路径可替换;Video-Tree 的裸调 OCR 换库后获得重试/熔断。
|
||
|
||
## 5. M4 迁移验证(目标: 两项目验收,发 v1.0)
|
||
|
||
**范围修订(2026-07-22 用户拍板)**: Video-Tree-TRM5 项目已放弃,退出迁移范围;v1.0 验收标准改为 GovDoc-SaaS 与 CHSAnalyzer 两项目全过。**顺序**: ① GovDoc-SaaS → ② CHSAnalyzer。每项目按其迁移文档执行,原测试全绿 + 真实冒烟 + 真实回归为过关;边界缺口回补进库后重验。全部通过后打 `v1.0.0`,发布至 Gitea PyPI(Q1 拍板)。**执行方式**: git worktree(reference/ 本体停 main 作蓝本,feature 分支在 `~/Projects/m4-worktrees/`);实施记录见 designs/plans/findings 的 2026-07-22-m4-* 三件套。
|
||
|
||
**主要风险**: 迁移中发现隐性行为依赖(参考 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**(2026-07-20) | ✅ 已决 |
|