# 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 ` 拉取结果 - 将结果推送至 OpenClaw 自己的通知/存储机制 ### 5.2 CLI 侧为 OpenClaw 提供的契约 ```bash # OpenClaw Skill 执行评测 agenteval run start --target-id --scenario-id # 返回包含 run-id 的输出 # OpenClaw Skill 拉取报告 agenteval report show --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 插件调用契约