omk

简体中文

English

简体中文

English

Appearance

omk 快速上手：跑出第一份 verdict ​

5 分钟跑出第一份报告，然后把 demo 换成你自己的 skill。目标读者：手里有一版（或几版）skill，想用数据看看「这版 skill 到底好不好」「v2 有没有变好」「能不能带证据发布」。

前置（1 分钟） ​

bash
npm i oh-my-knowledge -g
omk --version    # 能输出版本号即装好

默认 runtime 使用 claude CLI 作为执行器和评委，所以需要先安装并登录 Claude Code。如果你在 Codex 或 OpenAI 兼容 API 环境里，也可以继续往下看，首跑命令里会标出 runtime 参数怎么替换。

如果你想用「自然语言让 agent 帮你跑」的方式（推荐），还需要把 omk Agent Skill 装到你的 agent 工具里：

bash
omk install omk-agent-skill

默认只会安装到本机已检测到、且 omk 明确支持的目标：检测到 ~/.codex 或 ~/.agents 时写入 Codex/AGENTS，检测到 ~/.claude 时写入 Claude Code。要强制写入当前 omk 已知的全部目标，用 --to all；要指定自定义 skill 根目录，用 --dest。装好之后，agent 收到含「omk」「评测」「benchmark」之类的关键词就会自动加载 SKILL 上下文。

最快首跑：先用 demo 脚手架 ​

如果你第一次用 omk，先不要急着接自己的文件，从这里开始：

bash
omk init demo
cd demo
omk eval --control code-review-v1 --treatment code-review-v2 --dry-run
omk eval --control code-review-v1 --treatment code-review-v2

omk init 会创建两版 skill 和三条评测用例。--dry-run 先预览任务计划和预估调用次数；真跑后会打开 HTML 报告。demo 只有三条用例，verdict 经常是 UNDERPOWERED，这是正常教学结果，不是运行失败。

如果默认 Claude runtime 不可用，同一套 demo 可以加 runtime 参数：

bash
# Codex CLI 路径
omk eval --control code-review-v1 --treatment code-review-v2 \
  --executor codex --model <codex-model> \
  --judge-models codex:<codex-model>

# OpenAI 兼容 API 路径
export OPENAI_API_KEY="..."
export OPENAI_BASE_URL="https://api.example.com/v1"
omk eval --control code-review-v1 --treatment code-review-v2 \
  --executor openai-api --model <model> \
  --judge-models openai-api:<model>

Codex 的 <codex-model> 要换成本机 Codex 可用模型；可查看 ~/.codex/config.toml 或 $CODEX_HOME/config.toml 里的 model。OpenAI 兼容 API 则要确认模型名和 OPENAI_BASE_URL 指向的端点匹配。

准备 skill（1 分钟） ​

按 omk 默认布局把 skill 放到 skills/ 目录下。推荐用单 .md 文件，最简单：

skills/
├── my-skill-v1.md
└── my-skill-v2.md

只有当 skill 内容超长、想把示例 / 参考资料拆到独立文件时，再用目录式（每版一个目录）：

skills/
├── my-skill-v1/
│   └── SKILL.md
└── my-skill-v2/
    ├── SKILL.md
    └── references/      长示例 / 参考资料
        └── examples.md

两种形式 omk 都能识别，混用也行。要跑 v1 vs v2 对比就按上面放两版；只想看「有 skill vs 没 skill」的差距，放一份就够，用 baseline 对照。

把 demo 换成你自己的 skill ​

路径 A：自然语言（推荐） ​

打开你的 coding agent，进入项目目录，直接说一句话：

用 omk 对比 skills/my-skill-v1 跟 skills/my-skill-v2

omk skill 会自动判断：没有 eval-samples.json 就先帮你生成用例，然后跑评测，最后把报告浏览器弹出来。Claude Code 可以直接使用已安装的 omk skill；在 Codex 里则让 agent 执行 omk CLI。常见说法：

  • 「用 omk 对比 skills/my-skill-v1 跟 skills/my-skill-v2」
  • 「用 omk 给 skills/audit 跑 baseline 对照（有 skill vs 没 skill）」
  • 「用 omk 跑 skills/ 下面所有 skill 的批量评测」
  • 「用 omk evolve 自动改进 skills/my-skill-v2，跑 5 轮」

路径 B：直接命令行 ​

如果你只有一版 skill，最短有用对比是「有这个 skill」vs baseline：

bash
omk sample skills/my-skill.md                         # 第一次：让 AI 给你的 skill 生成评测用例
omk eval --control baseline --treatment my-skill --dry-run
omk eval --control baseline --treatment my-skill

如果你已经有 v1 / v2 两版，再做版本对比：

bash
omk sample skills/my-skill-v2.md                                  # 第一次:让 AI 给你的 skill 生成评测用例
omk eval --control my-skill-v1 --treatment my-skill-v2 --dry-run  # 预览要跑什么
omk eval --control my-skill-v1 --treatment my-skill-v2            # 真跑
omk studio                                                        # 启动报告浏览器

variant 名来自 skills/ 下的 skill 文件名或目录名；skills/my-skill.md 对应 my-skill，上面的 v1 / v2 布局对应 my-skill-v1 和 my-skill-v2。

--dry-run 预览时会告诉你预估调用次数和成本，确认 OK 再去掉 flag 真跑。omk eval 默认会先跑一次 doctor 健康度检查当门禁，发现 skill 写法有大问题就直接拦下来；如果你确认知道自己在干嘛，加 --skip-doctor 绕过。

模型或执行器失败时 ​

CLI 会尽量把首跑失败变成可执行的下一步：

  • Claude 失败：先登录 Claude Code，或按上面的参数切到 Codex / OpenAI API。
  • Codex 模型失败：换成 ~/.codex/config.toml 或 $CODEX_HOME/config.toml 里配置的模型，再用 codex exec -m <codex-model> "hi" 验证。
  • OpenAI / Anthropic API 模型失败：检查 --model、--judge-models、base URL，以及账号是否有该模型权限。
  • 如果只是想先验证断言和报告链路，加 --no-judge；它会跳过 LLM 评委，只使用断言分数。

看结果（1 分钟） ​

报告浏览器自动弹出（默认 http://127.0.0.1:7799/），重点看三个地方：

verdict（跨版本结论）：PROGRESS（变好）/ NOISE（差距在置信区间内不可区分）/ REGRESS（变差）/ CAUTIOUS（趋势好但置信不足）；外加两档边界情况 UNDERPOWERED（用例太少不足以下结论）与 SOLO（单变体，无可对比）。这是你能直接拿出去对焦的一句话结论。

综合分：每版 0-5 分平均，跟基线比 +Δ 多少。Δ 旁边的置信区间决定 verdict 落点 —— 默认 95%，多个实验组共用一个对照时按 Bonferroni 提到更高置信水平。

低分用例：点开看 LLM 在哪条用例上崩了。对照「rubric 期望」跟「LLM 实际输出」找差距 —— 通常能直接看出 skill 文档哪段写得不够清楚。

按 verdict 行动 ​

Verdict下一步
PROGRESS可以走正常发布流程。留存报告作为发布证据；如果这是已用 omk install 纳管的 skill，再运行 omk promote <name> 记录接受决定。
CAUTIOUS不要盲发。先看触发的告警（分层门控、评委分歧、稳定性或 holdout），修完再重跑；只有明确人工复核后才放宽门禁。
REGRESS不要发布。从最差层和失败用例开始定位，修好 artifact 后重跑评测。
NOISE暂不做发布判断。增加用例，或提高用例集区分度，让差异能从噪声里分离出来，再重跑。
UNDERPOWERED把用例扩到约 20 条以上，或至少按当前规模 2× 扩充后重跑。
SOLO先补对照组，通常用 omk eval --control baseline --treatment <name>，再做发布 / 不发布判断。

关键提示 ​

用例生成会花时间。omk 默认让 AI 给你的 skill 生成 10-20 条用例，但 AI 生成的用例有偏：容易扎堆在 skill 文档已经写清楚的「happy path」上，对边界 / 反例 / 误用场景覆盖不足。强烈建议第一次跑完之后花 30 分钟人工筛一遍：删掉不合理的、补缺关键边界、补几条「故意写错的用户指令」看 skill 会不会被带偏。这是评测结果可信度的最大变量。

评测会产生 LLM 费用。粗算单条用例 × 单 variant 约 $0.01-0.05 美元，10 条用例 × 2 variants 约 $0.2-1 美元。跑前 --dry-run 预览。

结论只对你给定的用例集负责。「我这版 skill 更好」这句话的天花板是「在你设计的 N 条用例上更好」。换用例集结论可能翻盘。所以用例设计本身就是结论可信度的源头 —— 不要把它当成「跑评测前的麻烦事」，它就是评测本身。

常见场景速查 ​

想做什么自然语言说法等价命令
第一次给 skill 跑分给 skills/X 跑 baseline 对照omk eval --control baseline --treatment X
改完前后对比对比 git 历史里的 skills/X 跟当前版本omk eval --control git:X --treatment X
让 omk 帮我自动改 skill用 omk evolve skills/X 跑 5 轮omk evolve skills/X.md --rounds 5
批量评测一批 skill给 skills/ 下所有 skill 跑评测omk eval --batch
只生成用例不跑评测给 skills/X 生成测试用例omk sample skills/X.md
单独跑健康度检查给 skills/X 做 doctor 体检omk doctor skills/X.md
看历史报告打开 omk studioomk studio

跑完第一份报告，对焦时拿这些信息走 ​

  • verdict + 综合分 + Δ + 95% CI 区间
  • 哪几条用例分数最低，rubric 期望 vs LLM 实际差在哪
  • 你对哪些用例的设计有疑问（避免「数据说话也要怀疑数据」的盲信）
  • doctor 健康度结论（eval 默认会跑，报告里有；如果想单独审一次跑 omk doctor）

更深的玩法 ​