Claw Eval

基于 PinchBench 风格 Markdown 任务定义 + 可插拔适配器系统的 Agent 评测框架。

快速开始

# 创建虚拟环境（需要 Python 3.11+）
python3.12 -m venv .venv
source .venv/bin/activate

# 安装（含开发依赖）
pip install -e ".[dev]"

# 校验所有任务定义
claw-eval validate

# 仅运行 P0 冒烟测试
claw-eval run --priority P0

# 使用 DryRun 适配器运行全部任务
claw-eval run --adapter dryrun

# 接入 DeskClaw Gateway 运行评测（指定模型）
claw-eval run --adapter deskclaw --model step-3.5-flash

# 接入 OpenClaw 运行评测
claw-eval run --adapter openclaw

# 从 JSON 结果生成 Markdown 报告
claw-eval report results/latest.json

# 对比多次评测结果
claw-eval compare results/deskclaw_minimax-m2.7_*.json results/deskclaw_step-3.5-flash_*.json

任务格式

任务以 Markdown 文件定义，YAML frontmatter 携带元数据。 每个任务自包含：prompt、workspace 预置文件、评分逻辑、LLM 评判标准，全在一个文件里。

---
id: task_example
name: 示例任务
category: basic
grading_type: hybrid
timeout_seconds: 120
grading_weights:
  automated: 0.4
  llm_judge: 0.6
priority: P0
tags: [smoke, readonly]
---

## Prompt
（发送给 Agent 的指令）

## Automated Checks
```python
def grade(transcript, workspace_path):
    return {"criterion": 1.0}

LLM Judge Rubric

Criterion 1: Quality (Weight: 50%)

Score 1.0: 完美完成 ...

### 扩展字段

| 字段 | 用途 |
|------|------|
| `gate: true` | Preflight 门禁，失败则跳过后续任务 |
| `multi_turn: true` + `turns` | 单会话内多轮对话 |
| `multi_session: true` + `sessions` | 跨会话记忆测试 |
| `routing_check` | 工具路由准确性校验 |
| `dynamic_fixtures` | 运行时动态数据注入 |
| `priority` | P0（冒烟）/ P1（每日）/ P2（完整） |
| `tags` | smoke / readonly / destructive / slow / requires_auth / requires_network |

## 任务总览

| 类别 | 数量 | 说明 |
|------|------|------|
| simple | 4 | 单轮快速任务：存活检查、时间感知、超时中断、技能缺失降级 |
| complex | 21 | 多步复杂任务：写作、研究、数据分析、文件操作、多轮对话、工具链调用、MCP 集成 |
| **合计** | **25** | |

## 架构

eval-framework/ ├── src/claw_eval/ │ ├── cli.py # CLI 入口：run / validate / report / compare │ ├── core/ │ │ ├── task_loader.py # 解析 Markdown + YAML frontmatter → Task 对象 │ │ ├── runner.py # 任务执行（单轮 / 多轮 / 多会话 / gate 门禁） │ │ ├── grader.py # 提取并执行嵌入的 Python grade 函数 │ │ ├── llm_judge.py # LLM-as-Judge（Claude 评分 + Rubric 解析） │ │ ├── scorer.py # 聚合 automated + judge 分数 + speed/cost │ │ └── reporter.py # 生成 Markdown / JSON 报告 + 对比报告 │ ├── adapters/ │ │ ├── base.py # ClawAdapter 抽象接口 + 注册表 │ │ ├── openclaw.py # OpenClaw 适配器 + DryRun 测试适配器 │ │ └── deskclaw.py # DeskClaw Gateway HTTP 适配器（主力） │ └── utils/ │ ├── transcript.py # Transcript JSONL 解析工具 │ ├── token_estimator.py # Token 用量估算 │ └── fixtures.py # 动态数据注入（API / 命令 / 文件 → 占位符替换） ├── tasks/ # 25 个任务定义（simple 4 + complex 21） ├── results/ # 评测结果（JSON + Markdown 报告 + 对比报告） ├── docs/ # 使用指南（评测指南、跨模型对比、跨框架对比） ├── config/ │ ├── models.yaml # 模型档位（flagship / standard / economy / opensource） │ └── profiles.yaml # 评分权重配置（default / security-first / cost-optimized） ├── docker/Dockerfile # 可选 Docker 隔离环境 └── tests/ # pytest 测试套件

## CLI 命令

```bash
# 运行评测
claw-eval run [OPTIONS]
  --adapter TEXT        适配器名称（deskclaw / openclaw / dryrun）
  --gateway-url TEXT    DeskClaw Gateway 地址（默认 http://127.0.0.1:18790）
  --agent-id TEXT       OpenClaw Agent ID（默认 main）
  --model TEXT          覆盖适配器默认模型
  --tasks-dir PATH      任务目录（默认 tasks/）
  --results-dir PATH    结果输出目录（默认 results/）
  --priority TEXT       按优先级过滤（P0 / P0,P1 / P0,P1,P2）
  --tags TEXT           按标签过滤（逗号分隔）
  --skip-tags TEXT      排除指定标签（逗号分隔）
  --task TEXT           按任务 ID 过滤（逗号分隔）
  --skip-slow           跳过 slow 标签任务
  --category TEXT       按类别过滤
  --judge-model TEXT    覆盖 Judge 模型（默认 claude-opus-4.6）
  --skip-judge          跳过 LLM Judge 评分
  -v                    详细日志

# 校验任务定义
claw-eval validate [OPTIONS]
  --tasks-dir PATH      任务目录
  -v                    显示每个任务的校验详情

# 生成报告
claw-eval report INPUT_PATH [OPTIONS]
  --output PATH         输出 Markdown 路径

# 对比多次评测结果
claw-eval compare RESULT_FILE1 RESULT_FILE2 [RESULT_FILE3 ...] [OPTIONS]
  --output PATH         输出对比报告路径
  --threshold FLOAT     只显示分差 >= 阈值的任务（默认 0.2）

适配器

内置适配器

适配器	说明
deskclaw	对接 DeskClaw Gateway HTTP API，支持本地桌面 Agent 评测（主力适配器）
openclaw	对接 OpenClaw 云端 Agent
dryrun	不调用任何 Agent，返回模拟结果，用于流程验证

自定义适配器

实现 ClawAdapter 接口即可接入新的 Agent 框架：

from claw_eval.adapters.base import ClawAdapter, register_adapter

class MyAdapter(ClawAdapter):
    def setup(self, task_config): ...
    def run(self, prompt, workspace, timeout) -> dict: ...
    def teardown(self): ...

register_adapter("my_framework", MyAdapter)

评分体系

• Automated Checks: 嵌入任务的 Python grade() 函数，检查文件、transcript、工具调用
• LLM Judge: Claude 按 Rubric 评分，5 级分数（1.0 / 0.75 / 0.5 / 0.25 / 0.0）
• Hybrid: 按 grading_weights 加权组合 automated + judge
• 三维指标: 成功率（Success Rate）+ 速度（Speed）+ 成本（Cost）