# AgentEvalTool v0.8 版本发布说明

**版本**: v0.8.0
**日期**: 2026-08-03
**状态**: 已发布(t480 开发线)
**代号**: 「比」(Period comparison milestone)
**作者**: AgentEval Team

---

## 一、版本定位

v0.8 的主题是**让周期评估"可比"**。v0.6/v0.7 回答了"这一期表现如何、问题在哪"，但读报告的人还要自己记住上期数字才能判断好坏。本版本在活动之上加**周期对比**：自动找到同活动串的上期活动作为基线，产出机械指标 diff 与 LLM 演进叙述，直接回答"这一期比上一期好了还是坏了"。

```
v0.1 (2026-07-09)  MVP 闭环
v0.2 (2026-07-14)  「稳」async 引擎 + 安全基线 + 部署规范化
v0.3 (2026-07-17)  「拓」多通道 + 规则扩展 + 模型配置中心
v0.4 (2026-07-28)  「联」AI 助手标准化 + 登录 + 仪表盘重构
v0.5 (2026-07-29)  「准」判定语义 + 场景版本化
v0.6 (2026-08-02)  「巡」评估活动 + 周期报告
v0.7 (2026-08-03)  「析」活动智能分析
v0.8 (2026-08-03)  ← 你在这里:「比」周期对比
```

## 二、关键设计决策

- **可比性单位**：同评测对象 + 同计划指纹（场景集合、偏移、次数、窗口完全一致）的活动串；指纹不一致即无自动基线
- **自动基线**：取活动串中按完成时间最近一个已有 completed 分析的上一期活动；仅正式线（time_scale == 1）参与自动配对，加速调试线不自动配对
- **手动基线**：可跨指纹手选任意有 completed 分析的历史活动（基线缺分析则 400 引导）
- **双主轴产出**：LLM 演进叙述（趋势判定 improving/stable/regressing + 问题演变 new/persisting/resolved + 建议落实跟踪 addressed/partial/unaddressed/new）+ 机械指标 diff（通过率/可用性/平均时延）
- **diff 口径**：机械 diff 按「生效基线」（已有对比行则为其存储基线，否则为自动基线）**现算、不存储**，避免基线变更后数据失真
- **存储**：`campaign_period_comparisons` 每活动一行 upsert（baseline_campaign_id + generating/completed/failed + result JSON + 模型快照 + 触发来源）
- **模型**：复用智能分析的模型解析链（活动覆盖 ?? 全局分析默认），无独立岗位
- **自动链**：正式线活动分析完成后自动 enqueue 周期对比（triggered_by=auto），失败不阻塞

## 三、主要功能（4 张 tracer-bullet 票）

### 3.1 计划指纹自动基线 + 机械指标 diff（ticket 01）
- 计划指纹由场景集合、偏移、次数、窗口归一化生成；`resolve_auto_baseline` 按完成时间倒序找同指纹且已有 completed 分析的前任活动
- `compute_metric_diff` 产出整窗 + 分场景的三指标 diff（baseline/current/delta）；比率以百分点、时延以毫秒表达

### 3.2 对比叙述 Agent + 存储 + API（ticket 02）
- 输入：本期与基线的智能分析结果 + 双侧活动报告聚合；输出结构化趋势、问题演变、建议落实跟踪
- `GET /api/campaigns/{id}/comparison`（含叙述行状态 + 自动基线 + 生效基线的机械 diff）、`POST` 触发/重跑（支持手动指定基线）
- 前置校验：活动须终态、本期须有 completed 分析、分析模型可解析；重跑 upsert 不新增行

### 3.3 报告抽屉「周期对比」区块（ticket 03）
- 独立组件 `PeriodComparisonSection`：状态行（生成中轮询/失败重试/未生成引导）
- 已生成：趋势徽标（改善/平稳/退化）+ 指标变化表（行 = 整窗 + 各场景，列 = 三指标，单元格 `基线 → 本期（±delta）`）+ 问题演变与建议落实标签
- 支持手动切换基线活动（下拉仅列已完成活动）与重新生成

### 3.4 正式线自动链（ticket 04）
- 分析完成回调处自动 enqueue 周期对比；加速线/无基线/无模型静默跳过，不阻塞

### 3.5 发布后改进（非票据）
- **双轴评审修复**（dd3b9a5）：共享 `gateway_chat_client` 工厂、指标元表抽取、对比区块组件化
- **Markdown 导出纳入周期对比**（14b09e1）：completed 对比行渲染 `## 周期对比` 附录（基线元信息 + 趋势 + 指标变化表 + 问题演变 + 建议落实），紧跟智能分析之后，缺则无痕；活动导出排版重优化（状态中文化、窗口/时段人类可读、友好时间戳、头部补评测对象名、「正式线」/「加速调试线 ×N」措辞）；Run 级导出不动
- **ruff 全量清理**（5ecb308）：49 项修复，backend/ 与 tests/ 全绿

## 四、测试与质量

| 指标 | v0.7 | v0.8 |
|---|---|---|
| 测试数量 | 443 | **492** |
| 新增 | — | 对比单元×约 30、对比 API×约 15、自动触发×约 8、迁移×1、导出区块×6 |

流程沿用 `/grill-with-docs → /to-spec → /to-tickets → /implement(×4, TDD + 内联双轴评审)`，spec 与票据在 `.scratch/v0.8/`；发布后另做了一次全量双轴代码评审并修复。

## 五、部署与配置变更

- 一个新迁移：`f2a9b7c34d18`（campaign_period_comparisons 表），容器启动自动应用
- 无新增环境变量
- **使用前提**：本期与基线活动均须有 completed 智能分析（分析岗位模型配置同 v0.7 要求）
- t480 验证：健康检查 version=0.8.0 一致；最后一次为 `--skip-build` 热加载部署，健康端点 commit 标签（镜像 build-arg）滞后于实际代码属预期
- CONTEXT.md 新增术语：周期对比（Period Comparison）、正式线 / 加速调试线（Production-line / Accelerated-line）

## 六、已知问题

1. volcengine-102 生产线停留在 v0.4 之前
2. 前端仍无自动化测试（仅 tsc）
3. 对比叙述质量依赖分析模型能力；基线活动数据缺失时 diff 单元格显示 `—`
4. `--skip-build` 部署下健康端点 commit 标签滞后（仅元数据，代码经 volume 热加载为最新）
5. 本地 main 领先 origin 若干提交，尚未推送

## 七、下一版候选方向

- 跨活动对比（多对象并行活动的横切对照）
- ADR-0003 v2：OpenClaw 自适应重规划进入调度热回路
- volcengine-102 同步
- 前端测试基线（vitest）