# AgentEvalTool v0.3 版本发布说明

**版本**: v0.3.0-dev
**日期**: 2026-07-17（发布至 t480）/ 2026-07-27（文档补齐）
**状态**: 已发布(t480 开发线, commit `affbf60`)
**代号**: 「拓」(Expansion milestone)
**作者**: AgentEval Team

---

## 一、版本定位

v0.3 是「先稳后拓」战略的第二步。在 v0.2 打好的异步引擎、安全基线和测试基线之上，本版本完成两条主线：

1. **滚动迭代**（v0.2 发布后至 v0.3 基线，任务号 v0.3-s1~s4 / v0.4-t1~t4）：多通道、规则扩展、报告增强、文件管理等平台能力。
2. **模型配置中心**（v0.3 核心主线，见 [plan-v0.3.md](plan-v0.3.md)）：统一管理工程内所有外部大模型连接，消除凭据分散与明文泄露风险。

```
v0.1 (2026-07-09)  MVP 闭环跑通
   │
   ├── v0.2 (2026-07-14)  「稳」async 引擎 + 安全基线 + 部署规范化
   │
   ├── v0.3 (2026-07-17)  ← 你在这里:「拓」多通道 + 规则扩展 + 模型配置中心
   │
   └── v0.4 (规划中)      待规划
```

---

## 二、滚动迭代能力（v0.2 → v0.3 基线）

| 任务 | 内容 | 提交 |
|---|---|---|
| s1 | 规则层异步化 + 工具函数去重 + **HTTP 通道** | `12481cd` |
| s2 | 3 个新规则（`semantic_similarity` / `json_schema` / `safety`）+ **all/any/weighted 组合逻辑** | `c7f1dca` |
| s3 | **Webhook 通知** + OpenClaw HTTP Skill + Markdown / 对比报告 | `349200e` |
| s4 | 场景模板库 + WebSocket 自动重连 + PageWrapper 复用 | `17aeba8` |
| t1/t2 | 测试覆盖率 62%→77% + **UTC 时区根本修复**（后端序列化带时区） | `e0b69fa` |
| t3/t4 | **OpenClaw 评测通道** + 前端 bundle 优化（懒加载 + chunk 拆分） | `12c1732` |
| — | 文件管理模块（分类树 + 上传下载 + 级联删除）| `a77cd83` `d7514f4` `9293f9e` |

至此通道达到 3 种（`tutu` / `http` / `openclaw`），规则达到 6 种，均通过注册表/工厂支持插件式扩展。

---

## 三、核心功能：模型配置中心

### 3.1 问题背景

此前模型连接信息分散在 `Scenario.llm_config` 和各规则 `params` 中，API Key 明文存储、随 API 响应泄露，且三处模型调用各自实现 httpx 请求，无统一的认证、超时、错误处理。

### 3.2 架构

```
模型配置页面 (/models)
    ↓
/api/model-configs → ModelConfigService → model_configs 表
                                        → Fernet 密钥加密/解密
                                        → 引用检查（被绑定禁止删除）
    ↓
ModelGateway ── chat()     → 动态用例生成 / LLM 评分
             ├─ embed()    → 语义相似度
             └─ moderate() → 安全检测
    ↓
协议适配器: openai / anthropic / dashscope / gemini
```

### 3.3 关键设计

- **场景只引用配置 ID**：`scenario_model_bindings` 表按用途（generator/judge/embedding/moderation）绑定，`(scenario_id, purpose)` 唯一。
- **凭据零泄露**：GET 响应只返回 `has_api_key`；PUT 不传 key 则保留原值；`cryptography` Fernet 加密落库。
- **能力匹配强约束**：chat 配置不能用于 embedding / moderation。
- **运行快照**：run 启动时保存不含密钥的模型快照，运行期间配置变更不影响进行中的评测。
- **协议与元数据分离**（`cc79d3a` / `affbf60`）：`provider` 表示调用协议，`capability` 表示评测用途，`input/output_modalities` 表示模型自身模态；厂商、区域、上下文窗口等为描述性元数据，写入运行快照但不改变网关请求参数。

### 3.4 数据迁移

- 新迁移: `8e91c70a5d3b_add_model_config_center` + `a64b2f8c9d10_add_model_metadata`
- `scripts/migrate_model_configs.py` 将存量 `llm_config` / 规则内嵌凭据迁移为配置引用（含单测覆盖）。

---

## 四、关键 Bug 修复

| 问题 | 根因 | 修复 |
|---|---|---|
| 多轮用例 LLM 评分普遍 0 分 | `llm_score` 的 question 提取按 turn 索引错位 | `c4962dd` |
| 前端运行时崩溃（白屏） | `vendor-charts` chunk 循环依赖 | `f765bee` |
| 动态用例生成失败无痕迹 | 失败原因未持久化 | 写入 `run.summary.case_errors`（`867d4e3`） |
| `--skip-build` 部署后代码未生效 | 容器未重启 + commit 校验误报 | 自动重启 + 校验降级（`69100c3`） |
| 场景页残留旧模型引用 | 模型配置迁移后前端未刷新 | `457dfed` |

---

## 五、测试与质量

| 指标 | v0.2 | v0.3 |
|---|---|---|
| 测试数量 | 24 | **218** |
| 覆盖率 | 57% | **82%** |
| 测试代码量 | ~800 行 | 3,746 行 |

新增测试模块：规则组合逻辑、HTTP/OpenClaw 通道、报告生成、webhook、场景模板、文件管理（repository/service/API）、模型配置（service/gateway/迁移/运行时集成）。

---

## 六、部署验证

```
$ curl http://192.168.8.145:8001/api/health
{"status":"ok","version":"0.3.0-dev","commit":"affbf60","built_at":"2026-07-17T15:00:21Z"}
```

- commit SHA 已随镜像注入（v0.2 遗留的 `no-git` 问题随 git 仓库建立自愈）。
- 远端仓库: 自建 Gitea（git.solahqb22.cn）。

---

## 七、已知问题与风险

1. **无 CI**：218 个测试仅靠手动执行，依赖漂移无法自动发现（2026-07-27 已补：pre-push hook + Gitea Actions 工作流）。
2. **t480 `.env` 手动维护**：新增环境变量需 SSH 手动补全（陷阱 #5，未根治）。
3. **`moderation` 能力覆盖有限**：safety 规则的 moderation 路径依赖外部审核端点可用性。
4. **前端无自动化测试**：仍只有 `tsc --noEmit` 类型检查。

---

## 八、下一版本（v0.4）候选方向

- 前端测试基线（vitest + 组件冒烟测试）
- 评测报告增强：趋势分析、多 run 聚合看板
- OpenClaw 深度集成第二阶段（插件双向调用）
- 多模态评测用例（依托模型配置中心的 modality 元数据）
- `.env` 配置同步自动化

待与团队确认后另行制定 plan-v0.4.md。