docs: v1.1.1 release notes + ADR-0010 + context/CLAUDE updates
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:
sinohqb 2026-08-18 19:01:14 +08:00
parent 5de46d514a
commit 0096c22e27
5 changed files with 126 additions and 5 deletions

View File

@ -111,6 +111,21 @@ SQLite StorageRepository 模式)
后端通过 `routers/proxy.py` 提供 HTTP + WebSocket 反向代理(路径前缀 `/openclaw`),将请求转发到 OpenClaw 服务docker-compose 中 `openclaw-eval` 容器。WS 桥接会自动注入认证 token 到 `connect.authenticate` 消息并重写 `Origin` 头。前端 `/openclaw` 路由以全屏 iframe 嵌入代理地址。 后端通过 `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 才允许 completedworker 触发 timeout 600s
### 文件管理模块 ### 文件管理模块
`/api/files` 端点提供分类树 + 文件上传/下载功能。`FileCategoryDB` 自引用(`parent_id`)实现树形结构,`FileRecordDB` 关联分类。文件物理存储在 `data/uploads/`,按分类子目录组织。删除分类会级联删除子分类 + 文件记录 + 物理文件。 `/api/files` 端点提供分类树 + 文件上传/下载功能。`FileCategoryDB` 自引用(`parent_id`)实现树形结构,`FileRecordDB` 关联分类。文件物理存储在 `data/uploads/`,按分类子目录组织。删除分类会级联删除子分类 + 文件记录 + 物理文件。

View File

@ -139,7 +139,7 @@ _Avoid_: 岗位(与模型用途的"岗位"概念冲突)
_Avoid_: 窗口(与静态评估的"服务周期窗口"混淆时需加前缀) _Avoid_: 窗口(与静态评估的"服务周期窗口"混淆时需加前缀)
**触发式执行Trigger-driven Execution**: **触发式执行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_: 轮询、调度(与静态评估活动调度混淆) _Avoid_: 轮询、调度(与静态评估活动调度混淆)
**Cron 池Cron Pool**: **Cron 池Cron Pool**:

View File

@ -1,8 +1,8 @@
# AgentEvalTool 文档索引 # AgentEvalTool 文档索引
**文档版本**: v1.1 **文档版本**: v1.2
**项目版本**: v1.0.0 **项目版本**: v1.1.1
**日期**: 2026-08-11 **日期**: 2026-08-18
**状态**: 已发布 **状态**: 已发布
**作者**: AgentEval Team **作者**: 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) | | **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.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) | | **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

View 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 隔离)

View 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 触发)
- **缺口**:方案③只自动化 executingworker与 completedanalystplanning 阶段无机制唤醒 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 sessionADR-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`);硬编码颜色走 tokenpassRateColor/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* 系列)保留,不影响运行