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