claw/docs/superpowers/plans/2026-04-18-g2-remediation-plan.md

G2 家族整改计划

Status: Draft Date: 2026-04-18 Author: Codex Upstream Spec: 2026-04-18-g2-remediation-design.md

Plan Intent

本计划用于把 G2 家族整改设计拆解为可执行任务，目标是把当前线损多模式报表家族从“信号能抓到但主链重建失败”，推进到“至少第一份样本达到候选验证门槛”。

本计划严格限定在 G2 家族整改，不扩展到：

1. G1
2. G3
3. 更大范围真实场景迁移
4. 登录恢复、宿主协议重构或运行时 transport 改造

Success Baseline

整改阶段的最低成功口径固定为：

1. 台区线损大数据-月_周累计线损率统计分析 不再坍缩为 paginated_enrichment
2. 至少该样本能生成 multi_mode_request 结构
3. bootstrap 落到线损主业务承载面
4. modes 至少恢复 month 与 week
5. mode-specific request/response/column/normalize 合同不再为空
6. readiness 不再在核心合同缺失时给出虚高 A
7. 样本结果达到“可进入候选验证”门槛

Scope Guardrails

执行过程中保持以下边界不变：

1. 不切换到 G1/G3 样本执行
2. 不继续补更多同类 G2 观察样本
3. 不在本计划中展开内网人工验证
4. 不在本计划中处理统一登录与隐藏域登录恢复
5. 不发散到 scene skill 平台通用重构

Target Samples

本计划整改与回归只围绕以下三份 G2 样本：

1. 台区线损大数据-月_周累计线损率统计分析
2. 白银线损周报
3. 线损同期差异报表

对应产物路径：

1. examples/real_scene_batch_round1/skills/real-tq-lineloss-report-r1
2. examples/real_scene_batch_round1/skills/real-baiyin-lineloss-weekly-r1
3. examples/real_scene_batch_round1/skills/real-lineloss-period-diff-r1

Workstreams

本计划拆为五条工作流，与上游 spec 一一对应：

1. WS1 G2 archetype 纠偏
2. WS2 bootstrap 纠偏
3. WS3 mode contract 重建
4. WS4 endpoint 去污染
5. WS5 readiness 收紧

Phase Overview

本计划按四个阶段推进：

1. Phase 0：冻结整改基线
2. Phase 1：修正识别与选择
3. Phase 2：重建 G2 合同
4. Phase 3：回归真实样本并产出整改报告

执行顺序固定为：

Phase 0 -> Phase 1 -> Phase 2 -> Phase 3

其中 Phase 1 先于 Phase 2，避免在错误 archetype 和错误 bootstrap 上继续堆模板逻辑。

Phase 0：冻结整改基线

Objective

把当前 G2 家族首轮 blocker、对标口径和验收门槛冻结，避免整改过程中边界漂移。

Tasks

1. 固化三份 G2 样本的当前失败画像
2. 固化 tq-lineloss-report 作为 G2 主锚点参考
3. 固化 G2 候选验证门槛
4. 固化整改阶段只围绕 G2 的边界

Deliverables

1. 本计划
2. 已存在的 G2 blocker 汇总
3. 已存在的第一轮迁移与候选验证报告

Exit Criteria

1. 后续执行不再追加同类 G2 观察样本
2. 不再用“先去内网试试”替代整改闭环

Phase 1：修正识别与选择

Objective

先把 G2 主链判定修正过来，解决 archetype、bootstrap 与 endpoint 污染这三个上游问题。

WS1：G2 Archetype Rectification

Task 1

审计当前 G2 archetype 误判来源，确认：

1. 哪些分页信号在夺权
2. 哪些 mode 信号没有进入主判定
3. 当前 multi_mode_request 与 paginated_enrichment 的优先级冲突点在哪里

Task 2

修改 G2 archetype 判定逻辑，使以下信号在 G2 中具备更高权重：

1. month/week
2. mode
3. tjzq
4. 同一场景内多组线损接口
5. 模式切换分支字段

Task 3

新增或更新回归测试，证明：

1. 当前 G2 fixture 不再判成 paginated_enrichment
2. G2 相关修正不会误伤现有 G3 fixture

WS2：Bootstrap Rectification

Task 4

审计当前 bootstrap 选择逻辑，确认为什么三份样本都稳定落到 20.77.115.36:31051。

Task 5

为 G2 引入更严格的 bootstrap 选择约束：

1. 优先真实线损业务承载页
2. 排除页面壳入口与错误主域
3. 继续排除 localhost:*、第三方库 URL、静态资源 URL

Task 6

新增或更新测试，证明：

1. G2 主样本 bootstrap 不再落到错误入口
2. localhost:* 仍只作为宿主依赖证据保留

WS4：Endpoint Purification

Task 7

审计当前 endpoint 提取污染来源，明确以下类别如何被误收进业务候选：

1. 第三方依赖库
2. 文档外链
3. 静态资源 URL
4. 其他业务系统遗留接口

Task 8

收紧 endpoint 候选过滤与排序规则，使 G2 样本中：

1. 线损主业务接口排在前列
2. 外链与依赖库 URL 不再进入主业务候选
3. 其他业务系统 endpoint 不再轻易抢占主链

Task 9

补充测试，证明：

1. G2 主 endpoint 排序明显改善
2. 噪声 endpoint 不再污染生成主脚本

Phase 1 Exit Criteria

1. G2 fixture archetype 判定修正
2. G2 bootstrap 选择修正
3. G2 endpoint 候选排序修正

Phase 2：重建 G2 合同

Objective

在主链判定正确后，恢复 G2 必需的 mode-specific 合同与更严格的 readiness。

WS3：Mode Contract Reconstruction

Task 10

为 G2 定义最小 mode contract，至少包括：

1. modes[]
2. defaultMode
3. modeSwitchField
4. per-mode requestTemplate
5. per-mode responsePath
6. per-mode columnDefs
7. per-mode normalizeRules

Task 11

修改 Scene IR 组装或生成逻辑，让 G2 样本在证据充分时真正输出 modes[]，而不是只保留空壳默认字段。

Task 12

修改 G2 生成脚本模板或编译路径，避免继续退化成通用：

• paginate -> secondary_request -> filter

要求生成结果能体现：

1. month 模式
2. week 模式
3. 不同模式的请求差异
4. 不同模式的列差异

Task 13

新增或更新测试，证明：

1. 台区线损大数据-月_周累计线损率统计分析 可输出非空 modes
2. 至少一个 G2 fixture 恢复出 mode-specific contract

WS5：Readiness Tightening

Task 14

为 G2 新增或收紧 gate，至少覆盖：

1. g2_archetype_resolved
2. g2_bootstrap_resolved
3. g2_modes_present
4. g2_request_contract_complete
5. g2_response_contract_complete

Task 15

调整 readiness 评级逻辑，保证以下情况不再给出高等级：

1. modes = []
2. requestTemplate = null
3. columnDefs = []
4. archetype 误判

Task 16

新增或更新测试，证明：

1. 不闭合 G2 样本会被降级或阻断
2. readiness 与候选验证门槛一致

Phase 2 Exit Criteria

1. 至少 G2 主样本拥有可解释的 mode contract
2. readiness 不再虚高
3. G2 生成结果在结构上具备进入候选门槛的可能

Phase 3：回归真实样本并产出整改报告

Objective

在整改完成后，重新生成三份 G2 真实样本，并输出第二轮正式结论。

Tasks

Task 17

重新生成以下三份 G2 样本：

1. 台区线损大数据-月_周累计线损率统计分析
2. 白银线损周报
3. 线损同期差异报表

Task 18

按与第一轮完全一致的口径，对比以下项目：

1. archetype
2. bootstrap
3. modes
4. request contract
5. response / column / normalize contract
6. readiness

Task 19

输出整改后的第二轮报告，至少包含：

1. 哪些 blocker 被修掉
2. 哪些 blocker 仍存在
3. 哪些样本进入候选验证名单
4. 哪些样本仍需 fail-closed

Deliverables

1. 第二轮 G2 真实样本生成结果
2. 第二轮 G2 整改回归报告
3. 更新后的候选验证名单

Acceptance Criteria

1. 台区线损大数据-月_周累计线损率统计分析 至少进入候选验证名单
2. 三份样本不再统一坍缩成 paginated_enrichment
3. readiness 与真实业务闭合程度基本一致

File-Level Targets

本计划执行时，至少会触达以下类型资产：

1. src/generated_scene/ 下的 analyzer / generator / readiness 相关实现
2. tests/fixtures/generated_scene/ 下的 G2 fixture 或 canonical 资产
3. tests/ 下与 scene generator / canonical / readiness 相关的回归测试
4. docs/superpowers/reports/ 下的第二轮整改报告

Completion Criteria

本计划完成的标志是：

1. G2 主样本达到候选验证门槛
2. G2 家族 blocker 从“稳定复现”转为“部分修复且可解释”
3. 后续是否切换到 G1/G3，可以建立在整改后二轮报告上，而不是继续依赖第一轮失败画像