# AgentEvalTool 需求分析文档

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

---

## 一、项目背景与目标

### 1.1 项目目标

构建一套智能体质量评估工具集平台，用于评估 AI 数字员工（大模型 + RAG）和 AI 助手（OpenClaw）的服务质量、效率与安全性，形成"定义评估 → 执行评估 → 分析结果 → 改进优化"的闭环。

### 1.2 当前进展

- 验证 tutu-api 消息通道连通性（`scripts/mock_call.py`）
- 确认消息发送、SSE 流式、历史记录查询接口可用
- 确认 `questionMsgId` 可用于问答配对
- 确认目标智能体可自动回复

### 1.3 V1 目标

在架构上保留扩展性，先跑通最小可用闭环：

**评测对象管理 → 评测场景管理 → OpenClaw 驱动评测 → 基础报告**

## 二、功能需求

### 2.1 评测对象管理

- 支持注册和管理多种评测对象（AI 数字员工、AI 助手）
- 支持配置消息通道参数（tutu-api 等）
- 支持连通性测试
- 支持对象状态管理（active/inactive/error）

### 2.2 评测场景管理

- 支持 YAML/JSON 格式的场景定义
- 支持单轮和多轮对话用例
- 支持评估规则配置（关键词匹配、响应时间、LLM 评分）
- 支持场景导入/导出/校验

### 2.3 评测执行

- 支持手动触发评测任务
- 支持实时进度反馈
- 支持对话轮次记录
- 支持评估结果持久化

### 2.4 报告生成

- 支持 JSON 格式报告
- 支持 HTML 格式报告
- 支持报告对比
- 展示总分、用例明细、规则通过/失败情况、响应时间

### 2.5 OpenClaw 集成

- 提供 CLI 接口供 OpenClaw 插件调用
- 支持评测策略编排（场景选择、调度、通知）
- OpenClaw 无需关心底层消息通道细节

### 2.6 Web 管理界面

- 评测对象可视化管理
- 评测场景在线编辑和校验
- 评测执行状态查看
- 报告查看和下载

## 三、非功能需求

### 3.1 可扩展性

- 消息通道、评测智能体、评估规则均通过抽象接口定义
- V1 只实现 tutu-api 与 OpenClaw 适配器，预留扩展点

### 3.2 数据可追踪

- 每轮对话、每次评测、每条评估结果都持久化
- 便于审计和对比分析

### 3.3 本地优先

- V1 使用 SQLite 和本地文件存储
- 降低部署成本，无需外部数据库

### 3.4 CLI 为核心

- 平台能力优先暴露为 CLI 工具
- OpenClaw 通过插件调用 CLI 自闭环完成评测策略编排

## 四、验证标准

1. CLI 可以完成：对象 CRUD、场景导入、手动运行、HTML 报告生成
2. 单次评测可以成功通过 tutu-api 发送消息并接收目标智能体回复
3. 报告准确展示总分、用例明细、规则通过/失败情况、响应时间
4. OpenClaw 插件 README 中的示例命令可以直接调用 CLI 完成一次评测并获取报告
5. Web 后台可以查看对象、场景、运行记录和报告

## 五、风险与约束

### 5.1 Token 过期

tutu-api token 为 30 天有效期，需在文档中标注，并预留 token 刷新机制设计（V1 手动更新 config）。

### 5.2 并发评测

V1 对同一目标建议串行执行，避免消息乱序；架构上保留并发控制设计。

### 5.3 LLM 评估成本

`LlmScoreRule` 需要配置外部 LLM API，V1 作为可选规则，默认使用关键词规则。

### 5.4 OpenClaw 环境依赖

插件示例假设 OpenClaw 环境已部署并可执行 shell 命令调用 `agenteval` CLI。