376 lines
13 KiB
Markdown
376 lines
13 KiB
Markdown
# Scene Skill Compiler Design
|
||
|
||
> **Status:** Draft
|
||
> **Date:** 2026-04-17
|
||
> **Author:** Codex
|
||
|
||
## Problem Statement
|
||
|
||
当前 `sg_scene_generate` 已经具备基础的场景识别、LLM 抽取和模板渲染能力，但整体上仍然更接近“场景元数据提取器 + 模板填充器”，还不是一个真正可复用的通用 skill 转化器。
|
||
|
||
这在两个对照样本上表现得很明显：
|
||
|
||
| 样本 | 转化方式 | 结果 |
|
||
|------|----------|------|
|
||
| `tq-lineloss-report` | 基于 Claude 的语义重建 | 生成结果接近可运行 skill，显式表达了月/周模式、请求体、列定义、响应路径 |
|
||
| `marketing-zero-consumer-report` | 基于当前项目自动转化 | 生成结果偏“骨架 skill”，无法正确表达分页、逐户补数、过滤、导出等复合工作流 |
|
||
|
||
### 根因
|
||
|
||
1. 当前生成流程主要抽取“字段”，没有稳定抽取“工作流”。
|
||
2. 生成器默认假设报表场景接近“单次请求 -> 表格归一化 -> 输出 artifact”。
|
||
3. `scene.toml`、bootstrap、参数合同和 browser script 之间仍存在较强硬编码。
|
||
4. LLM 输入存在截断，且缺少对关键逻辑片段的优先抽取。
|
||
5. 运行时 resolver 能力较弱，无法稳定承接更复杂的自动生成结果。
|
||
|
||
### 典型失败模式
|
||
|
||
以 `marketing-zero-consumer-report` 为例，原始场景实际是：
|
||
|
||
1. 获取组织或用户列表。
|
||
2. 按页拉取用户数据。
|
||
3. 对每个用户发起二次请求补充电费信息。
|
||
4. 根据 `charge !== 0` 做业务过滤。
|
||
5. 组装导出数据并通过本地服务导出。
|
||
|
||
但当前自动生成结果把它错误归类成了“单请求报表”，导致：
|
||
|
||
- bootstrap 域名和目标页面来源不稳定。
|
||
- browser script 只使用第一个 API 端点。
|
||
- 数据归一化直接对原始列表生效，没有分页循环和二次请求。
|
||
- 生成出的参数合同与真实业务流程不匹配。
|
||
|
||
## Goal
|
||
|
||
将当前场景生成器升级为一个面向常见内网场景的“迷你版 skill-creator / scene skill compiler”，使其具备以下能力：
|
||
|
||
1. 先理解场景工作流，再选择模板并生成 skill。
|
||
2. 覆盖常见报表类内网场景，而不是只覆盖单请求表格场景。
|
||
3. 在生成前给出可运行性评估，减少“生成成功但内网跑不通”的情况。
|
||
4. 让同类场景可以复用同一套转化机制，而不是逐个手工重写。
|
||
|
||
## Non-Goals
|
||
|
||
1. 不追求一次性支持所有历史场景和所有前端技术栈。
|
||
2. 不在第一阶段解决登录、鉴权、跨域和浏览器宿主差异的全部问题。
|
||
3. 不要求 LLM 单独完成完整语义恢复，必须允许规则提取参与。
|
||
4. 不要求生成结果 100% 无需人工审阅。
|
||
|
||
## Design Principles
|
||
|
||
### 1. 先建模，再生成
|
||
|
||
必须先把原始场景建模为统一的 `Scene IR`，再由编译器按 archetype 渲染 skill。
|
||
|
||
### 2. 抽取“工作流证据”优先于抽取“字段清单”
|
||
|
||
对通用 skill 转化器而言，分页、模式切换、二次请求、导出动作、过滤条件，比单纯的 URL 和列定义更重要。
|
||
|
||
### 3. 确定性优先，LLM 补全
|
||
|
||
URL、请求方法、分页变量、入口函数、列头、导出调用等确定性信息优先由规则提取；LLM 负责做语义归并、命名和补全。
|
||
|
||
### 4. 模板按 archetype 拆分
|
||
|
||
不能继续用一个通用模板覆盖所有报表场景。不同工作流 archetype 必须有独立编译路径。
|
||
|
||
### 5. 运行时合同必须与生成能力对齐
|
||
|
||
生成器输出什么参数合同，运行时 resolver 就必须能承接；否则生成器必须降级或提示人工补齐。
|
||
|
||
## Architecture
|
||
|
||
### Target Architecture
|
||
|
||
```text
|
||
原始场景目录
|
||
-> 场景扫描器
|
||
-> 确定性规则提取
|
||
-> LLM 语义补全
|
||
-> Scene IR 合并
|
||
-> archetype 分类
|
||
-> archetype 编译器
|
||
-> skill 包
|
||
-> 静态验收 / 可运行性评级
|
||
```
|
||
|
||
### Core Pipeline
|
||
|
||
1. 扫描 `index.html`、`scripts/*.js`、目录结构和可见依赖关系。
|
||
2. 规则提取器抓取确定性证据。
|
||
3. LLM 基于分块后的关键上下文提取高层语义。
|
||
4. 合并为统一 `Scene IR`。
|
||
5. 根据 `workflowArchetype` 路由到对应编译器。
|
||
6. 生成 `scene.toml`、`SKILL.toml`、browser script 和说明文档。
|
||
7. 执行静态门禁和 readiness 评级。
|
||
|
||
## Scene IR
|
||
|
||
### Top-Level Fields
|
||
|
||
```json
|
||
{
|
||
"sceneId": "marketing-zero-consumer-report",
|
||
"sceneName": "营销2.0零度户报表数据生成",
|
||
"sceneKind": "report_collection",
|
||
"workflowArchetype": "paginated_enrichment",
|
||
"bootstrap": {
|
||
"expectedDomain": "yx.gs.sgcc.com.cn",
|
||
"targetUrl": "http://yx.gs.sgcc.com.cn"
|
||
},
|
||
"params": [
|
||
{
|
||
"name": "org_code",
|
||
"resolver": "org_tree",
|
||
"required": true
|
||
}
|
||
],
|
||
"modes": [],
|
||
"workflowSteps": [
|
||
{ "type": "paginate", "entry": "getUserList" },
|
||
{ "type": "foreach", "source": "userList" },
|
||
{ "type": "secondary_request", "entry": "getUserCharges" },
|
||
{ "type": "filter", "expr": "charge !== 0" },
|
||
{ "type": "export", "entry": "exportExcel" }
|
||
],
|
||
"requestTemplate": {},
|
||
"responsePath": "data.rows",
|
||
"normalizeRules": {
|
||
"type": "field_map"
|
||
},
|
||
"artifactContract": {
|
||
"type": "report-artifact"
|
||
},
|
||
"validationHints": {
|
||
"requiresTargetPage": true
|
||
},
|
||
"evidence": []
|
||
}
|
||
```
|
||
|
||
### Required IR Blocks
|
||
|
||
| Block | Purpose |
|
||
|------|---------|
|
||
| `workflowArchetype` | 决定编译器路由 |
|
||
| `bootstrap` | 决定目标域名、目标页面和 helper page 行为 |
|
||
| `params` | 决定 `scene.toml` 参数合同 |
|
||
| `modes` | 表达月/周、日/月、报表类型切换等多模式逻辑 |
|
||
| `workflowSteps` | 表达分页、循环、二次请求、过滤、导出等复合流程 |
|
||
| `requestTemplate` | 表达固定请求体和参数映射 |
|
||
| `responsePath` | 指定响应数据抽取路径 |
|
||
| `normalizeRules` | 指定字段映射、空行过滤和关键字段校验 |
|
||
| `artifactContract` | 指定输出 artifact 结构和状态语义 |
|
||
| `evidence` | 保留抽取证据，便于 UI 预览和人工复核 |
|
||
|
||
## Workflow Archetypes
|
||
|
||
第一阶段建议先稳定支持以下 archetype：
|
||
|
||
| Archetype | 场景特征 | 典型样本 |
|
||
|-----------|----------|----------|
|
||
| `single_request_table` | 单次请求，直接返回表格或列表 | 简单报表场景 |
|
||
| `multi_mode_request` | 同一场景存在月/周等多模式，请求体和列定义随模式切换 | `tq-lineloss-report` |
|
||
| `paginated_enrichment` | 先分页拉主列表，再逐条或逐批补数，再过滤或导出 | `marketing-zero-consumer-report` |
|
||
| `page_state_eval` | 更偏状态检查、页面判定、轻量采集 | 监测类或状态判定类场景 |
|
||
|
||
### Routing Rules
|
||
|
||
1. 有显式模式切换条件，优先判定为 `multi_mode_request`。
|
||
2. 有分页调用且伴随逐条二次请求，优先判定为 `paginated_enrichment`。
|
||
3. 无明确请求链、以页面状态判定为主，归到 `page_state_eval`。
|
||
4. 其余默认归到 `single_request_table`，但标记为低置信度。
|
||
|
||
## Extraction Architecture
|
||
|
||
### Stage 1: Deterministic Extraction
|
||
|
||
规则提取器负责抽取高确定性信息：
|
||
|
||
1. URL、请求方法、`contentType`、请求体拼装方式。
|
||
2. 分页参数，例如 `page`、`rows`、`pageSize`、`sidx`、`sord`。
|
||
3. 入口函数、导出函数、列表函数、详情函数。
|
||
4. `if/switch` 模式分支。
|
||
5. 表头、列定义、字段映射。
|
||
6. 明确的过滤条件，例如 `charge !== 0`。
|
||
|
||
### Stage 2: LLM Semantic Completion
|
||
|
||
LLM 负责以下内容：
|
||
|
||
1. 对规则提取结果做归并和命名。
|
||
2. 补全 `workflowSteps` 的高层描述。
|
||
3. 判断 archetype。
|
||
4. 推断 `requestTemplate`、`responsePath`、`normalizeRules`。
|
||
5. 输出不确定项和置信度。
|
||
|
||
### Input Strategy
|
||
|
||
当前“截前 15000/3000 字符”的做法需要替换为：
|
||
|
||
1. 目录结构摘要。
|
||
2. `index.html` 分块。
|
||
3. 命中关键模式的函数片段优先注入。
|
||
4. URL 和请求构建语句优先注入。
|
||
5. 同一场景允许分阶段提问，而不是一次性塞完整上下文。
|
||
|
||
## Compiler Architecture
|
||
|
||
### Compiler Split
|
||
|
||
建议把当前单一生成器改成 archetype 路由后的多编译器：
|
||
|
||
| Compiler | Responsibility |
|
||
|----------|----------------|
|
||
| `single_request_table` compiler | 生成简单表格采集 skill |
|
||
| `multi_mode_request` compiler | 生成多模式切换 skill |
|
||
| `paginated_enrichment` compiler | 生成分页 + 补数 + 过滤类 skill |
|
||
| `page_state_eval` compiler | 生成状态判定或轻量监测类 skill |
|
||
|
||
### Compiler Outputs
|
||
|
||
每个编译器都负责：
|
||
|
||
1. 生成 `scene.toml`。
|
||
2. 生成 `SKILL.toml`。
|
||
3. 生成 browser script。
|
||
4. 生成引用说明文档，例如 `collection-flow.md`。
|
||
5. 输出 readiness 评级和风险说明。
|
||
|
||
### Marketing Case
|
||
|
||
`marketing-zero-consumer-report` 必须走 `paginated_enrichment` 编译器，至少生成这些逻辑骨架：
|
||
|
||
1. 主列表分页采集。
|
||
2. 对每个用户执行二次请求。
|
||
3. 聚合字段。
|
||
4. 业务过滤。
|
||
5. 导出或 report artifact 输出。
|
||
|
||
### TQ Case
|
||
|
||
`tq-lineloss-report` 必须走 `multi_mode_request` 编译器，至少生成这些逻辑骨架：
|
||
|
||
1. 模式识别。
|
||
2. 模式专属请求体构建。
|
||
3. 模式专属列定义。
|
||
4. 固定响应路径抽取。
|
||
5. 统一 artifact 输出。
|
||
|
||
## Runtime Contract Alignment
|
||
|
||
当前运行时参数解析器主要集中在 [src/compat/scene_platform/resolvers.rs]，能力仍偏基础。编译器设计必须显式处理这层约束。
|
||
|
||
### Short-Term Strategy
|
||
|
||
短期有两种可选策略：
|
||
|
||
1. 扩展 resolver 集合，支持更多参数合同。
|
||
2. 在生成阶段限制输出，只允许生成当前运行时能消化的参数模型。
|
||
|
||
### Recommended Resolver Additions
|
||
|
||
第一阶段建议补齐以下解析能力：
|
||
|
||
- `mode_enum`
|
||
- `date_range`
|
||
- `org_tree`
|
||
- `page_size`
|
||
- `hidden_static`
|
||
- `derived_param`
|
||
|
||
如果 resolver 暂时不扩，则生成器必须在 UI 和生成报告中明确标出“不兼容运行时合同”的风险。
|
||
|
||
## Verification And Readiness Gates
|
||
|
||
### Static Gates
|
||
|
||
生成完成后必须先过静态门禁：
|
||
|
||
1. 是否识别到业务入口。
|
||
2. 是否识别到核心请求链。
|
||
3. 是否识别到正确 bootstrap。
|
||
4. 参数合同是否与 archetype 匹配。
|
||
5. 编译器是否覆盖全部关键步骤。
|
||
|
||
### Readiness Levels
|
||
|
||
建议为每个生成结果打分级标签：
|
||
|
||
| Level | Meaning |
|
||
|-------|---------|
|
||
| `A` | 可以直接进入内网试跑 |
|
||
| `B` | 结构正确，但建议人工校验后试跑 |
|
||
| `C` | 只适合作为草稿，需要人工补逻辑 |
|
||
|
||
### Minimum Acceptance For Reference Scenes
|
||
|
||
`marketing-zero-consumer-report`：
|
||
|
||
1. 被识别为 `paginated_enrichment`。
|
||
2. 识别出主列表请求和二次补数请求。
|
||
3. 识别出 `charge !== 0` 过滤逻辑。
|
||
4. 生成结果不再退化为单请求表格模板。
|
||
|
||
`tq-lineloss-report`：
|
||
|
||
1. 被识别为 `multi_mode_request`。
|
||
2. 识别出月/周双模式。
|
||
3. 模式切换字段、请求体和列定义被区分。
|
||
4. 生成结果与手工 skill 在结构上同构。
|
||
|
||
## File Impact
|
||
|
||
### New Or Modified Areas
|
||
|
||
| File | Responsibility |
|
||
|------|----------------|
|
||
| `frontend/scene-generator/llm-client.js` | 深度抽取 schema、分块上下文、置信度输出 |
|
||
| `frontend/scene-generator/generator-runner.js` | 文件读取、关键片段抽取、目录摘要 |
|
||
| `frontend/scene-generator/server.js` | 分析接口、IR 透传、生成报告 |
|
||
| `frontend/scene-generator/sg_scene_generator.html` | 抽取预览、风险展示、readiness 展示 |
|
||
| `src/bin/sg_scene_generate.rs` | 接收 `Scene IR` 或 IR JSON 参数 |
|
||
| `src/generated_scene/analyzer.rs` | 确定性提取、archetype 辅助识别 |
|
||
| `src/generated_scene/generator.rs` | archetype 路由和多编译器编排 |
|
||
| `src/generated_scene/ir.rs` | 定义统一 `Scene IR` |
|
||
| `src/compat/scene_platform/resolvers.rs` | 参数合同对齐与扩展 |
|
||
|
||
## Migration Strategy
|
||
|
||
### Phase 1
|
||
|
||
先修当前明显错误：
|
||
|
||
1. bootstrap 来源修正。
|
||
2. 移除通用报表默认硬编码。
|
||
3. 替换截断式 LLM 输入。
|
||
4. 生成前展示抽取预览。
|
||
|
||
### Phase 2
|
||
|
||
引入 `Scene IR`，完成“先建模、再生成”的主干改造。
|
||
|
||
### Phase 3
|
||
|
||
接入 archetype 分类器和多编译器。
|
||
|
||
### Phase 4
|
||
|
||
补运行时 resolver，加入 readiness 门禁。
|
||
|
||
## Open Questions
|
||
|
||
1. `Scene IR` 是否作为单独 JSON 文件落地到输出目录，便于后续复用和回放。
|
||
2. `page_state_eval` 是否继续共用当前 `report-artifact`，还是定义独立 artifact 类型。
|
||
3. 是否允许用户在 Web UI 中手工修正 archetype、bootstrap 和参数合同后再生成。
|
||
|
||
## Acceptance Criteria
|
||
|
||
满足以下条件时，可以认为本设计达到预期：
|
||
|
||
1. 同一套生成流程能够同时覆盖 `tq-lineloss-report` 和 `marketing-zero-consumer-report` 两类差异明显的场景。
|
||
2. `marketing` 不再因错误 archetype 导致内网必然跑不通。
|
||
3. `scene.toml` 不再默认带入错误的组织、周期和标题关键字。
|
||
4. 生成结果具备明确的 readiness 分级，用户能在生成前识别风险。
|
||
5. 生成器在定位上从“模板填充器”升级为“通用场景 skill 编译器”。
|