claw/docs/superpowers/specs/2026-04-17-scene-generator-quality-improvement-design.md

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：

  {
    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 变更不在本方案范围内（后续独立方案处理）