clawguard-eval

name	clawguard-eval
description	ClawGuard v4 — OpenClaw 插件完整评测框架。自动编排 6 步流水线： extract → probe → profile → evaluate → certify → report， 输出三大类（安全合规·功能质量·性能开销）× 子维度评测报告。 触发词：帮我评测、clawguard eval、evaluate plugin、插件评测、认证插件、 plugin certification、run clawguard、clawguard 评测、评测一下。 不适用于：纯代码审查（非 OpenClaw 插件）、一般软件测试。

ClawGuard v4 — 插件评测编排

工作原理

Agent 是调度员，不打分。所有评分由 CLI 确定性计算完成：

exec: clawguard extract   → plugin-data.json     （静态分析：安全/规范/代码质量原始信号）
exec: clawguard probe     → probe-report.json    （动态探针：FUNC/STABLE/HOOK/CONTEXT）
exec: clawguard profile   → profile-data         （性能剖析：FOOTPRINT token 统计）
tool: clawguard_evaluate  → eval-report.json     （A/B评测：VALUE/E2E_IMPACT）
exec: clawguard certify   → certification.json   （v4三大类独立评分）
agent: 读取 clawguard-report Skill → report.md   （开发者可读报告）

v4 评分体系

三大类独立评分，各 0-100：

Safety & Compliance（安全合规）: SEC(40%) · COMPLIANCE(40%) · QUALITY(20%)
Functional Quality（功能质量）: FUNC(40%) · STABLE(30%) · VALUE(30%)
Performance（性能开销）: FOOTPRINT(30%) · CONTEXT(20%) · HOOK_OVERHEAD(20%) · E2E_IMPACT(15%) · TOKEN_COST(15%)

COMPLIANCE 使用 CAP 机制：required 工具 > 5 个会降低上限（每超出 1 个 cap -5，最低 20）。

进度输出规范

每完成一步，立即向用户输出进度，不等全部完成再汇报：

⏳ Step 1/6: Extract 进行中...
✅ Step 1/6: Extract 完成 — {fileCount} 文件 / {vulns} 漏洞 / lethalTrifecta={bool}

⏳ Step 2/6: Probe 进行中...
✅ Step 2/6: Probe 完成 — FUNC={n} STABLE={n} HOOK={n} CONTEXT={n|N/A}

⏳ Step 3/6: Profile 进行中...
✅ Step 3/6: Profile 完成 — {tokens} tokens / {ms}ms

⏳ Step 4/6: Evaluate 开始（共 N 个用例，逐个执行）
  ▶ Task 1/N: "{task_id}" 执行中...
  ✅ Task 1/N: "{task_id}" — contracts X/Y passed, baseline={n}ms, plugin={n}ms
  ...（每个用例完成后立即输出）
✅ Step 4/6: Evaluate 完成 — VALUE={n} E2E_IMPACT={raw}%

⏳ Step 5/6: Certify 进行中...
✅ Step 5/6: Certify 完成
             Safety & Compliance（安全合规）= {n}
             Functional Quality（功能质量）= {n}
             Performance（性能开销）= {n}

⏳ Step 6/6: Report 生成中...
✅ Step 6/6: 评测完成！

进度数据来源：

• Extract：fileCount、knownVulnerabilities.length、lethalTrifecta
• Probe：dimensions.FUNC、STABLE、HOOK_OVERHEAD、CONTEXT
• Profile：footprint.totalInjection、profilingTimeMs
• Evaluate：dimensions.VALUE、E2E_IMPACT（原始百分比）
• Certify：categories（safetyCompliance / functionalQuality / performance 三类独立分）

如 CLI 命令失败，输出完整错误信息，说明哪步失败，可继续的步骤继续执行。

前置检查

1. CLI 路径（按顺序尝试）：

   • clawguard（全局命令，已 npm link）
   • node /root/claw_guard/cli/dist/cli.js
   • 找不到 → 告知用户：cd /root/claw_guard/cli && npm run build && npm link

2. 插件路径：

   • 绝对路径 → 直接用
   • 插件名（如 lossless-claw）→ 在 /root/.openclaw/extensions/ 下查找
   • 未指定 → 询问用户

3. Gateway 登记状态（关键——Step 2 real-probe 和 Step 4 Evaluate 都依赖此项）：

   • 检查 ~/.openclaw/openclaw.json 中 plugins.allow 是否同时包含：
     • 目标插件 <plugin-id>
     • clawguard-bench（Step 4 需要）
     • clawguard-probe（Step 2 real 模式需要；mock 模式不需要）
   • 全部登记 → 继续
   • 有缺失 → 告知用户并等确认，不要自动改用户配置：

     ⚠️  以下插件未在 Gateway 登记：
       - <plugin-id>
       - clawguard-probe（Step 2 --real 模式需要）
     可以先运行：
       clawguard install <plugin-path> --dry-run                         # 先看计划
       clawguard install <plugin-path> --yes                             # 确认后安装
       clawguard install /root/claw_guard/plugin-probe --yes             # 如需真 Gateway 探针
     安装后需要重启 Gateway（openclaw gateway stop && openclaw gateway run --force）。
     是否跳过 Step 4 Evaluate 继续？(VALUE/E2E_IMPACT 会标记 N/A)
     

   • 用户选择跳过 → 仍按 5 步继续，Step 4 标记 N/A（Step 2 回退 mock 模式）
   • 用户选择安装 → 引导执行 install，然后提示用户重启 Gateway再继续

4. Gateway 运行状态（关键——Step 2 real 模式 + Step 4 都需要）：

   • openclaw gateway call health --json --timeout 3000 检查
   • 未运行 → 告知用户：openclaw gateway run --force（后台启动），或者让 clawguard probe --real 自动临时启动并在结束时自动停掉
   • 运行中 → 记录，在必要时不要重启它

5. Fixture 文件：

   • 查找 /root/claw_guard/plugin-bench/fixtures/<plugin-id>.json
   • 不存在 → 提示用户用 clawguard genfix <plugin-path> 自动生成一份起手样板，然后让用户按需改；Step 4 才能用。

执行流程

PLUGIN_PATH=<插件绝对路径>
PLUGIN_ID=$(basename $PLUGIN_PATH)
OUT=/tmp/clawguard-eval-$(date +%s)
CLI="clawguard"
mkdir -p $OUT

Step 1：Extract

$CLI extract "$PLUGIN_PATH" -o "$OUT/extract"
STATIC="$OUT/extract/plugin-data.json"

进度输出示例：✅ Step 1/6: Extract 完成 — {fileCount} 文件 / {vulns} 漏洞 / lethalTrifecta={bool}

Step 2：Probe

推荐：--real 模式（直接调用 Gateway 里真实的 tool.execute()）。需要 clawguard-probe 已登记 + Gateway 已运行。

$CLI probe "$PLUGIN_PATH" --real -o "$OUT/probe"
DYNAMIC="$OUT/probe/probe-report.json"

如果 Gateway 未运行 / clawguard-probe 未登记，回退 mock 模式：

$CLI probe "$PLUGIN_PATH" -o "$OUT/probe"    # mock 模式（FUNC/STABLE 对 native 依赖插件不准）

模式区别（⚠️ 报告里务必标清哪种模式）：

• --real：真 Gateway，tool.execute 真跑 native 依赖。FUNC/STABLE 可信。
• 无 --real：mock runtime，native 依赖加载会走降级路径。FUNC/STABLE 只反映"写法正确"，不反映"真能跑"。

进度输出示例：

• real 模式：✅ Step 2/6: Probe [real] 完成 — FUNC={n} STABLE={n}（真 Gateway 下实测）
• mock 模式：⚠️ Step 2/6: Probe [mock] 完成 — FUNC={n} STABLE={n}（mock runtime，native 依赖插件结果不可信）

Step 3：Profile

$CLI profile "$PLUGIN_PATH" -o "$OUT/profile-data"
PROFILE="$OUT/profile-data"

进度输出示例：✅ Step 3/6: Profile 完成 — {tokens} tokens / {ms}ms

Step 4：Evaluate（逐用例执行，实时展示进度）

Fixture 自动生成（不存在时）：

1. 读取 $STATIC 的 apiUsage.registeredCapabilities，取前 3 个工具为 targetTools
2. 根据 manifest.raw.kind 生成对应场景任务（详见 references/fixture-format.md）
3. 保存到 /root/claw_guard/plugin-bench/fixtures/<plugin-id>.json，告知用户可手动调整

执行流程（逐个用例，每完成一个立即向用户汇报）：

1. 先读取 fixture 文件获取总任务数
2. 对每个任务，调用 clawguard_evaluate 工具的 单任务模式（传入 task_index）
3. 每个任务完成后，立即向用户输出进度
4. 全部完成后，汇总 VALUE 和 E2E_IMPACT

# 1. 读取 fixture 获取任务列表
exec: cat /root/claw_guard/plugin-bench/fixtures/<plugin-id>.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d[tasks]))"

# 2. 逐个用例执行（每个都是独立的 tool call）
for i in range(task_count):
    tool: clawguard_evaluate
    params:
      fixture_path: /root/claw_guard/plugin-bench/fixtures/<plugin-id>.json
      task_index:   {i}
      timeout_ms:   90000
    
    # 调用完成后立即输出给用户：
    # ✅ Task {i+1}/{total}: "{task_id}" — contracts {passed}/{total} passed
    #    baseline={N}ms, plugin={N}ms, 工具调用: {tool_names}

# 3. 汇总 VALUE 和 E2E_IMPACT
# VALUE = 所有任务合同通过率 × 100
# E2E_IMPACT = 所有任务 (plugin_ms - baseline_ms) / baseline_ms 的平均百分比

进度输出示例：

⏳ Step 4/6: Evaluate 开始（共 3 个用例，逐个执行 A/B 测试）

  ▶ Task 1/3: "search_weather" 执行中（A/B 各跑 3 次，约 1-3 分钟）...
  ✅ Task 1/3: "search_weather" — contracts 2/2 passed
     baseline=12345ms, plugin=8234ms, 工具调用: [web_search, weather_tool]

  ▶ Task 2/3: "create_event" 执行中...
  ✅ Task 2/3: "create_event" — contracts 1/1 passed
     baseline=9876ms, plugin=7654ms, 工具调用: [calendar_create]

  ▶ Task 3/3: "summarize_doc" 执行中...
  ✅ Task 3/3: "summarize_doc" — contracts 3/3 passed
     baseline=15432ms, plugin=11234ms, 工具调用: [doc_fetch, summarize]

✅ Step 4/6: Evaluate 完成 — VALUE=100, E2E_IMPACT=-25.3%

汇总后写入 eval-report.json：

# 用 exec 将汇总结果写入文件（供 certify 使用）
cat > $OUT/eval/eval-report.json << EOJSON
{
  "pluginId": "<plugin-id>",
  "timestamp": "<ISO时间>",
  "tasks": [<各任务的完整结果>],
  "dimensions": {
    "VALUE": <合同通过率 × 100>,
    "E2E_IMPACT": <平均延迟差异百分比>
  }
}
EOJSON

Step 5：Certify

$CLI certify \
  --static   "$STATIC" \
  --dynamic  "$DYNAMIC" \
  --profile  "$PROFILE" \
  --evaluate "$OUT/eval/eval-report.json" \
  --output   "$OUT/cert"
CERT=$(find "$OUT/cert" -name "certification.json" | head -1)

注意：--evaluate 是独立参数，不能省略，否则 VALUE/E2E_IMPACT 为 N/A。

进度输出示例：

✅ Step 5/6: Certify 完成
             Safety & Compliance（安全合规）= {n}
             Functional Quality（功能质量）= {n}
             Performance（性能开销）= {n}

Step 6：Report

读取 clawguard-report Skill，按模板生成 report.md。不调用 CLI 命令。

步骤：

1. 读取 clawguard-report Skill 的指导说明
2. 读取 certification.json + plugin-data.json（必需）
3. 可选读取 probe-report.json + profile-data
4. 按 Skill 中的模板和扣分项说明规范，生成 $OUT/report.md

进度输出示例：✅ Step 6/6: 评测完成！

错误处理

错误	处理
CLI 找不到	告知 build 命令，停止
插件路径不存在	询问正确路径
extract 失败	停止（后续步骤依赖此产出）
probe / profile 失败	告知，继续（certify 对缺失维度标 N/A）
evaluate 超时/失败	告知，继续 certify（VALUE/E2E 标 N/A）
certify 失败	显示完整错误
Static Only 警告	告知功能质量/性能开销无数据，建议补跑 probe + profile