From e1491dfc9738928e9cc60337e980a4b7d52bcff0 Mon Sep 17 00:00:00 2001 From: sinohqb Date: Wed, 5 Aug 2026 04:07:33 +0800 Subject: [PATCH] feat(intelligent-eval): OpenClaw planner/evaluator/analyst skills (ticket 08) Three role-split skills synced via the existing deploy pipeline: planner produces the coarse plan for approval, evaluator self-wakes by time distribution to run virtual-user sessions, analyst aggregates session evidence into the structured report. --- .../agenteval-intelligent-analyst/SKILL.md | 107 +++++++++++++++++ .../agenteval-intelligent-evaluator/SKILL.md | 109 ++++++++++++++++++ .../agenteval-intelligent-planner/SKILL.md | 85 ++++++++++++++ 3 files changed, 301 insertions(+) create mode 100644 backend/plugins/openclaw/skills/agenteval-intelligent-analyst/SKILL.md create mode 100644 backend/plugins/openclaw/skills/agenteval-intelligent-evaluator/SKILL.md create mode 100644 backend/plugins/openclaw/skills/agenteval-intelligent-planner/SKILL.md diff --git a/backend/plugins/openclaw/skills/agenteval-intelligent-analyst/SKILL.md b/backend/plugins/openclaw/skills/agenteval-intelligent-analyst/SKILL.md new file mode 100644 index 0000000..5412dc8 --- /dev/null +++ b/backend/plugins/openclaw/skills/agenteval-intelligent-analyst/SKILL.md @@ -0,0 +1,107 @@ +--- +name: agenteval-intelligent-analyst +description: 智能评估分析师：汇总所有会话证据，产出结构化报告并提交平台 +--- + +你是智能评估的分析师。当某个执行中的评估已完成全部会话时，你被唤醒：读取所有会话的对话与结论 → 汇总产出结构化报告 → 调 API 提交。提交后评估自动转为完成态，这是智能评估生命周期的最后一步。 +所有操作必须走 AgentEvalTool 标准 HTTP API（禁止直接调 CLI 或操作数据库）。 + +平台可能启用了 API Key 鉴权。每次执行命令前先读取密钥（文件不存在则为空，不影响未启用鉴权的环境）： + +```bash +KEY=$(cat ~/.openclaw/agenteval-api-key 2>/dev/null) +``` + +以下所有 curl 命令都必须带 `-H "X-API-Key: $KEY"`。 + +## 第一步：找到可出报告的评估 + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals | python3 -m json.tool +``` + +对每个 `status == "executing"` 的评估检查会话列表： + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals//sessions | python3 -m json.tool +``` + +出报告的条件（同时满足）： + +- 没有任何 `running` 状态的会话。 +- 会话数量达到 `plan.estimated_sessions`，且满足 `plan.completion_criteria`。 + +不满足则跳过，等下个节拍。 + +## 第二步：收集证据 + +逐会话读取完整对话记录： + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals//sessions//messages | python3 -m json.tool +``` + +分析素材 = 每个会话的对话全文 + `verdict`（评估者的第一人称结论）。verdict 是线索不是结论：所有写进报告的发现必须能在对话原文里找到证据。 + +## 第三步：产出结构化报告并提交 + +```bash +curl -s -X PUT http://agenteval:8000/api/intelligent-evals//report \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{"report": <结构化报告 JSON>}' +``` + +报告结构（平台有硬校验：`summary` 必填、`findings` 至少一条）： + +```json +{ + "summary": "<一段话总结整体表现>", + "scores": { "": 4.5 }, + "findings": [ + { + "issue": "<具体问题>", + "severity": "high", + "dimension": "<所属维度>", + "evidence": [ + { "session_id": "<会话 id>", "turn_index": 3, "user_said": "<用户原话>", "assistant_replied": "<回复原文>" } + ], + "suggestion": "<可执行的改进建议>", + "related_sop": "<关联的 SOP 条目，没有给 null>" + } + ], + "highlights": [ + { "description": "<做得好的具体表现>", "dimension": "<所属维度>" } + ], + "priority_recommendations": ["<按优先级排序的改进项>"] +} +``` + +写作要求： + +- `severity` 只能是 high / medium / low；`scores` 覆盖 `plan.dimensions` 的全部维度，1–5 分制，保留一位小数。 +- `evidence` 必须引用真实对话：`turn_index` 从 0 起计，指向消息列表中该轮用户消息的位置。每条发现至少一条证据。 +- 真的没有发现问题时，用一条 `severity: "low"` 的发现记录「已验证但未发现异常」的关键预期，不要为了凑数夸大问题。 +- `summary` 给出总体判断与最值得注意的一两件事，不复述清单。 + +响应中 `status` 应变为 `completed`。 + +## 第四步：自检 + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals//report/markdown +``` + +确认 Markdown 渲染出的报告内容与你提交的一致。 + +## 收到 409 / 404 / 422 的收敛行为 + +- 409（不在执行中）→ 评估已被取消或已提交过报告，停止并不重试。 +- 404（评估不存在）→ 跳过。 +- 422（报告校验失败）→ 按响应的字段错误修正报告后重新提交，这是唯一允许重试的情况。 + +## 汇报要求 + +提交成功后向用户汇报：评估名称、各维度得分、高严重度发现摘要（一句话一条）、优先改进建议，并提示可在平台「智能评估 → 报告页」查看完整报告与 Markdown 导出。 + +请将 、 等占位符替换为实际值。 diff --git a/backend/plugins/openclaw/skills/agenteval-intelligent-evaluator/SKILL.md b/backend/plugins/openclaw/skills/agenteval-intelligent-evaluator/SKILL.md new file mode 100644 index 0000000..3304de5 --- /dev/null +++ b/backend/plugins/openclaw/skills/agenteval-intelligent-evaluator/SKILL.md @@ -0,0 +1,109 @@ +--- +name: agenteval-intelligent-evaluator +description: 智能评估评估者：按粗计划的时间分布自唤醒，扮演虚拟用户执行会话并提交会话结论 +--- + +你是智能评估的评估者，通过自身 cron 机制周期性自唤醒。每次唤醒执行一个节拍：找到执行中的评估 → 按时间分布派发到期会话 → 以虚拟用户身份对话 → 关闭并提交结论。 +所有操作必须走 AgentEvalTool 标准 HTTP API（禁止直接调 CLI 或操作数据库）。 + +平台可能启用了 API Key 鉴权。每次执行命令前先读取密钥（文件不存在则为空，不影响未启用鉴权的环境）： + +```bash +KEY=$(cat ~/.openclaw/agenteval-api-key 2>/dev/null) +``` + +以下所有 curl 命令都必须带 `-H "X-API-Key: $KEY"`。 + +## 第一步：找到执行中的评估 + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals | python3 -m json.tool +``` + +筛出 `status == "executing"` 的评估。没有则本节拍结束。 + +## 第二步：对账——哪些会话到期、哪些还没建 + +对每个执行中的评估，读取详情与会话列表： + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals/ | python3 -m json.tool +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals//sessions | python3 -m json.tool +``` + +- 模拟时钟 = 当前时间 − `started_at`，窗口长度为 `time_window_hours`。`plan.time_distribution` 的 `time_slot`（如 `8-10h`）是相对窗口起点的偏移区间：区间起点 ≤ 模拟时钟的时段即为「到期」。 +- 对账方式：会话的 `persona.time_slot` 字段记录了它属于哪个时段（见下），据此统计每个时段已建会话数，与 `sessions` 配额相减得到欠账。 +- 到期的欠账本节拍补建；未到期的不要提前。窗口已走完仍有欠账时尽快补齐（时间窗口是模拟约束，不是硬截止）。 + +## 第三步：创建会话 + +persona 与 goal 必须取自 `plan.virtual_users`（可按时段情境微调，但人设底色不变），并在 persona 中写入 `time_slot` 与 `scenario` 留痕： + +```bash +curl -s -X POST http://agenteval:8000/api/intelligent-evals//sessions \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "persona": {"name": "<人设名>", "background": "...", "personality": "...", "time_slot": "<所属时段>", "scenario": "<时段情境>"}, + "goal": "<该虚拟用户的目标>", + "dimension": "<本会话主测维度>" + }' +``` + +响应中的 `id` 即 session_id，后续所有步骤都要用它。 + +## 第四步：驱动会话对话 + +以 persona 的身份向被评对象推进 goal，每轮发送一条用户消息，响应同步返回对方回复： + +```bash +curl -s -X POST http://agenteval:8000/api/intelligent-evals//sessions//messages \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{"content": "<本轮用户消息>"}' +``` + +响应为 `{"reply": "...", "latency_ms": 1234, "turn_count": 3}`。 + +- 演得像：按人设的耐心程度与语气说话，会追问、会跑题再拉回来，不要像测试脚本。 +- 根据 `reply` 决定下一轮：追问、纠正、换路径，直到目标达成或确认走不通。 +- 单会话轮数不得超过 `plan.budget.max_turns_per_session`，接近上限时尽快收尾。 +- 全局预算 `plan.budget.total_max_turns` 是契约，平台第一版不做硬拦截——每个节拍开始前自查累计轮数，超支风险自己控制。 +- 502 表示通道异常；连续两次 502 就提前关闭会话，把异常写进 verdict 备注。 + +## 第五步：关闭会话并提交结论 + +会话必须显式关闭——verdict 是分析师汇总的第一手材料，务必如实： + +```bash +curl -s -X POST http://agenteval:8000/api/intelligent-evals//sessions//close \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "verdict": { + "goal_achieved": true, + "issues": ["<具体问题：事实描述，不写空泛评价>"], + "highlights": ["<做得好的具体表现>"], + "notes": "<整体体验简述；通道异常提前收尾时在此说明>" + } + }' +``` + +- `issues` 与 `highlights` 写具体事实（如「让我重复提供订单号三次」），没有就给空数组。 +- 响应中 `status` 应为 `completed`。 + +## 收到 409 / 404 / 502 的收敛行为 + +409 是平台状态机的明确拒绝，一律停止当前动作、不重试： + +- 创建会话 409（评估不在执行中）→ 评估已被取消或完成，跳过该评估。 +- 发消息 409（会话不在进行中）→ 会话已被收口，跳过。 +- 关闭 409 → 放弃并记录原因。 +- 404（评估或会话不存在）→ 跳过。 +- 502（通道异常）→ 按第四步的规则处理，不要无限重试。 + +## 汇报要求 + +每个节拍结束后向用户汇报：执行中的评估数、本节拍创建的会话数、关闭的会话及其目标达成情况、剩余预算（会话数与轮数）。若评估的所有会话都已关闭，提示 analyst 可以出报告了。 + +请将 、 等占位符替换为实际值。 diff --git a/backend/plugins/openclaw/skills/agenteval-intelligent-planner/SKILL.md b/backend/plugins/openclaw/skills/agenteval-intelligent-planner/SKILL.md new file mode 100644 index 0000000..8470a76 --- /dev/null +++ b/backend/plugins/openclaw/skills/agenteval-intelligent-planner/SKILL.md @@ -0,0 +1,85 @@ +--- +name: agenteval-intelligent-planner +description: 智能评估规划师：读取评估输入，产出粗计划并提交平台审批 +--- + +你是智能评估的规划师。当某个智能评估进入 `planning` 状态（新建或被审批人打回）时，你被唤醒。 +你的唯一职责：读取评估输入 → 产出粗计划 JSON → 调 API 提交。**不要批准、不要执行、不要写报告**——那是 evaluator 与 analyst 的职责。 +所有操作必须走 AgentEvalTool 标准 HTTP API（禁止直接调 CLI 或操作数据库）。 + +平台可能启用了 API Key 鉴权。每次执行命令前先读取密钥（文件不存在则为空，不影响未启用鉴权的环境）： + +```bash +KEY=$(cat ~/.openclaw/agenteval-api-key 2>/dev/null) +``` + +以下所有 curl 命令都必须带 `-H "X-API-Key: $KEY"`。 + +## 第一步：找到待规划的评估 + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals | python3 -m json.tool +``` + +筛出 `status == "planning"` 的评估，逐个处理。 + +## 第二步：读取评估输入 + +```bash +curl -s -H "X-API-Key: $KEY" http://agenteval:8000/api/intelligent-evals/ | python3 -m json.tool +``` + +规划依据是「四件套」： + +- `goal`：这次评估要回答什么问题——粗计划的一切围绕它展开。 +- `seeds`：用户提供的种子数据（真实问题样例、SOP 摘录等），虚拟用户的目标必须从种子衍生。 +- `intent`：重点关注的能力或风险，应体现在 `dimensions` 里。 +- `role_description`：被评对象的角色设定，persona 设计要与它匹配。 + +另有 `time_window_hours`：模拟的服务周期长度，时间分布必须落在窗口内。 + +**区分首规划与重规划**：若 `plan_feedback` 非空，说明上一版计划被打回——`plan_feedback` 是审批人的修改要求，必须逐条回应；`plan` 字段是上一版计划，可在此基础上修订而非推倒重来。 + +## 第三步：产出粗计划并提交 + +```bash +curl -s -X PUT http://agenteval:8000/api/intelligent-evals//plan \ + -H "X-API-Key: $KEY" \ + -H "Content-Type: application/json" \ + -d '{"plan": <粗计划 JSON>}' +``` + +粗计划结构（字段缺一不可）： + +```json +{ + "dimensions": ["<评测维度1>", "<评测维度2>"], + "virtual_users": [ + { "persona": { "name": "<人设名>", "background": "...", "personality": "...", "patience": "low" }, "goal": "<该虚拟用户要完成的事>" } + ], + "time_distribution": [ + { "time_slot": "0-2h", "sessions": 1, "scenario": "<该时段的情境说明>" } + ], + "estimated_sessions": 5, + "budget": { "max_turns_per_session": 12, "total_max_turns": 60 }, + "completion_criteria": "<什么情况下可以出报告>" +} +``` + +规划原则： + +- `time_distribution` 的 `time_slot` 是相对窗口起点的偏移区间（如 24h 窗口里的 `8-10h`），所有区间必须落在 `time_window_hours` 内；`sessions` 之和等于 `estimated_sessions`。 +- 时段设计要符合服务常识：早高峰咨询多、午间冷清、晚间投诉多——不要把所有会话堆在同一时段。 +- 预算就是契约：评估者会严格按 `budget` 执行，平台第一版不做硬拦截，超支是规划师的责任。 +- 响应中的 `status` 应变为 `pending_approval`。 + +## 收到 409 / 404 的收敛行为 + +- 409（不在 planning 状态）→ 说明评估已被批准、取消或已被其他实例处理，停止并记录，不重试。 +- 404（评估不存在）→ 跳过。 + +## 汇报要求 + +每完成一个规划，向用户汇报：评估名称、是否重规划（如是，复述打回反馈与你的应对）、维度列表、预估会话数、预算。提醒用户去平台审批——批准前评估不会执行。 + +请将 等占位符替换为实际值。