docs: v1.1.1 release notes + ADR-0010 + context/CLAUDE updates
All checks were successful
CI / test (push) Successful in 3m58s
All checks were successful
CI / test (push) Successful in 3m58s
更新本次智能评估全链路修复与 UI/UX 优化的必要文档: - ADR-0010 新增:方案③触发采用独立 OpenClaw session(main 持久 session 上下文 缓存污染导致 worker 幻觉不执行)+ 时段分布约束 - CONTEXT.md:触发式执行词条补充时段约束与独立会话语义 - release-notes-v1.1.1.md 新增:智能评估全链路稳定化、任务队列监控、UI/UX 一致性 - docs/README.md:补 v1.1.0/v1.1.1 发布说明索引,版本升 v1.2 - CLAUDE.md:补智能评估执行机制(方案③)章节(scan loop 职责 + 独立 session/ 时段分布/状态一致性关键约束)
This commit is contained in:
parent
5de46d514a
commit
0096c22e27
15
CLAUDE.md
15
CLAUDE.md
@ -111,6 +111,21 @@ SQLite Storage(Repository 模式)
|
||||
|
||||
后端通过 `routers/proxy.py` 提供 HTTP + WebSocket 反向代理(路径前缀 `/openclaw`),将请求转发到 OpenClaw 服务(docker-compose 中 `openclaw-eval` 容器)。WS 桥接会自动注入认证 token 到 `connect.authenticate` 消息并重写 `Origin` 头。前端 `/openclaw` 路由以全屏 iframe 嵌入代理地址。
|
||||
|
||||
### 智能评估执行机制(方案③触发式执行)
|
||||
|
||||
智能评估的 Worker 自动化(取代旧 Cron 池,见 ADR-0009/0010)由 `app.py::_intelligent_eval_scan_loop` 驱动(lifespan 后台任务,每 60s):
|
||||
|
||||
1. **requeue_stale_assigned_tasks**:assigned 超时(>10min)且评估 executing → 回 pending(卡死恢复)
|
||||
2. **scan_and_enqueue_tasks**:扫描 executing 评估,时段到期/欠账 → 入队(任务队列)
|
||||
3. **settle_tasks_for_finished_evals**:评估离开 executing 后,其 pending/assigned 任务回收为 completed
|
||||
4. **_supplement_decision_logs**:agent 未上报决策日志时按状态兜底补录
|
||||
5. **触发**:有 planning 评估 → 触发 planner skill;有 pending 任务 → 触发 worker skill
|
||||
|
||||
关键约束:
|
||||
- **独立 session**:触发命令必须带 `--session-id`(`agenteval-worker-<ts>` / `agenteval-planner-<ts>`),**禁止复用 `--agent main` 的持久 session**——main session 多次触发累积上下文缓存后 worker 会幻觉不执行(见 ADR-0010)
|
||||
- **时段分布**:触发指令明确"仅执行当前到期时段内欠账的会话",平台每 60s 持续触发推进后续时段,保证 1h 窗口按时段分批
|
||||
- **状态一致性**:`submit_report` 要求会话全部 close 才允许 completed;worker 触发 timeout 600s
|
||||
|
||||
### 文件管理模块
|
||||
|
||||
`/api/files` 端点提供分类树 + 文件上传/下载功能。`FileCategoryDB` 自引用(`parent_id`)实现树形结构,`FileRecordDB` 关联分类。文件物理存储在 `data/uploads/`,按分类子目录组织。删除分类会级联删除子分类 + 文件记录 + 物理文件。
|
||||
|
||||
@ -139,7 +139,7 @@ _Avoid_: 岗位(与模型用途的"岗位"概念冲突)
|
||||
_Avoid_: 窗口(与静态评估的"服务周期窗口"混淆时需加前缀)
|
||||
|
||||
**触发式执行(Trigger-driven Execution)**:
|
||||
智能评估的执行机制:**平台掌控节奏**——每 60s 扫描 executing 评估,判断时段到期/欠账后入队;**有任务时触发一个无状态 OpenClaw agent**(headless,执行 worker skill 后即退)从任务队列取任务执行。执行单元自主决策(执行会话/等待/开始分析),平台负责节奏与兜底(assigned 超时重入队、决策日志补录)。取代旧"常驻 cron 每分钟自唤醒"机制(见 Cron 池,已废弃)。(决策见 ADR-0009)
|
||||
智能评估的执行机制:**平台掌控节奏**——每 60s 扫描 executing 评估,判断时段到期/欠账后入队;**有任务时触发一个无状态 OpenClaw agent**(headless,执行 worker skill 后即退)从任务队列取任务执行。执行单元自主决策(执行会话/等待/开始分析),平台负责节奏与兜底(assigned 超时重入队、决策日志补录)。**时段约束**:每次触发只执行当前到期时段(time_distribution 中当前 offset 所在时段)内欠账的会话,绝不创建未来时段会话——由平台每 60s 持续触发推进后续时段,保证时间窗口内的交互按时段分布而非一次建完。**独立会话**:每次触发用独立 OpenClaw session(避免复用 main 持久会话导致上下文缓存污染、agent 幻觉不执行)。取代旧"常驻 cron 每分钟自唤醒"机制(见 Cron 池,已废弃)。(决策见 ADR-0009、ADR-0010)
|
||||
_Avoid_: 轮询、调度(与静态评估活动调度混淆)
|
||||
|
||||
**Cron 池(Cron Pool)**:
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
# AgentEvalTool 文档索引
|
||||
|
||||
**文档版本**: v1.1
|
||||
**项目版本**: v1.0.0
|
||||
**日期**: 2026-08-11
|
||||
**文档版本**: v1.2
|
||||
**项目版本**: v1.1.1
|
||||
**日期**: 2026-08-18
|
||||
**状态**: 已发布
|
||||
**作者**: AgentEval Team
|
||||
|
||||
@ -50,6 +50,8 @@ AgentEvalTool 是一个智能体质量评估工具集平台,用于评估 AI
|
||||
|
||||
| 文档 | 说明 | 链接 |
|
||||
|------|------|------|
|
||||
| **V1.1.1 发布说明** | 智能评估全链路稳定化(方案③)、任务队列监控、UI/UX 一致性 | [release-notes-v1.1.1.md](release-notes-v1.1.1.md) |
|
||||
| **V1.1.0 发布说明** | Cron 池架构、智能评估可扩展性 | [release-notes-v1.1.0.md](release-notes-v1.1.0.md) |
|
||||
| **V1.0.0 发布说明** | 双评测体系、耐久 Campaign、架构深化与双线部署 | [release-notes-v1.0.md](release-notes-v1.0.md) |
|
||||
| **V0.8 发布说明** | Campaign 周期对比与正式线演进基线 | [release-notes-v0.8.md](release-notes-v0.8.md) |
|
||||
| **V0.2 发布说明** | async 引擎、安全基线、测试基线、部署规范化 | [release-notes-v0.2.md](release-notes-v0.2.md) |
|
||||
@ -142,4 +144,4 @@ AgentEvalTool 是一个智能体质量评估工具集平台,用于评估 AI
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-08-11
|
||||
**最后更新**: 2026-08-18
|
||||
|
||||
42
docs/adr/0010-isolated-openclaw-session-for-triggers.md
Normal file
42
docs/adr/0010-isolated-openclaw-session-for-triggers.md
Normal file
@ -0,0 +1,42 @@
|
||||
# ADR-0010: 方案③触发采用独立 OpenClaw session
|
||||
|
||||
**状态**: 已接受
|
||||
**日期**: 2026-08-18
|
||||
**决策者**: 架构团队
|
||||
**相关**: ADR-0009(触发式执行取代 Cron 池)、CONTEXT.md(触发式执行)
|
||||
|
||||
## Context
|
||||
|
||||
方案③(ADR-0009)以 `docker exec openclaw-eval openclaw agent --agent main -m "<worker/planner skill>" --json` 触发 OpenClaw headless agent 执行 worker / planner skill。t480 实测发现:评估进入 executing 后**一直卡"等待 OpenClaw 创建会话"**——任务入队(pending)但 worker 从不认领。
|
||||
|
||||
排查(diagnosing-bugs 闭环)确认:
|
||||
- scan loop 每 60s 正常触发 worker(时间戳证实)
|
||||
- worker 被触发后 **0 次工具调用**,直接幻觉输出"评估 pending_approval"(实际 executing)
|
||||
- model usage 显示 **cacheRead ~12 万 token**:`--agent main` 复用 **main 持久 session**,多次触发累积了大量历史上下文缓存
|
||||
- **验证**:手动用独立 `--session-id` 触发 → worker 恢复正常(取任务、建会话、close)
|
||||
|
||||
根因:OpenClaw main agent 的持久 session 在多次触发后上下文缓存膨胀,LLM 不再执行 worker skill 的 API 步骤,而是从旧上下文幻觉输出——复用 main session 的"缓存命中"收益在触发式执行(高频、长链工具调用)下不可靠。
|
||||
|
||||
## Decision
|
||||
|
||||
方案③的 worker / planner 触发命令**加 `--session-id`(每次唯一)**:
|
||||
|
||||
```bash
|
||||
docker exec openclaw-eval openclaw agent --agent main \
|
||||
--session-id agenteval-worker-<unix-ts> \
|
||||
-m "<worker skill 指令>" --json
|
||||
```
|
||||
|
||||
- worker 用 `agenteval-worker-<ts>`、planner 用 `agenteval-planner-<ts>`,每次触发独立 session
|
||||
- 触发 timeout 从 300s 调到 600s(独立 session 首次加载 skill + 执行更慢)
|
||||
|
||||
**为什么独立 session 可行**:worker/planner 的决策完全基于平台状态(任务队列、评估/会话/决策日志 API),**不依赖跨触发记忆**——每次干净 session 无副作用。
|
||||
|
||||
**时段分布约束**(同一决策):触发指令明确"仅执行当前 offset 所在时段内欠账的会话,绝不创建未来时段会话";worker 完成当前时段后 complete 任务,平台每 60s 再次触发推进后续时段——保证 1h 窗口的交互按时段(如 0-20/20-40/40-60min)分布,而非一次性建完。
|
||||
|
||||
## Consequences
|
||||
|
||||
- **每次触发新建 session**:无上下文缓存命中,首次加载 skill 更慢(触发一次约 1-5 分钟),但行为可靠(不再幻觉)
|
||||
- **无跨触发状态**:worker/planner 无记忆,全部状态在平台 DB(设计本如此)
|
||||
- **scan loop 节奏**:worker 执行当前时段(分钟级),完成后平台每 60s 触发推进;与 1h 窗口时段匹配
|
||||
- 旧 main session 的历史缓存不影响新触发(独立 session 隔离)
|
||||
62
docs/release-notes-v1.1.1.md
Normal file
62
docs/release-notes-v1.1.1.md
Normal file
@ -0,0 +1,62 @@
|
||||
# AgentEvalTool v1.1.1 发布说明
|
||||
|
||||
**版本**:v1.1.1
|
||||
**发布日期**:2026-08-18
|
||||
**状态**:已发布
|
||||
**作者**:AgentEval Team
|
||||
|
||||
---
|
||||
|
||||
## 一、版本概述
|
||||
|
||||
v1.1.1 是 v1.1.0 的**收尾与稳定化版本**:将方案③(触发式执行,取代 Cron 池)在 t480 上完整跑通并修复全链路暴露的流程缺口,同时完成 UI/UX 全面盘点与一致性修复。核心成果:**智能评估从规划到报告的 1 小时窗口全自动闭环在 t480 上稳定可用**。
|
||||
|
||||
## 二、智能评估全链路稳定化
|
||||
|
||||
v1.1.0 引入 Cron 池后,实际部署暴露了执行机制的多个缺口,v1.1.1 逐一修复(t480 实测驱动):
|
||||
|
||||
### 2.1 规划阶段自动化(planner 触发)
|
||||
- **缺口**:方案③只自动化 executing(worker)与 completed(analyst),planning 阶段无机制唤醒 planner → 评估永远停 planning
|
||||
- **修复**:scan loop 每 60s 检测 planning 评估,触发 `agenteval-intelligent-planner` skill 产出粗计划并提交审批
|
||||
|
||||
### 2.2 分钟级时段解析
|
||||
- **缺口**:planner 对短窗口(1h)产出分钟级时段(`0-20min`),`parse_time_slot` 只支持小时级(`8-10h`)→ 审批后永不入队
|
||||
- **修复**:时段解析支持 `h`/`min` 后缀统一换算小时
|
||||
|
||||
### 2.3 时间窗口时段分布
|
||||
- **缺口**:触发指令"立即完成"让 worker 一次性创建所有会话 → 1h 窗口几分钟跑完,时段分布失效
|
||||
- **修复**:触发指令 + worker skill 明确"仅执行当前到期时段内欠账的会话",平台每 60s 持续触发推进后续时段 → 1h 窗口严格按时段(0-20/20-40/40-60min)分批
|
||||
|
||||
### 2.4 独立 OpenClaw session(ADR-0010)
|
||||
- **缺口**:`--agent main` 复用 main 持久 session,多次触发累积上下文缓存后 worker 幻觉输出(报 pending_approval)不执行 API → 评估卡"等待创建会话"
|
||||
- **修复**:worker/planner 触发加 `--session-id`(每次唯一),独立 session 执行
|
||||
|
||||
### 2.5 状态一致性
|
||||
- **会话关闭校验**:`submit_report` 在会话未全部 close 时拒绝(409),杜绝"评估 completed 但进度 0%"
|
||||
- **任务回收**:评估离开 executing 后,其 pending/assigned 任务回收为 completed,杜绝队列残留
|
||||
|
||||
## 三、任务队列监控与评估列表
|
||||
|
||||
- **任务队列独立页**(`/intelligent-evals/tasks`):状态统计条(点击筛选)+ 单行表格,5s 轮询,展示方案③的定时触发
|
||||
- **评估列表增强**:状态统计条(含 cancelled)、服务端分页(默认 10 条/页)、会话进度进度条、单行表格、"查看"按钮 + 整行点击
|
||||
- **详情抽屉回归**:详情/报告合一单层抽屉(Tabs:概览/决策过程/配置历史/报告),审批动作在抽屉头部
|
||||
|
||||
## 四、UI/UX 盘点与一致性
|
||||
|
||||
全面盘点(`.scratch/ui-ux-audit.md`)并修复:
|
||||
|
||||
- **P0 功能缺陷**:决策过程/配置历史一次性加载 → useEffect + 刷新按钮;useRunSession 轮询统一 usePolling(后台暂停);useFiles 接 tabPath(跳回自动刷新)
|
||||
- **P1 一致性**:收敛 3 处重复状态映射(统一走 `intelligent_eval/status.ts`);硬编码颜色走 token(passRateColor/statusColors/colors)
|
||||
- **P2 + 清理**:抽 SectionHeader 组件消重复;删除废弃的 CronPoolMonitor 页面
|
||||
- **综合评分**:EvalReport 兼容扁平/嵌套两种 scores 结构(analyst 输出不可控)
|
||||
|
||||
## 五、质量
|
||||
|
||||
- **测试**:901 passed(含触发/时段/会话校验/任务回收等回归)
|
||||
- **前端**:tsc 0 错误、vitest 16 passed
|
||||
- **文档**:ADR-0009(触发式执行)、ADR-0010(独立 session)新增;CONTEXT.md 领域词汇更新
|
||||
|
||||
## 六、已知事项
|
||||
|
||||
- 智能评估**暂无 delete API**:completed 的历史测试评估无法通过平台删除(需后续开发 delete + 级联清理)
|
||||
- t480 上的 completed 验证评估(融侨城 1h* 系列)保留,不影响运行
|
||||
Loading…
Reference in New Issue
Block a user