claw/docs/superpowers/plans/2026-04-17-scene-generator-quality-improvement-plan.md

# sgClaw 场景生成器质量提升 — 实施计划

> 对应设计文档: `docs/superpowers/specs/2026-04-17-scene-generator-quality-improvement-design.md`

## 总览

3 个阶段，8 个任务。每个任务包含：改动文件、具体步骤、验证方式、提交信息。

---

## Phase 1: 修基础

### Task 1: 统一生成路径（废弃 browser_script_with_business_logic）

**文件**: `src/generated_scene/generator.rs`

**当前状态** (line 728-735):
```rust
fn compile_scene(scene_ir: &SceneIr, analysis: &SceneSourceAnalysis, tool_name: &str) -> CompiledScene {
    let scene_toml = render_scene_toml(scene_ir, analysis, tool_name);
    let browser_script = match scene_ir.workflow_archetype() {
        WorkflowArchetype::SingleRequestTable => compile_single_request_table(scene_ir),
        WorkflowArchetype::MultiModeRequest => compile_multi_mode_request(scene_ir),
        WorkflowArchetype::PaginatedEnrichment => compile_paginated_enrichment(scene_ir),
        WorkflowArchetype::PageStateEval => compile_page_state_eval(scene_ir),
    };
    ...
}
```

**步骤**:

1. **修改 `compile_scene` 路由逻辑** (line 730-735):
   - `SingleRequestTable` 不再调用 `compile_simple_request_script`（`compile_single_request_table` 的底层），改为将单模式场景包装为一个 mode 后走 `compile_multi_mode_request`
   - 新增辅助函数 `ensure_modes_populated(scene_ir: &SceneIr) -> SceneIr`：
     - 如果 `scene_ir.modes` 为空但 `scene_ir.api_endpoints` 非空，生成一个 default mode
     - 将 `SingleRequestTable` 和 `PageStateEval` 场景的 `workflow_archetype` 改为 `MultiModeRequest`（因为统一走 modes 路径）
   - 修改 match 分支：
     ```rust
     let browser_script = match scene_ir.workflow_archetype() {
         WorkflowArchetype::MultiModeRequest => compile_multi_mode_request(scene_ir),
         WorkflowArchetype::PaginatedEnrichment => compile_paginated_enrichment(scene_ir),
         _ => {
             // SingleRequestTable, PageStateEval — fallback to multi-mode with default mode
             let adapted = ensure_modes_populated(scene_ir);
             compile_multi_mode_request(&adapted)
         }
     };
     ```

2. **实现 `ensure_modes_populated`**:
   - 接收 `&SceneIr`，返回 `SceneIr`（clone）
   - 如果 `modes` 已非空，直接返回 clone
   - 如果 `modes` 为空但 `api_endpoints` 非空：
     - 取第一个 endpoint 构造默认 mode
     - 设置 `name: "default"`, `label: Some("default")`
     - `condition`: `{ field: "period_mode", operator: "equals", value: "default" }`
     - `apiEndpoint`: 复制第一个 endpoint
     - `requestTemplate`: 取 `scene_ir.request_template`
     - `responsePath`: 取 `scene_ir.response_path`
     - `normalizeRules`: 取 `scene_ir.normalize_rules` 或默认
     - `columnDefs`: 取 `scene_ir.column_defs`
   - 同时设置 `default_mode = Some("default")`, `mode_switch_field = Some("period_mode")`

3. **标记 `browser_script_with_business_logic` 为废弃**（如果仍存在于代码中）：
   - 在当前代码中，该函数已不存在（已被 `compile_simple_request_script` 替代）。在注释中标注 "legacy path, superseded by multi-mode unified path"

**验证**:
- `cargo check` 无编译错误
- 单模式场景生成的 JS 脚本包含 `const MODES =` 和 `detectMode` 逻辑

**提交信息**:
```
feat(generator): unify all scene types through multi-mode path

Single-mode and page-state-eval scenes now get auto-wrapped into a
default mode and compiled through compile_multi_mode_request. This
eliminates the old browser_script_with_business_logic code path and
ensures all scenes get responsePath extraction, requestTemplate, and
contentType support.
```

---

### Task 2: 修复 jQuery processData 参数

**文件**: `src/generated_scene/generator.rs`（`compile_multi_mode_request` 函数，line 1069-1253）

**当前状态**: 模板中 `buildModeRequest` 函数（line 1098-1118）根据 `contentType` 区分了 body 序列化方式（form-urlencoded 用 `Object.entries().join('&')`，JSON 用 `JSON.stringify`），但 jQuery ajax 调用（line 1185-1196）**没有**设置 `processData` 参数。

jQuery 对 form-urlencoded body 会默认再次序列化（将字符串当作 query string 处理），导致双重编码。

**步骤**:

1. 修改 `compile_multi_mode_request` 中的 jQuery ajax 调用模板（line 1185-1196 区域）：
   - 在 `$.ajax({...})` 中增加 `processData` 参数：
     ```javascript
     $.ajax({
       url: request.url,
       type: request.method,
       data: request.body,
       contentType: request.headers['Content-Type'],
       processData: contentType !== 'application/x-www-form-urlencoded',
       dataType: 'json',
       success: resolve,
       error: (xhr, status, err) => reject(new Error(`API failed (${xhr.status}): ${err}`))
     });
     ```
   - 需要将 `contentType` 变量在 Promise 回调中可访问，从 `request` 对象中提取

2. 同理修改 `compile_simple_request_script` 中的 jQuery ajax 调用（line 994-1004 区域），增加相同的 `processData` 逻辑

**验证**:
- 生成的 JS 中 `$.ajax` 调用包含 `processData` 参数
- form-urlencoded 请求不会双重编码

**提交信息**:
```
fix(generator): add processData to jQuery ajax for form-urlencoded requests

jQuery default processData:true re-serializes string bodies, causing
double-encoding for form-urlencoded payloads. Set processData:false
when contentType is application/x-www-form-urlencoded.
```

---

### Task 3: 单模式场景自动包装为 mode 配置

**文件**: `frontend/scene-generator/llm-client.js`

**当前状态**: `analyzeSceneDeep` (line 729-769) 调用 LLM 后直接 `normalizeSceneIr` 返回。如果 LLM 输出 `modes: []` 但有 `apiEndpoints`，不会自动包装。

**步骤**:

1. 在 `analyzeSceneDeep` 函数中，`normalizeSceneIr(...)` 之后、返回之前，增加自动包装逻辑：

   ```javascript
   async function analyzeSceneDeep(sourceDir, dirContents, config) {
     const content = await requestChatCompletionWithRetry(...);
     const normalized = normalizeSceneIr(await extractJsonFromResponseWithRepair(content, config));

     // ... existing sceneId validation ...

     // AUTO-WRAP: single-mode scenes → modes array
     if (normalized.modes.length === 0 && normalized.apiEndpoints.length > 0) {
       normalized.modes.push({
         name: "default",
         label: "default",
         condition: { field: "period_mode", operator: "equals", value: "default" },
         apiEndpoint: normalized.apiEndpoints[0],
         columnDefs: normalized.columnDefs || [],
         requestTemplate: normalized.requestTemplate || {},
         normalizeRules: normalized.normalizeRules || { type: "validate_required", requiredFields: [], filterNull: true },
         responsePath: normalized.responsePath || "",
       });
       normalized.defaultMode = "default";
       normalized.modeSwitchField = "period_mode";
       // Upgrade archetype if it was single_request_table
       if (normalized.workflowArchetype === "single_request_table") {
         normalized.workflowArchetype = "multi_mode_request";
       }
     }

     return normalized;
   }
   ```

2. 同时在 `normalizeSceneIr` 中确保 `defaultMode` 和 `modeSwitchField` 有正确的默认值（已有 line 477-478 处理）

**验证**:
- 对单模式场景（如 `用户日电量监测`）运行生成，确认 `modes` 数组包含一个 default mode
- 确认 `workflowArchetype` 被正确升级为 `multi_mode_request`

**提交信息**:
```
feat(llm-client): auto-wrap single-mode scenes into modes array

When the LLM returns an empty modes array but has apiEndpoints,
automatically create a default mode with the first endpoint,
requestTemplate, responsePath, and normalizeRules. This ensures all
scenes compile through the multi-mode path.
```

---

## Phase 2: 增强提取

### Task 4: 增强 LLM prompt 的强制约束

**文件**: `frontend/scene-generator/llm-client.js`（`DEEP_SYSTEM_PROMPT`，line 19-82）

**当前状态**: prompt 中已列出 schema 但没有强调哪些字段是**必须**填充的。LLM 经常跳过 `contentType`、`responsePath`、`requestTemplate`。

**步骤**:

1. 在 `DEEP_SYSTEM_PROMPT` 的 schema 定义后，增加**强制字段约束**段落：

   ```
   MANDATORY FIELDS (never leave empty):
   - apiEndpoints[].contentType: detect from source code.
     * For $.ajax({}): look for 'contentType' property. Default 'application/json' if absent.
     * For $http.sendByAxios(): contentType is 'application/json' (axios default).
     * For XMLHttpRequest: look for setRequestHeader('Content-Type', ...).
     * For form submissions: 'application/x-www-form-urlencoded'.
   - modes[].responsePath: the JSON path from raw API response to the data array.
     * Common patterns: 'data.list', 'data.rcvblAcctSumAll.rcvblAcctVOS', 'content', 'data.records'
     * If response is the array itself, use empty string "".
   - modes[].requestTemplate: the static request body shape from the source code.
     * Extract ALL keys that appear in the request body object.
     * Mark dynamic values as "${args.fieldName}" and static values as literals.
   - apiEndpoints[].url: the full API URL as seen in the source code.

   RULES:
   - If you cannot determine contentType, default to 'application/json'.
   - If you cannot determine responsePath, default to '' (empty string).
   - If you cannot determine requestTemplate, use {} (empty object).
   - NEVER leave these fields as null or undefined.
   ```

2. 将这段文字插入到 `DEEP_SYSTEM_PROMPT` 中 schema 定义之后、`Instructions` 之前

**验证**:
- 对 `营销2.0零度户报表数据生成` 场景运行生成，确认 LLM 输出的 `contentType` 和 `responsePath` 不再为空
- 确认 `requestTemplate` 包含了业务必需字段

**提交信息**:
```
feat(llm-client): add mandatory field constraints to DEEP_SYSTEM_PROMPT

Explicitly require LLM to fill contentType, responsePath, and
requestTemplate with detected values or defaults. Reduces empty-field
rate from ~60% to target ~10%.
```

---

### Task 5: 增加业务 JS 文件提取

**文件**:
- `frontend/scene-generator/server.js`
- `frontend/scene-generator/generator-runner.js`

**当前状态**: `readDirectory` 在 `generator-runner.js` 中已经读取所有文件到 `dirContents`，但 `buildDeepAnalyzePrompt`（`llm-client.js` line 125-157）主要推送 `index.html` 的 fragments。业务 JS 文件（如 `js/mca.js`, `js/sgApi.js`）的内容没有被单独提取推送。

**步骤**:

1. **在 `generator-runner.js` 中增加业务 JS 文件识别**:
   - 在 `buildAnalysisContext` 函数中，增加一个 `businessJsFragments` 数组
   - 识别 `js/` 目录下的 `.js` 文件（排除 `vue.js`, `element-ui` 等第三方库）
   - 对每个业务 JS 文件，提取前 600 字符的关键片段（函数定义、API 调用、配置对象）
   - 将结果放入 `analysisContext.businessJsFragments`

2. **在 `llm-client.js` 的 `buildDeepAnalyzePrompt` 中推送业务 JS 片段**:
   - 在现有的 `pushFragments` 调用后增加：
     ```javascript
     pushFragments(parts, "business JS files", context.businessJsFragments, 4);
     ```
   - 确保总 prompt 大小不超过 `MAX_DEEP_PROMPT_CHARS`（60000）

3. **在 `server.js` 中确保业务 JS 文件被读取**:
   - 检查 `/handle-analyze-deep` 端点中 `readDirectory` 的调用是否已经读取了 `js/` 目录下的文件
   - 如果没有，增加对 `js/*.js` 文件的读取逻辑

**验证**:
- 对 `台区线损大数据` 场景运行，确认 `js/mca.js` 或类似业务文件的内容被推送给 LLM
- 确认 prompt 总大小不超过 60000 字符

**提交信息**:
```
feat(scene-generator): extract business JS files for LLM analysis

Identify and push js/ directory business logic files (mca.js, sgApi.js,
etc.) to the LLM prompt. Exclude third-party libraries. Capped at 4
fragments to stay within MAX_DEEP_PROMPT_CHARS budget.
```

---

### Task 6: 提取后验证与二次追问

**文件**: `frontend/scene-generator/llm-client.js`

**当前状态**: `analyzeSceneDeep` 拿到 LLM 返回后直接 `normalizeSceneIr` 然后返回，没有检查关键字段是否缺失。

**步骤**:

1. 新增 `validateExtractedSceneInfo(sceneIr)` 函数:
   ```javascript
   function validateExtractedSceneInfo(sceneIr) {
     const issues = [];

     // Check: at least one apiEndpoint has contentType
     const endpointsWithCt = (sceneIr.apiEndpoints || []).filter(
       ep => ep && ep.contentType
     );
     if ((sceneIr.apiEndpoints || []).length > 0 && endpointsWithCt.length === 0) {
       issues.push("missing_contentType_on_endpoints");
     }

     // Check: at least one mode has responsePath (if modes exist)
     if ((sceneIr.modes || []).length > 0) {
       const modesWithPath = sceneIr.modes.filter(m => m.responsePath !== undefined && m.responsePath !== null);
       if (modesWithPath.length === 0) {
         issues.push("missing_responsePath_on_modes");
       }
     }

     // Check: workflowArchetype is set
     if (!sceneIr.workflowArchetype) {
       issues.push("missing_workflowArchetype");
     }

     return issues;
   }
   ```

2. 在 `analyzeSceneDeep` 中，`normalizeSceneIr` 之后调用验证：
   ```javascript
   const issues = validateExtractedSceneInfo(normalized);
   if (issues.length > 0) {
     // Secondary prompt
     const followUpPrompt = `The previous extraction has these issues:\n${issues.join('\n')}\nPlease re-analyze the source snippets and fill in the missing fields. Use defaults if truly unavailable.`;

     const followUpContent = await requestChatCompletionWithRetry(
       [
         { role: "system", content: DEEP_SYSTEM_PROMPT },
         { role: "user", content: followUpPrompt },
       ],
       { ...config, maxTokens: 2400, timeoutMs: DEEP_REQUEST_TIMEOUT_MS, retryAttempts: 1 }
     );

     const repaired = normalizeSceneIr(await extractJsonFromResponseWithRepair(followUpContent, config));
     // Merge repaired fields into normalized (only fill empty fields)
     Object.assign(normalized, mergeSceneIrFields(repaired, normalized));
   }
   ```

3. 新增 `mergeSceneIrFields(repaired, original)` 辅助函数：
   - 仅当 original 的字段为空/默认值时，才用 repaired 的值覆盖
   - 避免丢失第一次提取的有效信息

**验证**:
- 模拟一个 LLM 返回缺少 `contentType` 的场景，确认二次追问触发
- 确认最多追问 1 次，不会无限循环

**提交信息**:
```
feat(llm-client): add post-extraction validation with one-shot retry

After LLM returns scene IR, validate that critical fields (contentType,
responsePath, workflowArchetype) are present. If missing, send one
follow-up prompt to fill gaps. Merges repaired fields without overwriting
valid data from the first extraction.
```

---

## Phase 3: 测试验证

### Task 7: 单元测试

**文件**: `tests/scene_generator_modes_test.rs`（新增）

**步骤**:

1. 创建测试文件 `tests/scene_generator_modes_test.rs`

2. 编写 5 个测试用例：

   ```rust
   #[cfg(test)]
   mod tests {
       use super::*; // adjust imports as needed
       use crate::generated_scene::generator::*;
       use crate::generated_scene::ir::*;
       use serde_json::json;

       #[test]
       fn test_single_mode_generates_modes_array() {
           // Create a SingleRequestTable scene with one endpoint
           let scene_ir = make_test_scene_ir();
           // ... assertions: generated JS contains "const MODES ="
       }

       #[test]
       fn test_multi_mode_generates_mode_routing() {
           // Create a MultiModeRequest scene with two modes
           // ... assertions: generated JS contains "detectMode"
       }

       #[test]
       fn test_snake_camel_consistency() {
           // Verify field name serialization is consistent
           // between Rust (snake_case) and JS (camelCase)
       }

       #[test]
       fn test_form_urlencoded_request_body() {
           // Create a mode with contentType = "application/x-www-form-urlencoded"
           // ... assertions: body is Object.entries().join('&'), not JSON.stringify
       }

       #[test]
       fn test_response_path_extraction_in_template() {
           // Create a mode with responsePath = "data.list"
           // ... assertions: generated JS contains "safeGet(raw, mode.responsePath"
       }
   }
   ```

3. 每个测试构造一个 `SceneIr` 实例，调用 `compile_multi_mode_request`，然后检查生成的字符串包含预期的代码片段

**验证**:
- `cargo test scene_generator_modes_test` 全部通过

**提交信息**:
```
test: add unit tests for multi-mode generation path

Covers: single-mode auto-wrap, multi-mode routing, snake/camel
consistency, form-urlencoded body format, and responsePath extraction.
```

---

### Task 8: 集成测试

**步骤**:

1. **选择两个代表性场景跑完整生成**:
   - 简单场景: `用户日电量监测`（模式 C，直接 AJAX）
   - 复杂场景: `台区线损大数据-月_周累计线损率统计分析`（模式 A，双模式）

2. **对比生成结果与 tq-lineloss-report**:
   - 对比 `SKILL.toml` 结构
   - 对比 `scripts/*.js` 的关键函数（`buildModeRequest`, `detectMode`, `normalizeRows`）
   - 对比 `scene.toml` 的 bootstrap 和 params 配置

3. **产出集成测试报告**:
   - 文件: `docs/superpowers/reports/2026-04-17-integration-test-report.md`
   - 内容: 差距清单、质量评分、遗留问题

4. **记录差距清单**:
   - 哪些字段仍未正确提取
   - 哪些逻辑仍需手动修正
   - 哪些场景仍不适合自动化

**验证**:
- 集成测试报告已写入
- 至少一个场景的生成质量达到 tq-lineloss-report 的 80% 以上

**提交信息**:
```
docs: add integration test report for scene generator quality

Generated skills for user-daily-power and tq-lineloss scenes. Compared
against manually-authored tq-lineloss-report. Quality assessment and
gap analysis documented.
```

---

## 执行顺序

```
Task 1 → Task 2 → Task 3 → Task 4 → Task 5 → Task 6 → Task 7 → Task 8
   ├──── Phase 1: 修基础 ────┤   ├───── Phase 2: 增强提取 ─────┤   ├─ Phase 3 ─┤
```

Phase 1 的三个任务有依赖关系（Task 1 必须先完成，Task 2 和 Task 3 可并行）。
Phase 2 的三个任务可并行（Task 4/5/6 修改不同文件）。
Phase 3 依赖 Phase 1+2 全部完成。

## 风险与缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| LLM 二次追问增加生成时间 | 用户体验下降 | 限制追问 1 次，超时 120s |
| 统一路径后 SingleRequestTable 场景生成的 JS 包含不必要的 mode 逻辑 | 脚本体积增大 | default mode 条件判断简单，性能影响可忽略 |
| 业务 JS 文件过多导致 prompt 超限 | LLM 无法处理 | 限制 4 个文件，每个 600 字符 |
| `processData` 修改影响现有正常场景 | 回归问题 | 仅对 form-urlencoded 设置 false，JSON 不受影响 |