9cdbc41808
All 8 tickets' acceptance criteria checked off (incl. the real OpenClaw E2E verified on t480). Trivial import-sort fix from ruff included.
263 lines
13 KiB
Markdown
263 lines
13 KiB
Markdown
# v1.0 规格说明：智能评估第一期 —— OpenClaw 驱动的独立评测体系
|
||
|
||
**状态**: draft
|
||
**日期**: 2026-08-04
|
||
**决策依据**: grilling 共识清单（16 项）、ADR-0003 v2 修订、CONTEXT.md「探索式评测」章节
|
||
|
||
## Problem Statement
|
||
|
||
平台的评测能力（v0.8 静态评估）全部建立在"固定场景（考纲）"之上：预设题目、预设规则、统计通过率。这能回答"考纲过了多少"，但无法模拟真实用户的复杂行为——用户不按考纲出牌，他们会改主意、追问、被绕晕、放弃。
|
||
|
||
v0.9 把探索式评测嵌入了现有活动作为增强层，但探索仍是"活动内的附加"，没有独立生命周期。
|
||
|
||
本期引入**智能评估**——与静态评估并列的独立评测体系：用户只给方向（目标+种子+意图+角色），OpenClaw 全权规划与执行，产出可驱动被评对象改善的结构化报告。
|
||
|
||
## Solution
|
||
|
||
### 体系定位
|
||
|
||
两套评测体系正式分家：
|
||
|
||
| | 静态评估（v0.8） | 智能评估（v1.0） |
|
||
|---|---|---|
|
||
| 驱动者 | 平台调度器 | OpenClaw |
|
||
| 输入 | 固定场景（考纲） | 目标+种子+意图+角色 |
|
||
| 判定 | 规则驱动（关键词/时延/LLM打分） | OpenClaw 自主判定 |
|
||
| 产出 | 通过率、对比报告 | 结构化发现报告（可驱动被评对象进化） |
|
||
| 数据模型 | Campaign → Run → Turn → Result | IntelligentEval → Session → Message → Verdict |
|
||
|
||
### 核心概念
|
||
|
||
- **智能评估（IntelligentEval）**：独立实体，与 Campaign 平级。单对象绑定，拥有自己的状态机、配置、报告结构
|
||
- **粗计划（Coarse Plan）**：OpenClaw 产出的评估规划——评估维度、虚拟用户、时间分布、预算。入库可见，用户审批后才执行
|
||
- **智能评估会话（IntelligentEvalSession）**：OpenClaw 以虚拟用户身份与被评对象的一段完整对话，全新实体不复用 exploration_sessions
|
||
- **结构化报告**：发现清单+证据+严重程度+改善建议，可喂给被评对象的提示词/SOP 改善流程
|
||
|
||
## User Stories
|
||
|
||
1. As an 评测平台用户, I want 创建智能评估时提供目标、种子集、考察意图和 OpenClaw 角色描述, so that OpenClaw 有方向但不被锁死路径
|
||
2. As an 评测平台用户, I want 看到 OpenClaw 产出的粗计划并决定是否批准, so that 评估方向在我掌控之中
|
||
3. As an 评测平台用户, I want 打回不满意的计划并附反馈, so that OpenClaw 能根据反馈重新规划
|
||
4. As an 评测平台用户, I want 在管理页面看到执行进度, so that 我知道评估走到哪了
|
||
5. As an 评测平台用户, I want 评估完成后看到结构化报告（发现清单、证据、建议）, so that 我知道被评对象的问题在哪
|
||
6. As an 评测平台用户, I want 点开单个会话查看完整对话, so that 每个"发现"都能下钻到原文证据
|
||
7. As an 评测平台用户, I want 取消正在执行的评估, so that 方向错误时能及时止损
|
||
8. As an 评测平台用户, I want 导出报告为 Markdown, so that 离线分享材料完整
|
||
9. As an OpenClaw planner, I want 收到评估输入后产出粗计划并通过 API 提交, so that 用户能审批我的规划
|
||
10. As an OpenClaw evaluator, I want 按时间分布自唤醒执行会话, so that 交互合理分布在模拟的服务周期内
|
||
11. As an OpenClaw analyst, I want 汇总所有会话结果产出结构化报告, so that 发现可驱动被评对象改善
|
||
12. As an 平台, I want OpenClaw 停摆时智能评估标记 failed 而非无限等待, so that 不留悬挂评估
|
||
|
||
## Implementation Decisions
|
||
|
||
### 数据模型
|
||
|
||
**IntelligentEval（智能评估）**——独立实体，与 Campaign 平级：
|
||
|
||
```
|
||
IntelligentEval {
|
||
id: str (uuid)
|
||
name: str // 评估名称
|
||
target_id: str // 绑定的评测对象（单对象）
|
||
status: IntelligentEvalStatus // 状态机
|
||
|
||
// 用户输入（四件套）
|
||
goal: str // 一句话目标
|
||
seeds: JSON // 种子集（人设数组 + 目标数组）
|
||
intent: str // 考察意图
|
||
role_description: str // OpenClaw 角色描述
|
||
|
||
// 粗计划（OpenClaw 产出）
|
||
plan: JSON | null // 评估维度、虚拟用户、时间分布、预算、完成标准
|
||
plan_feedback: str | null // 打回时用户的反馈
|
||
|
||
// 时间窗口
|
||
time_window_hours: int // 模拟服务周期（如 24）
|
||
|
||
// 报告
|
||
report: JSON | null // 结构化报告（发现清单+证据+建议）
|
||
|
||
// 时间戳
|
||
created_at: datetime
|
||
updated_at: datetime
|
||
started_at: datetime | null // 批准执行时
|
||
completed_at: datetime | null // 完成/取消/失败时
|
||
}
|
||
```
|
||
|
||
**IntelligentEvalSession（智能评估会话）**——全新实体：
|
||
|
||
```
|
||
IntelligentEvalSession {
|
||
id: str (uuid)
|
||
eval_id: str // 归属的智能评估
|
||
target_id: str // 被评对象
|
||
persona: JSON // 虚拟用户人设
|
||
goal: str // 会话目标
|
||
dimension: str | null // 所属评估维度
|
||
status: SessionStatus // running / completed / failed / expired
|
||
|
||
// 会话级评估（OpenClaw 关闭时提交）
|
||
verdict: JSON | null // 结构化评估（达成度、问题、建议）
|
||
|
||
turn_count: int
|
||
created_at: datetime
|
||
closed_at: datetime | null
|
||
}
|
||
```
|
||
|
||
**IntelligentEvalMessage（会话消息）**：
|
||
|
||
```
|
||
IntelligentEvalMessage {
|
||
id: str (uuid)
|
||
session_id: str // 归属会话
|
||
role: str // "user" | "assistant"
|
||
content: str // 消息内容
|
||
latency_ms: int | null // 被评对象回复延迟
|
||
created_at: datetime
|
||
}
|
||
```
|
||
|
||
**状态机**：
|
||
|
||
```
|
||
IntelligentEvalStatus:
|
||
draft → planning → pending_approval → executing → completed
|
||
→ cancelled
|
||
→ failed
|
||
|
||
pending_approval 可打回 → planning（附反馈）
|
||
executing 可取消 → cancelled
|
||
```
|
||
|
||
### API 契约（全部 X-API-Key 鉴权，沿用 `require_api_key`）
|
||
|
||
**规划阶段：**
|
||
- `POST /api/intelligent-evals`：创建智能评估（body = name, target_id, goal, seeds, intent, role_description, time_window_hours）→ 状态 draft → planning
|
||
- `PUT /api/intelligent-evals/{id}/plan`：OpenClaw 提交粗计划（body = plan JSON）→ 状态 planning → pending_approval
|
||
|
||
**审批阶段：**
|
||
- `POST /api/intelligent-evals/{id}/approve`：用户批准 → 状态 pending_approval → executing，记录 started_at
|
||
- `POST /api/intelligent-evals/{id}/reject`：用户打回（body = feedback）→ 状态 pending_approval → planning
|
||
|
||
**执行阶段（OpenClaw 调用）：**
|
||
- `GET /api/intelligent-evals/{id}`：读取评估配置与计划
|
||
- `POST /api/intelligent-evals/{id}/sessions`：创建会话（body = persona, goal, dimension）→ 返回 session_id
|
||
- `POST /api/intelligent-evals/{id}/sessions/{sid}/messages`：发消息（body = content）→ 平台转发到被评对象通道，返回回复与延迟
|
||
- `POST /api/intelligent-evals/{id}/sessions/{sid}/close`：关闭会话（body = verdict JSON）→ 状态转 completed
|
||
|
||
**收尾阶段：**
|
||
- `PUT /api/intelligent-evals/{id}/report`：OpenClaw 提交结构化报告 → 状态 executing → completed
|
||
- `POST /api/intelligent-evals/{id}/cancel`：用户取消 → 状态 → cancelled
|
||
|
||
**读出口（前端用）：**
|
||
- `GET /api/intelligent-evals`：列表
|
||
- `GET /api/intelligent-evals/{id}`：详情（含计划、进度）
|
||
- `GET /api/intelligent-evals/{id}/sessions`：会话列表
|
||
- `GET /api/intelligent-evals/{id}/sessions/{sid}/messages`：单会话对话记录
|
||
- `GET /api/intelligent-evals/{id}/report`：结构化报告
|
||
- `GET /api/intelligent-evals/{id}/report/markdown`：Markdown 导出
|
||
|
||
### 通道复用
|
||
|
||
智能评估的消息转发复用现有 ChannelFactory——通过 target_id 找到对应的通道配置，用同一套 send/poll 机制与被评对象交互。不新建通道。
|
||
|
||
### 护栏
|
||
|
||
第一版信任 OpenClaw 自律：粗计划里约定的预算（会话数、轮数）就是契约，平台不做硬校验。后续版本可加硬护栏（超了返 409）。
|
||
|
||
### OpenClaw 技能（按角色拆分）
|
||
|
||
三个独立技能文件，走部署脚本既有 skill 同步管线分发：
|
||
|
||
| 技能 | 角色 | 职责 | 触发方式 |
|
||
|------|------|------|---------|
|
||
| `agenteval-intelligent-planner` | 规划师 | 收到评估输入 → 产出粗计划 → 调 API 提交 | 平台状态转 planning 时唤醒 |
|
||
| `agenteval-intelligent-evaluator` | 评估者 | 按时间分布自唤醒 → 创建会话 → 对话 → 关闭 → 提交会话评估 | OpenClaw cron 自唤醒 |
|
||
| `agenteval-intelligent-analyst` | 分析师 | 所有会话完成 → 汇总产出结构化报告 → 调 API 提交 | 平台状态检测到所有会话完成时唤醒 |
|
||
|
||
每个角色可配置不同的大模型（规划师用推理强的、评估者用对话自然的、分析师用结构化输出好的）。
|
||
|
||
### 粗计划结构
|
||
|
||
```json
|
||
{
|
||
"dimensions": ["退货流程", "投诉处理", "多轮追问"],
|
||
"virtual_users": [
|
||
{ "persona": { "background": "...", "personality": "...", "patience": "low" }, "goal": "完成退货" },
|
||
{ "persona": { "background": "...", "personality": "...", "patience": "high" }, "goal": "了解政策" }
|
||
],
|
||
"time_distribution": [
|
||
{ "time_slot": "0-2h", "sessions": 1, "scenario": "早间咨询" },
|
||
{ "time_slot": "8-10h", "sessions": 2, "scenario": "工作时段高峰" },
|
||
{ "time_slot": "18-22h", "sessions": 2, "scenario": "晚间投诉" }
|
||
],
|
||
"estimated_sessions": 5,
|
||
"budget": { "max_turns_per_session": 12, "total_max_turns": 60 },
|
||
"completion_criteria": "每个维度至少一个会话产出评估"
|
||
}
|
||
```
|
||
|
||
### 结构化报告模板（第一版）
|
||
|
||
```json
|
||
{
|
||
"summary": "一段话总结整体表现",
|
||
"scores": { "维度": 分数 } | null,
|
||
"findings": [
|
||
{
|
||
"issue": "退货流程中未主动确认订单号",
|
||
"severity": "high" | "medium" | "low",
|
||
"dimension": "退货流程",
|
||
"evidence": [
|
||
{ "session_id": "...", "turn_index": 3, "user_said": "...", "assistant_replied": "..." }
|
||
],
|
||
"suggestion": "在退货意图识别后，增加订单号确认步骤",
|
||
"related_sop": "退货处理流程 §3.2" | null
|
||
}
|
||
],
|
||
"highlights": [
|
||
{ "description": "多轮追问中保持了上下文连贯性", "dimension": "多轮追问" }
|
||
],
|
||
"priority_recommendations": ["先修 退货确认 问题，再优化 投诉共情"]
|
||
}
|
||
```
|
||
|
||
### 前端
|
||
|
||
独立顶级页面「智能评估」，四个子页面：
|
||
|
||
1. **列表页**：所有智能评估的列表（名称、对象、状态、创建时间），可新建
|
||
2. **管理页**：展示当前状态、用户输入、粗计划（待审批时可批准/打回）、执行进度
|
||
3. **报告页**：结构化报告展示——发现清单（问题+证据+建议）、亮点、会话列表
|
||
4. **会话详情页**：单个会话的完整对话记录 + 会话级评估
|
||
|
||
### 时间窗口语义
|
||
|
||
时间窗口是**模拟约束**而非硬截止。"模拟 24 小时服务周期内的用户交互"——OpenClaw 规划时要考虑交互的时间分布（早高峰、午间冷清、晚间投诉多），合理分布会话时机。OpenClaw 通过自身 cron 机制在对应时间点自唤醒执行。
|
||
|
||
## Testing Decisions
|
||
|
||
- 好测试只测外部行为：API 契约、状态机迁移、报告渲染；不测 OpenClaw 内部决策
|
||
- **集成测试（TestClient，主力接缝）**：智能评估生命周期（创建→规划→审批→执行→报告）、状态机各分支（打回、取消）、会话生命周期（创建→对话→关闭）
|
||
- **纯函数单测**：Markdown 渲染（dict 进 string 出）
|
||
- 前端仅 `tsc --noEmit`（沿用现状）
|
||
- OpenClaw 技能行为不进自动化测试，靠部署后端到端验证（与 v0.4 以来 skill 验收方式一致）
|
||
|
||
## Out of Scope
|
||
|
||
- 多对象绑定（第一版单对象，后续按需扩展）
|
||
- 平台硬护栏（第一版信任 OpenClaw 自律，后续可加 409 拒绝）
|
||
- 跨智能评估对比（多期智能评估的横向对照）
|
||
- 报告模板可配置（第一版固定模板）
|
||
- 事件驱动唤醒（纯 cron 自唤醒）
|
||
- 菜单二级化重构（稍后单独处理）
|
||
|
||
## Further Notes
|
||
|
||
- 智能评估与静态评估完全独立：不共享数据表、不共享状态机、不共享报告结构
|
||
- OpenClaw 三个角色技能可配不同大模型，模型配置走现有 model_configs 体系
|
||
- 时间分布编排由 OpenClaw 在粗计划中决定，平台只存储不校验
|
||
- 报告的消费者有两个：人（看问题）和 AI（拿报告去改提示词/SOP）——结构化是核心要求
|