claw/docs/superpowers/specs/2026-04-17-generated-scene-rectification-design.md

Generated Scene Rectification Design

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

Problem Statement

当前自动场景转 skill 流程虽然已经引入了 Scene IR、workflowArchetype 和 readiness 分级，但对营销类复杂报表场景仍存在三类致命偏差：

1. sceneId 会从中文场景名退化成低信息量标识，例如 营销2.0零度户报表数据生成 -> 2-0。
2. bootstrap 会被 localhost 导出或辅助服务污染，导致内网入口域名解析错误。
3. workflow 会在证据不完整时提前归类，导致 paginated_enrichment 场景缺失 paginate、secondary_request 等关键步骤证据。

这三个问题叠加后，会出现“结构上看似已生成 skill，实际上放到内网一定跑不通”的假阳性结果。现有生成器仍然偏向“模板填充”，没有形成一条对内网场景足够保守、可审计、可拒绝错误输出的整改链路。

Rectification Goal

本次整改目标不是继续提升“生成成功率”，而是把生成器收敛成一个更稳的 scene skill rectifier，做到：

1. 不再产出 2-0 这类无业务语义的 sceneId。
2. 不再让 localhost、静态资源地址、模板噪声参与 bootstrap 竞争。
3. 不再在工作流证据缺失时冒然输出 paginated_enrichment 或其它高复杂 archetype。
4. 不再把低可信生成结果伪装成“可直接内网试跑”的 skill。
5. 为后续 mini 版 skill-creator 打下可复用的整改底座。

Non-Goals

1. 不在本轮整改中解决全部历史场景兼容性。
2. 不要求本轮整改覆盖登录态恢复、复杂鉴权、宿主浏览器差异。
3. 不要求 LLM 单独完成中文场景语义恢复，整改仍以确定性证据优先。
4. 不要求一步到位生成所有 browser workflow 细节；允许在 readiness 门禁前失败关闭。

Current Failure Reconstruction

以 营销2.0零度户报表数据生成 为例，当前错误链路大致如下：

1. 目录名 fallback 经过仅保留 [a-z0-9] 的 slug 规则后，中文主体被剥离，只剩 2-0。
2. URL 候选集合没有分层，http://localhost:13313/... 与 http://yx.gs.sgcc.com.cn、http://yxgateway.gs.sgcc.com.cn/... 被放在同一个 bootstrap 竞争池。
3. 工作流分类优先命中通用的“多模式字段”信号，导致 archetype 判定先偏向 multi_mode_request。
4. endpoint 集合又被 ${apiUrl}、静态模板串、localhost 导出地址等噪声稀释，最终 workflow step 构造无法稳定提取“分页主请求 -> 逐户补数 -> 过滤 -> 导出”的完整证据。
5. 生成器仍然给出可输出 skill，造成用户误以为该 skill 具备内网可运行性。

所以整改不能只修某一个 if 分支，而是必须同时修正命名链、bootstrap 链、workflow 链和 readiness 链。

Rectification Principles

1. Fail Closed 优先于 Fail Open

当 sceneId、bootstrap、workflow 任一关键链路证据不足时，生成器必须降级、阻断或明确标红，而不是继续生成一个“看起来完整”的 skill。

2. 先判定证据类别，再消费证据

URL、函数名、分页变量、过滤条件、导出调用，必须先完成“证据分层”与“噪声剔除”，再参与 archetype 分类和模板编译。

3. Bootstrap 与 Export 必须解耦

内网业务入口域名与本地导出服务是两类完全不同的运行时概念。localhost 可以作为 export/downstream evidence，但绝不能作为 bootstrap candidate。

4. 命名必须具备业务可读性

sceneId 不是目录技术标识，而是 skill 的业务身份。任何低熵、数字化、占位式 id 都必须被视为无效结果。

5. Archetype 输出必须受完整工作流约束

paginated_enrichment 不是“有分页字段”就能输出，而必须同时满足主列表请求、分页证据、二次请求证据和聚合/过滤/导出链路中的最低组合。

Target Architecture

source scene
  -> source scan
  -> evidence stratification
  -> naming chain
  -> bootstrap chain
  -> workflow chain
  -> archetype gating
  -> readiness grading
  -> skill generation or fail-closed report

整改后的核心不是新增一个大模型步骤，而是在现有 Scene IR 前后补齐四道约束：

1. 命名约束
2. bootstrap 约束
3. workflow 约束
4. readiness 约束

Rectification Design

Naming Chain Rectification

sceneId 整改的目标是让“中文目录名 -> 业务可读 sceneId”成为一条受控链路，而不是任由 fallback 退化。

整改方案如下：

1. sceneId 候选来源按优先级分层：
   • LLM 明确返回的业务语义 id
   • 确定性抽取出的英文业务关键词组合
   • 基于中文场景名的受控 transliteration / alias 规则
   • 最终 fallback 仅可作为 invalid_candidate，不可直接落盘
2. 新增 sceneId 有效性校验：
   • 不能是纯数字或数字主导
   • 不能短于业务最小可读长度
   • 不能只由版本号或通用词组成
   • 不能与 sceneName 语义完全脱钩
3. 对 2-0、1-0、report、scene 这类低熵 id 统一判为 invalid_scene_id。
4. 一旦命中无效 id，生成器只能输出整改报告或要求人工确认，不允许直接生成正式 skill 目录。

这条链路的结果是：sceneId 从“字符串清洗结果”升级为“业务标识产物”。

Bootstrap Chain Rectification

bootstrap 整改的目标是把 URL 候选集拆成不同证据层，彻底消除 localhost 污染。

整改方案如下：

1. 对 URL 候选先做角色分层：
   • business_entry
   • business_api
   • gateway_api
   • export_service
   • local_helper
   • static_asset
   • template_noise
2. 角色识别规则要求：
   • localhost、127.0.0.1、SurfaceServices、ReportServices 默认归入 export_service 或 local_helper
   • .js、.css、模板占位 URL、字符串格式化残片归入 static_asset 或 template_noise
   • 页面常量中的 sourceUrl、首页入口地址、业务网关前缀优先归入 business_entry 或 business_api
3. bootstrap 决策只允许消费：
   • business_entry
   • business_api
   • gateway_api
4. 当 business_entry 与 gateway_api 并存时：
   • expectedDomain 取业务主域
   • API 前缀保留在 request evidence 中，不直接覆盖 target page
5. 当只识别到 localhost 或噪声地址时，bootstrap 必须判为 unresolved_bootstrap，生成器直接降级。

这条链路的结果是：localhost 仍可保留为“导出依赖证据”，但永远不再有资格被提升成业务入口域名。

Workflow Chain Rectification

workflow 整改的目标是从“字段特征分类”转为“请求链重建分类”。

整改方案如下：

1. 在 Scene IR 中把 workflow 证据拆成四层：
   • request evidence
   • pagination evidence
   • secondary request evidence
   • post-process evidence
2. archetype 分类不再优先依赖泛化字段名如 type/tab/mode/status，而是优先依赖：
   • 是否存在主列表请求
   • 是否存在稳定分页变量组合
   • 是否存在逐项或逐批二次请求
   • 是否存在过滤、聚合或导出动作
3. endpoint 进入工作流前必须经过归一化：
   • 去掉 ${apiUrl}、格式化占位串、日志文本、异常字符串
   • 去掉 localhost export endpoint 对 archetype 的干扰
   • 合并同一业务 API 的不同拼接形态
4. paginated_enrichment 的最小证据门槛改为：
   • 至少一个主列表请求
   • 至少一组分页变量
   • 至少一个二次请求入口或明确定义的逐户补数函数
   • 至少一个后处理动作：filter、transform、export 之一
5. 如果只满足部分证据：
   • 可保留为 candidate_paginated_enrichment
   • 但不得进入正式 paginated_enrichment 编译路径
6. multi_mode_request 只在“模式切换显著改变请求体、列定义或响应路径”时成立，不能仅凭通用字段名命中。

这条链路的结果是：营销类场景只有在真正重建出“分页 + 补数 + 后处理”证据后，才会进入对应编译器。

Readiness Chain Rectification

readiness 整改的目标是把“能否生成”与“能否内网试跑”明确分开。

整改方案如下：

1. 新增关键门禁：
   • scene_id_valid
   • bootstrap_resolved
   • workflow_complete_for_archetype
   • runtime_contract_compatible
2. 只有全部通过时，结果才可标为 A 或 B。
3. 任一关键门禁失败时：
   • 结果只能是 C
   • UI 与报告中必须显式展示缺失项
   • 允许输出分析报告，但不应默认输出可运行 skill
4. 对 marketing-zero-consumer-report 这类参考场景，readiness 最低通过条件应明确写死为：
   • 非退化 sceneId
   • bootstrap 指向 yx.gs.sgcc.com.cn 体系
   • workflow 含 paginate
   • workflow 含 secondary_request
   • workflow 含 filter 或 export

这条链路的结果是：生成器从“只要能写文件就算成功”切换为“只有通过门禁才算可试跑”。

Superpowers Landing Strategy

本整改必须通过 superpowers 的 spec -> plan -> execution 三段式落地，不接受直接跳到零散修补。

落地顺序应为：

1. 先基于本设计补一份对应的 docs/superpowers/plans 执行计划。
2. 再按计划拆解到 naming、bootstrap、workflow、readiness 四个任务包。
3. 实施过程中严格以计划边界为准，不额外扩展到登录、鉴权、宿主接入等非本轮范围。

File Impact

本设计预期主要影响以下区域：

File	Responsibility
frontend/scene-generator/generator-runner.js	命名 fallback、URL 分层、workflow 证据重建、门禁前分析
frontend/scene-generator/llm-client.js	sceneId 语义补全约束、证据摘要输入、低熵输出拦截
frontend/scene-generator/server.js	readiness 汇总、整改风险输出、生成阻断策略
frontend/scene-generator/sg_scene_generator.html	显示 invalid sceneId、bootstrap 角色、workflow 缺证和 readiness 风险
src/generated_scene/analyzer.rs	证据分类、endpoint 去噪、archetype 前置判断
src/generated_scene/ir.rs	承载分层 evidence、candidate archetype、门禁状态
src/generated_scene/generator.rs	按门禁决定是否允许进入编译器和正式输出

Acceptance Criteria

满足以下条件时，视为本整改设计达成目标：

1. 中文场景目录不再退化生成 2-0、1-0 等低熵 sceneId。
2. localhost、127.0.0.1、导出服务地址不再进入 bootstrap 竞争链。
3. marketing-zero-consumer-report 只有在具备 paginate + secondary_request + post-process 证据时才会进入 paginated_enrichment 编译路径。
4. 证据不足时，系统输出整改报告和 readiness 风险，而不是默认生成可运行 skill。
5. 生成器对外定位从“自动模板生成器”收敛为“带门禁的通用场景 skill 转化器”。

Open Questions

1. sceneId 的中文转英文策略是引入固定 alias 词表，还是允许 LLM 先给候选再由规则校验收敛。
2. gateway_api 与 business_entry 并存时，是否需要在 Scene IR 中同时保留 entryDomain 与 apiDomain。
3. readiness 阻断后，默认是否仍允许用户手工确认并强制生成一个 draft skill 包。