# 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

```text
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 包。