AgentEvalTool/docs/architecture-v1.0.md

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

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

class EvalAgent(ABC):
    @abstractmethod
    def run(self, scenario: Scenario, channel: EvalChannel) -> RunResult: ...

V1 实现：OpenClawPluginAgent（实际评测行为由 OpenClaw 技能完成，CLI 侧提供统一接口供插件调用）。
预留扩展：ScriptAgent、HermesAgent。

3.3 评估规则抽象 EvalRule

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 提供的契约

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