# M4 迁移验证实现计划(GovDoc → CHS → v1.0)

> **依据**: designs/2026-07-22-m4-migration-design.md(已过人类门 2026-07-22:worktree 工作区、两阶段依赖、judge 走实验室中转)。
> **目标**: 两项目按各自迁移文档完成全量迁移与验收(原测试全绿 + 冒烟 + 回归),缺口回补进库,发 v1.0.0 至 Gitea PyPI。
> **概述**: 先搭 worktree 与 conda 环境并留基线(T0);GovDoc 走 T1-T6(装配净新增为主,风险低);CHS 走 T7-T12(shim + scope 切换 + judge 收编);全过后 T13 发布、T14 文档同步。
> **涉及技术**: git worktree、conda、pip editable、pydantic-settings 多源配置、twine/Gitea PyPI、httpx 事件循环生命周期。

## 0. 全局约定(每个任务都适用)

- **路径**: 库 = `/Users/yuchengzhang/Projects/PolyGateway`(下称 PGW);工作区 = `/Users/yuchengzhang/Projects/m4-worktrees/{GovDoc-SaaS,CHSAnalyzer}`(下称 WT/G、WT/C);蓝本 = `reference/{GovDoc-SaaS,CHSAnalyzer}`(只读,停在 main 作对照)。
- **环境**: GovDoc 用 conda `GovDoc-SaaS`(Py3.11);CHS 用 conda `chs`(Py3.13);库自身用 `PolyGateway`。两项目 Makefile 已硬编码各自环境名,worktree 内直接 `make ...` 即可。
- **硬约束**: reference/ 本体不写;Redis 只用实验室 db3;PG 只用 polygateway 库(严禁 chs_prod 等);凭据先从 PGW `.env` / 用户提供处读真实值再写,读写 `.env` 只在 python 代码内(dotenv);两项目测试不与库 soak 并跑。
- **提交纪律**: worktree 内提交遵循**各自项目**的既有 commit 风格(先 `git log --oneline -10` 核对),英文祈使句、无 AI 签名;每任务至少一个 commit 作回滚点;修复与 commit 分开两次工具调用。
- **测试证据**: 每个行为变更任务出示"先失败后通过"证据;基线/验收控制台输出落 PGW `tests/outputs/m4/`(不提交,验收结论汇入 findings)。
- **缺口口径**: 任一"库能力不足以让原测试通过/原行为复现" = 边界缺口 → 在 PGW 侧走红绿流程回补(feat/m4-migration 分支)→ editable 即时生效 → 项目侧重验;禁止项目侧变通掩盖。

## 1. 文件结构总览

**GovDoc(WT/G,按 migrations/govdoc-saas.md §2 修订版)**
- 删除: `packages/docagent-core/src/docagent_core/llm/`(client/breaker/streaming/redis_cache/telemetry_sqlite/__init__ 六文件)、`packages/docagent-core/tests/test_breaker.py`、`packages/docagent-core/src/docagent_core/retrieval/embedding.py`
- 改写: `packages/docagent-core/src/docagent_core/types.py`(LLMResponse 改 re-export)、`protocols.py`(删 TelemetryRecorder)、`packages/docagent-core/tests/test_imports.py`、`packages/docagent-core/pyproject.toml`(删 redis extra)、根 `pyproject.toml`(加 polygateway 依赖)、`Makefile`(install 行 extras)、`.env.example`(§5 键映射)
- 新增: api lifespan / arq worker 入口的装配段(具体文件在 `src/govdoc/` 内实测后定,现骨架期零 import docagent_core)

**CHS(WT/C,按 migrations/chsanalyzer.md §2 + 设计 §3 漂移修订)**
- 删除: `app/providers/{governance,invokers,selector,streaming}.py`、`app/coordination/{limiter,scripts,provider_gate}.py`、对应自测(`tests/` 内以被删模块为对象的单测,留档清单见 T0)
- 改写: `app/domain/errors.py`(Provider 族删除)、`app/config.py`(治理解析段删)、`app/container.py`(治理装配换库工厂)、`app/ports.py`(限流/熔断端口删;VlmProvider/TableLocator/ProviderOutcome/Usage 保留)、`app/providers/table_locator.py`(消费 OcrLayoutResult)、`app/workers/tracking.py`(except 库异常)、`core/eval/judge.py`(桥接收编)、`.env.example`
- 新增: `app/providers/pgw_shims.py`(PgwVlmProvider;唯一新增文件)

**PGW(库仓库,feat/m4-migration 分支)**: 缺口回补代码(如有)、`pyproject.toml` 版本 bump、ROADMAP/ARCHITECTURE/migrations/CLAUDE.md 文档同步、findings 报告。

## 2. 任务清单

### T0 基础设施与基线(GovDoc + CHS 一次做完)

- [ ] worktree: `git -C reference/GovDoc-SaaS worktree add /Users/yuchengzhang/Projects/m4-worktrees/GovDoc-SaaS -b feat/polygateway-migration`;CHS 同式。验证: 两 worktree 内 `git status` 干净、分支正确;reference/ 本体仍在 main。
- [ ] conda 环境: `conda create -n GovDoc-SaaS python=3.11 -y` → WT/G 内 `make install`;`conda create -n chs python=3.13 -y` → WT/C 内 `conda run -n chs pip install -r requirements.txt -r requirements-dev.txt`。任一失败即停,与用户对齐(设计 §14 风险)。
- [ ] editable 装库: 两环境各 `pip install -e "/Users/yuchengzhang/Projects/PolyGateway[redis,structured]"`(chs 加 `postgres`)。验证: `conda run -n <env> python -c "import polygateway; print(polygateway.__version__)"`。
- [ ] 基线留档: WT/G `make ci`、WT/C `make test`(worktree 内容 = main,即旧版基线)。控制台全文落 `tests/outputs/m4/{govdoc,chs}_baseline.log`,并整理**pass/skip 剖面 + 预期测试增删清单**(G 侧将删 test_breaker.py 及 test_imports 两行;C 侧将删的治理自测文件名逐一列出)至 `tests/outputs/m4/baseline_profile.md`。CHS 侧 requires_db/requires_redis 的 skip 属基线组成部分。
- [ ] 提交点: 无代码变更,不提交;基线文件留盘。

### T1 GovDoc 冒烟 spike(迁移文档 §6-3)

- [ ] 从 PGW `.env` 用 python(dotenv)读实验室网关真实凭据,生成 WT/G `.env`(单源 `LLM__{PROVIDER}__1__*` + `PGW_TELEMETRY_BACKEND=sqlite` + 缓存 namespace=`govdoc-saas` + Redis db3);不提交 `.env`。
- [ ] spike 脚本放 PGW scratchpad(不进 GovDoc 仓库): `from_env()` 装配 → `assert isinstance(client, docagent_core.protocols.LLMProvider)` → `AgentLoop(client, retryable_exceptions=(TransientError, AllSourcesExhausted))` 真实跑一次最小对话 → 打印 LLMResponse 全字段 → 查询遥测 db 该 call_id 行存在。
- [ ] 验证: spike 输出 + 遥测行;失败即首个缺口(按 §0 缺口口径处理)。
- [ ] 提交点: WT/G 仅 `.env.example` 若有同步则提交,否则无提交。

### T2 GovDoc 配置迁移(§6-4)

- [ ] `.env.example` 按 govdoc-saas.md §5 映射改键(平铺 → `LLM__{PROVIDER}__1__*`;新增 namespace/`PGW_*` 键;`REDIS_CACHE_TTL` 语义改 TTL>0 必填,注释说明)。`.env` 同步(python 内改写)。
- [ ] 先失败后通过: 删一个关键键跑 `from_env()` 须报缺配置错(防御验证),补回后通过。
- [ ] 验证: spike 重跑通过。提交点: `git commit`(.env.example + 相关注释)。

### T3 GovDoc 装配进入口(§6-5)

- [ ] 实测 `src/govdoc/` 现有 api 入口(骨架期可能仅 `api/deps.py`);把装配段(约 5 行,设计文档 §7-G4 形态: from_env + AgentLoop retryable_exceptions 显式传参 + lifespan/shutdown 处 `await client.aclose()`)接入 api lifespan;若 arq worker 入口尚不存在则仅 api 侧,并在 commit message 说明。
- [ ] 先失败后通过: 注错测试——用假 transport 抛 TransientError,断言 AgentLoop 步级重试确实触发(防"静默失效",迁移文档 B15)。
- [ ] 验证: `make ci` 绿。提交点: commit。

### T4 GovDoc embedding 迁移(设计 §7-G5)

- [ ] 删 `retrieval/embedding.py`,消费点换 `polygateway.EmbeddingClient`(映射: batch_size→`EMBED__BATCH_SIZE`、dimension 校验→`EMBED__EXPECTED_DIM`、on_usage 回调→改读遥测;retrieval 内调用点以 grep 实测为准)。
- [ ] 先失败后通过: 删除后 retrieval 测试先红,改写消费点后绿;EXPECTED_DIM 不符抛 ResultInvalidError 有断言。
- [ ] 验证: `make ci` 绿。提交点: commit。

### T5 GovDoc 清场(§6-6)

- [ ] 执行 §1 删除清单;`types.py` 改 `from polygateway import LLMResponse`(re-export 一行,conftest 旧 11 字段构造零改动);`protocols.py` 删 TelemetryRecorder;`test_imports.py` 改 import 目标;两处 pyproject + Makefile install 行改 extras(`docagent-core[dev]`,redis extra 删除)。
- [ ] 验证: `make ci` 全绿 + import-linter 过 + `grep -r "docagent_core.llm" packages/ src/` 零命中。
- [ ] 提交点: commit。

### T6 GovDoc 验收

- [ ] 验收公式逐项核对(govdoc-saas.md §1);`make ci` 输出与基线剖面对照(全绿、skip 不增、分母按预期增删清单修正)。
- [ ] 冒烟即回归(设计 §9): spike 复跑 + 重跑同请求断言缓存命中(cache_hit=True)。
- [ ] 全新上下文 verifier subagent(只读)按迁移文档逐条核验,问题清零。
- [ ] 提交点: WT/G 最终 commit;PGW 侧若有缺口回补则库测试同步绿。**T6 全过后才进入 T7。**

### T7 CHS shim 与异常分支(设计 §8-C2;二选一已钉死)

- [ ] 新增 `app/providers/pgw_shims.py`: PgwVlmProvider 骨架(字段映射按 chsanalyzer.md §3,以 WT/C `app/ports.py` 实测签名为准):

```python
class PgwVlmProvider:
    """实现 app.ports.VlmProvider: bytes+instruction → 库多模态 chat → ProviderOutcome。"""
    def __init__(self, client: GatewayClient) -> None:
        self._client = client
    async def complete(self, image: bytes, instruction: str) -> ProviderOutcome:
        data_url = "data:image/jpeg;base64," + base64.b64encode(image).decode()
        resp = await self._client.chat([{"role": "user", "content": [
            {"type": "text", "text": instruction},
            {"type": "image_url", "image_url": {"url": data_url}},
        ]}])
        # 映射按 chsanalyzer.md §3: usage.total_tokens ← prompt+completion,
        # elapsed_s ← latency_ms/1000;Usage/ProviderOutcome 构造以 WT/C ports.py 实测字段为准。
        # 注意库 LLMResponse 无 raw 字段: 实施时 grep ProviderOutcome.raw 消费点,
        # 无消费则置 {},有消费按消费需求组装(如塞 call_id/provider 元数据)。
        return ProviderOutcome(text=resp.content, source_name=resp.source_name,
                               model=resp.model,
                               usage=Usage(total_tokens=resp.prompt_tokens + resp.completion_tokens,
                                           elapsed_s=resp.latency_ms / 1000),
                               raw={})
```

- [ ] 异常分支**不做翻译 shim**,`app/workers/tracking.py` 直接 `except GatewayUnavailableError`(理由: C10 清场本就删除 Provider 错误族,翻译层是死代码;库异常自带 scope/reason/retry_after_s/per_source_reasons,G1 已闭)。arq defer 时长改读 `exc.retry_after_s`(注意 M2.5 后上限 300s,迁移文档追记已声明属期望)。
- [ ] 先失败后通过: shim 字段映射单测(含 per_source_reasons 透传、usage 换算)先红后绿。
- [ ] 验证: `conda run -n chs pytest tests/unit/test_worker_tasks.py <shim 单测> -v` 绿。提交点: commit。

### T8 CHS VLM scope 切换(§8-C3,漂移修订后单段灰度)

- [ ] `app/container.py` VLM 治理装配(约 96 行)换 `GatewayClient.from_env("VLM")` + PgwVlmProvider;extractors/classifiers 经业务端口零改动;灰度期 CacheMW 关闭(`PGW_CACHE_BACKEND=none`,迁移文档 §8 裁决);`.env` 键原样继承(`VLM__QWEN__1__*` 命名即库约定)。
- [ ] **保真校验**(迁移类硬门): 对照 chsanalyzer.md §7 审计表逐条核验迁移后行为(重点: 六道闸语义、预扣结算、探针租约、RequestRejected 二分、429 细分、ResultInvalid 不熔断);发现库侧未落地项即缺口回补。蓝本对照读 reference/CHSAnalyzer(main)。
- [ ] 双实现对拍: 同一小批样本(3-5 张)旧栈(reference 侧代码逻辑,经基线记录)与新栈输出结构对齐;真实调用走实验室网关配额,串行执行。
- [ ] 验证: 提取/分类相关单测 + integration 绿。提交点: commit。

### T9 CHS OCR scope 切换(§8-C4)

- [ ] `table_locator.py` 改消费 `OcrLayoutPort.parse_layout`(约 5 行: 首个 `type=="table"` 元素 + `int()` 四元组,M3 设计 §1.2 已 35 样本取证 bbox 一致);container 装配 `OcrClient.from_env("OCR")`(MonkeyOCR 双端点 10.77.0.20:7866/7867,`OCR__MONKEY__N__TRUST_ENV=false`)。
- [ ] 先失败后通过: table_locator 单测按新返回类型先红后绿;无表样本合法空语义有断言。
- [ ] 验证: `extract_table` integration 全绿(真实 MonkeyOCR)。提交点: commit。

### T10 CHS judge 收编(§6 方案 1,桥接已钉死)

- [ ] `core/eval/judge.py` `_call_llm` 改同步桥接(client 生命周期封在单次 asyncio.run 内,杜绝 httpx 跨事件循环复用):

```python
def _call_llm(self, prompt: str) -> str:
    async def _once() -> str:
        client = GatewayClient.from_env("JUDGE")
        try:
            resp = await client.chat([{"role": "user", "content": prompt}])
            return resp.content
        finally:
            await client.aclose()
    return asyncio.run(_once())
```

- [ ] JSON 解析换库 `JsonRepairStrategy`(删手写 find/rfind);`JUDGE__{PROVIDER}__1__*` 配实验室中转 + claude 模型名(真实值向用户/PGW .env 读取)。**先真实探测一次**中转是否代理该模型;不通即停,回人类门(设计 §6 回退)。
- [ ] 先失败后通过: test_eval_judge 桩测试(含解析失败重问路径)先红后绿 + 真实 judge 调用一次输出落 tests/outputs/m4/。
- [ ] 提交点: commit(judge 独立文件,单独可回滚)。

### T11 CHS 清场(§8-C6)

- [ ] 执行 §1 删除清单;`errors.py` Provider 族删除(业务异常保留);`config.py` 治理解析段删除;`ports.py` 限流/熔断端口删除;`.env.example` 定稿(新增 `PGW_LIMITER_BACKEND=redis`、`PGW_BREAKER_BACKEND=redis`、`PGW_TELEMETRY_BACKEND=postgres` 指 PG polygateway 库、缓存 namespace=`chsanalyzer:{scope}`)。
- [ ] 验证: `make test` 全绿(skip 剖面≥基线,分母按增删清单修正)+ `grep -rE "from app.(providers.(governance|invokers|selector|streaming)|coordination.(limiter|scripts|provider_gate))" app/ core/` 零命中。
- [ ] 提交点: commit。

### T12 CHS 验收与回归

- [ ] 冒烟: 单张真实样本完整提取 pipeline(治理走库,Redis db3 + PG polygateway 库)。
- [ ] 回归对拍: **先与用户商定**样本量/一致率阈值/跑批环境(设计 §9 候选 a: 20-50 张新旧串行对拍);商定前不跑批。
- [ ] 全新上下文 verifier subagent 按 chsanalyzer.md 全文逐条核验(含审计表 26 条、能力对标清单、生产切换手册是否交付),问题清零。
- [ ] 生产切换手册: WT/C `research-wiki/`(或 deploy/ 说明)新增一页——整 scope 原子切换、禁混版 worker、低峰执行、Redis key 前缀自然过期(迁移文档 §6/§8),只交付不代执行。
- [ ] 提交点: WT/C 最终 commit。

### T13 v1.0.0 发布(设计 §10;需用户提供 Gitea token)

- [ ] 先用 0.1.0 做试发布演练: `python -m build` → twine 传 `https://gitea.iomgaa.online/api/packages/iomgaa/pypi` → 临时 conda 环境 `pip install --index-url .../pypi/simple/ polygateway==0.1.0` 回装成功。不通则退 git+https(设计 §5)并告知用户。
- [ ] PGW `pyproject.toml` bump `1.0.0` + changelog(README 或 CHANGELOG 节)→ `make ci` 全绿(发布门)→ build → 上传 → 干净环境回装 `==1.0.0` 并重跑**两项目**测试套件绿 → 两项目 pyproject 定稿 `polygateway[...]==1.0.*` + README/Makefile 记安装命令 → PGW 打 tag `v1.0.0`。
- [ ] token 处置: 用户提供后写 `~/.pypirc` 或环境变量,不入任何仓库。
- [ ] 提交点: PGW commit(bump/changelog)+ 两 worktree 各一 commit(依赖定稿)。

### T14 文档同步与收尾(设计 §15 七项)

- [ ] ROADMAP §1/§5(两项目范围、VT 放弃、状态推进);ARCHITECTURE §11.2 标注 VT 放弃、§13 Q1/Q6 落拍板;migrations/video-tree-trm5.md 头部标注放弃;migrations/{govdoc-saas,chsanalyzer}.md 回写(extras 更正、embedding 拍板、漂移修订、实施结果);CLAUDE.md reference/ 条目加"只读=工作区与 main 检出不变"括注;库 README 加 Gitea 安装命令。
- [ ] findings 报告: `research-wiki/findings/2026-07-XX-m4-acceptance.md`(≤300 行: 两项目验收证据、缺口回补清单、回归数字、发布记录)。
- [ ] 迁移合并后收尾(用户在远端合并 feature 分支后执行): `git -C reference/<proj> pull --ff-only` + `git -C reference/<proj> worktree remove <路径>`。
- [ ] 记忆文件更新(MEMORY.md + scope-decisions: M4 完成态、v1.0 已发、VT 放弃)。
- [ ] 提交点: PGW commit;合并方式交用户定。

## 3. 保真校验声明(迁移类计划必做)

本计划**不向库内迁移新蓝本**(治理代码 M1-M3 已迁毕),但属"库替换项目治理层"的反向迁移——保真对象是**项目旧行为**: 以 migrations/{govdoc-saas §7(17 条),chsanalyzer §7(26 条)} 审计表为准绳,T5/T8/T11 各含逐条核验检查点;"保留"项行为必须复现,"替换/修复"项按表内声明执行,发现表外行为差异先回写迁移文档再动代码。蓝本对照一律读 reference/(main),这是 worktree 方案保住的能力。

## 4. 中断恢复与风险

- 每任务一 commit,任务内失败回退上一 commit;两 worktree 与 PGW 分支互不阻塞(但 T6 门控 T7,T12 门控 T13)。
- 环境创建失败、中转不代理 claude、Gitea 发布不通三事项均"即停 → 与用户对齐",设计 §14 已列缓解。
- CHS requires_db/requires_redis 若需真实后端解锁更多用例,只允许指向实验室 Redis db3 / PG polygateway 库,并在基线剖面注明差异。