2d7679a6bb
Some checks failed
CI / test (push) Failing after 49s
周期对比发布说明：计划指纹自动基线、机械 diff + LLM 演进叙述、 抽屉对比区块、正式线自动链，及发布后评审修复、导出纳入与 ruff 清理。
92 lines
6.0 KiB
Markdown
92 lines
6.0 KiB
Markdown
# 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）
|