solahqb/AgentEvalTool
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 1 Wiki Activity
d7514f4e65
AgentEvalTool/docs/plan-v0.3.md
sinohqb 12481cd1b8 v0.3-s1: 规则层异步化 + 工具函数去重 + HTTP 通道 
## 核心变更

### 规则层全面异步化（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>
2026-07-17 10:52:32 +08:00

10 KiB
Raw Blame History

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（规则异步化 + 多通道）启动