claw/docs/superpowers/specs/2026-04-18-g2-remediation-design.md

G2 家族整改设计

Status: Draft Date: 2026-04-18 Author: Codex

Problem Statement

第一轮真实样本迁移已经完成 G2 家族三份代表样本的真实生成与对标分析：

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

分析结论已经在以下文档中固化：

1. docs/superpowers/reports/2026-04-18-r1-real-tq-lineloss-analysis.md
2. docs/superpowers/reports/2026-04-18-g2-first-round-blocker-summary.md
3. docs/superpowers/reports/2026-04-18-first-round-migration-and-candidate-validation-report.md

当前问题已经不再是“生成器能不能产出 skill 包”，而是：

生成器能产出包，但对 G2 线损多模式报表家族仍无法恢复主业务语义，因此没有任何样本达到候选验证门槛。

G2 家族已经稳定复现以下 blocker：

1. archetype 从 multi_mode_request 坍缩为 paginated_enrichment
2. bootstrap 稳定落错到 20.77.115.36:31051
3. modes = []，只残留默认字段，不存在真实 mode 结构
4. requestTemplate = null，参数合同为空
5. columnDefs = []，列语义与 required fields 缺失
6. endpoint 候选被静态依赖、外链、其他业务系统严重污染
7. readiness 过度乐观，与真实可运行性脱节

因此，整改阶段的目标不是继续扩样，而是先把 G2 家族的主矛盾打透。

Goal

在不脱离现有 Scene IR + generator + readiness 框架的前提下，把 G2 家族从“能抽取部分信号”提升到“能稳定恢复线损多模式报表主链”。

整改阶段的直接目标如下：

1. 正确识别 G2 家族 archetype 为 multi_mode_request
2. 正确恢复主业务 bootstrap，而不是落到错误入口域
3. 恢复 month/week 模式矩阵
4. 恢复 mode-specific request contract
5. 恢复 mode-specific response path / column defs / normalize rules
6. 对 endpoint 污染建立有效隔离
7. 让 readiness 与真实业务闭合程度一致，避免虚高

Success Criteria

整改阶段完成后，G2 样本至少要满足以下门槛：

1. workflowArchetype = multi_mode_request
2. bootstrap.expectedDomain 与 targetUrl 锚定到线损主业务承载面
3. modes 不为空，至少包含 month 与 week
4. 每个 mode 都有明确 request contract
5. 每个 mode 都有明确 response path 与 column defs
6. 生成脚本不再退化成通用 paginate -> secondary_request -> filter 骨架
7. readiness 不能在核心合同缺失时继续给出 A

整改阶段的通过标准仍然是“进入候选验证门槛”，不是直接宣称已经内网可运行。

Non-Goals

本整改阶段不处理以下事项：

1. 不扩展到 G1/G3 家族整改
2. 不解决统一平台登录、目标系统后台登录或宿主认证恢复
3. 不重写整套 Scene IR 框架
4. 不把所有 BrowserAction 链完整抽象成全新 runtime 模型
5. 不在本阶段追求覆盖全部 102 个场景

Scope

本阶段整改范围严格限定为：

1. G2 家族语义识别与编译链
2. 与 G2 识别直接相关的 analyzer / evidence / generator / readiness 逻辑
3. G2 对应的 fixture、测试与对标基线

不进入：

1. G1 家族量产优化
2. G3 复杂分页补数 workflow 整改
3. 运行时 transport、浏览器桥接协议、登录链重构

Root Cause Framing

基于第一轮报告，当前 G2 失真不是单点 bug，而是四层问题叠加：

1. Signal Weighting 错位

系统虽然抓到了：

1. month/week/tjzq/mode
2. 线损核心 endpoint
3. responsePath = content

但最终决策时，分页、补数、过滤等噪声信号权重更高，导致 archetype 选错。

2. Bootstrap Selection 错位

bootstrap 候选选择逻辑把“可见入口页”与“真实业务承载页”混淆，导致 targetUrl 稳定落错。

3. Mode Reconstruction 缺失

系统能看到模式词面信号，但没有把这些信号提升为：

1. mode matrix
2. per-mode request builder
3. per-mode response parser
4. per-mode column / normalize contract

4. Readiness Gate 过宽

当前 readiness 更像“结构生成完成度”，而不是“业务合同闭合度”，导致错误结果被高分放行。

Design Principles

整改阶段遵循以下原则：

1. 先修判定，再修模板
2. 先修主链，再修文案
3. 先收窄 G2 边界，再扩到其他家族
4. 所有修复都必须落到可回归的 fixture 与测试
5. 任何无法闭合的 G2 样本必须 fail-closed，而不是继续伪装为候选 skill

Workstreams

整改阶段拆为五条工作流：

WS1: G2 Archetype Rectification

目标：

让 G2 家族不再被分页/补数噪声夺权，优先命中 multi_mode_request。

包含内容：

1. 收紧 G2 archetype 识别条件
2. 提升 month/week/tjzq/mode 信号权重
3. 降低通用分页信号对 G2 的误导

WS2: Bootstrap Rectification

目标：

让 bootstrap 选择聚焦真实业务承载面，而不是页面壳或错误入口。

包含内容：

1. 区分入口页、壳页面、真实主业务页
2. 对 localhost:*、静态资源、外链保持排除
3. 为 G2 增加主业务 bootstrap 选择约束

WS3: Mode Contract Reconstruction

目标：

从证据层恢复 month/week 模式矩阵，并输出 mode-specific 合同。

包含内容：

1. 识别 mode switch field
2. 恢复 modes[]
3. 为每个 mode 恢复 request template
4. 为每个 mode 恢复 response path / column defs / normalize rules

WS4: Endpoint Purification

目标：

把真正业务 endpoint 从依赖库、外链、其他系统噪声中剥离出来。

包含内容：

1. 过滤第三方库和文档 URL
2. 过滤静态资源与依赖包字符串
3. 提高线损业务 endpoint 候选排序权重

WS5: Readiness Tightening

目标：

让 readiness 真正代表“合同闭合度”，而不是“生成是否完成”。

包含内容：

1. 新增 G2 必过 gate
2. 当 modes / request / columnDefs 缺失时降级
3. 阻断虚高 A

Required Deliverables

整改阶段至少应产出：

1. G2 整改 plan
2. G2 对应 fixture / canonical 对比资产更新
3. G2 回归测试
4. G2 整改后第二轮真实迁移报告

Acceptance

整改阶段验收以 G2 家族三份样本为准：

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

至少满足以下要求：

1. 三者不再统一坍缩到 paginated_enrichment
2. 至少第一份样本达到候选验证门槛
3. 第二、第三份样本至少能输出更接近真实结构的 G2 合同，或者在证据不足时明确 fail-closed

Next Step

基于本设计，下一步应直接落：

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

该 plan 只围绕 G2 整改，不扩展到 G1/G3 或大规模场景迁移。