a77cd83e6a
## 新增功能 - 文件管理模块：分类树 + 文件上传/下载/删除 - 文件上传支持拖拽（Dragger）+ 手动上传（customRequest 模式） ## 页面布局统一（参照评测执行页） - 仪表盘/评测对象/评测场景/评测报告 全部改为全高 flex 布局 - 统一内联页头样式（h2 + 竖线分隔 + 描述） - 表格撑满高度、overflow 处理 - 每页添加刷新按钮 ## Bug 修复 - 分类树操作按钮 hover 不可见（CSS 规则缺失） - 文件上传失败（multipart boundary 缺失） - LLM API 响应 content blocks 数组格式支持（_extract_content_from_api_response） - response_time_max_ms 被静默忽略（隐式规则传空 params） - 空 messages 导致 IndexError 崩溃 - poll_reply 异常中止整个 run（缺 try/catch） - engine finally 未关闭 session - 3 个页面 UTC 时间戳解析偏差 8 小时 ## 后端 - EvalEngine: poll_reply 异常保护、空 dialog 保护、session 关闭 - LLM API 响应解析支持 content-block-array 格式 - 隐式 response_time 规则正确传递 max_ms 参数 ## 前端 - api.ts: 移除手动 Content-Type（让浏览器自动添加 boundary） - Files.tsx: customRequest 替代 beforeUpload、布局优化 - index.css: 分类树 hover 规则 - Targets/Scenarios/Home/Reports: 全高布局改造 - 3 个页面时间戳改用 formatDateTime()（修复 UTC 偏差） Co-Authored-By: Claude <noreply@anthropic.com>
216 lines
11 KiB
Markdown
216 lines
11 KiB
Markdown
# AgentEvalTool 架构设计文档
|
||
|
||
**版本**: v1.0
|
||
**日期**: 2026-07-09
|
||
**状态**: 已发布
|
||
**作者**: AgentEval Team
|
||
|
||
---
|
||
|
||
## 一、架构原则
|
||
|
||
1. **抽象优先**：消息通道、评测智能体、评估规则均通过接口/抽象类定义，V1 只实现 tutu-api 与 OpenClaw 适配器。
|
||
2. **CLI 为核心**：平台能力优先暴露为 CLI 工具，OpenClaw 通过插件调用 CLI 自闭环完成评测策略编排。
|
||
3. **Web 为辅助**：Web 后台用于可视化管理和报告查看，V1 保持轻量。
|
||
4. **数据可追踪**：每轮对话、每次评测、每条评估结果都持久化，便于审计和对比。
|
||
5. **本地优先**：V1 使用 SQLite 和本地文件存储，降低部署成本。
|
||
|
||
## 二、系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ OpenClaw 平台 │
|
||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||
│ │ OpenClaw 插件 (agenteval-openclaw-plugin) │ │
|
||
│ │ - 读取 OpenClaw 中配置的评测策略（场景、对象、调度） │ │
|
||
│ │ - 调用 AgentEvalTool CLI 执行评测任务 │ │
|
||
│ └───────────────────────┬──────────────────────────────────────┘ │
|
||
│ │ shell / subprocess │
|
||
└──────────────────────────┼──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ AgentEvalTool CLI 工具集 │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │ eval-target│ │eval-scenario│ │ eval-run │ │eval-report │ │
|
||
│ │ 评测对象 │ │ 评测场景 │ │ 执行引擎 │ │ 报告生成 │ │
|
||
│ └────────────┘ └────────────┘ └─────┬──────┘ └────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────────────────────┼────────────────────────┐ │
|
||
│ │ Core Evaluation Library │ │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─┴─────────────┐ ┌────────┐│ │
|
||
│ │ │EvalChannel │ │ EvalAgent │ │EvalEngine │ │ Scorer ││ │
|
||
│ │ │ 消息通道 │ │ 评测智能体 │ │ 执行编排 │ │ 评估器 ││ │
|
||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └────────┘│ │
|
||
│ └──────────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│ HTTP / SQLite
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ AgentEvalTool Web Backend (FastAPI) │
|
||
│ - 评测对象管理 API │
|
||
│ - 评测场景管理 API │
|
||
│ - 评测执行状态 API │
|
||
│ - 报告查看 API │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ AgentEvalTool Web Frontend (React) │
|
||
│ - 管理界面：对象、场景、执行列表、报告 │
|
||
│ - 报告详情页：得分、明细、趋势 │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 三、核心抽象设计
|
||
|
||
### 3.1 消息通道抽象 `EvalChannel`
|
||
|
||
```python
|
||
class EvalChannel(ABC):
|
||
@abstractmethod
|
||
def send(self, message: EvalMessage) -> SendResult: ...
|
||
|
||
@abstractmethod
|
||
def poll_reply(self, question_msg_id: str, timeout: float) -> Optional[Reply]: ...
|
||
|
||
@abstractmethod
|
||
def health_check(self) -> ChannelHealth: ...
|
||
```
|
||
|
||
V1 实现：`TutuApiChannel`（基于现有 `scripts/mock_call.py` 逻辑提取封装）。
|
||
预留扩展：OpenClawChannel、HttpChannel。
|
||
|
||
### 3.2 评测智能体抽象 `EvalAgent`
|
||
|
||
```python
|
||
class EvalAgent(ABC):
|
||
@abstractmethod
|
||
def run(self, scenario: Scenario, channel: EvalChannel) -> RunResult: ...
|
||
```
|
||
|
||
V1 实现：`OpenClawPluginAgent`（实际评测行为由 OpenClaw 技能完成，CLI 侧提供统一接口供插件调用）。
|
||
预留扩展：`ScriptAgent`、`HermesAgent`。
|
||
|
||
### 3.3 评估规则抽象 `EvalRule`
|
||
|
||
```python
|
||
class EvalRule(ABC):
|
||
@abstractmethod
|
||
def evaluate(self, case: Case, dialog: List[Turn]) -> RuleResult: ...
|
||
```
|
||
|
||
V1 实现：
|
||
- `KeywordMatchRule`：关键词包含/排除匹配
|
||
- `ResponseTimeRule`：响应时间阈值
|
||
- `LlmScoreRule`：调用 LLM 对回复质量打分
|
||
|
||
### 3.4 评估标准来源抽象 `StandardSource`
|
||
|
||
V1 实现：`FileStandardSource`（从 YAML/JSON 文件加载）。
|
||
预留扩展：`KbStandardSource`、`SopStandardSource`。
|
||
|
||
## 四、项目结构
|
||
|
||
```
|
||
AgentEvalTool/
|
||
├── backend/ # Python 后端代码
|
||
│ ├── agenteval/ # 核心 Python 库
|
||
│ │ ├── channels/ # 消息通道适配器
|
||
│ │ ├── agents/ # 评测智能体适配器
|
||
│ │ ├── scenarios/ # 评测场景
|
||
│ │ ├── evaluation/ # 评估分析
|
||
│ │ │ └── rules/ # 规则实现
|
||
│ │ ├── storage/ # 数据持久化
|
||
│ │ └── web/ # FastAPI 后台
|
||
│ │ └── routers/
|
||
│ ├── cli/ # CLI 入口
|
||
│ └── plugins/ # 外部平台插件
|
||
│ └── openclaw/ # OpenClaw 插件
|
||
├── frontend/ # React 前端
|
||
│ └── web/
|
||
├── docs/ # 文档
|
||
│ ├── requirements-v1.0.md # 需求分析
|
||
│ ├── architecture-v1.0.md # 架构设计
|
||
│ ├── data-models-v1.0.md # 数据模型
|
||
│ ├── api-reference/ # API 参考
|
||
│ ├── deployment/ # 部署文档
|
||
│ ├── guides/ # 使用指南
|
||
│ └── external-references/ # 外部参考文档
|
||
├── config/ # 配置文件
|
||
│ └── config.json # tutu-api 配置
|
||
├── scripts/ # 工具脚本
|
||
│ └── mock_call.py # API 调用脚本
|
||
├── data/ # 本地数据目录
|
||
│ ├── scenarios/ # 场景 YAML 文件
|
||
│ ├── reports/ # 报告 HTML/JSON 输出
|
||
│ └── agenteval.db # SQLite 数据库
|
||
├── tests/ # 测试
|
||
│ ├── unit/
|
||
│ └── integration/
|
||
├── deploy/ # 部署配置
|
||
│ └── t480/ # t480 服务器部署
|
||
├── pyproject.toml # 项目依赖与脚本入口
|
||
└── README.md
|
||
```
|
||
|
||
## 五、OpenClaw 插件集成
|
||
|
||
OpenClaw 插件以 Skill 形式存在，通过调用 AgentEvalTool CLI 完成评测。
|
||
|
||
### 5.1 插件职责
|
||
|
||
- 在 OpenClaw 侧配置评测策略（目标、场景、触发时机）
|
||
- 触发时调用本地或远程的 `agenteval run start ...`
|
||
- 获取 run-id 后调用 `agenteval report show <run-id>` 拉取结果
|
||
- 将结果推送至 OpenClaw 自己的通知/存储机制
|
||
|
||
### 5.2 CLI 侧为 OpenClaw 提供的契约
|
||
|
||
```bash
|
||
# OpenClaw Skill 执行评测
|
||
agenteval run start --target-id <id> --scenario-id <id>
|
||
# 返回包含 run-id 的输出
|
||
|
||
# OpenClaw Skill 拉取报告
|
||
agenteval report show <run-id> --format json
|
||
# 返回完整报告 JSON
|
||
```
|
||
|
||
### 5.3 自闭环说明
|
||
|
||
OpenClaw 无需关心 tutu-api 细节，只需使用 `agenteval` CLI 作为统一接口；评测策略（场景选择、调度、通知）完全由 OpenClaw 自身能力编排。
|
||
|
||
## 六、关键实现步骤
|
||
|
||
### Step 1：项目骨架搭建
|
||
- 创建 `pyproject.toml` 定义依赖（Typer、Pydantic、SQLModel、FastAPI、Jinja2、PyYAML、requests）
|
||
- 创建 `backend/` 目录结构，分离 Python 后端代码
|
||
- 保留 `scripts/mock_call.py` 作为历史参考
|
||
|
||
### Step 2：核心库实现
|
||
- 实现数据模型（Pydantic / SQLModel）
|
||
- 实现 `TutuApiChannel`
|
||
- 实现 `EvalEngine` 基础执行流程
|
||
- 实现 SQLite Repository 层
|
||
|
||
### Step 3：CLI 实现
|
||
- 使用 Typer 实现 `agenteval` 主命令和子命令模块
|
||
- 先完成 `target` 和 `scenario` 管理
|
||
- 再实现 `run` 执行与 `report` 报告
|
||
|
||
### Step 4：评估规则实现
|
||
- `KeywordMatchRule`
|
||
- `ResponseTimeRule`
|
||
- `LlmScoreRule`
|
||
|
||
### Step 5：OpenClaw 插件示例
|
||
- 在 `backend/plugins/openclaw/` 提供最小 Skill 示例
|
||
- 编写 README 说明接入方式
|
||
|
||
### Step 6：Web 后台
|
||
- FastAPI 实现 REST API
|
||
- React 实现最小管理界面
|
||
|
||
### Step 7：验证
|
||
- 使用真实 tutu-api 配置跑通一次完整评测
|
||
- 验证报告生成
|
||
- 验证 OpenClaw 插件调用契约
|