# AgentEvalTool CLI 命令参考

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

---

## 一、概述

AgentEvalTool 提供命令行工具 `agenteval` 用于管理评测对象、场景、执行评测和生成报告。

**安装**：
```bash
pip install -e .
```

**主入口**：
```bash
agenteval [command] [subcommand] [options]
```

## 二、评测对象管理

### 2.1 列出所有评测对象

```bash
agenteval target list
```

### 2.2 添加评测对象

```bash
agenteval target add --name "社区医院AI客服" --config config/config.json
```

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

### 2.3 获取评测对象详情

```bash
agenteval target get <id>
```

### 2.4 更新评测对象

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

### 2.5 删除评测对象

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

### 2.6 测试评测对象连通性

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

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

## 三、评测场景管理

### 3.1 列出所有评测场景

```bash
agenteval scenario list
```

### 3.2 校验评测场景文件

```bash
agenteval scenario validate data/scenarios/health_basic.yaml
```

### 3.3 导入评测场景

```bash
agenteval scenario import data/scenarios/health_basic.yaml
```

### 3.4 导出评测场景

```bash
agenteval scenario export <id> > data/scenarios/health_basic.yaml
```

### 3.5 获取评测场景详情

```bash
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>
```

**参数**：
- `--target-id`: 评测对象 ID（必填）
- `--scenario-id`: 评测场景 ID（必填）
- `--output-json`: 运行结束后输出 JSON 报告（可选）

**示例**：
```bash
# 基本执行
agenteval run start --target-id aa4cd4e4-1c84-41d0-b3d7-06ee7dd94971 \
                    --scenario-id 5b1a8cf7-25bc-4424-97d0-795b61149c0c

# 执行并输出 JSON
agenteval run start --target-id <id> --scenario-id <id> --output-json
```

### 4.2 查看评测状态

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

### 4.3 列出所有评测记录

```bash
agenteval run list
```

### 4.4 查看评测日志（对话轮次）

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

## 五、报告管理

### 5.1 生成 HTML 报告

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

**参数**：
- `--format`: 报告格式，`html` 或 `json`（默认 `json`）

### 5.2 查看报告

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

### 5.3 对比报告

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

## 六、Web 服务

### 6.1 启动 Web 后台服务

```bash
agenteval server start --host 0.0.0.0 --port 8000
```

**参数**：
- `--host`: 监听地址（默认 `0.0.0.0`）
- `--port`: 监听端口（默认 `8000`）
- `--reload`: 开发模式热重载（可选）

## 七、OpenClaw 集成示例

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",
])
```

## 八、退出码

| 退出码 | 说明 |
|--------|------|
| 0 | 成功 |
| 1 | 一般错误（对象不存在、参数错误等） |
| 2 | 评测执行失败 |
| 3 | 通道连接失败 |