AgentEvalTool

当前版本: v0.2.0 「稳」(2026-07-14) · 里程碑路线图见 docs/release-notes-v0.2.md

智能体质量评估工具集平台。

功能

• 评测对象管理（AI 数字员工 / AI 助手）
• 评测场景管理（YAML/JSON 配置）
• 异步评测执行引擎(v0.2:真并发/真取消/可配置超时)
• 评估规则（关键词匹配、响应时间、LLM 评分）
• 基础报告生成（JSON / HTML）
• OpenClaw 插件示例 + 免登录 iframe 集成
• Web 管理后台（FastAPI + React）

v0.2 亮点

• async EvalEngine + asyncio.Task 注册表,支持真取消与并发执行
• 安全基线:Pydantic Settings + .env + APIKey 鉴权 + CORS 收紧
• 测试基线:24 个测试,57% 覆盖率(engine 61%, runs.py 86%)
• 部署规范化:scripts/deploy-t480.sh 一键部署 + 镜像版本 tag + /api/health 验证
• Alembic 迁移:容器启动自动 alembic upgrade head

快速开始

安装

pip install -e ".[dev]"

CLI 使用

# 查看帮助
agenteval --help

# 添加评测对象
agenteval target add --name "社区医院AI客服" --config config/config.json

# 导入评测场景
agenteval scenario import data/scenarios/health_basic.yaml

# 执行评测
agenteval run start --target <target-id> --scenario <scenario-id>

# 查看报告
agenteval report show <run-id> --format json
agenteval report generate <run-id> --format html

启动 Web 后台

agenteval server start --host 0.0.0.0 --port 8000

启动 Web 前端

cd frontend/web
npm install
npm run dev

文档

完整的文档集位于 docs/ 目录：

• 文档索引 - 文档导航和快速查找
• 需求分析 - 项目背景、功能需求、验证标准
• 架构设计 - 系统架构、核心抽象、项目结构
• 数据模型 - 数据库表结构、模型关系
• API 参考 - CLI 命令和 Web API 文档
• 部署文档 - 部署指南和运维说明
• 使用指南 - 快速开始和详细使用指南
• 外部参考 - tutu-api 等外部文档

项目结构

AgentEvalTool/
├── backend/                # Python 后端代码
│   ├── agenteval/          # 核心 Python 库
│   │   ├── channels/       # 消息通道适配器
│   │   ├── agents/         # 评测智能体适配器
│   │   ├── scenarios/      # 评测场景模型和加载
│   │   ├── evaluation/     # 评估引擎和规则
│   │   ├── storage/        # 数据持久化（SQLite）
│   │   └── web/            # FastAPI Web 后台
│   ├── cli/                # CLI 命令入口
│   └── plugins/            # 外部平台插件
│       └── openclaw/       # OpenClaw 插件示例
├── frontend/               # React 前端
│   └── web/                # Web 管理界面
├── config/                 # 配置文件
│   └── config.json         # tutu-api 配置
├── scripts/                # 工具脚本
│   └── mock_call.py        # API 测试脚本
├── docs/                   # 完整文档集
│   ├── requirements-v1.0.md
│   ├── architecture-v1.0.md
│   ├── data-models-v1.0.md
│   ├── api-reference/
│   ├── deployment/
│   ├── guides/
│   └── external-references/
├── deploy/                 # 部署配置
│   └── t480/               # t480 服务器部署
├── data/                   # 本地数据和报告
│   ├── scenarios/          # 场景 YAML 文件
│   ├── reports/            # 生成的 HTML/JSON 报告
│   └── agenteval.db        # SQLite 数据库
└── tests/                  # 测试
    ├── unit/
    └── integration/

架构说明

AgentEvalTool 采用"CLI 工具集 + Web 后台"的交付方式：

• CLI 是核心能力入口，OpenClaw 可通过插件调用 CLI 完成评测自闭环。
• Web 后台提供可视化的对象、场景、执行、报告管理。
• 消息通道、评测智能体、评估规则均通过抽象接口定义，便于后续扩展。

许可证

MIT