1aa453ef0a
Implement Ticket 01 of intelligent eval cron pool architecture (ADR-0007): - Add 4 new tables: task_queue, cron_pool, config_snapshots, decision_logs - Implement task enqueueing logic with priority calculation - Implement task assignment and completion APIs - Add unit tests (9) and integration tests (7) - Update CONTEXT.md with new vocabulary - Add ADR-0007 documenting cron pool architecture decision All 760 tests passing.
174 lines
14 KiB
Markdown
174 lines
14 KiB
Markdown
# AgentEvalTool
|
||
|
||
智能体质量评估平台的领域词汇表。评估 AI 数字员工 / AI 助手的服务质量：向被评智能体发送消息、收集回复、按规则打分并生成报告。
|
||
|
||
## Language
|
||
|
||
**评测对象（Target / EvalTarget）**:
|
||
被评估的智能体本身。每个被评智能体只有一个可访问地址，评测对象与其通道连接信息一一对应（不区分测试/生产等多环境部署）。
|
||
_Avoid_: 被测系统、机器人、环境
|
||
|
||
**平台类型（Platform）**:
|
||
被评智能体的产品形态分类（AI 数字员工 / AI 助手），意图是未来据此选择评测策略；目前仅作分类标签，不参与任何评测逻辑。
|
||
_Avoid_: 产品线、渠道
|
||
|
||
**通道（Channel）**:
|
||
向评测对象收发消息的技术接入协议（tutu-api / openclaw / http）。通道决定"怎么连"，与平台类型（"是什么形态"）相互独立。
|
||
_Avoid_: 接口、连接器
|
||
|
||
**期望（Expectation）**:
|
||
用例层面的业务意图描述：智能体应当如何回应（意图、必含/禁含关键词、时延上限）。表达"想要什么"，与评估规则（"怎么判定"）叠加生效，不是规则的替代品。
|
||
_Avoid_: 断言、预期结果
|
||
|
||
**评估规则（EvalRule）**:
|
||
对单轮回复的可执行判定标准（keyword_match / response_time / llm_score），产出通过与否和得分。用例的唯一正式判定机制。
|
||
_Avoid_: 校验器、断言
|
||
|
||
**连通用例（Connectivity Case）**:
|
||
不配置任何规则与期望的用例，仅验证消息能发出且收到回复，收到即通过。合法用法，但报告中应与判定型用例区分标注，避免稀释通过率。
|
||
_Avoid_: 空用例、无效用例
|
||
|
||
**场景（Scenario）**:
|
||
一组评测用例的集合，定义一次评测的"考纲"——考察哪些能力维度。场景是对比报告的可比性单位：同场景的两次运行即可比，无论具体对话内容是否相同。
|
||
_Avoid_: 测试集、题库
|
||
|
||
**用例（Case）**:
|
||
场景内的单个考察项，分单轮（single）、多轮（multi_turn）、动态（dynamic）三类。静态用例题目固定；动态用例只固定考察意图（prompt），每次运行由 AI 现场生成对话消息。
|
||
_Avoid_: 测试点、题目
|
||
|
||
**对比报告（Compare Report）**:
|
||
同一场景（同版本考纲）下两次运行的逐项对照。可比性来自"同考纲"而非"同考卷"——动态用例题目不同不影响可比。跨场景对比无意义，系统拒绝。
|
||
_Avoid_: 差异报告
|
||
|
||
**场景版本（Scenario Version）**:
|
||
场景考纲的版本标识。仅考纲字段（用例集、模型绑定、LLM 配置）变更时递增；名称、描述、标签等元数据编辑不升版。（决策见 ADR-0001）
|
||
_Avoid_: 修订号
|
||
|
||
**评测运行（Run / EvalRun）**:
|
||
一次"评测对象 × 场景"的完整执行记录，含触发来源（手动 / AI 助手 / CLI）、逐轮对话与全部判定结果。
|
||
_Avoid_: 任务、作业、测试
|
||
|
||
**轮次（Turn）**:
|
||
一次完整的问答往返：向评测对象发出一条消息并收到其回复。不是单方向的一条消息——`turns: 3` 表示 3 个问答对。
|
||
_Avoid_: 消息、回合（round 仅作代码内索引名）
|
||
|
||
**通过率（Pass Rate）**:
|
||
通过用例数 ÷ 全部用例数。刻意采用服务视角：通道故障、超时等执行失败同样计为不通过——用户视角里"没回复"就是质量问题，不从分母中剔除。（决策见 ADR-0002）
|
||
_Avoid_: 成功率、达标率
|
||
|
||
## 周期评估
|
||
|
||
**评估活动（Campaign）**:
|
||
针对**单个评测对象**、跨一个服务周期窗口的评估聚合，模拟该智能体在完整服务周期内面对的真实用户行为。活动是 Run 之上的聚合：按计划在窗口内派生多个普通 Run（每个 Run 仍是"一个对象 × 一个场景"的单次执行），最终聚合成周期评估报告（时间趋势 + 能力汇总双主轴）。活动状态入库、抗重启。多对象通过并行多个活动 + 跨活动对比实现。
|
||
_Avoid_: 批量任务、计划任务、24小时任务（窗口长度可配，不特指 24h）
|
||
|
||
**服务周期窗口（Service-Cycle Window）**:
|
||
活动的时间跨度，模拟被评智能体一个完整的持续服务周期。长度可自定义（如 6 / 12 / 24 / 48 / 72 小时），24 小时为"一天"的默认代表。
|
||
_Avoid_: 时长、周期（周期单指这个窗口）
|
||
|
||
**活动计划（Campaign Plan）**:
|
||
活动在窗口内"何时、对哪个对象、跑哪个场景、多大强度、以何种用户人设"的时间编排。由 OpenClaw 作为"虚拟用户大脑"在活动层生成，并在窗口内的决策点依据已完成时段的结果**自适应调整**后续编排；平台调度器负责耐久执行（派生 Run、重启后续跑、决策点唤醒 OpenClaw）。计划编排已有场景，时段内的具体对话仍由动态用例生成器产出。
|
||
_Avoid_: 排程、日程表
|
||
|
||
**可用性（Availability）**:
|
||
活动周期报告中的一个维度：某时段（或整窗）内**正常完成**的子 Run 占比（completed / 已派生）。与通过率正交——通过率反映"回答质量"（用例级、含故障判不通过，ADR-0002），可用性反映"服务是否可达/执行是否成功"。通道故障导致的失败子 Run 拉低可用性。
|
||
_Avoid_: 在线率、健康度
|
||
|
||
**周期对比（Period Comparison）**:
|
||
同一活动串（同评测对象 + 同计划指纹：场景集合、偏移、次数、窗口完全一致）中，相邻两期正式线活动的对照，回答"这一期比上一期好了还是坏了"。自动按完成时间取前一个已有 completed 分析的活动为基线；计划指纹不一致即无自动基线，可手动另选。区别于"跨活动对比"（多对象并行活动的横切对照）与"对比报告"（Run 级逐项对照）。
|
||
_Avoid_: 环比（暗示固定自然周期，活动窗口可任意长）
|
||
|
||
**正式线 / 加速调试线（Production-line / Accelerated-line）**:
|
||
活动的两种运行档位，由时间倍速区分：`time_scale == 1` 为正式线（窗口按真实时长走完，代表真实服务周期，享受自动分析、自动周期对比等全链自动化）；`time_scale > 1` 为加速调试线（压缩窗口用于快速验证流程，自动化能力默认关闭，仅手动按需触发）。
|
||
_Avoid_: 真实线、快速模式
|
||
|
||
## 探索式评测
|
||
|
||
**虚拟用户（Virtual User）**:
|
||
OpenClaw 在探索式评测中扮演的角色：按人设与探索目标模拟拟真用户行为、与被评对象自主对话的智能体。是"行动者"而非"台词生成器"——对话节奏、追问、放弃均由其自主决定。
|
||
_Avoid_: 测试员、脚本机器人、模拟器
|
||
|
||
**探索式评测（Exploratory Evaluation）**:
|
||
与固定场景并行的第二种评测模式：不预设考纲，由虚拟用户按种子自由行动，产出"发现的问题"而非"通过率"。固定场景保留为回归基线（可比性、周期对比建在其上），两模式共用活动/窗口/报告外壳，可在同一活动内混编。（决策见 ADR-0003 v2 修订）
|
||
_Avoid_: 自由测试、压力测试、探索测试
|
||
|
||
**探索会话（Exploration Session）**:
|
||
虚拟用户以"人设 × 目标"组合执行的一段完整对话过程，独立实体存储（`exploration_sessions`，不并入评测运行——Run 绑定场景与规则判定，探索会话两者皆无）。平台提供会话对象、护栏与留痕，对话由 OpenClaw 驱动。
|
||
_Avoid_: 运行、用例、测试会话
|
||
|
||
**种子集（Seed Set）**:
|
||
活动级配置的种子人设（背景、性格、耐心度）与种子目标（如"完成退货"）集合，是探索式评测的可比性单位（对应固定场景的"考纲"，与 `plan` 同构）。虚拟用户可在预算约束内从种子衍生有限变体（换表达、换追问策略），全部留痕。
|
||
_Avoid_: 题库、人设库、剧本
|
||
|
||
**体验记录（Experience Record）**:
|
||
探索会话结束时虚拟用户产出的结构化自报：目标是否达成、卡点、被误导处、情绪变化。探索式评测的第一手证据——意图-结果闭环只有行动者自己能给；judge 岗位对抽样对话独立复核补充质量维度，两条证据链在分析层汇合。
|
||
_Avoid_: 评测结果、断言、日志
|
||
|
||
**巡检（Patrol）**:
|
||
常驻代理的周期性自主行动：经 OpenClaw heartbeat/cron 唤醒，调平台巡检 API 查看进行中活动的新结果与预算余量，自主决定"继续观察 / 派探索会话"。全局一个常驻巡检作业，无状态地巡检所有活动；OpenClaw 停摆只暂停探索，固定计划照常。
|
||
_Avoid_: 轮询、心跳（heartbeat 是 OpenClaw 机制名，巡检是平台侧行为）
|
||
|
||
## 智能评估
|
||
|
||
**静态评估（Static Evaluation）**:
|
||
v0.8 已完整的评测体系：考纲驱动、平台执行、规则判定。预设场景（用例+规则）、平台调度器派生 Run、统计通过率。回答"考纲过了多少"。
|
||
_Avoid_: 固定评估、传统评估
|
||
|
||
**智能评估（Intelligent Evaluation）**:
|
||
与静态评估并列的独立评测体系：目标驱动、OpenClaw 规划执行、AI 判定。用户只给方向（目标+种子+意图+角色），OpenClaw 全权规划与执行，产出可驱动被评对象改善的结构化报告。独立实体（IntelligentEval），与 Campaign 平级，不共享数据表与状态机。
|
||
_Avoid_: 动态评估、自动评估
|
||
|
||
**粗计划（Coarse Plan）**:
|
||
OpenClaw 在智能评估中产出的评估规划：评估维度、虚拟用户列表、时间分布编排、预算、完成标准。入库可见，用户审批后才执行。"粗"在于只定方向不定细节——具体对话策略、追问节奏、何时放弃由执行时动态决定。
|
||
_Avoid_: 计划、方案（太泛）
|
||
|
||
**智能评估会话（IntelligentEvalSession）**:
|
||
OpenClaw 以虚拟用户身份与被评对象的一段完整对话，全新实体（不复用 exploration_sessions）。归属智能评估、含人设/目标/维度、会话级评估（verdict）。
|
||
_Avoid_: 探索会话（那是静态评估增强层的概念）、运行
|
||
|
||
**结构化报告（Structured Report）**:
|
||
智能评估的最终产出：发现清单（问题+证据+严重程度+改善建议）+ 亮点 + 优先级建议。消费者有两个：人（看问题）和 AI（拿报告去改被评对象的提示词/SOP，驱动其进化）。
|
||
_Avoid_: 评估报告（与静态评估的报告混淆）、分析（与 Analysis 岗位混淆）
|
||
|
||
**评估角色（Evaluation Role）**:
|
||
OpenClaw 在智能评估中按职责拆分的三个角色：规划师（planner，产出粗计划）、评估者（evaluator，执行对话）、分析师（analyst，汇总报告）。每个角色可配置不同大模型，对应三个独立技能文件。
|
||
_Avoid_: 岗位（与模型用途的"岗位"概念冲突）
|
||
|
||
**时间窗口（Time Window）**:
|
||
智能评估的模拟约束：模拟一个完整服务周期（如 24h）内的用户交互分布。OpenClaw 规划时考虑交互时机（早高峰、午间冷清、晚间投诉多），通过 cron 自唤醒在对应时间点执行。是模拟约束而非硬截止。
|
||
_Avoid_: 窗口（与静态评估的"服务周期窗口"混淆时需加前缀）
|
||
|
||
**Cron 池（Cron Pool）**:
|
||
OpenClaw 侧的工作单元池（5-20 个 cron），每个 cron 可以处理任意智能评估。池化管理避免"一个评估一个 cron"导致的 cron 爆炸，同时保持每个 cron 的自主决策能力。平台负责创建/删除 cron，OpenClaw 负责执行。（决策见 ADR-0007）
|
||
_Avoid_: 任务池、工作池（太泛）
|
||
|
||
**工作单元（Worker）**:
|
||
Cron 池中的一个 cron + 其 state，表示一个可用的执行单元。Worker 每分钟唤醒，从平台任务队列取一个任务执行，完成后归还到池中。Worker 有完整的决策权：执行会话、等待、开始分析。
|
||
_Avoid_: 执行器、处理器（失去自主性含义）
|
||
|
||
**任务队列（Task Queue）**:
|
||
平台侧的待处理评估队列，持久化在 DB。每分钟扫描所有 executing 评估，判断哪些需要立即处理（时段到期、有欠账），按优先级排序（时段到期 > 欠账多 > 等待时间长）。Worker 从队列取任务。
|
||
_Avoid_: 消息队列（与 MQ 混淆）、任务列表
|
||
|
||
**配置快照（Config Snapshot）**:
|
||
智能评估配置的历史版本（四件套、粗计划、时间窗口）。创建评估、提交计划、修改配置时自动保存，支持对比和回滚。用于追溯配置变更历史。
|
||
_Avoid_: 版本（与场景版本混淆）、备份
|
||
|
||
**决策日志（Decision Log）**:
|
||
Worker 每次唤醒时的决策记录（执行会话/等待/开始分析 + 原因 + 上下文）。持久化在 DB，用于调试和审计 OpenClaw 的自主决策过程。
|
||
_Avoid_: 日志（太泛）、审计日志（与安全审计混淆）
|
||
|
||
## 模型配置
|
||
|
||
**模型能力（Capability）**:
|
||
供给侧属性：一个已接入模型本身能干什么（对话 / 向量 / 审核）。描述模型，不描述评测流程。
|
||
_Avoid_: 功能、类型
|
||
|
||
**模型用途（Purpose）**:
|
||
需求侧属性：评测流程中的角色岗位（出题 generator / 判卷 judge / 向量 embedding / 审核 moderation / 分析 analysis）。场景通过模型绑定为每个岗位指派一个具备相应能力的模型；一个对话能力模型可同时胜任出题、判卷、分析等岗位。
|
||
_Avoid_: 能力、角色（role 留给对话消息的 role 字段）
|
||
|
||
**分析（Analysis）岗位**:
|
||
模型用途的一种：对一整次评估活动（Campaign）的聚合结果做复杂诊断，产出结构化的问题分析与服务质量改善建议。区别于判卷（judge 只裁单轮回复），分析是活动级、跨场景的叙述性研判。因活动跨场景，分析模型不按场景绑定，而是全局默认指派、活动创建时可覆盖。
|
||
_Avoid_: 判卷、总结
|