diff --git a/research-wiki/ARCHITECTURE.md b/research-wiki/ARCHITECTURE.md index 0c1e7c0..23bc24e 100644 --- a/research-wiki/ARCHITECTURE.md +++ b/research-wiki/ARCHITECTURE.md @@ -545,8 +545,8 @@ src/polygateway/ | 阶段 | 交付 | 可接入 | |---|---|---| -| M1 核心 | types/errors/ports、OpenAICompat transport(含非流式)、看门狗、RetryMW、内存版限流/熔断、缓存(Redis+内存)、SQLite 遥测、结构化输出双策略、provider 注册表、from_env | GovDoc、Video-Tree | -| M2 分布式 | Redis 限流(六道闸+契约测试)/熔断后端、多源多账号+选源、背压 stall、Postgres 遥测、pricing 成本 | CHSAnalyzer(治理部分) | +| M1 核心 | types/errors/ports、OpenAICompat transport(含非流式)、看门狗、RetryMW、**多源多账号+选源+源冷却备忘(2026-07-20 人类拍板,自 M2 提前——理由: RetryMW 循环与端口签名 M1 冻结,多源行为一并钉死避免 M2 返工)**、内存版限流/熔断、缓存(Redis+内存)、SQLite 遥测、结构化输出双策略、provider 注册表、from_env | GovDoc、Video-Tree | +| M2 分布式 | Redis 限流(六道闸+契约测试)/熔断后端、多源 × Redis 后端联合验证(全局限额跨 worker)、背压 stall、Postgres 遥测、pricing 成本 | CHSAnalyzer(治理部分) | | M3 OCR | OcrText/OcrLayout 端口 + MonkeyOCR transport,走同一治理栈 | CHSAnalyzer(全量)、Video-Tree(OCR 升级) | | M4 迁移验证 | 三项目逐一按 §11 验收,缺口回补 | 全部 | diff --git a/research-wiki/ROADMAP.md b/research-wiki/ROADMAP.md index 3d800f5..93edf49 100644 --- a/research-wiki/ROADMAP.md +++ b/research-wiki/ROADMAP.md @@ -15,8 +15,8 @@ | 阶段 | 内容 | 接入方 | 状态 | |---|---|---|---| | 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(治理) | ⬜ 未开始 | +| M1 核心 | 内核类型 + httpx transport + 治理中间件(内存后端)+ 多源多账号 + 缓存 + SQLite 遥测 + 结构化输出 + from_env | GovDoc、Video-Tree | ⬜ 未开始(前置: M1 设计文档过人类门) | +| M2 分布式 | Redis 限流/熔断后端、多源 × Redis 联合验证、背压、Postgres 遥测、成本 | CHSAnalyzer(治理) | ⬜ 未开始 | | M3 OCR | OCR 端口族 + MonkeyOCR transport | CHSAnalyzer(全量)、Video-Tree(OCR 升级) | ⬜ 未开始 | | M4 迁移验证 | 三项目逐一按 ARCHITECTURE §11 验收,缺口回补,发 v1.0 | 全部 | ⬜ 未开始 | @@ -30,7 +30,7 @@ | 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 自研,单层原则) | 依赖错误分类;先于限流接入便于独立测试 | +| 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 | @@ -38,13 +38,15 @@ | 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` 路径跑通。 +**验收出口(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)→ ③ 多源多账号 + 选源策略 + 源冷却备忘 → ④ 背压 stall 判定 → ⑤ `telemetry/postgres.py` + `pricing.py` 成本入遥测 → ⑥ (若 Q3 拍板纳入)Embedding 客户端复用治理栈。 +**内部顺序**: ① Redis 限流六道闸(移植 CHS Lua + **契约测试与内存版共用一套**,原则 3)→ ② Redis 熔断(epoch fencing)→ ③ 多源 × Redis 后端联合验证(多 worker 下全局限额/熔断共享;多源本体已随 M1 交付)→ ④ 背压 stall 判定 → ⑤ `telemetry/postgres.py` + `pricing.py` 成本入遥测 → ⑥ (若 Q3 拍板纳入)Embedding 客户端复用治理栈。 **验收出口**: 双后端在同一契约测试套件下全绿;多 worker 压测下全局限额真实生效(RPM 不超配);CHSAnalyzer 的 `limiter/provider_gate/governance` 能力对标清单逐项打钩(ARCHITECTURE §11.3);Redis 掉线时降级方向符合铁律(限流/熔断报错、缓存静默)。