docs(release): add v0.3 release notes and minimal CI baseline

- 补齐 release-notes-v0.3.md，更新 AGENT.md 里程碑表与 README 至 v0.3 现状 - 新增 scripts/ci-check.sh（版本一致性 + ruff + pytest + tsc） - 新增 .gitea/workflows/ci.yml 与本地 pre-push hook 约定
2026-07-27 16:51:19 +08:00 · 2026-07-27 16:51:19 +08:00 · 92f98c3af7
commit 92f98c3af7
parent f1eb123dd1
5 changed files with 233 additions and 17 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@ -0,0 +1,30 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install backend deps
+        run: pip install -e ".[dev]"
+      - name: Version consistency
+        run: python scripts/sync_version.py --check
+      - name: Lint
+        run: ruff check backend/
+      - name: Tests
+        run: python -m pytest -q
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Frontend type check
+        run: |
+          cd frontend/web
+          npm ci
+          npx tsc --noEmit
--- a/AGENT.md
+++ b/AGENT.md
@ -6,7 +6,7 @@

 **AgentEvalTool** 是智能体质量评估工具集平台，评估 AI 数字员工（大模型 + RAG）和 AI 助手（OpenClaw）的服务质量。核心闭环：定义评估 → 执行评估 → 分析结果 → 改进优化。

- **当前版本**: v0.2.0（2026-07-14，里程碑「稳」）
+- **当前版本**: v0.3.0-dev（2026-07-17 发布至 t480，里程碑「拓」）
 - **运行环境**: t480 测试服务器（192.168.8.145:8001）
 - **语言**: Python 3.11（后端） + TypeScript/React 18（前端）

@ -15,11 +15,11 @@
 | 版本 | 代号 | 日期 | 主题 | 状态 |
 |---|---|---|---|---|
 | v0.1 | MVP | 2026-07-09 | 核心闭环跑通 | ✅ 已发布 |
-| **v0.2** | **「稳」** | **2026-07-14** | **async 引擎 + 安全基线 + 测试 + 部署规范化** | **✅ 已发布(t480)** |
-| v0.3 | 「拓」 | 规划中(2026-08) | 多通道 + 规则扩展 + OpenClaw 深度集成 | 📋 规划中 |
-| v0.4 | 「展」 | 远景 | 多租户 / SSO / 监控告警 / 对外服务 | 💭 远景 |
+| v0.2 | 「稳」 | 2026-07-14 | async 引擎 + 安全基线 + 测试 + 部署规范化 | ✅ 已发布(t480) |
+| **v0.3** | **「拓」** | **2026-07-17** | **多通道 + 规则扩展 + 模型配置中心** | **✅ 已发布(t480)** |
+| v0.4 | — | 规划中 | 前端测试 / 报告增强 / OpenClaw 深度集成二期 / 多模态用例 | 📋 待规划 |

-详细路线图见 [docs/release-notes-v0.2.md](docs/release-notes-v0.2.md) 第八节。
+详细内容见 [docs/release-notes-v0.3.md](docs/release-notes-v0.3.md)。

 ## 技术栈

@ -212,3 +212,11 @@ agenteval server start --host 0.0.0.0 --port 8000
 - 前端 TypeScript 使用 `tsc --noEmit` 类型检查
 - 文档文件名带版本号（如 `architecture-v1.0.md`）
 - 用户偏好简体中文交互
+
+## CI 检查
+
+- `scripts/ci-check.sh` 一键跑：版本号一致性 + ruff + pytest + tsc（`--fast` 跳过 tsc）
+- 本地 `git push` 会自动触发 pre-push hook 执行 `ci-check.sh --fast`（`.git/hooks/pre-push`，新 clone 需手动重装）
+- Gitea Actions 工作流：`.gitea/workflows/ci.yml`（需 Gitea 实例启用 Actions + 注册 runner 才生效）
+- 紧急绕过：`git push --no-verify`（仅限救急，事后必须补跑）
+
--- a/README.md
+++ b/README.md
@ -1,26 +1,29 @@
 # AgentEvalTool

-> **当前开发版本**: v0.3.0-dev 「拓」 · 开发计划见 [docs/plan-v0.3.md](docs/plan-v0.3.md)
+> **当前开发版本**: v0.3.0-dev 「拓」 · 已发布至 t480 · 发布说明见 [docs/release-notes-v0.3.md](docs/release-notes-v0.3.md)

 智能体质量评估工具集平台。

 ## 功能

 - 评测对象管理（AI 数字员工 / AI 助手）
- 评测场景管理（YAML/JSON 配置）
- **异步评测执行引擎**(v0.2:真并发/真取消/可配置超时)
- 评估规则（关键词匹配、响应时间、LLM 评分）
- 基础报告生成（JSON / HTML）
- OpenClaw 插件示例 + 免登录 iframe 集成
+- 评测场景管理（YAML/JSON 配置 + 模板库 + 动态用例生成）
+- 异步评测执行引擎（真并发 / 真取消 / 可配置超时 / WS 实时进度）
+- 评测通道：tutu-api / HTTP / OpenClaw
+- 评估规则：关键词、响应时间、LLM 评分、语义相似度、JSON Schema、安全检测 + all/any/weighted 组合
+- 模型配置中心（统一凭据管理 + 加密落库 + OpenAI/Anthropic/DashScope/Gemini 协议）
+- 报告生成（JSON / HTML / Markdown / 对比报告）+ Webhook 通知
+- 文件管理（分类树 + 上传下载）
+- OpenClaw 免登录 iframe 集成 + HTTP Skill
 - Web 管理后台（FastAPI + React）

-## v0.2 亮点
+## v0.3 亮点

- **async EvalEngine** + `asyncio.Task` 注册表,支持真取消与并发执行
- **安全基线**:Pydantic Settings + `.env` + APIKey 鉴权 + CORS 收紧
- **测试基线**:24 个测试,57% 覆盖率(engine 61%, runs.py 86%)
- **部署规范化**:`scripts/deploy-t480.sh` 一键部署 + 镜像版本 tag + `/api/health` 验证
- **Alembic 迁移**:容器启动自动 `alembic upgrade head`
+- **模型配置中心**：模型连接统一管理，场景只引用配置 ID，API Key 加密落库、响应零泄露
+- **ModelGateway**：chat / embed / moderate 统一入口，4 种协议适配器
+- **3 通道 + 6 规则**：工厂/注册表模式，插件式扩展
+- **测试基线**：218 个测试，82% 覆盖率
+- **报告增强**：Markdown 导出、run 对比、Webhook 通知

 ## 快速开始

--- a/docs/release-notes-v0.3.md
+++ b/docs/release-notes-v0.3.md
@ -0,0 +1,136 @@
+# 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。
--- a/scripts/ci-check.sh
+++ b/scripts/ci-check.sh
@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Minimal CI check: run locally (pre-push hook) or in Gitea Actions.
+# Usage: scripts/ci-check.sh [--fast]   (--fast skips frontend type check)
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+FAST=0
+[[ "${1:-}" == "--fast" ]] && FAST=1
+
+if [[ -f .venv/bin/activate ]]; then
+    # shellcheck disable=SC1091
+    source .venv/bin/activate
+fi
+
+echo "==> 1/4 版本号一致性 (pyproject ↔ package.json)"
+python scripts/sync_version.py --check
+
+echo "==> 2/4 ruff lint"
+if command -v ruff >/dev/null 2>&1; then
+    ruff check backend/
+else
+    echo "    ruff 未安装，跳过（pip install -e '.[dev]'）"
+fi
+
+echo "==> 3/4 pytest"
+python -m pytest -q
+
+if [[ $FAST -eq 1 ]]; then
+    echo "==> 4/4 前端类型检查（--fast 跳过）"
+else
+    echo "==> 4/4 前端类型检查 (tsc --noEmit)"
+    if [[ -d frontend/web/node_modules ]]; then
+        (cd frontend/web && npx tsc --noEmit)
+    else
+        echo "    node_modules 不存在，跳过（cd frontend/web && npm install）"
+    fi
+fi
+
+echo "✅ CI 检查全部通过"