claw/docs/superpowers/plans/2026-04-17-scene-skill-60-to-90-roadmap-plan.md

# sgClaw Scene Skill 60-to-90 Roadmap Plan

> **Status:** Draft  
> **Date:** 2026-04-17  
> **Author:** Codex  
> **Upstream Spec:** [2026-04-17-scene-skill-60-to-90-roadmap-design.md](D:/data/ideaSpace/rust/sgClaw/claw-new/docs/superpowers/specs/2026-04-17-scene-skill-60-to-90-roadmap-design.md)

## Plan Intent

本计划用于将“scene skill 自动生成能力从 60 分提升到 90 分”的设计方案拆解为可执行的交付阶段、任务边界、验收条件与实施顺序。计划严格服从上游 `spec`，不额外扩展问题空间，不提前引入未在 `spec` 中确认的实现目标。

本计划覆盖的核心目标仅包括：

1. 建立可裁决的语义证据层
2. 建立最小可编译业务契约
3. 冻结 P0 样板标准答案
4. 按 P0 到 P1 的路线推动 scene skill 自动转化能力从结构识别升级到业务语义恢复

## Success Criteria Baseline

本计划默认采用上游 `spec` 中已经收敛的成功标准：阶段性成功不再以“生成结果是否尽量接近某个参考 skill 的结构”作为唯一目标，而是以通用场景生成后的 skill 能否在内网环境中直接运行、拿到正确数据并产出正确报表作为主判定口径。

因此，实施验收默认同时检查以下三层闭环：

1. 执行闭环：生成 skill 可在自研浏览器承载的内网环境中完成执行
2. 数据闭环：查询、分页、提取后的数据正确且完整
3. 产物闭环：生成的 Excel 或其他报表符合业务规则

## Scope Guardrails

本计划执行过程中，以下边界保持不变：

1. 不以“一次覆盖全部 102 个场景”为目标
2. 不在本计划中展开统一平台登录或目标业务系统后台登录的自动恢复实现
3. 不把 BrowserAction 全链路抽象一次性做完
4. 不把复杂文档渲染、模板上传、附件解析场景纳入 P0
5. 不以“先做更多 prompt 调优”代替证据层、契约层和标准答案建设

## Scene Family Baseline

本计划执行时，默认承接上游 `spec` 对 `102` 个场景的家族分组结果：

1. `G1` 通用单页报表组：`68`
2. `G2` 多模式报表组：`11`
3. `G3` 分页明细补数组：`10`
4. `G4` 工具检测前置组：`8`
5. `G5` 低优先级噪声组：`5`

本计划的主线实施范围以 `G1 + G2 + G3` 为主，它们合计 `89` 个场景，约占全部样本的 `87%`。`G4` 作为后续检测类扩展前置保留，`G5` 默认降级处理，不进入首轮主线。

## Workstreams

本计划拆分为四条主工作流：

1. `WS1` 语义证据层建设
2. `WS2` 最小可编译业务契约建设
3. `WS3` P0 标准答案与校准基线建设
4. `WS4` P0/P1 样板路线落地与验证

四条工作流之间的依赖关系为：

`WS1 + WS2 + WS3 -> WS4`

## Phase Overview

计划按五个阶段推进：

1. Phase 0：冻结边界与样板
2. Phase 1：建立语义证据层
3. Phase 2：建立最小可编译业务契约
4. Phase 3：冻结 P0 canonical answers
5. Phase 4：按 P0/P1 路线逐步验证 60-to-90 能力提升

其中 Phase 4 不是按业务部门推进，而是按场景家族推进，顺序固定为：

1. 先打 `G2` 多模式报表组，验证语义恢复上限
2. 再打 `G1` 通用单页报表组，验证规模化迁移能力
3. 再打 `G3` 分页明细补数组，验证复杂 workflow 与 fail-closed
4. `G4` 保留到后续检测类扩展
5. `G5` 默认降级处理

## Phase 0：冻结边界与样板

### Objective

在进入建设阶段前，先冻结问题边界、P0 样板、P1 家族和对标基线，避免实施过程中反复漂移。

### Tasks

1. 固化 P0 样板清单
2. 固化 P1 家族清单
3. 固化 `台区线损大数据-月_周累计线损率统计分析 -> tq-lineloss-report` 的 canonical mapping
4. 固化宿主浏览器执行上下文和 `localhost:*` 的语义分类口径
5. 固化“业务语义层 / 宿主浏览器能力层 / 登录与本地桥接层”的分层约束
6. 固化 `102` 个场景的五大分组和分组口径
7. 固化各分组到 archetype / 阶段 / 验收重点的映射关系

### Deliverables

1. 冻结后的样板名单
2. 样板与 archetype 对照表
3. 宿主与业务分层约束说明
4. canonical benchmark 映射说明
5. 五大场景分组清单
6. 分组实施映射说明

### Exit Criteria

1. P0 / P1 样板不再变动
2. `tq-lineloss-report` 已被明确为 P0-1 的 canonical benchmark
3. `localhost:*` 已被明确定义为宿主桥接证据而非默认业务域
4. `102` 个场景的五大分组和分组实施口径不再漂移

## Phase 1：建立语义证据层

### Objective

将“源码直接汇总到 Scene IR”的生成路径，升级为“源码先形成可裁决语义证据，再归约为 Scene IR”的路径。

### Tasks

1. 定义统一证据对象 schema
2. 定义证据来源分层
3. 定义证据归并与冲突消解规则
4. 定义证据到 `Scene IR` 的映射边界
5. 建立核心证据类型集合

### Required Evidence Types

第一版最小证据类型集合固定为：

1. `bootstrap_candidate`
2. `endpoint_candidate`
3. `mode_candidate`
4. `request_template_candidate`
5. `response_path_candidate`
6. `column_defs_candidate`
7. `normalize_rules_candidate`
8. `workflow_candidate`
9. `localhost_dependency_candidate`
10. `browser_action_candidate`
11. `export_candidate`

### Deliverables

1. 证据对象 schema 文档
2. 证据类型字典
3. 证据归并规则文档
4. 证据到 `Scene IR` 的映射规则文档
5. P0 样板的证据抽取结果样例

### Acceptance Criteria

1. 任一 P0 样板都能输出结构化证据集合
2. `localhost:*`、宿主 JS 注入、隐藏域行为可进入独立证据槽位
3. `Scene IR` 的核心字段均可回溯到对应证据来源
4. 证据冲突时存在明确裁决路径，而不是被最终总结直接吞没

## Phase 2：建立最小可编译业务契约

### Objective

把 archetype 判断从“关键词命中”升级为“最小业务契约是否成立”，让 compiler 只接收证据闭合的输入。

### Tasks

1. 定义各 archetype 的最小可编译契约
2. 定义统一 gate 列表
3. 定义 gate 失败时的阻断规则
4. 定义 archetype 最小输出契约
5. 建立 fail-closed 优先的 readiness 判定口径

### Required Gates

统一 gate 名称最少包括：

1. `bootstrap_resolved`
2. `request_contract_complete`
3. `response_contract_complete`
4. `workflow_contract_complete`
5. `runtime_contract_compatible`

### Deliverables

1. archetype 最小契约表
2. gate 判定表
3. blocker / readiness 规则表
4. archetype 输出契约样例

### Acceptance Criteria

1. `multi_mode_request`、`single_request_table`、`paginated_enrichment` 均有明确最小契约
2. 没有通过 gate 的场景不能再伪装为 runnable skill
3. readiness 结果能够区分“业务证据不足”和“宿主运行时依赖未满足”
4. compiler 输入边界清晰，不能继续吞入未闭合 IR

## Phase 3：冻结 P0 Canonical Answers

### Objective

为 P0 三个主样板建立稳定的标准答案、关键证据清单和验收基线，作为后续回归与迁移的唯一校准源。

### Tasks

1. 固化三个 P0 样板的标准 `Scene IR`
2. 固化三个 P0 样板的关键证据清单
3. 固化三个 P0 样板的验收标准
4. 固化三个 P0 样板的失败 taxonomy
5. 建立 canonical answer 与实际生成结果的比对方式

### P0 Canonical Targets

1. `台区线损大数据-月_周累计线损率统计分析`
   参考 `tq-lineloss-report`
2. `用户日电量监测`
   对标单请求量产样板
3. `95598工单明细表`
   对标分页补数识别与阻断样板

### Deliverables

1. 三个 P0 样板的 canonical `Scene IR`
2. 三个 P0 样板的关键语义证据基线
3. 三个 P0 样板的验收表
4. 三个 P0 样板的失败类型表

### Acceptance Criteria

1. P0-1 能明确以 `tq-lineloss-report` 作为高质量参考样板，而非唯一硬标准答案
2. 三个 P0 样板都存在“生成结果 vs canonical answer”的对齐方式
3. 后续每次能力升级均可回归验证是否偏离 P0 标准答案

## Phase 4：按 P0/P1 路线逐步验证 60-to-90 提升

### Objective

按照 `spec` 已定义的优先级，以 P0 为主、P1 为扩展，逐步验证自动转化器从结构识别向业务语义恢复的提升路径。

本阶段不按业务部门推进，而按场景家族推进。其首轮目标不是“覆盖全部 `102` 个场景”，而是先打穿主流报表型场景，再逐步扩展。

### Track A：P0-1 `tq` 主样板

#### Goal

打通 `multi_mode_request.month_week_table` 的主样板能力，并使结果在关键业务语义、内网可执行性与报表正确性上达到 `tq-lineloss-report` 同等级别。

#### Tasks

1. 恢复完整 `month / week` 模式矩阵
2. 恢复每个模式的请求契约与响应契约
3. 恢复列定义、归一化规则和导出语义
4. 校验 bootstrap 与目标系统上下文约束
5. 建立自动结果与 `tq-lineloss-report` 的关键语义比对

#### Acceptance Criteria

1. `mode matrix` 稳定恢复
2. 关键 request / response contract 稳定恢复
3. 生成结果在关键业务语义与内网报表结果上达到高质量参考水平

### Track B：P0-2 单请求量产样板

#### Goal

证明单请求报表家族可以形成高通过率的通用转化模板。

#### Tasks

1. 恢复 request / response / normalize 三件套
2. 压缩伪通用兜底主路径
3. 验证同家族样板迁移能力

#### Acceptance Criteria

1. `single_request_table` 样板稳定通过
2. 同家族样板具备可复用性
3. 结果判定不再过度依赖全文总结

### Track C：P0-3 分页补数样板

#### Goal

正确识别复杂分页补数场景的问题空间，并在证据不足时稳定阻断。

#### Tasks

1. 拆开主请求链、补数链、导出链
2. 建立 `paginated_enrichment` 最小可编译证据集
3. 区分业务 workflow 与宿主桥接行为
4. 落地 fail-closed 判定

#### Acceptance Criteria

1. 分页补数 workflow 被正确拆解
2. 证据不足时稳定 fail-closed
3. 不再把宿主链或 `localhost:*` 误判为业务主链

### Track D：P1 家族扩展

#### Goal

在 P0 样板稳定后，将能力迁移到已定义的 P1 家族，验证路线具备规模化复制能力。

#### Tasks

1. 迁移线损 / 电量多模式家族
2. 迁移单请求报表家族
3. 迁移分页补数家族
4. 记录每一类家族的复用成功率与失败类型

#### Acceptance Criteria

1. 每个 P1 家族至少完成一轮代表场景迁移验证
2. P1 验证主要依赖 P0 已沉淀的证据、契约和标准答案体系
3. 若超出当前 archetype 或契约能力边界，结果应明确 fail-closed

### Track E：Scene Family Expansion Policy

#### Goal

以五大场景分组为单位，明确哪些家族进入主线，哪些家族仅做预留或降级。

#### Tasks

1. 对 `G1` 通用单页报表组建立量产迁移节奏
2. 对 `G2` 多模式报表组建立深做样板节奏
3. 对 `G3` 分页明细补数组建立复杂链识别节奏
4. 对 `G4` 工具检测前置组仅保留架构入口与后续扩展口径
5. 对 `G5` 低优先级噪声组建立默认降级口径

#### Acceptance Criteria

1. `G1 + G2 + G3` 成为首轮主线范围
2. `G4` 不抢占当前主线资源，但保留后续检测类扩展入口
3. `G5` 不污染主线 archetype 和验收口径

## Milestone Order

总前置里程碑的发生顺序固定为：

1. 先完成语义证据层
2. 再完成最小可编译业务契约
3. 再冻结 P0 标准答案

在这三个里程碑完成之前，不进入大规模家族扩展。

## File-Level Planning Targets

本计划要求后续实施至少覆盖以下资产类型：

1. `docs/superpowers/specs/` 中的上游设计稿
2. `docs/superpowers/plans/` 中的阶段计划与进展计划
3. scene 生成链中的证据层、契约层、readiness / blocker 相关实现
4. P0 样板对应的 fixture、golden IR、验收基线或等价校准资产

## Completion Criteria

本计划完成的标志为：

1. `tq` 主样板可以稳定恢复核心业务语义，并在内网运行与报表结果上达到高质量参考水平
2. 单请求主样板可以形成可复制的高通过率模板，并覆盖主流通用报表场景
3. 分页补数主样板可以稳定识别复杂 workflow，并在证据不足时 fail-closed
4. `Scene IR` 前存在可裁决的证据层
5. archetype 前存在明确契约 gate
6. P0 标准答案已成为后续迁移与回归的统一校准基线
7. 实施主线明确聚焦 `G1 + G2 + G3`，不再被边界场景牵引偏航

## Risks and Control Points

1. 若证据层先天过薄，后续契约和 canonical answer 会失去支撑
2. 若契约 gate 定义过宽，系统会继续伪造 runnable skill
3. 若 P0 标准答案不冻结，后续优化将失去对齐基线
4. 若过早进入 P1 扩展，容易在未完成分层前再次引入宿主噪声污染

## Out of Plan

以下事项明确不属于本计划直接交付范围：

1. 统一平台登录流程自动恢复
2. 目标业务系统后台登录实现细节
3. 浏览器宿主能力的全量抽象
4. 所有场景的一次性端到端可运行保证