12481cd1b8
## 核心变更
### 规则层全面异步化（DEBT-1）
- EvalRule.evaluate() 签名改为 async def，全量同步改造（无兼容层）
- LlmScoreRule._call_llm: requests.post → httpx.AsyncClient，彻底消除事件循环阻塞
- engine._save_rule_results: rule.evaluate() → await rule.evaluate()
### 工具函数去重（DEBT-2）
- 新建 agenteval/utils/llm.py，统一三个函数：
- extract_reply_text (原 5 处重复)
- extract_content_from_llm_response (原 2 处重复)
- parse_json_from_llm_text (统一 LLM 输出 JSON 解析)
- engine.py / llm_score.py / runs.py / report.py 全部切换到 utils.llm
### HTTP 通用通道（S1-3）
- 新建 channels/http.py (HttpChannel)
- 配置化 send_url / reply_url 模板 ({message}, {msg_id} 占位)
- dot-path 提取 msg_id 和 reply_text
- 可选 reply_ready_path 就绪标志
- 长连接 AsyncClient 复用
- ChannelFactory 注册 ChannelType.HTTP → HttpChannel
### 测试
- 新增 tests/unit/test_http_channel_and_rules.py (19 个测试)
- _get_path / health_check / send / poll_reply / 超时 / 就绪标志 / async 规则评估
- 测试总数：24 → 43，全部通过
Co-Authored-By: Claude <noreply@anthropic.com>
196 lines
10 KiB
Markdown
196 lines
10 KiB
Markdown
# AgentEvalTool v0.3 「拓」迭代规划
|
||
|
||
**版本**: v0.3.0（规划）
|
||
**制定日期**: 2026-07-16
|
||
**基线**: v0.2.0-dev（已部署 t480，含文件管理 + 布局统一 + 6 bug 修复）
|
||
**代号**: 「拓」(Extensibility milestone)
|
||
**状态**: 待评审
|
||
|
||
---
|
||
|
||
## 一、版本定位
|
||
|
||
v0.3 是「先稳后拓」战略的第二步。v0.2 已让核心闭环具备生产可用性，v0.3 的使命是：
|
||
|
||
> 把「单通道 + 3 规则」的稳定闭环，扩展成「多通道 + 可组合规则」的评估平台，
|
||
> 并打通 OpenClaw 双向集成，让评估能力可被 AI 助手自主编排。
|
||
|
||
```
|
||
v0.1 (07-09) MVP 闭环
|
||
v1.1 (07-10) Ant Design 前端重构
|
||
v0.2 (07-14) 「稳」async + 安全 + 测试 + 部署
|
||
└─ (07-16) 文件管理 + 布局统一 + bug 修复
|
||
v0.3 (规划) 「拓」← 本文档
|
||
└─ 多通道 · 规则扩展 · OpenClaw 深度集成 · 报告升级
|
||
```
|
||
|
||
---
|
||
|
||
## 二、现状评估
|
||
|
||
### 2.1 已具备的能力
|
||
|
||
| 层面 | 现状 |
|
||
|---|---|
|
||
| 引擎 | async EvalEngine，真取消，可配置超时，并发信号量 |
|
||
| 通道 | 仅 `tutu-api`（工厂已预留 register 扩展点） |
|
||
| 规则 | 3 种：keyword_match / response_time / llm_score |
|
||
| 报告 | JSON + HTML |
|
||
| 存储 | SQLite + Alembic + 级联删除 + 文件管理 |
|
||
| 安全 | X-API-Key + .env + CORS 收紧 |
|
||
| 测试 | 24 个后端测试，57% 覆盖率 |
|
||
| 部署 | 一键脚本 + 镜像版本 tag + /api/health 校验 |
|
||
|
||
### 2.2 技术债务盘点（v0.3 前置或并行处理）
|
||
|
||
| 编号 | 债务 | 严重度 | 影响 |
|
||
|---|---|---|---|
|
||
| **DEBT-1** | **规则评估层同步阻塞**：`EvalRule.evaluate()` 是 `def` 而非 `async def`；`llm_score` 用同步 `requests.post(timeout=60)` | 🔴 架构级 | 阻塞事件循环，与 v0.2 async 化目标矛盾；**是 P0 规则扩展的前置阻塞项** |
|
||
| DEBT-2 | 后端 `_extract_text`/`_extract_reply_text` 重复 5 处，`_extract_content_from_api_response` 重复 2 处 | 🟡 | 一处修复遗漏另一处即产生 bug |
|
||
| DEBT-3 | 前端 `PageWrapper` 已成死代码，6 页面重复布局 JSX；`statusColor` 多页重复 | 🟡 | 改布局需改 6 处 |
|
||
| DEBT-4 | 测试盲区：rules 覆盖率 15-30%，文件管理零测试，`_generate_messages` 无测试 | 🟡 | 规则/文件功能回归无保护 |
|
||
| DEBT-5 | WebSocket 断线无自动重连；前端 bundle ~2.8MB | 🟢 | 体验问题 |
|
||
|
||
> **关键判断**：DEBT-1 必须在 P0 规则扩展之前解决。semantic_similarity（调 embedding API）、safety（调 moderation API）本质都是网络 IO 规则，若继续在同步 `evaluate()` 上叠加，每条规则都会阻塞整个事件循环，v0.2 的异步化收益被规则层抵消。
|
||
|
||
---
|
||
|
||
## 三、v0.3 范围
|
||
|
||
### 3.1 做什么（In Scope）
|
||
|
||
#### P0 — 核心能力（必须交付）
|
||
|
||
**P0-0 规则评估层异步化**（前置技术改造）
|
||
- `EvalRule.evaluate()` → `async def evaluate()`
|
||
- `engine._save_rule_results` 相应 `await rule.evaluate(...)`
|
||
- `llm_score._call_llm`：`requests` → `httpx.AsyncClient`
|
||
- 涉及文件：`evaluation/rules/base.py`、`keyword.py`、`response_time.py`、`llm_score.py`、`evaluation/engine.py`、`tests/unit/test_engine.py`
|
||
- 验收：4 个规则全部 async；`pytest` 全绿；并发评测时 LLM 评分不阻塞 WebSocket 推送
|
||
|
||
**P0-1 多通道插件化**
|
||
- 新增 `HttpChannel`（通用 HTTP 请求/响应通道，配置化 request 模板 + response JSONPath 提取）
|
||
- 新增 `OpenClawChannel`（直接对接 OpenClaw WS，复用现有 proxy 认证逻辑）
|
||
- `ChannelFactory` 补齐 `HTTP` / `OPENCLAW` 映射
|
||
- （可选）entry_points 插件发现 —— 见决策点 D3
|
||
- 涉及文件：`channels/http.py`（新）、`channels/openclaw.py`（新）、`channels/factory.py`、`models.py`（ChannelType 已有枚举）
|
||
- 验收：可创建 HTTP 通道类型的评测对象并跑通一次评测；连通性测试可用
|
||
|
||
**P0-2 规则扩展 + 组合逻辑**
|
||
- 新增规则：
|
||
- `semantic_similarity`（回复与参考答案的语义相似度，embedding + 余弦）
|
||
- `json_schema`（回复 JSON 结构校验）
|
||
- `safety`（敏感内容检测，可接 moderation API 或关键词黑名单降级）
|
||
- 组合逻辑：Case 支持 `rule_logic: "all" | "any" | "weighted"`，weighted 支持每规则权重 + 阈值
|
||
- 涉及文件：`rules/semantic.py`（新）、`rules/json_schema.py`（新）、`rules/safety.py`（新）、`rules/__init__.py`、`models.py`（Case 加 rule_logic 字段）、`engine.py`（组合判定逻辑）、Alembic 迁移
|
||
- 验收：3 个新规则注册可用；weighted 组合的 pass_rate 计算正确；前端场景编辑器模板包含新规则示例
|
||
|
||
#### P1 — 重要能力
|
||
|
||
**P1-1 OpenClaw 深度集成（双向）**
|
||
- OpenClaw skill 可触发评测（现有 CLI 调用链打通 + 结构化返回）
|
||
- 评测完成 webhook 通知（`POST` 到配置的回调地址，附报告摘要）
|
||
- 涉及文件：`plugins/openclaw/agenteval_skill.py`、`web/routers/runs.py`（webhook hook）、`config/settings.py`（webhook 配置）
|
||
- 验收：OpenClaw 对话触发评测后能收到完成通知
|
||
|
||
**P1-2 报告能力升级**
|
||
- 对比报告：选两次 run，side-by-side 展示规则/用例差异
|
||
- Markdown 导出（补充现有 JSON/HTML）
|
||
- 报告模板外置（Jinja2 模板从代码抽到 `templates/` 目录）
|
||
- 涉及文件：`web/routers/reports.py`、`evaluation/report.py`、`templates/`（新）、前端 `pages/Reports.tsx`
|
||
- 验收：对比视图可用；Markdown 导出格式正确
|
||
|
||
**P1-3 测试补全**（还 DEBT-4）
|
||
- rules 单测：每个规则（含 3 个新规则）覆盖 pass/fail/边界
|
||
- 文件管理测试：上传/下载/分类级联删除
|
||
- 前端引入 vitest：`sessionReducer` 单测（v0.2 已抽纯函数，就等测试）
|
||
- 验收：后端覆盖率 → 70%+；前端有首批 reducer 测试
|
||
|
||
#### P2 — 体验优化
|
||
|
||
**P2-1 场景能力增强**
|
||
- 内置场景模板库（单轮问答 / 多轮对话 / 压力测试 / 动态生成）
|
||
- 参数化场景（变量占位 + 批量实例化）
|
||
|
||
**P2-2 前端体验 + 债务清理**（还 DEBT-3 / DEBT-5）
|
||
- WebSocket 自动重连（指数退避）
|
||
- `PageWrapper` 复用改造 或 删除；`statusColor` 抽到 tokens
|
||
- bundle 优化：路由级懒加载
|
||
|
||
### 3.2 不做什么（Out of Scope）
|
||
|
||
明确排除，维持「个人/小团队」定位，避免过度设计：
|
||
|
||
- ❌ 多租户 / RBAC 权限系统
|
||
- ❌ PostgreSQL / 分布式数据库（SQLite 足够）
|
||
- ❌ Celery / RQ 任务队列（async + asyncio.Task 足够）
|
||
- ❌ 移动端适配
|
||
- ❌ entry_points 全动态插件市场（见决策点 D3，倾向轻量注册）
|
||
|
||
---
|
||
|
||
## 四、迭代节奏
|
||
|
||
按「先还债、再扩展、后体验」组织为 4 个 Sprint。工作量按人天（PD）估算，基于项目快速迭代节奏。
|
||
|
||
| Sprint | 主题 | 工作项 | 估算 |
|
||
|---|---|---|---|
|
||
| **S1** | 还债 + 通道 | P0-0 规则异步化 + P0-1 多通道 + DEBT-2 后端工具函数合并 | 4-5 PD |
|
||
| **S2** | 规则扩展 | P0-2 新规则 + 组合逻辑 + P1-3 规则测试同步 | 5-6 PD |
|
||
| **S3** | 集成 + 报告 | P1-1 OpenClaw 双向 + P1-2 报告升级 | 4-5 PD |
|
||
| **S4** | 体验 + 收尾 | P2-1 场景模板 + P2-2 前端债务清理 + 文件管理测试 | 3-4 PD |
|
||
|
||
**合计约 16-20 PD（≈ 3-4 周）**，与原 release notes 的 4-5 周估算基本吻合（本计划把还债前置，S1 会略慢）。
|
||
|
||
**里程碑验收点**：
|
||
- M1（S1 末）：HTTP 通道跑通一次评测，规则层全 async，pytest 全绿
|
||
- M2（S2 末）：5 种规则 + weighted 组合可用，后端覆盖率 65%+
|
||
- M3（S3 末）：OpenClaw 对话触发评测 + 收到 webhook，对比报告可用
|
||
- M4（S4 末）：场景模板库 + WebSocket 重连，v0.3 部署 t480
|
||
|
||
---
|
||
|
||
## 五、需要拍板的决策点
|
||
|
||
以下决策会显著影响实现，建议在 S1 启动前确认：
|
||
|
||
| 编号 | 决策 | 选项 | 倾向 |
|
||
|---|---|---|---|
|
||
| **D1** | semantic_similarity 的 embedding 来源 | A) 外部 API（豆包/OpenAI embedding，成本+网络依赖） B) 本地 sentence-transformers（部署重，+模型体积） | **A**：与现有 llm_score 一致的外部 API 模式，部署轻 |
|
||
| **D2** | safety 规则实现深度 | A) 接 moderation API B) 关键词黑名单 C) 两者，API 不可用时降级黑名单 | **C**：默认黑名单保证可用，API 可选增强 |
|
||
| **D3** | 通道/规则插件机制 | A) entry_points 动态发现 B) 现有工厂 register + 装饰器注册 | **B**：小团队无需插件市场，现有机制已够，避免过度设计 |
|
||
| **D4** | 规则异步化是否 breaking | 改 `evaluate` 签名会影响所有规则 | 全量改造（4 规则少，一次到位），无需兼容层 |
|
||
| **D5** | v0.3 是否顺带升级前端数据层（TanStack Query） | A) 引入 B) 维持 useState + 手动 load | **B**：当前页面数据量小，S4 仅做重连 + 懒加载，Query 留 v0.4 |
|
||
|
||
---
|
||
|
||
## 六、风险
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|---|---|---|
|
||
| 规则异步化牵连 engine + 全部规则 + 测试 | S1 工期 | 规则数量少（4 个），且有 24 个测试兜底，一次改到位 |
|
||
| semantic/safety 依赖外部 API 稳定性 | 评测可靠性 | 规则内 try/except，API 失败降级为「规则跳过 + 明确 reason」，不中止 run |
|
||
| OpenClaw webhook 依赖外部可达性 | P1-1 集成 | webhook 失败不影响评测结果，仅记录日志 |
|
||
| 组合逻辑 weighted 的 pass_rate 语义变化 | 报告一致性 | 明确定义：weighted 下 case 通过 = 加权分 ≥ 阈值；文档 + 测试锁定 |
|
||
|
||
---
|
||
|
||
## 七、验收标准（v0.3 Definition of Done）
|
||
|
||
1. 可创建 tutu-api / HTTP / OpenClaw 三类通道的评测对象并各跑通一次评测
|
||
2. 5 种规则（3 旧 + semantic/json_schema/safety 选交付）可用，支持 all/any/weighted 组合
|
||
3. 规则评估层全 async，并发评测时 LLM/embedding 调用不阻塞 WebSocket 推送
|
||
4. OpenClaw 对话可触发评测并收到完成通知
|
||
5. 报告支持 JSON/HTML/Markdown 导出 + 两次 run 对比
|
||
6. 后端测试覆盖率 ≥ 70%，前端有首批 reducer 测试
|
||
7. 后端工具函数去重（DEBT-2），前端布局债务清理（DEBT-3）
|
||
8. v0.3 部署 t480，`/api/health` 显示 0.3.0 版本
|
||
|
||
---
|
||
|
||
## 八、下一步
|
||
|
||
1. 评审本计划，确认第五节 5 个决策点
|
||
2. 确认后按 Sprint 拆分为可执行 issue（每项含涉及文件 + 验收）
|
||
3. 从 S1（规则异步化 + 多通道）启动
|