From 92f98c3af725eb58a2d3ffd53799d1945de0cb58 Mon Sep 17 00:00:00 2001 From: sinohqb Date: Mon, 27 Jul 2026 16:51:19 +0800 Subject: [PATCH] docs(release): add v0.3 release notes and minimal CI baseline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补齐 release-notes-v0.3.md，更新 AGENT.md 里程碑表与 README 至 v0.3 现状 - 新增 scripts/ci-check.sh（版本一致性 + ruff + pytest + tsc） - 新增 .gitea/workflows/ci.yml 与本地 pre-push hook 约定 --- .gitea/workflows/ci.yml | 30 ++++++++ AGENT.md | 18 +++-- README.md | 27 ++++---- docs/release-notes-v0.3.md | 136 +++++++++++++++++++++++++++++++++++++ scripts/ci-check.sh | 39 +++++++++++ 5 files changed, 233 insertions(+), 17 deletions(-) create mode 100644 .gitea/workflows/ci.yml create mode 100644 docs/release-notes-v0.3.md create mode 100755 scripts/ci-check.sh diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..dfa4886 --- /dev/null +++ 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 diff --git a/AGENT.md b/AGENT.md index cfe441f..c26e6f2 100644 --- 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`（仅限救急，事后必须补跑） + diff --git a/README.md b/README.md index 1a9c132..071adf9 100644 --- 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 通知 ## 快速开始 diff --git a/docs/release-notes-v0.3.md b/docs/release-notes-v0.3.md new file mode 100644 index 0000000..7436b65 --- /dev/null +++ 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。 diff --git a/scripts/ci-check.sh b/scripts/ci-check.sh new file mode 100755 index 0000000..577c28e --- /dev/null +++ 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 检查全部通过"