32—AI Skill 测评不是“跑一下”：从环境预检到 PASS 门禁的完整作战图

很多人以为 AI Skill 测评就是"跑一下用例，看通过率"。

真正危险的地方在于：AI 会解释、会补锅、会自我合理化。工具没调成功，它可能说"已完成"；数据没查到，它可能根据规则猜一个结果；执行 Agent 自己评价自己，往往会把问题讲成"基本符合"。

所以 SkillSentry 的目标不是让 AI 说自己做对了，而是用 transcript、工具调用、断言、独立 Grader、baseline 对照和发布门禁 证明它真的做对了。

上一篇解决的是测评前的环境可信问题。环境稳定之后，读者还需要一张完整作战图：从你输入 测评 xxx 开始，到报告给出 PASS / CONDITIONAL PASS / FAIL，中间到底发生了什么？

这篇不是讲理念，而是给第一次实操的人一张完整路线图。你不需要一次记住所有分支，只需要知道：

每一步做什么。
失败时先看哪里。
什么时候继续，什么时候停下来修。
最终 PASS / CONDITIONAL PASS / FAIL 是怎么得出的。

整条链路背后只有一个原则：不让 AI 自证清白。独立 Grader、文件系统隔离、transcript 双分离格式、断言强度分级、并行对照组，都是为了让测评结论来自系统原始证据，而不是执行 Agent 的自我描述。

先看全流程地图

一次完整测评的主干流程如下：

安装
  └─ 定位被测 Skill
       └─ MCP 工具预检（mcp_based 类型才有）
            └─ 智能工作流推断（MD5缓存对比）
                 └─ cases：用例设计
                      └─ executor：双侧并行执行
                           └─ grader-report：断言评审 + 汇总报告 + 发布建议
                                └─ publish：交付报告与发布判断

整篇文章按这条主干展开。每个节点讲两件事：做什么 和 遇到什么岔路时怎么选。

新手默认路径：先别纠结，按这 4 步走

如果你是第一次跑 SkillSentry，不需要先理解所有分支，按这个默认路径就够：

第一次测：测评 <Skill名>             → 让系统推断 quick / smoke / regression
刚改完规则：smoke 测评 <Skill名>     → 先确认核心路径没崩
发布前：standard/full 测评 <Skill名> → 跑完整链路和发布门禁
失败排查：diagnostics → transcript → grading → report

记住一个判断：

能从 transcript 和 grading 找到证据的失败，才值得改 Skill；找不到证据的失败，先查环境、数据、MCP、fixture 或 Grader。

---

一、安装：10 分钟内完成

获取 SkillSentry 发布包后进入目录
cd SkillSentry
./install.sh       # macOS / Linux / WSL
.\install.ps1      # Windows PowerShell

脚本会自动检测两个目录是否存在：

• <本地助手目录>
• ~/.config/opencode（OpenCode）

两个都有就部署两份，只有一个就只部署一份。部署内容包括 SkillSentry 主编排器 + 当前能力（sentry-static / cases / executor / grader-report / sentry-report）。其中 sentry-report 是已有 grading 后重新出报告的特殊入口，不是主流程里的评分步骤。

验证安装 ：部署完成后，在 本地编码助手环境 里说 验证 SkillSentry 安装，会逐一列出每个工具的状态，有缺失的会标红。

支持的运行环境：

平台	说明
本地编码助手	主要开发和测试平台，终端交互
OpenCode	CLI/IDE 环境，install 脚本自动部署
OpenClaw（飞书/龙虾）	飞书消息触发，每个关键节点自动推送进度，完成后发摘要卡片

OpenClaw 模式支持简化语法：测评 my-skill quick 自动，一条消息完成模式选择和用例确认，全程不需要人盯着。

---

二、被测 Skill 的准备

目录结构

<skills-root>/
├── SkillSentry/
│   ├── inputs/<Skill名>/          ← 外部用例文件 + 缓存（跨次复用）
│   └── sessions/<Skill名>/<日期>/ ← 每次测评独立目录
│
└── em-reimbursement-v3/           ← 被测 Skill（示例）
    └── SKILL.md

可选：放入外部用例（Golden Set）

在 inputs/<Skill名>/ 下放 *.cases.md 文件，这些是你认为最重要、必须每次都测的场景：

# 正常差旅报销流程
> 我上周去北京出差，帮我报一下差旅费，发票在附件里

- [ ] saveExpenseDoc 调用参数 docStatus="10"
- [ ] 输出包含详情链接，不含字面占位符 {fdId}

格式规则：一级标题 = 用例名称，引用块 = 用户 prompt，勾选列表 = 预期断言。这些用例被标记为 golden，优先级高于 AI 自动生成的，AI 只补你没有覆盖的路径。

---

三、三种使用姿势

在进入流程细节之前，先说清楚三种调用方式，这决定了后面哪些步骤会执行：

姿势	怎么说	适合什么时候	走哪些步骤
自动推断	测评 em-reimbursement-v3	最常用，系统自己判断工作流	完整流程，工作流由 MD5 缓存推断
单工具	检查结构 em-reimbursement-v3	只想做某一步	只跑指定工具，30秒~10分钟
指定深度	smoke 测评 em-reimbursement-v3	明确知道要跑多深	按指定工作流走

单工具快速路径汇总：

说什么	运行工具	时间	无需 MCP
检查结构 <Skill名> / static	sentry-static（静态检查）	~30 秒	✅
测触发率 <Skill名>	sentry-static（触发率检查）	~2 分钟	✅
check <Skill名>	sentry-static（静态检查 + 触发检查）	~2.5 分钟	✅
只设计用例	cases	~5-10 分钟	✅
用现有用例跑	executor → grader-report	~10-15 分钟	❌
已有评分重新出报告	sentry-report	~1 分钟	✅

---

四、完整流程：每个节点的细节与分支

Step 0：识别运行环境

来自飞书/Telegram？
  → 是：openclaw 模式，每个关键节点自动推送进度
  → 否：本地 CLI / 兼容 CLI 模式，正常终端输出

验证安装 是特殊命令，识别后直接执行，跳过后续所有步骤。

---

Step 1：定位被测 Skill + 识别类型

查找顺序：

1. 用户给了路径 → 直接用
2. 只给了名字 → 先找 <skills-root>/<名>/SKILL.md，再找 ~/.config/opencode/skills/<名>/SKILL.md
3. 「测评这个」→ 当前工作目录下的 SKILL.md

找不到时：不报错退出，输出三条排查引导（名字拼写 / 路径位置 / 直接提供完整路径）。

Skill 类型自动识别：

类型	判断依据	执行策略
mcp_based	SKILL.md 中有 MCP 工具引用	调用真实工具，需要 MCP Server 在线
code_execution	描述了 Bash/脚本执行	执行真实命令
text_generation	其他情况	纯文本模式，无需外部依赖

---

Step 1.5：MCP 工具可用性预检（仅 mcp_based）

text_generation 和 code_execution 直接跳过这一步。

预检做什么：列出 SKILL.md 里引用的所有工具名，和当前可用工具列表对比，输出差异。

分支一：全部可用 → 继续执行。

分支二：有工具不可用 → 给用户两个选项：

⚠️ 以下工具当前不可用：mi_expense_cn_claw_test

[继续] 强制执行
       → transcript 中工具调用会失败
       → Skill 会用推断填补工具应返回的数据
       → 测出来的通过率是虚高的假阳性
       → 报告标注「MCP 推断模式，结论不可作为发布依据」

[中止] 先配好环境再测

这个分支非常重要。「Skill 工具不可用时静默降级，用推断填补工具返回的数据」是假阳性最常见的来源------你以为测过了，其实测的是模型的想象力，不是真实的工具调用链路。

---

Step 2：智能工作流推断

系统计算被测 SKILL.md 的 MD5，与缓存对比，推断最合适的工作流：

缓存状态	推断工作流	背后逻辑
无 rules.cache.json	quick	首次测评，需要完整流程
hash 不匹配	smoke	Skill 内容有变更，先快速验证核心路径没崩
hash 匹配 + 有 cases.cache.json	regression	规则和用例都没变，直接跑，最省时间
hash 匹配 + 无用例缓存	quick	规则没变但用例还没设计

输出确认提示（必须等用户确认，或 30 秒后自动开始）：

✅ 已找到被测 Skill：em-reimbursement-v3

📊 状态检测：
  规则缓存：命中（hash: 2947f6b0）
  用例缓存：不存在

→ 推断工作流：quick
   原因：规则未变更，但用例缓存不存在，需重新设计
   工具链：cases → case-quality-check → executor → grader-report → publish
   预计时间：8-10 分钟（mcp_based）/ 15-20 分钟（其他）
   Token 预估：~5-10 万

用户可以在这里改口：说 full / smoke / lint / regression 直接切换，不需要重走流程。

---

Step 3：规则缓存

规则是用例设计的原材料，提炼一次有一定开销：

• 缓存命中（hash 匹配） → 直接加载规则列表，跳过提炼，减少 1-2 分钟
• 缓存未命中 → 读 SKILL.md，提炼所有 P1/P2 约束 → 写入 rules.cache.json

缓存文件格式：

{
  "skill_hash": "2947f6b0...",
  "extracted_at": "2026-04-10T...",
  "rules": ["规则1", "规则2", ...]
}

下次 SKILL.md 没有改动，这份规则直接复用。

---

Step 4：cases --- 用例设计

先检查用例缓存 ：cases.cache.json 存在且 hash 匹配时，smoke/quick 自动复用，standard/full 询问是否重新设计。未命中才执行下面的设计流程。

4.1 加载外部用例（Golden Set）

扫描 inputs/<Skill名>/ 下的 *.cases.md，解析出用例名、prompt、断言列表，标记为 source: external, tag: golden，优先级最高。

4.2 AI 补齐未覆盖路径

按模式决定用例数量和覆盖目标：

模式	用例数	覆盖目标	每用例运行次数
smoke	4-5	≥20%，核心路径不崩	1
quick	8-10	≥40%	2
standard	20-25	≥70%	3
full	30-35	≥90%	3

8 类用例类型，E2E 和 happy_path 优先级最高：

优先级	类型	核心价值
★★★	e2e	唯一能发现多条规则同时激活时互相干扰的用例类型
★★★	happy_path	主流程跑通
★★	boundary	边界条件
★★	negative	不该触发时不触发
★★	robustness	工具失败时不崩溃
★	atomic	单步操作，用于失败定位
★	consistency	相同场景多次执行结果一致
★	business_logic	边界规则和业务逻辑验证

4.3 断言强度分级

每条断言必须标注 precision：

强度	precision	定义	计入发布判断
精确断言	exact_match	有具体可验证的字段值/计数/格式	✅ 核心指标
语义断言	semantic	需要语义理解	✅ 辅助参考
存在性断言	existence	只验证存在/不存在	❌ 不计入

自检规则：对每条断言问「没有这个 Skill，这条断言还会通过吗？」如果会，这条断言是无效的，应该升级为 exact_match。

内置告警：existence 断言占比 > 50% 时自动提示「测评有效性存疑」------通过率高但没有区分度，是最常见的虚高来源。

4.4 判断是否需要 without_skill baseline

稳定流程不再按单个用例类型粗暴决定 skip_without_skill，而是先看 Skill 类型和测评模式：

条件	baseline 处理
mcp_based + smoke/quick	默认跳过 without_skill，Delta 记为 N/A
mcp_based + standard/full	默认保留可比较 baseline；单个 eval 不可比时标为 partial 或 N/A
text_generation / code_execution	默认运行 baseline，除非安全或环境约束不允许

负向、安全、鲁棒性用例如果无法形成有意义对照，不要硬算 Delta；保留 with_skill 结果，并把不可比原因写进报告。

输出 ：evals.json（供 executor 使用）+ cases.cache.json（供下次复用）

---

Step 5：executor --- 用例执行

5.1 断点续跑检查

每次启动前先扫描 eval-N/with_skill/outputs/transcript.md 是否存在且非空：

检测到上次执行记录：
  已完成：eval-1, eval-3（共 2 个）
  待执行：eval-2, eval-4（共 2 个）

[跳过已完成，只跑剩余] ← 默认，30 秒后自动选
[全部重跑]

中途断了不需要从头来，重新触发后自动接着跑。

5.2 强制并行执行

每个用例的 with_skill 和 without_skill 必须在同一条消息中同时发出：

❌ 串行（浪费一倍时间）：eval-1 with → 完成 → eval-1 without → ...
✅ 并行：同一消息同时发出 eval-1 with + eval-1 without

quick 模式 mega-batch ：2 次运行直接合并进同一批次，run1 with + run1 without + run2 with + run2 without 四个 subagent 同时启动。两轮时间塌缩为一轮，减少约 6-8 分钟。

工具调用次数上限（防止工具失败时无限重试卡死）：

Skill 类型	with_skill	without_skill
mcp_based	15 steps	8 steps
code_execution	10 steps	6 steps
text_generation	5 steps	5 steps

5.3 without_skill 沙箱隔离（P0 约束）

without_skill 是对照组，必须完全独立：

• 禁止读取 with_skill 目录下任何文件（含 transcript、uploads、中间产物）
• 工具调用达到上限后立即停止并标注
• 执行完必须在 response.md 末尾写沙箱自检：
  • 「是否读取了 with_skill 目录的任何文件？」
  • 「所有结果是否全部由本次独立执行产生？」
• 违规 → Grader 标记该用例结果 INVALID，Δ 失效，需重测

这个设计解决的问题：如果 without_skill 复用了 with_skill 上传的附件，Δ 会虚高------你以为「有 Skill 比没有好很多」，实际上 without_skill 借用了 with_skill 的成果。

5.4 Grader 流水线调度

多批次执行时，Grader 不再等每批执行完才启动：

工作流	Grader 调度方式	减少时间
smoke	同步等待	---
quick / standard / full	后台非阻塞启动	~3-5 分钟

非阻塞模式下：每批 Executor 完成 → 后台启动 Grader → 立即启动下一批 Executor → Grader 完成时收到 task notification → 上下文压缩（每批结果压缩为 ≤1 行摘要）。

进入 grader-report 汇总前有强制等待点 ：检查所有 eval-N/grading.json 或等价评分结果是否就绪，每 30 秒轮询一次，最长等待 10 分钟。超时则跳过未完成的 eval 并告警。

5.5 快速失败检测（仅 quick 模式）

quick 模式在第一批用例完成后，会触发一次快速失败检测，判断是否值得继续跑剩余批次。

机制 ：第一批 Grader 强制同步等待（覆盖非阻塞规则），完成后读取这批所有 eval-N/grading.json 的 authoritative_pass_rate，计算均值：

第一批均值	处理
≥ 20%	静默继续，后续 Grader 恢复非阻塞模式
< 20%	告警 + 选项弹出，30 秒后默认终止

通过率 < 20% 时的输出：

⚠️ 前 [N] 个用例平均通过率 [X]%，Skill 可能存在根本性问题
失败集中在：[列出 fail 最多的断言类型]

选项：
  [继续执行剩余用例]
  [立即终止，查看当前结果] ← 默认，30 秒后自动选择

为什么阈值是 20%：这不是「成绩差」的信号，而是「根本性问题」的信号。前几个核心用例通过率不到 20%，通常意味着主流程根本没有按预期运行------比如 MCP 工具静默失败、Skill 触发条件不对、执行环境异常。这种情况下继续跑只是在产出更多无效数据，不如先终止、看已有报告、修复后重测。

为什么只在 quick 模式触发：smoke 本身就是同步全量执行，自然具备早期信号。standard/full 的目的是深度测评，前几个失败不应该中断------那恰恰是需要看完整报告才能定位问题的场景。

---

5.6 并行度审计

每批完成后自动计算并行率（with_skill 和 without_skill 启动时间差 ≤ 30 秒视为并行）：

并行率	处理
≥ 80%	正常继续
50-80%	下批次额外输出警告
< 50%	暂停，列出串行用例的时间差，询问是否继续

---

Step 6：grader-report --- 断言评审与报告生成

grader-report 是独立于执行 Agent 的评审员，也是主流程的报告生成步骤。这是消除自判卷偏差、同时减少评分与报告之间重复调度的核心设计。

6.1 脚本预验证（AI 评审前）

能脚本化的 exact_match 断言先用脚本跑，结果确定性 0/1，不含主观空间：

断言文本特征	脚本类型
工具 X 只被调用 N 次	tool_call_count
工具 X 入参 field=value	args_field
输出不包含某字符串	response_not_contains
输出包含某关键词	response_contains
输出不超过 N 字	response_word_count

脚本验证结果标注 method: script，其余进入 AI 评审标注 method: grader，最终由 grader-report 分开统计。

6.2 Evidence 引用优先级

grader-report 的 PASS 判定必须引用 transcript 原文，不允许「整体看起来对」：

优先级 1：[tool_calls] 区块（原始系统数据，最可信）
  → 引用格式："transcript [tool_calls] Step5 - Tool: xxx, Return: {...}"

优先级 2：response.md（Skill 的最终输出）

优先级 3：[agent_notes] 区块（AI 主观解释）
  → 仅有 [agent_notes] 而无 [tool_calls] 支撑 → 判 FAIL

防编造规则 ：如果工具调用的 Return 值是自然语言描述（「返回了全量资源用量类型列表」）而不是原始 JSON，该断言标注 fabrication_risk: high，报告中橙色警告------这说明 AI 描述了它认为应该发生的事，不是系统实际返回的数据。

---

Step 7：grader-report --- 汇总与发布决策

7.1 三个通过率

指标	定义	作用
精确通过率	exact_match 断言通过率	唯一准入判断依据
语义通过率	semantic 断言通过率	辅助参考
综合通过率	全部断言通过率	仅供显示，勿用于决策

quick 模式两次运行取均值（不取最优），差距 > 15% 标红「结果不稳定，建议升级 standard」。

7.2 发布等级

等级	精确通过率	增益 Δ	P95 响应时间
S	≥ 95%	> 0	< 15s
A	≥ 90%	> 0	< 15s
B	≥ 80%	≥ -5%	< 30s
C	≥ 70%	---	< 30s
FAIL	< 70%	---	---

smoke 模式不出 PASS/FAIL，只出「冒烟通过 / 冒烟失败」。

7.3 CONDITIONAL PASS 触发条件

以下任一条件触发 S/A 级自动降级：

触发条件	背后逻辑
TP 触发率 < 70%	用户说了对的话，Skill 也不触发，功能形同虚设
触发率置信度 low 且 TP < 80%	description 连 AI 都判断不了，真实用户更难判断
TN 中有误触发预测	不该触发时触发，打断用户正常流程
quick 两次运行差距 > 15%	今天过，明天不过，不稳定
精确通过率在准入阈值 3% 范围内	险过，下一版随机性可能就不过了

7.4 四条绝对红线

触发任意一条，不得发布：

1. Δ < 0：加了 Skill 比不加更差，规则在帮倒忙
2. S/A 级灾难场景（越权/信息泄露/数据错误）有任何失败
3. MCP 工具不可用时以推断模式运行：结论是假数字，不代表真实能力
4. S 级幻觉次数 > 0：S 级 Skill 要求零幻觉，任何一次编造数据都不允许发布

7.5 改进建议输出格式

强制按优先级分层输出，每条对应 SKILL.md 具体位置：

🔴 P0 必须修复（影响发布决策）
  1. [规则缺失] Step 3 未处理用户拒绝确认的情况
     → 在 SKILL.md Step 3 补充「用户拒绝 → 终止流程并告知」

🟡 P1 建议修复（影响可靠性）
  1. [断言过弱] eval-4 金额校验断言为 existence 级
     → 建议改为：报销金额等于发票识别金额 [具体值]

🟢 P2 可选优化（提升质量）
  1. [冗余规则] 规则 7 与规则 3 重叠，可合并

报告路径：

• macOS/Linux：<workspace_dir>/report.html
• Windows：C:\Users\<用户名>\<skills-root>\SkillSentry\sessions\<Skill名>\<日期>_<NNN>\report.html

---

五、六大可信度保障机制

这是 SkillSentry 和「自己测自己」最根本的区别：

机制	解决什么问题
独立 Grader	执行 Agent 无法自评，消除自判卷偏差（LLM 自评结果平均高估 15-20%）
文件系统隔离沙箱	without_skill 不能借用 with_skill 的中间产物，Δ 才反映真实差距
transcript 双分离格式	[tool_calls] 原始数据与 [agent_notes] AI 解释严格分离，Grader 只信原始数据
断言强度分级	existence 断言不计入准入，「输出非空」不能算通过
多次运行取均值	quick 强制 2 次，standard/full 强制 3 次，单次结果不可信
脚本预验证	能脚本化的断言用正则/字符串匹配确定，结果不含主观空间

---

六、工程阈值口径说明

本文中出现的时间、Token、通过率、快速失败阈值和风险等级要求，都是 SkillSentry 当前工程口径，不是行业统一标准。

这些阈值的作用不是证明"80%/95% 是绝对真理"，而是让团队在同一套规则下做发布判断：

• quick 的快速失败阈值，用来判断是否存在根本性环境或流程问题。
• standard/full 的多次运行，用来降低单次 LLM 随机性的影响。
• 高风险场景更高通过率要求，用来保护资金、写操作、权限和合规路径。
• Delta 用来判断 Skill 是否真的带来增益，而不是只看绝对通过率。

如果你的团队风险等级、模型稳定性、执行成本不同，可以调整阈值，但必须在报告中记录当次使用的门禁口径。

---

七、开销与适用场景

模式	用例数	时间（含 Grader）	Token	典型场景
smoke	4-5	~5-7 分钟	~1-2 万	改了一处规则，快速验证没崩
quick	8-10	~8-10 分钟（mcp_based）/ ~15-20 分钟（其他）	~5-10 万	常规迭代验证，首次测评
standard	20-25	~30-45 分钟	~8-15 万	提测前，需要较高覆盖率
full	30-35	~45 分钟+	~15-20 万	正式发布前，S/A 级 Skill

缓存减少：规则缓存命中跳过提炼（减少 1-2 分钟）；用例缓存命中后 smoke/quick 直接复用（减少 5-10 分钟）。hash 不匹配时退化到 smoke，先快速确认核心路径，再决定是否跑完整测评。

风险等级与准入基线：

业务风险	典型场景	精确通过率要求	Δ 要求
高（涉及资金/写操作/合规）	报销提交、合同生成	≥ 95%	> 0
中（下游系统输入）	数据提取、状态更新	≥ 90%	> 0
低（体验增强）	摘要、建议、问答	≥ 80%	≥ -5%

---

八、常见卡点与处理方式

卡点现象	根因	处理方式
MCP 预检失败	MCP Server 未注册	选「继续」（只测流程逻辑，结论不反映真实能力），或先配好再测
执行中途断了	超时/网络	重新触发，断点续跑自动跳过已完成的 eval
找不到报告文件	路径太深	grader-report / sentry-report 末尾打印完整 Windows/Mac 路径，直接复制
两次运行差距 > 15%	模型随机性较大	报告标红提示，升 standard（3 次取均值）提升稳定性
existence 断言占比高	用例断言设计太宽松	cases 步骤会提示，手动将关键断言升级为 exact_match
Δ < 0	Skill 在帮倒忙	不允许发布，逐条排查最近新增的规则，删掉后重测
Grader 超时 10 分钟	后台任务卡死	自动跳过该 eval，在报告中标注缺失，可事后单独重跑
触发率置信度 low	description 表达不清	优化 description，明确触发词和排除场景，重跑 测触发率 <Skill名>
通过率达标但Δ接近0	Skill 没起作用	检查 description 是否真的触发了，可能测的是无 Skill 状态

---

总结

SkillSentry 的核心设计哲学只有一句话：不让 AI 自证清白。

所有机制------独立 Grader、沙箱隔离、transcript 双分离、断言强度分级------都在解决同一个问题：AI 系统在没有外部约束的情况下，会系统性地高估自己的表现。单次测试、模糊断言、执行者自评，是虚高通过率的三个来源，SkillSentry 针对每一个都有对应的工程机制。

操作上，记住三件事就够了：

1. 第一次用 ：直接说 测评 <Skill名>，系统帮你推断工作流，30 秒内给出确认提示
2. 迭代修改后 ：说 smoke 测评 <Skill名>，5-7 分钟验证核心路径没崩，再决定要不要跑完整测评
3. 正式发布前 ：说 full 测评 <Skill名>，跑完整链路，有 PASS 决策才上线