# 使用 OpenClaw + AgentEvalTool 进行 AI 评测的流程

## 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      AgentEvalTool 管理后台                       │
│                     http://192.168.8.145:8001                    │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │ 评测对象  │  │ 评测场景  │  │ 评测执行  │  │ AI 助手(OpenClaw)│ │
│  │ (Target) │  │(Scenario)│  │  (Run)   │  │                  │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
└──────────────┬───────────────────────────────┬──────────────────┘
               │ HTTP API + 轮询               │ iframe 嵌入
               ▼                               ▼
        ┌──────────────┐              ┌──────────────┐
        │  tutu-api    │              │  OpenClaw    │
        │  (被评测对象)  │              │  容器        │
        │  AI 客服      │              │  doubao-     │
        └──────────────┘              │  seed-2.0    │
                                      └──────────────┘
```

**角色说明：**

| 组件 | 角色 | 说明 |
|------|------|------|
| AgentEvalTool | 评测引擎 | 发送消息、收集回复、执行评测规则、生成报告 |
| tutu-api | 被评测对象 | AI 数字员工 / AI 助手，通过 tutu 聊天 API 收发消息 |
| OpenClaw | AI 助手 + 编排者 | 可通过对话触发评测，也可直接在管理后台使用 |

---

## 第一步：配置评测对象（Target）

评测对象是你要测试的 AI 系统。在管理后台「评测对象」页面新增。

### 配置信息

```json
{
  "base_url": "https://tutu-gateway.lovebenefits.com/tutu-api",
  "token": "Bearer JWT Token",
  "tenant": "sx-jczs",
  "chat_channel_id": "0qlox3lg",
  "chat_contact_id": "vooddlwv"
}
```

| 字段 | 说明 |
|------|------|
| `base_url` | tutu-api 网关地址 |
| `token` | 鉴权 JWT Token |
| `tenant` | 租户标识 |
| `chat_channel_id` | 聊天频道 ID |
| `chat_contact_id` | 聊天联系人 ID（模拟用户身份发消息） |

### 验证连通性

配置完成后点击「测试」按钮，系统会调用 `GET /api/{tenant}/v1/chat/message` 验证连通性。

---

## 第二步：创建评测场景（Scenario）

评测场景包含一组测试用例，每个用例定义要发送的消息和评测规则。

### 场景 JSON 格式

```json
[
  {
    "id": "case-001",
    "type": "single",
    "messages": [
      "你好，我想问下你们那边是否有做三伏灸"
    ],
    "expectations": {
      "response_time_max_ms": 30000,
      "keywords_include": ["三伏灸"]
    },
    "eval_rules": [
      {
        "type": "keyword_match",
        "params": { "keywords": ["三伏灸"] }
      },
      {
        "type": "response_time",
        "params": { "max_ms": 30000 }
      }
    ]
  }
]
```

### 多轮对话用例

```json
{
  "id": "case-002",
  "type": "multi_turn",
  "messages": [
    "你们医院在哪里",
    "周末可以看诊吗"
  ],
  "eval_rules": [
    {
      "type": "response_time",
      "params": { "max_ms": 30000 }
    }
  ]
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 用例唯一标识 |
| `type` | `single` / `multi_turn` | 单轮 / 多轮对话 |
| `messages` | string[] | 依次发送给被评测对象的消息列表 |
| `eval_rules` | object[] | 评测规则列表（见下方） |
| `expectations` | object | 预期结果（可自动推导规则） |

### 评测规则

| 规则类型 | 说明 | 参数 |
|----------|------|------|
| `keyword_match` | 检查回复是否包含/不包含指定关键词 | `keywords`: 必须包含的关键词列表 |
| `response_time` | 检查回复延迟是否在阈值内 | `max_ms`: 最大允许延迟（毫秒） |
| `llm_score` | 调用 LLM 对回复质量打分 | `api_url`, `api_key`, `model`, `criteria`, `min_score` |

> **提示**：如果不写 `eval_rules`，系统会根据 `expectations` 自动推导规则。

---

## 第三步：启动评测（Run）

### 方式一：Web 管理后台

1. 打开「评测执行」页面
2. 选择评测对象和评测场景
3. 点击「启动评测」
4. 右侧抽屉实时显示 WebSocket 推送的执行日志

### 方式二：CLI 命令

```bash
agenteval run start --target-id <target_id> --scenario-id <scenario_id>
```

### 方式三：OpenClaw AI 助手

在管理后台的「AI 助手」页面，通过对话让 OpenClaw 帮你触发评测：

```
请帮我执行一次评测，评测对象是社区医院AI客服，场景是社区医院基础服务评测
```

OpenClaw 会通过插件调用 `agenteval run start` CLI 命令，并返回评测报告。

---

## 第四步：查看评测结果

### 执行过程（实时）

评测启动后，系统对每个用例依次执行：

```
发送消息 → 轮询等待回复（最长30秒）→ 记录对话 → 执行评测规则 → 输出结果
```

WebSocket 实时推送以下事件：

| 事件 | 说明 |
|------|------|
| `case_start` | 开始执行某个用例 |
| `turn_end` | 一轮对话完成（含用户消息 + AI 回复 + 延迟） |
| `rule_result` | 一条评测规则的判定结果 |
| `turn_error` | 消息发送或回复超时 |

### 评测报告

评测完成后，在「评测报告」页面查看：

- **统计数据**：总用例数、通过数、失败数、通过率
- **元信息**：评测对象、场景、开始/完成时间
- **用例明细**：每个用例的逐轮对话内容 + 规则判定结果

也可以导出 HTML 报告。

---

## 当前已配置的资源

### 评测对象

| 名称 | 平台 | 通道 | 状态 |
|------|------|------|------|
| 社区医院AI客服 | AI 数字员工 | tutu-api | active |

### 评测场景

| 名称 | 用例数 | 标签 |
|------|--------|------|
| 社区医院基础服务评测 | 2 | health, basic-service |
| 科室导航与挂号咨询 | 3 | health, department, navigation |

### 历史评测记录

已执行 8 次评测，全部通过（pass_rate 100%），平均响应时间约 11 秒。

---

## 快速上手 Checklist

- [ ] 确认评测对象连通性（管理后台 → 评测对象 → 测试）
- [ ] 创建或选择评测场景
- [ ] 启动评测（Web UI / CLI / OpenClaw 对话）
- [ ] 查看实时执行日志
- [ ] 查看评测报告和用例明细