AgentEvalTool/docs/guides/user-guide-v1.0.md

# AgentEvalTool 用户使用指南

**版本**: v1.0  
**日期**: 2026-07-09  
**状态**: 已发布  
**作者**: AgentEval Team

---

## 一、概述

本指南详细介绍 AgentEvalTool 的各项功能和使用方法，帮助用户充分利用平台进行智能体质量评估。

## 二、评测对象管理

### 2.1 添加评测对象

评测对象代表被评估的智能体服务。

```bash
agenteval target add --name "对象名称" --config config/config.json
```

**参数说明**：
- `--name`: 对象名称（必填）
- `--config`: 通道配置文件路径（必填）

**配置文件格式**（tutu-api）：
```json
{
  "base_url": "https://api.example.com",
  "token": "jwt-token",
  "tenant": "tenant-id",
  "chat_channel_id": "channel-id",
  "chat_contact_id": "contact-id"
}
```

### 2.2 查看评测对象

```bash
# 列出所有对象
agenteval target list

# 查看对象详情
agenteval target get <id>
```

### 2.3 更新评测对象

```bash
agenteval target update <id> --config config/config.json
```

### 2.4 删除评测对象

```bash
agenteval target remove <id>
```

### 2.5 测试连通性

```bash
agenteval target test <id>
```

验证消息通道是否正常连接。

## 三、评测场景管理

### 3.1 场景文件格式

评测场景使用 YAML 格式定义：

```yaml
name: 场景名称
description: 场景描述
tags:
  - tag1
  - tag2
cases:
  - id: case-001
    type: single  # single 或 multi_turn
    messages:
      - "你好，我想咨询一个问题"
    expectations:
      keywords:
        - "你好"
        - "咨询"
      excluded_keywords:
        - "错误"
    eval_rules:
      - type: keyword_match
        config:
          keywords: ["你好", "咨询"]
      - type: response_time
        config:
          threshold_ms: 30000
```

### 3.2 导入场景

```bash
agenteval scenario import path/to/scenario.yaml
```

### 3.3 校验场景

```bash
agenteval scenario validate path/to/scenario.yaml
```

### 3.4 导出场景

```bash
agenteval scenario export <id> > path/to/scenario.yaml
```

### 3.5 查看场景

```bash
# 列出所有场景
agenteval scenario list

# 查看场景详情
agenteval scenario get <id>
```

### 3.6 删除场景

```bash
agenteval scenario remove <id>
```

## 四、评测执行

### 4.1 启动评测

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

**可选参数**：
- `--output-json`: 运行结束后输出 JSON 报告

**执行过程**：
1. 验证对象和场景存在
2. 逐个执行用例
3. 发送消息并等待回复
4. 应用评估规则
5. 记录结果
6. 生成摘要

### 4.2 查看评测状态

```bash
agenteval run status <run-id>
```

### 4.3 查看评测列表

```bash
agenteval run list
```

### 4.4 查看评测日志

```bash
agenteval run logs <run-id>
```

显示所有对话轮次的详细信息。

## 五、报告管理

### 5.1 查看报告（JSON）

```bash
agenteval report show <run-id> --format json
```

**报告内容**：
- 运行基本信息（ID、对象、场景、时间）
- 执行摘要（总用例数、通过数、失败数、通过率）
- 用例详情（每轮对话、评估结果）

### 5.2 生成报告（HTML）

```bash
agenteval report generate <run-id> --format html
```

报告保存在 `data/reports/` 目录。

### 5.3 对比报告

```bash
agenteval report compare <run-id-1> <run-id-2>
```

对比两次评测的结果差异。

## 六、评估规则

### 6.1 关键词匹配规则（keyword_match）

检查回复是否包含指定关键词。

```yaml
eval_rules:
  - type: keyword_match
    config:
      keywords: ["关键词1", "关键词2"]
      excluded_keywords: ["排除词1"]
```

### 6.2 响应时间规则（response_time）

检查响应时间是否在阈值内。

```yaml
eval_rules:
  - type: response_time
    config:
      threshold_ms: 30000  # 30秒
```

### 6.3 LLM 评分规则（llm_score）

调用 LLM 对回复质量打分（需配置外部 LLM API）。

```yaml
eval_rules:
  - type: llm_score
    config:
      api_url: "https://api.openai.com/v1/chat/completions"
      api_key: "your-api-key"
      model: "gpt-4"
      prompt_template: "请评估以下回复的质量：{reply}"
      min_score: 0.7
```

## 七、Web 界面

### 7.1 启动服务

```bash
# 启动后端
agenteval server start --host 0.0.0.0 --port 8000

# 启动前端（开发模式）
cd frontend/web
npm install
npm run dev
```

### 7.2 功能页面

- **首页**：评测运行概览
- **评测对象页**：列表、新增/编辑、连通性测试
- **评测场景页**：列表、YAML 在线编辑、校验
- **评测执行页**：运行列表、实时日志、触发运行
- **报告页**：报告列表、报告详情（得分、明细、失败项）

## 八、OpenClaw 集成

### 8.1 插件调用方式

OpenClaw 通过调用 CLI 完成评测：

```python
import subprocess

# 触发评测
subprocess.run([
    "agenteval", "run", "start",
    "--target-id", "<target-id>",
    "--scenario-id", "<scenario-id>",
], check=True)

# 获取报告
report = subprocess.check_output([
    "agenteval", "report", "show", "<run-id>", "--format", "json",
])
```

### 8.2 定时评测

在 OpenClaw 中配置定时任务：

```yaml
skill: agenteval_skill
schedule: "0 9 * * *"  # 每天早上 9 点
config:
  target_id: "<target-id>"
  scenario_id: "<scenario-id>"
  report_format: "json"
```

## 九、最佳实践

### 9.1 场景设计

- 覆盖核心业务场景
- 包含正常和异常用例
- 设置合理的响应时间阈值
- 使用多维度评估规则

### 9.2 Token 管理

- 定期检查 token 有效期
- 建立 token 更新流程
- 使用环境变量或密钥管理服务

### 9.3 数据备份

- 定期备份 `data/` 目录
- 导出重要场景文件
- 保留关键评测报告

### 9.4 性能优化

- 避免并发评测同一目标
- 合理设置响应时间阈值
- 使用 LLM 评分时注意成本

## 十、故障排查

### 10.1 通道连接失败

**原因**：
- Token 过期
- 网络问题
- 配置错误

**解决**：
```bash
# 测试连通性
agenteval target test <id>

# 检查配置
cat config/config.json
```

### 10.2 评测超时

**原因**：
- 目标智能体响应慢
- 阈值设置过低

**解决**：
- 调整 `response_time` 规则的 `threshold_ms`
- 检查目标智能体状态

### 10.3 报告生成失败

**原因**：
- 数据目录权限问题
- 磁盘空间不足

**解决**：
```bash
# 检查权限
ls -la data/

# 检查磁盘空间
df -h data/
```

## 十一、获取帮助

- [快速开始指南](quick-start-v1.0.md)
- [CLI 命令参考](../api-reference/cli-v1.0.md)
- [Web API 参考](../api-reference/web-api-v1.0.md)
- [架构设计文档](../architecture-v1.0.md)
- [部署文档](../deployment/README.md)