# 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）——结构化是核心要求