# AgentEvalTool — AI Agent 项目知识

> 本文件为 AI 助手提供项目上下文，帮助快速理解项目并参与开发。

## 项目概述

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

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

## 里程碑路线图

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

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

## 技术栈

### 后端
- **框架**: FastAPI + Uvicorn
- **ORM**: SQLModel（基于 SQLAlchemy）
- **CLI**: Typer + Rich
- **数据库**: SQLite（StaticPool 模式）
- **模板引擎**: Jinja2（HTML 报告）
- **关键依赖**: Pydantic v2、requests、PyYAML

### 前端
- **框架**: React 18 + TypeScript + Vite 5
- **UI 库**: Ant Design 5.x + ProComponents
- **代码编辑**: Monaco Editor（JSON 场景编辑）
- **图表**: @ant-design/charts
- **路由**: react-router-dom v6
- **HTTP**: axios（带请求拦截器和统一错误提示）

## 项目结构

```
AgentEvalTool/
├── backend/
│   ├── agenteval/            # 核心 Python 库
│   │   ├── agents/           # EvalAgent 抽象（SimpleAgent）
│   │   ├── channels/         # 消息通道（TutuApiChannel）
│   │   ├── evaluation/       # 评测引擎 + 规则
│   │   │   └── rules/        # keyword_match, response_time, llm_score
│   │   ├── scenarios/        # 场景加载/校验
│   │   ├── storage/          # SQLite + Repository 模式
│   │   └── web/              # FastAPI 后端
│   │       ├── routers/      # targets, scenarios, runs, reports, stats
│   │       └── websocket.py  # WebSocket 实时进度推送
│   ├── cli/                  # CLI 入口（Typer）
│   └── plugins/openclaw/     # OpenClaw 插件示例
├── frontend/web/             # React 前端（Vite + Ant Design）
├── config/config.json        # tutu-api 配置（敏感信息）
├── data/                     # SQLite DB + 场景 YAML + 报告输出
├── deploy/t480/              # Docker 部署配置
├── docs/                     # 版本化文档集
├── scripts/mock_call.py      # 历史参考脚本
└── pyproject.toml            # hatchling 构建 + 依赖定义
```

## 核心架构

### 消息通道（EvalChannel）
- 抽象接口：`send()` / `poll_reply()` / `health_check()`
- V1 实现：`TutuApiChannel`（HTTP + Bearer Token + questionMsgId 配对）
- 工厂模式：`ChannelFactory` 按 channel_type 创建实例

### 评测引擎（EvalEngine）
- 遍历 Scenario.cases → 每个 case 遍历 messages（多轮对话）
- 发送消息 → 轮询回复 → 记录 Turn → 执行规则 → 保存 EvalResult
- 支持 `progress_callback` 实时推送事件（WebSocket 集成）
- 支持 `existing_run` 参数复用已有 run 记录

### 评估规则（EvalRule）
- `keyword_match`：关键词包含/排除匹配
- `response_time`：响应时间阈值检查
- `llm_score`：LLM-as-judge 评分（OpenAI 兼容 API）

### 数据模型
- `EvalTarget` → `EvalRun` ← `Scenario`
- `EvalRun` → `Turn`（对话轮次）
- `EvalRun` → `EvalResult`（规则结果）

## 部署知识

### t480 测试服务器
- **地址**: sola-t480（192.168.8.145）
- **端口**: 8001（映射容器内 8000）
- **部署方式**: Docker Compose 双容器（agenteval + openclaw-eval）
- **Python 镜像**: python:3.11.15-slim-bookworm
- **APT/Pip 镜像**: 阿里云（绕过 GFW）

### 版本号（单一数据源）
- **pyproject.toml** 是版本号的唯一来源
- **package.json** 的版本号由 `scripts/sync_version.py` 自动同步
- 每次部署前必须运行 `python3 scripts/sync_version.py`（deploy 脚本会自动做）
- 镜像 tag 同时打 `t480-agenteval:<version>` 和 `t480-agenteval:latest`

### 部署流程（标准）
```bash
# 推荐: 一键部署（build/sync/rebuild/verify 全包）
scripts/deploy-t480.sh

# 仅代码变更（跳过镜像重建, backend 通过 volume 热加载）
scripts/deploy-t480.sh --skip-build

# 预览命令, 不实际执行
scripts/deploy-t480.sh --dry-run
```

脚本会自动:
1. 同步版本号 `pyproject.toml → package.json`
2. `npm run build` 构建前端
3. rsync 代码 + dist 到 t480
4. `docker compose build --build-arg BUILD_COMMIT=... --build-arg BUILD_TIME=...`
5. `docker tag t480-agenteval:<version>`
6. `docker compose up -d`（容器启动时自动跑 `alembic upgrade head`）
7. curl `/api/health` 验证版本号和 commit 一致

### 部署验证
```bash
curl http://192.168.8.145:8001/api/health
# 返回: {"status":"ok","version":"0.2.0-dev","commit":"abc1234","built_at":"2026-07-14T10:33:41Z"}
# 如果 version 不匹配本地 pyproject.toml → 部署失败, 脚本会报错退出
```

### 关键 Volume 挂载
- `data/` → `/app/data`（SQLite DB + 报告 + openclaw 状态, 可写）
- `config/config.json` → `/app/config/config.json:ro`
- `frontend/web/dist/` → `/app/frontend/web/dist:ro`（**必须 build 后再部署**）
- `backend/` → `/app/backend:ro`（代码热更新）
- `.env` → `/app/.env:ro`（Pydantic Settings 配置, 见 `.env.example`）

### 镜像 tag 约定
- `t480-agenteval:<version>` — 不可变, 对应某次具体构建
- `t480-agenteval:latest` — 可变, 总是指向最新部署
- 回滚: `docker tag t480-agenteval:<old-version> t480-agenteval:latest && docker compose up -d`

## 重要踩坑记录

### 1. SQLite + FastAPI 必须用 StaticPool
- 默认 QueuePool 在多线程环境下快速耗尽
- `check_same_thread=False` + `StaticPool` 是 SQLite 的正确配置

### 2. Docker COPY vs Volume 挂载
- Dockerfile 中 `COPY backend ./backend` 烘焙的代码不会随 rsync 更新
- 必须通过 volume 挂载 `backend/` 才能实现代码热更新
- 只有 Dockerfile 或 Python 依赖变更时才需要 `--build`

### 3. Session 生命周期管理
- 所有 Router 必须使用 `Depends(get_db)` 管理 Session
- `get_db()` 是 generator，`finally` 中 `session.close()` 确保连接释放
- 后台任务也需要 `try/finally` 关闭 Session

### 4. EvalEngine.run() 与 API 端点的 run 创建
- API 端点先创建 run（pending），返回 run_id 给前端
- 后台任务通过 `existing_run` 参数复用该记录，避免重复创建

### 5. 中国网络环境
- Docker Hub 和 npm 在国内访问极慢或被墙
- 使用阿里云 APT/Pip 镜像
- Clash 代理不可靠时，优先使用镜像策略

### 6. 前端 dist 必须显式构建再部署
- `frontend/web/dist/` 是构建产物, 不是源码
- rsync 时如果 `--exclude='frontend/web/dist'`, t480 会一直跑旧 dist, 看起来像"页面回到老版本"
- 必须 `npm run build` 之后再 rsync, 或者直接用 `scripts/deploy-t480.sh`(自动做这两步)
- 部署后用 `curl /api/health` 验证 version/commit 和本地一致, 脚本会自动做

### 7. OpenClaw 免登录依赖 Origin 注入
- OpenClaw 的 `gateway.controlUi.allowedOrigins` 检查 WebSocket 的 Origin header
- `proxy.py` 必须注入 `origin=http://192.168.8.145:8001`(或 settings.allowed_origins 的第一项)
- 如果 Origin 缺失, OpenClaw 拒收 WS 连接, SPA 会显示登录页
- v0.2 起 `openclaw_ws_origin` 从 `allowed_origins` 自动推导, 不再硬编码

## CLI 命令速查

```bash
agenteval target add --name "名称" --config config/config.json
agenteval target list
agenteval target test <id>

agenteval scenario import data/scenarios/xxx.yaml
agenteval scenario list

agenteval run start --target-id <id> --scenario-id <id>
agenteval run list

agenteval report show <run-id> --format json
agenteval report generate <run-id> --format html

agenteval server start --host 0.0.0.0 --port 8000
```

## 当前数据（t480）

- **评测对象**: 1（社区医院AI客服，tutu-api 通道）
- **评测场景**: 2（社区医院基础服务评测 + 科室导航与挂号咨询）
- **API 端点**: `http://192.168.8.145:8001/`
- **WebSocket**: `ws://192.168.8.145:8001/ws/runs/{run_id}`

## 开发约定

- Python 代码使用 `ruff` 做 lint（line-length 120, target py310）
- 前端 TypeScript 使用 `tsc --noEmit` 类型检查
- 文档文件名带版本号（如 `architecture-v1.0.md`）
- 用户偏好简体中文交互