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