106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
# OpenClaw 插件 for AgentEvalTool
|
||
|
||
本目录提供 OpenClaw 调用 AgentEvalTool 的标准接入方式，使 OpenClaw（AI 助手）能够自闭环完成评测。
|
||
|
||
## 设计原则
|
||
|
||
- AgentEvalTool 负责：
|
||
- 评测对象管理
|
||
- 评测场景管理
|
||
- 评测执行与原始数据收集
|
||
- 评估分析与报告生成
|
||
- OpenClaw 负责：
|
||
- 评测策略编排（选择对象、场景、触发时机）
|
||
- 定时调度（OpenClaw 自身的 cron + skill 机制）
|
||
- 结果通知与后续动作
|
||
|
||
## 唯一标准接入方式：HTTP API
|
||
|
||
**所有 OpenClaw 触发的评测必须走 AgentEvalTool 的 HTTP API**（`POST /api/runs` 等），
|
||
并在启动评测时携带 `"triggered_by": "ai_assistant"`，以便平台区分手动触发与 AI 助手触发。
|
||
|
||
> ⚠️ 禁止在 OpenClaw 中通过 subprocess 调用 `agenteval` CLI。
|
||
> CLI 直接写入其运行环境下的本地 SQLite（路径硬编码），与 Web 后台的数据库不共享，
|
||
> 会导致评测记录"消失"——Web 页面永远查不到。CLI 仅用于开发者在 agenteval
|
||
> 服务同一环境下的手工调试。
|
||
|
||
### 方式一：agenteval-run 技能（推荐）
|
||
|
||
`skills/agenteval-run/SKILL.md` 是标准技能文件，指导 AI 助手用 `curl` 走 API 全流程
|
||
（列对象/场景 → 启动评测 → 轮询状态 → 取报告）。
|
||
|
||
部署脚本（`scripts/deploy-t480.sh`）会自动把它同步到 OpenClaw 工作区：
|
||
`data/openclaw/workspace/skills/agenteval-run/SKILL.md`。
|
||
|
||
### 方式二：agenteval-patrol 巡检技能（探索式评测，v0.9）
|
||
|
||
`skills/agenteval-patrol/SKILL.md` 指导 AI 助手作为常驻巡检代理完成探索闭环：
|
||
调巡检 API（`GET /api/exploration/patrol`）→ 研判新结果与预算余量 → 决定是否派发
|
||
探索会话 → 以虚拟用户身份驱动会话对话 → 提交体验记录关闭会话。说明书内含收到
|
||
409 时的收敛行为与衍生变体的种子回溯（`seed_ref`）要求。
|
||
|
||
部署脚本会把 `backend/plugins/openclaw/skills/` 下的每个技能同步到
|
||
`data/openclaw/workspace/skills/<skill-name>/SKILL.md`。
|
||
|
||
### 方式三：Python Skill 封装
|
||
|
||
参考 `agenteval_skill.py`（httpx 调 API），在 OpenClaw 中注册技能时传入配置：
|
||
|
||
```json
|
||
{
|
||
"api_base_url": "http://agenteval:8000",
|
||
"api_key": "<可选，对应 AGENTEVAL_API_KEY>",
|
||
"target_id": "<target-id>",
|
||
"scenario_id": "<scenario-id>",
|
||
"report_format": "json"
|
||
}
|
||
```
|
||
|
||
## OpenClaw 定时评测示例
|
||
|
||
OpenClaw 的 cron 配置（具体格式以 OpenClaw 平台为准）：
|
||
|
||
```yaml
|
||
skill: agenteval_skill
|
||
schedule: "0 9 * * *" # 每天早上 9 点执行
|
||
config:
|
||
api_base_url: "http://agenteval:8000"
|
||
target_id: "<target-id>"
|
||
scenario_id: "<scenario-id>"
|
||
report_format: "json"
|
||
```
|
||
|
||
### 常驻巡检作业（探索式评测）
|
||
|
||
巡检代理需注册为全局常驻作业，默认节拍 1 小时；调度状态由 OpenClaw 自身持久化，
|
||
重启后不丢：
|
||
|
||
```yaml
|
||
skill: agenteval-patrol
|
||
schedule: "0 * * * *" # 每小时整点巡检一次
|
||
config:
|
||
api_base_url: "http://agenteval:8000"
|
||
```
|
||
|
||
巡检 API 自带水位（`last_patrolled_at`），每个节拍只报增量结果，重复触发不会
|
||
重复上报；预算与间隔护栏在服务端强制执行，代理收到 409 即收敛。
|
||
|
||
## API 速查
|
||
|
||
| 操作 | 请求 |
|
||
|---|---|
|
||
| 启动评测 | `POST /api/runs` body: `{"target_id", "scenario_id", "triggered_by": "ai_assistant"}` |
|
||
| 查询状态 | `GET /api/runs/{run_id}`（轮询至 completed/failed） |
|
||
| 获取报告 | `GET /api/reports/{run_id}` |
|
||
| 巡检探索 | `GET /api/exploration/patrol`（无参数，报增量新结果与预算余量） |
|
||
| 派发探索会话 | `POST /api/exploration/sessions` body: `{"campaign_id", "persona", "goal", "seed_ref?", "triggered_by"}` |
|
||
| 驱动会话对话 | `POST /api/exploration/sessions/{session_id}/messages` body: `{"content"}` |
|
||
| 提交体验记录 | `POST /api/exploration/sessions/{session_id}/close` body: `{"experience"}` |
|
||
|
||
如果平台设置了 `AGENTEVAL_API_KEY`，所有请求需带 `X-API-Key` 头。
|
||
|
||
## 扩展建议
|
||
|
||
- 可以在 OpenClaw Skill 中根据报告结果触发告警、创建工单或通知相关人员。
|
||
- 可以将报告推送到企业微信、钉钉、邮件等通道。
|