# PRD — 智能定位 Claude 语义增强

> **文档版本**: v1.0  
> **创建日期**: 2026-08-06  
> **作者**: Claude Code  
> **状态**: 待确认

---

## 一、背景与问题

### 1.1 当前智能定位的局限

当前智能定位采用**纯关键词匹配**算法，在微前端架构的复杂页面中存在精度问题：

| 问题类型 | 示例 | 根因 |
|---------|------|------|
| 关键词撞车 | "点击会议预约分类" 匹配到 "新建会议按钮" | 多个元素包含相同关键词 |
| 元素类型误判 | "会议名称输入" 匹配到按钮而非输入框 | 关键词匹配无法理解"输入"需要 input 元素 |
| 上下文缺失 | 无法判断步骤执行顺序对元素可见性的影响 | 每个步骤独立定位，无上下文关联 |
| 语义理解缺失 | "点击编辑按钮" 无法定位到图标按钮 | 无法理解"编辑"可能对应图标而非文本 |

### 1.2 实际案例

```
用例：会议管理-新建会议

步骤8: 点击会议预约分类
  当前定位: div:has-text("新建会议")  ❌ 错误
  
步骤9: 点击新建会议按钮
  当前定位: div:has-text("新建会议")  ✅ 正确但撞车
  
步骤10: 会议名称输入：自动化新建会议
  当前定位: div:has-text("新建会议")  ❌ 应该是 input 元素
```

### 1.3 解决思路

引入 **Claude CLI 语义理解能力**，对关键词匹配的候选结果进行二次筛选：

```
原流程：关键词匹配 → 返回第一个匹配元素
新流程：关键词匹配 → 获取候选列表 → Claude语义排序 → 返回最精确元素
```

---

## 二、目标与非目标

### 2.1 目标

1. **提升定位精确度**：从当前 ~60% 提升至 90%+
2. **支持语义理解**：理解步骤意图（输入、点击、选择等）
3. **支持上下文关联**：基于前序步骤判断当前步骤的元素范围
4. **可控成本**：仅在有多个候选时调用 Claude，单候选直接返回
5. **可回退**：Claude 服务不可用时自动回退到关键词匹配

### 2.2 非目标

1. 不替代 Playwright 执行引擎
2. 不修改前端界面
3. 不处理非 UI 类步骤（如数据库验证）
4. 不支持多语言步骤描述（仅中文）

---

## 三、技术方案

### 3.1 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                    智能定位 API                          │
│               POST /api/element/smart-locate            │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Step 1: 关键词初筛                          │
│   - 提取步骤关键词                                        │
│   - Playwright 遍历页面元素（含 iframe/微前端）           │
│   - 返回候选元素列表（按置信度排序）                       │
└─────────────────────┬───────────────────────────────────┘
                      │
          候选数 > 1 ? │
                      │
        ┌─────────────┴─────────────┐
        │ Yes                       │ No
        ▼                           ▼
┌───────────────────┐      ┌───────────────────┐
│ Step 2: Claude    │      │ 直接返回唯一候选   │
│ 语义排序          │      └───────────────────┘
│ - 构建候选描述    │
│ - 调用 Claude API │
│ - 返回最优选择    │
└────────┬──────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│              Step 3: 返回定位结果                        │
│   - 选择器信息                                          │
│   - 置信度分数                                          │
│   - 排序理由（可选，用于调试）                           │
└─────────────────────────────────────────────────────────┘
```

### 3.2 Claude 调用策略

**调用时机**：仅当候选元素 ≥ 2 个时调用

**调用方式**：宿主机 Claude CLI（已部署在 192.168.5.60）

**Prompt 模板**：

```
你是一个 UI 自动化测试专家。请根据步骤描述，从候选元素中选择最匹配的一个。

## 步骤信息
- 步骤名称: {step_name}
- 动作类型: {action}
- 参数: {params}

## 候选元素列表
{candidate_elements}

## 选择标准
1. 元素类型匹配动作类型（如 fill 需要 input/textarea）
2. 文本内容语义匹配步骤描述
3. 元素位置合理（如按钮应在可操作区域）
4. 考虑前序步骤的上下文

## 输出格式
返回 JSON:
{
  "selected_index": 0,  // 选中候选的索引（从0开始）
  "confidence": 0.95,   // 置信度 0-1
  "reason": "选择理由"
}
```

### 3.3 候选元素描述格式

```json
[
  {
    "index": 0,
    "tag": "BUTTON",
    "text": "新建会议",
    "selector": "button:has-text(\"新建会议\")",
    "attributes": {
      "class": "el-button el-button--primary",
      "type": "button"
    },
    "position": {"x": 100, "y": 200, "width": 80, "height": 32}
  },
  {
    "index": 1,
    "tag": "DIV",
    "text": "会议预约",
    "selector": ".el-drawer >> text=\"会议预约\"",
    "attributes": {
      "class": "menu-item"
    },
    "position": {"x": 50, "y": 150, "width": 200, "height": 40}
  }
]
```

### 3.4 成本控制

| 场景 | Claude 调用 | 预估成本 |
|------|------------|---------|
| 单候选元素 | 不调用 | 0 |
| 2-5 个候选 | 调用 1 次 | ~0.01 元 |
| 6-10 个候选 | 调用 1 次 | ~0.02 元 |
| 10+ 个候选 | 调用 1 次（限制最多传 10 个） | ~0.03 元 |

**预估日均成本**：假设每天定位 100 个步骤，平均 50% 需要调用 Claude
- 日成本：100 × 0.5 × 0.02 = **1 元/天**
- 月成本：**30 元/月**

### 3.5 容错与回退

| 异常场景 | 处理策略 |
|---------|---------|
| Claude CLI 不可用 | 回退到关键词匹配，日志记录告警 |
| Claude 响应超时（>10s） | 回退到关键词匹配 |
| Claude 返回格式错误 | 回退到关键词匹配，日志记录原始响应 |
| 所有候选都不合适 | 返回置信度最高的候选 + 低置信度标记 |

---

## 四、API 设计

### 4.1 智能定位请求（不变）

```http
POST /api/element/smart-locate
Content-Type: application/json

{
  "steps": [
    {
      "order": 1,
      "name": "点击新建会议按钮",
      "action": "click",
      "params": {}
    }
  ],
  "auto_login": true,
  "navigate_menu": "会议预约",
  "page_url": "https://192.168.5.44",
  "use_claude": true  // 新增：是否启用 Claude 增强，默认 true
}
```

### 4.2 智能定位响应（增强）

```json
{
  "success": true,
  "total_steps": 1,
  "located_steps": 1,
  "results": [
    {
      "order": 1,
      "name": "点击新建会议按钮",
      "success": true,
      "action": "click",
      "params": {
        "selector": "button:has-text(\"新建会议\")"
      },
      "selectors": {
        "primary": "button:has-text(\"新建会议\")",
        "candidates": [
          {
            "type": "css",
            "value": "button:has-text(\"新建会议\")",
            "confidence": 0.95,
            "priority": 1
          }
        ]
      },
      "claude_enhanced": true,           // 新增：是否经过 Claude 增强
      "claude_reason": "步骤要求点击按钮，候选1是BUTTON元素且文本完全匹配",  // 新增：Claude 选择理由
      "message": "Claude语义增强定位成功"
    }
  ]
}
```

---

## 五、实现范围

### 5.1 本次实现

| 模块 | 内容 | 优先级 |
|------|------|--------|
| Claude CLI 集成 | 调用宿主机 Claude CLI 进行语义排序 | P0 |
| 候选元素收集 | 扩展 keyword_matcher.py，收集候选详情 | P0 |
| Prompt 模板 | 设计高效的 Claude Prompt | P0 |
| 容错机制 | 超时、异常、格式错误的回退处理 | P0 |
| 配置开关 | `use_claude` 参数控制是否启用 | P1 |
| 日志记录 | Claude 调用日志、选择理由记录 | P1 |

### 5.2 后续迭代

| 模块 | 内容 | 优先级 |
|------|------|--------|
| 上下文增强 | Claude 可获取前序步骤信息 | P2 |
| 批量优化 | 多步骤批量调用 Claude，减少调用次数 | P2 |
| 缓存机制 | 相似步骤复用 Claude 结果 | P2 |
| 前端展示 | 定位结果展示 Claude 选择理由 | P3 |

---

## 六、验收标准

### 6.1 功能验收

| 测试场景 | 预期结果 |
|---------|---------|
| 单候选元素 | 不调用 Claude，直接返回 |
| 多候选元素 | 调用 Claude，返回最精确的选择器 |
| Claude 不可用 | 自动回退，不影响定位流程 |
| 复杂步骤（如"点击编辑按钮"） | 正确定位到图标按钮 |

### 6.2 性能验收

| 指标 | 目标 |
|------|------|
| 单步骤定位时间（无 Claude） | ≤ 3s |
| 单步骤定位时间（有 Claude） | ≤ 5s |
| Claude 调用成功率 | ≥ 99% |

### 6.3 精度验收

使用现有 19 个 UI 用例进行回归测试：

| 指标 | 当前 | 目标 |
|------|------|------|
| 步骤定位成功率 | ~60% | ≥ 85% |
| 选择器误匹配率 | ~40% | ≤ 15% |

---

## 七、风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| Claude CLI 服务不稳定 | 定位失败率上升 | 自动回退 + 告警通知 |
| 成本超预算 | 运营成本增加 | 每日用量监控 + 阈值告警 |
| Prompt 效果不佳 | 定位精度不达预期 | A/B 测试 + 迭代优化 |
| 响应延迟高 | 用户体验下降 | 超时控制 + 异步调用 |

---

## 八、参考资料

- `HANDOFF_UI自动化.md` — UI 自动化模块交接文档
- `_PRD_自然语言用例智能定位功能.md` — 原智能定位 PRD
- `backend/app/services/keyword_matcher.py` — 当前关键词匹配实现
- `backend/app/services/smart_locate_service.py` — 智能定位服务

---

*本文档待用户确认后进入执行计划阶段。*
