# 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 插件调用契约
