237 lines
11 KiB
Markdown
237 lines
11 KiB
Markdown
# 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 包。
|