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