AgentEvalTool/docs/plan-v0.4.md
sinohqb 595409487b
Some checks failed
CI / test (push) Failing after 38s
docs(release): v0.4「联」发布说明与里程碑收尾
- 新增 release-notes-v0.4.md(事故排查 + 功能总结 + v0.5 候选方向)
- AGENT.md 里程碑表更新至 v0.4 + 鉴权配置说明
- README / plan-v0.4 状态同步
2026-07-28 17:41:20 +08:00

3.7 KiB
Raw Blame History

AgentEvalTool v0.4.0 「联」开发计划

开发版本: v0.4.0-dev 制定日期: 2026-07-27 代码基线: 92f98c3(v0.3.0-dev 已发布 t480) 核心目标: AI 助手评测链路标准化 + 报告查询体验优化 状态: ✅ 已发布(t480, 2026-07-28),发布说明见 release-notes-v0.4.md


一、背景:run 95ee8738 "消失"事故排查

用户通过 AI 助手触发评测(run 95ee8738-11e7-4959-a3cf-45e3536b28eb),但在"评测执行"和"评测报告"页面均查不到。

排查结论(2026-07-27):

检查项 结果
t480 数据库 eval_runs ✅ run 存在,status=completed
GET /api/runs ✅ 正常返回,列表第一条
t480 SKILL.md(openclaw 工作区) ✅ 走标准 POST /api/runs
前端展示 ❌ 根因所在

根因:前端采用 keep-alive 标签页架构(页面挂载后永不卸载),Runs / Reports 页只在首次挂载时加载一次列表,切回标签页不刷新。AI 助手评测发生在页面已挂载之后 → 两个页面全是旧数据。叠加因素:Runs 页默认时间过滤为"今天"、Reports 页只显示 completed 状态。

数据与 API 完全正常,纯前端展示层问题。

二、需求与实现

需求 1:触发来源标记 + AI 助手标准化链路

  • EvalRun.triggered_by 枚举字段(manual / ai_assistant / cli,默认 manual),全链路透传:models → EvalRunDB → repository → engine → CLI → API
  • 迁移 b7d4e6f81c22:eval_runs 加列,存量回填 manual
  • POST /api/runs 接受可选 triggered_by(非法值 422)
  • 标准 skill 纳入版本管理:backend/plugins/openclaw/skills/agenteval-run/SKILL.md(要求带 triggered_by: "ai_assistant"),deploy 脚本自动同步到 openclaw 工作区
  • plugins/openclaw/README.md 移除 CLI subprocess 模式(CLI 写孤立库,禁止 OpenClaw 使用)
  • 前端:RunList 与 Reports 下拉显示来源 Tag(AI 助手=紫色 / CLI=蓝色 / 手动不显示)

需求 1.5(排查衍生,本次事故的直接修复):标签页激活刷新

  • 新 hook useOnTabActive(path, cb):监听 tabStore.activeKey,标签页重新激活时触发刷新(跳过首次挂载)
  • Runs、Reports 两页接入

需求 2:报告页查询体验优化

  • 后端 GET /api/runs 返回冗余 scenario_name / target_name
  • Reports 页选择区重做:
    • 场景筛选器(含各场景 run 数量统计)
    • run 下拉富选项:场景名 · 对象名 · 时间 · 通过率 · 来源 Tag,支持关键字搜索
    • 修复旧版 .reverse() 导致最旧记录排最前的问题

需求 3:对比报告限制同场景

  • 后端 GET /api/reports/compare:场景不同返回 400 对比报告要求两个运行使用相同场景
  • generate_compare_report 入口双保险(ValueError)
  • 顺带修复:case 无规则结果时 all([]) == True 被误判为通过 → 改为 None
  • 前端:报告 B 下拉只列同场景 run;A 变更后 B 场景不符自动清空

三、测试

  • 新增 6 个测试:triggered_by 默认值/透传持久化/非法值 422、list 含名称字段、compare 跨场景 400/ValueError
  • 全量 224 通过(v0.3 基线 218 → 224)

四、发布验证清单(t480)

  1. scripts/deploy-t480.sh 部署(自动同步 SKILL.md 到 openclaw 工作区)
  2. /api/health 返回 version=0.4.0-dev
  3. 手动触发一次评测 → Runs 页显示无来源 Tag(manual)
  4. 让 AI 助手触发一次评测 → 切回 Runs/Reports 页不刷新浏览器即可看到新记录,带"AI 助手"标记
  5. 对比报告:跨场景 run 不可选、同场景可正常对比