AgentEvalTool/.scratch/v1.0/spec.md

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 提交	平台状态检测到所有会话完成时唤醒

每个角色可配置不同的大模型（规划师用推理强的、评估者用对话自然的、分析师用结构化输出好的）。

粗计划结构

{
  "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": "每个维度至少一个会话产出评估"
}

结构化报告模板（第一版）

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