docs: add scene generator quality improvement design spec

🤖 Generated with [Qoder][https://qoder.com]
2026-04-17 18:13:45 +08:00
parent a6aa18c6d9
commit 1c964c3e70
1 changed files with 192 additions and 0 deletions
--- a/docs/superpowers/specs/2026-04-17-scene-generator-quality-improvement-design.md
+++ b/docs/superpowers/specs/2026-04-17-scene-generator-quality-improvement-design.md
@@ -0,0 +1,192 @@
+# sgClaw 场景生成器质量提升设计
+
+## 问题陈述
+
+sgClaw 场景生成器能将 `D:\desk\智能体资料\场景\` 下的原始 HTML 场景转化为 skill 包，但自动生成质量仅为 Claude 手写的 tq-lineloss-report 的 ~40%。
+
+### 四个核心问题
+
+| # | 问题 | 根因 |
+|---|------|------|
+| 1 | Content-Type 硬编码为 `application/json` | `browser_script_with_business_logic()` 模板硬编码，`ApiEndpointJson` 无 content_type 字段 |
+| 2 | 请求体缺少业务必需字段 | 仅做 `{...STATIC_PARAMS, ...args}` 简单合并，无 requestTemplate 机制 |
+| 3 | 响应数据未正确提取 | 无 responsePath 提取步骤，`normalizeRows` 直接接收原始响应 |
+| 4 | 缺乏多模式路由能力 | 旧路径硬编码 `API_ENDPOINTS[0]`，无模式检测 |
+
+### 根本架构缺陷
+
+生成器有两条路径：
+- `browser_script_with_modes()` — 新路径，支持所有高级特性
+- `browser_script_with_business_logic()` — 旧路径，仅支持基础功能
+
+LLM 判断为单模式的场景走旧路径，所有高级特性丢失。
+
+### 原始场景分类
+
+13 个场景按 API 调用模式分为三类：
+
+- **模式 A：BrowserAction 跨页面注入**（5 场景）— 线损类、服务风险类、约时工单类
+- **模式 B：$http.sendByAxios 营销网关**（2 场景）— 营销2.0零度户、光伏
+- **模式 C：直接 AJAX**（6 场景）— 95598 类、监测类、大电量类
+
+按复杂度分三个梯队：
+
+| 梯队 | 场景数 | 当前质量 | 目标质量 | 特征 |
+|------|--------|---------|---------|------|
+| 第一梯队 | 5 | ~60% | ~90% | 单模式、直接 AJAX、无 BrowserAction |
+| 第二梯队 | 5 | ~40% | ~70% | 涉及 BrowserAction 或 form-urlencoded |
+| 第三梯队 | 3 | ~20% | ~40% | 链式多步 API 调用，仍需人工介入 |
+
+## 解决方案
+
+### 核心策略
+
+统一生成路径 + 增强 LLM 提取深度 + 修复已知问题
+
+### 架构变更
+
+```
+修改前：
+  browser_script()
+    ├─ modes 非空 → browser_script_with_modes()     [新路径]
+    ├─ api_endpoints 非空 → browser_script_with_business_logic()  [旧路径，质量差]
+    └─ 其他 → browser_script_skeleton()             [骨架路径]
+
+修改后：
+  browser_script()
+    ├─ modes 非空 → browser_script_with_modes()     [统一路径]
+    ├─ 单模式场景 → 自动包装为 modes=[default_mode] → browser_script_with_modes()
+    └─ 无端点 → browser_script_skeleton()           [骨架路径]
+```
+
+## 实施阶段
+
+### 阶段一：修基础（统一路径，修模板）
+
+#### Task 1：统一生成路径
+
+**目标**：废弃 `browser_script_with_business_logic()`，所有场景统一走 `browser_script_with_modes()`
+
+**改动**：
+- 修改 `browser_script()` 路由逻辑：单模式场景自动包装为一个 mode
+- `browser_script_with_business_logic()` 标记为 `#[deprecated]`
+- `browser_script_skeleton()` 仅用于无端点、无列定义的场景
+
+**文件**：`src/generated_scene/generator.rs`
+
+#### Task 2：修复 jQuery processData 参数
+
+**目标**：form-urlencoded 请求在 jQuery ajax 中正确序列化
+
+**改动**：
+- `buildModeRequest` 函数中根据 `contentType` 区分处理：
+  - `application/x-www-form-urlencoded`：body 传对象，jQuery 调用加 `processData: false`
+  - `application/json`：body 传 `JSON.stringify()`，不加 processData
+- 在模板中为 jQuery ajax 调用增加 `processData` 条件判断
+
+**文件**：`src/generated_scene/generator.rs`（`browser_script_with_modes` 模板）
+
+#### Task 3：单模式场景自动包装为 mode 配置
+
+**目标**：LLM 输出无 modes 但有 apiEndpoints 时，自动包装为单 mode
+
+**改动**：
+- `analyzeSceneDeep()` 中增加自动包装逻辑
+- 当 `modes` 为空且 `apiEndpoints` 非空时，生成默认 mode：
+  ```js
+  {
+    name: "default",
+    condition: { field: "period_mode", operator: "equals", value: "default" },
+    apiEndpoint: apiEndpoints[0],  // 使用第一个端点
+    columnDefs: columnDefs,
+    requestTemplate: staticParams,
+    responsePath: "",
+    normalizeRules: { type: "validate_all_columns", filterNull: true }
+  }
+  ```
+- 设置 `defaultMode: "default"`, `modeSwitchField: "period_mode"`
+
+**文件**：`frontend/scene-generator/llm-client.js`
+
+### 阶段二：增强提取（让 LLM 提取更准）
+
+#### Task 4：增强 LLM prompt 的强制约束
+
+**目标**：让 LLM 必须输出 Content-Type、responsePath、requestTemplate 等关键字段
+
+**改动**：
+- `DEEP_SYSTEM_PROMPT` 中增加强制字段约束说明
+- 增加"如果找不到就填默认值"的指导，避免 LLM 跳过这些字段
+- 增加 contentType 判断示例（`$.ajax` 中找 `contentType` 属性，`$http.sendByAxios` 中看封装）
+
+**文件**：`frontend/scene-generator/llm-client.js`
+
+#### Task 5：增加业务 JS 文件提取
+
+**目标**：LLM 不仅读 index.html，还要读 js/ 目录下的业务逻辑文件
+
+**改动**：
+- `frontend/scene-generator/server.js` 的切片逻辑：识别并提取 `js/mca.js`, `js/ami.js`, `js/sgApi.js`, `js/power.js` 等业务文件
+- `buildDeepAnalyzePrompt` 中增加业务 JS 文件的片段推送
+- 限制总 token 数不超过 `MAX_DEEP_PROMPT_CHARS`（60000）
+
+**文件**：
+- `frontend/scene-generator/server.js`（新增业务 JS 文件识别和提取）
+- `frontend/scene-generator/llm-client.js`（prompt 中增加业务 JS 片段）
+
+#### Task 6：提取后验证与二次追问
+
+**目标**：LLM 返回后检查关键信息是否缺失，缺失则二次追问
+
+**改动**：
+- 新增 `validateExtractedSceneInfo()` 函数
+- 检查项：至少一个 apiEndpoint 有 contentType、至少一个 mode 有 responsePath
+- 如果缺失，构造二次 prompt 要求补充
+- 最多追问 1 次，超时则使用默认值
+
+**文件**：`frontend/scene-generator/llm-client.js`
+
+### 阶段三：测试验证
+
+#### Task 7：单元测试
+
+**目标**：为多模式生成路径添加测试覆盖
+
+**改动**：
+- 新增 `tests/scene_generator_modes_test.rs`
+- 测试用例：
+  1. 单模式场景生成包含 `const MODES =` 的 JS
+  2. 多模式场景生成包含 mode 路由逻辑
+  3. 蛇形/驼峰序列化一致性
+  4. form-urlencoded 请求体格式正确
+  5. responsePath 提取步骤存在
+
+**文件**：`tests/scene_generator_modes_test.rs`（新增）
+
+#### Task 8：集成测试
+
+**目标**：用真实场景验证生成质量
+
+**步骤**：
+1. 拿 `用户日电量监测`（最简单的模式 C 场景）跑一次完整生成
+2. 拿 `台区线损大数据`（最复杂的模式 A 双模式场景）跑一次完整生成
+3. 对比生成结果与 tq-lineloss-report 的差异
+4. 记录差距清单
+
+**产出**：集成测试报告文档
+
+## 影响范围
+
+| 文件 | 改动类型 | 涉及 Task |
+|------|---------|-----------|
+| `src/generated_scene/generator.rs` | 修改 | Task 1, Task 2 |
+| `frontend/scene-generator/llm-client.js` | 修改 | Task 3, Task 4, Task 6 |
+| `frontend/scene-generator/server.js` | 修改 | Task 5 |
+| `tests/scene_generator_modes_test.rs` | 新增 | Task 7 |
+| 集成测试报告 | 新增 | Task 8 |
+
+## 非目标
+
+- 第三梯队场景（链式多步 API 调用）的完全自动化不在本方案范围内
+- BrowserAction 跨页面注入的自动识别和转换在第二梯队中部分支持，不追求 100% 准确
+- Web UI 变更不在本方案范围内（后续独立方案处理）