docs: sync M4 outcomes into roadmap, architecture, and migration docs
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.
This commit is contained in:
@@ -525,7 +525,9 @@ src/polygateway/
|
||||
| `protocols.py` 的 `LLMProvider.chat(messages, *, session_id, parent_call_id)` 签名 | 库保持兼容(或一行 shim) |
|
||||
| 倒推的库需求 | `from_env` 工厂(GovDoc 装配层本就缺失,库直接补上)、Postgres 遥测、缓存 key namespace 含租户 |
|
||||
|
||||
### 11.2 Video-Tree-TRM5(难度中)
|
||||
### 11.2 Video-Tree-TRM5(难度中)——**已放弃迁移(2026-07-22 用户拍板: 项目本体已放弃)**
|
||||
|
||||
> 下表保留作历史记录与能力倒推依据(VT 倒推的库能力——多逻辑角色、cache salt、多模态摘要进 hash、OcrTextPort 等——均已交付且被其他消费方使用,不回收);v1.0 验收标准相应改为 §11.1 + §11.3 两项目。
|
||||
|
||||
| 项目侧 | 处置 |
|
||||
|---|---|
|
||||
@@ -564,9 +566,9 @@ src/polygateway/
|
||||
|
||||
| # | 问题 | 建议 |
|
||||
|---|---|---|
|
||||
| Q1 | 打包与分发: 内网 pip index / git+ssh 依赖 / submodule? | git+ssh 起步,稳定后内网 index |
|
||||
| Q1 | 打包与分发 | **已拍板(2026-07-22 用户)**: Gitea PyPI 包注册(gitea.iomgaa.online,内置 registry;twine 上传、项目侧 `pip install --index-url .../api/packages/iomgaa/pypi/simple/`);git+https 留作退路 |
|
||||
| Q2 | Python 最低版本 | 3.11(覆盖三项目: 3.11×2 + 3.13×1) |
|
||||
| Q3 | Embedding 客户端是否纳入。**勘误(2026-07-20,VT 迁移文档 R11)**: 初版称"各有一套独立重试实现"不实——GovDoc 的 `OpenAICompatEmbedding` 有自研退避,但 Video-Tree 的 `RemoteEmbeddingProvider` 是**同步 SDK 裸调、无任何重试**;纳入库还需异步化其端口 | **已拍板(2026-07-20 人类)**: 纳入 M2(消灭无治理的裸调 + 统一重试),含端口异步化;Embedding 端口为公共 API,随 M2 设计文档过人类门 |
|
||||
| Q6 | CHSAnalyzer 的 judge(`core/eval/judge.py`,同步裸调 anthropic SDK)迁移路径: 走 OpenAI 兼容中转网关(零库改动)还是库提供 Anthropic 原生 transport(D2 有端口预留,未排里程碑) | 待人类拍板(CHS 迁移文档 G7) |
|
||||
| Q6 | CHSAnalyzer 的 judge 迁移路径 | **已拍板(2026-07-22 用户)**: M4 实测 judge/core-eval 评估流水线**零调用方、从未接线**(全仓仅自测消费),且实验室网关无 claude 系模型——本轮**豁免不动**,judge.py 原样保留;待评估流水线真正启用时再收编走库(届时裁判模型从网关现有模型选) |
|
||||
| Q4 | conda 环境名 | `PolyGateway` |
|
||||
| Q5 | 本仓库工程脚手架(git init、`.claude/` skills、Makefile、pyproject、import-linter)何时落地 | 本文档终审通过后、M1 编码前一次落地 |
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
| 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 迁移验证 | 三项目逐一按 ARCHITECTURE §11 验收,缺口回补,发 v1.0 | 全部 | ⬜ 未开始 |
|
||||
| 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 可试点接入)
|
||||
|
||||
@@ -58,9 +58,9 @@
|
||||
|
||||
**验收出口**: 对真实 MonkeyOCR 服务(LAN)双端点集成测试通过;CHSAnalyzer 的 `MonkeyOcrParseInvoker` 路径可替换;Video-Tree 的裸调 OCR 换库后获得重试/熔断。
|
||||
|
||||
## 5. M4 迁移验证(目标: 三项目验收,发 v1.0)
|
||||
## 5. M4 迁移验证(目标: 两项目验收,发 v1.0)
|
||||
|
||||
**顺序**(按难度递增,每个项目的缺口回补后再迁下一个): ① GovDoc-SaaS → ② Video-Tree-TRM5 → ③ CHSAnalyzer。每项目按其迁移文档(`research-wiki/migrations/<project>.md`,含删除清单、调用点映射、配置迁移、分步回滚点、旧版行为审计)执行,原测试全绿为过关;发现的边界缺口回补进库(可能触发小版本迭代)后重验。全部通过后打 `v1.0.0`,分发方式按 Q1 拍板结果执行。
|
||||
**范围修订(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 已内置该环节)。
|
||||
|
||||
|
||||
@@ -1,5 +1,13 @@
|
||||
# CHSAnalyzer 迁移文档(迁移即验收)
|
||||
|
||||
> [!NOTE]
|
||||
> **迁移已完成并验收(2026-07-22,M4;回归 50/50、verifier 1I3M 全清)**——worktree 分支 feat/polygateway-migration,证据见 `findings/2026-07-22-m4-acceptance.md` §2,生产切换手册在项目侧 `research-wiki/findings/2026-07-22-polygateway-cutover-runbook.md`。实施对本文的勘误/裁决:
|
||||
> ① **上游漂移(基点 7eb8482)**: positioning 已重构为纯图像模板分类,`PositionCallScheduler`/`load_single_vlm_capacity`/`vascular_positioner.py` 上游已删——§2"load_single_vlm_capacity 保留"、§6-S3"灰度先切 position worker"、§4 的 vascular_positioner 调用点三条作废;VLM 消费点收敛为 extractors/classifiers(pipeline worker 单段切换)。
|
||||
> ② **judge(§4/G7)**: 实测 core/eval/ 零调用方、从未接线,且实验室网关无 claude 系——用户拍板豁免不动(Q6 落定,见 ARCHITECTURE §13)。
|
||||
> ③ **G1 消费形态**: tracking.py 直接 `except GatewayUnavailableError`(无翻译 shim——Provider 错误族随 §2 清场删除,翻译层是死代码);`_TERMINAL` 同步改捕库 `RequestRejectedError`。
|
||||
> ④ **magic bytes 归属**: 审计表"移入库 transport"修订为"移入业务 shim(`pgw_shims._data_url` 逐字保真)"——库 chat 的多模态组装归业务侧(ARCH §11.2 同款边界),transport 不拆 data URL。
|
||||
> ⑤ 装配期守卫(G6 lease/stall)归库 from_env,container 本地守卫与其自测删除;限流契约文件(tests/contracts_limiter.py)已由库契约套件继任后删除。
|
||||
|
||||
> **定位**: 本文是 `ARCHITECTURE.md §11.3` 的展开——库建成后如何合并进 CHSAnalyzer、替换哪些内部组件。与 ARCHITECTURE.md 冲突时**以 ARCHITECTURE.md 为准**。CHSAnalyzer 是三项目中迁移难度最高、能力对标要求最高的一个:库必须先达到其治理能力**逐项对等**(§1 对标清单),迁移才有动机。全部结论基于 2026-07-20 对 `reference/CHSAnalyzer/` 的代码实测(file:line 为证)。
|
||||
|
||||
## 1. 迁移目标与验收定义
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# GovDoc-SaaS 迁移文档(迁移即验收)
|
||||
|
||||
> [!NOTE]
|
||||
> **迁移已完成并验收(2026-07-22,M4;verifier 清零)**——worktree 分支 feat/polygateway-migration,证据见 `findings/2026-07-22-m4-acceptance.md` §1。实施对本文的勘误: ① 文中 `polygateway[redis,telemetry-sqlite]` extras 不存在,实际为 `[redis,structured]`(SQLite 遥测零 extra;docagent-core 本体依赖裸 `polygateway`,因 types.py re-export);② §1"不迁 embedding(待 Q3)"已被 Q3 拍板(2026-07-20 纳入 M2)推翻——实施已将 embedding 换 `EmbeddingClient` + `PgwEmbeddingProvider` 薄适配器(保留文件路径,删 165 行手写实现);③ 装配点净新增为 `api/assembly.py` + app.py lifespan(arq worker 入口骨架期尚不存在,届时按 assembly.py 同款接入)。
|
||||
|
||||
> **定位**: 本文是 `ARCHITECTURE.md` §11.1 的展开——库建成后如何合并进 GovDoc-SaaS、替换其哪些内部组件。它既是 M4 迁移的操作指南,也是 M1-M3 设计的反向约束(库公共 API 必须让本文描述的迁移成立)。**与 ARCHITECTURE.md 冲突时以 ARCHITECTURE.md 为准。**
|
||||
> 证据基线: 2026-07-20 对 `reference/GovDoc-SaaS/` 的代码实测(Read/Grep/wc),所有 file:line 相对该仓库根。
|
||||
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# Video-Tree-TRM5 迁移文档（迁移即验收）
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **本迁移已放弃(2026-07-22 用户拍板: VT 项目本体已放弃,不再迁移)。** 全文保留作历史记录与能力倒推依据——VT 倒推的库能力(R1-R12,含多逻辑角色/cache salt/多模态摘要/OcrTextPort/trust_env/check_health)均已在 M1-M3 交付,不因放弃而回收。v1.0 验收标准改为 GovDoc + CHS 两项目(见 ROADMAP §5)。
|
||||
|
||||
> **定位**: 本文是 `ARCHITECTURE.md §11.2` 的展开——库建成后如何合并进 Video-Tree-TRM5、替换其哪些内部组件。它既是 M4 迁移的操作指南，也是 M1-M3 设计的反向约束（库公共 API 必须让本文描述的迁移成立）。**与 ARCHITECTURE.md 冲突时以 ARCHITECTURE.md 为准。** 全部结论基于 2026-07-20 对 `reference/Video-Tree-TRM5/` 的代码实测（file:line 均为实测证据）。
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user