Skip to content

v0.21.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 Apr 15:28
· 598 commits to main since this release
v0.21.0
0faef58
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Minor — BREAKING bench ci 改名 bench gate(消除 omk 里 "CI" 歧义,从此 CI 永远只指置信区间),gate 内核切换为完整 verdict;single-run 盲区在用户旅程三处可见;CLI 双语 i18n 全面落地;发版自动化(publish.yml 现自动从 CHANGELOG 抽 release notes 建 GitHub Release)。

注:0.20.2 已 merge 到 main 但未发到 npm(tag 没打),所以从 0.20.1 升级的用户会在本版本一次性收到 0.20.2 + 0.21.0 两批改动。

Added

  • CLI 双语输出 (zh / en):omk 所有 CLI 输出现支持中英两种语言。优先级 --lang flag > OMK_LANG 环境变量 > 默认 zh。覆盖范围:
    • omk --help 主帮助文档(140 行)+ 所有子命令 help(gold / verdict / diagnose / failures / saturation / debias-validate / diff / analyze)
    • 实时进度反馈(预检 / 重试 / 执行中 / 评委评审 / 已完成 / 已跳过 / 错误)
    • 评测完成提示 + report server 启动信息 + gold dataset 对比反馈
    • 参数校验提示(--repeat / --judge-repeat / --judge-models / --bootstrap-samples / --no-debias-length 等)
    • bench gen-samples / bench evolve / bench gold / bench saturation 等子命令的 runtime 反馈
  • CLI i18n 基础设施:src/cli/i18n.ts(tCli / getCliLang / parseLangFromArgv / langFromArgv / makeOnProgress factory)+ src/cli/i18n-dict.ts(~80 个 key,zh/en 双写,Record 类型强制对齐)。新增 test/cli-i18n.test.ts(10 用例)做 dict parity / placeholder 替换 / lang 优先级 runtime 校验。
  • src/cli/i18n-dict.ts 头部翻译守则文档(受 lizhiyao/cc-viewer i18n 方案启发):明确"保留原文白名单"(产品名 / 子命令名 / 业务术语 skill/variant/sample/judge / 技术参数 / 文件名 / 数学缩写) vs "必须翻译的内容"(动作 / 状态 / 引导文案 / 解释),后续维护者按守则审 dict。

Changed

  • ⚠️ BREAKING:bench ci 删除,改名 bench gate,内核同步升级为完整 verdict:omk 里 "CI" 一直有歧义——既指 Continuous Integration(bench ci 命令),又指 Confidence Interval(bootstrap CI / diff CI / 95% CI)。读代码注释 / 文档 / commit message 时常常需要看上下文猜哪个 CI。本版直接删除 bench ci(omk 0-1 阶段不留兼容层),命令改名 bench gate,从此 omk 里 CI 永远只指置信区间。

    改动范围:

    • CLI:omk bench ci → omk bench gate(= runEvaluation + computeVerdict + 0/1 exit code)
    • 内部:evaluateCiGates → evaluateLayerGates,CiGateResult → LayerGateResult,VerdictOptions.ciThreshold → gateThreshold
    • 文件:src/eval-core/ci-gates.ts → layer-gates.ts,test/ci-gates.test.ts → test/layer-gates.test.ts
    • 文档:README.md / README.zh.md / docs/comparison.md / docs/zh/comparison.md / docs/knowledge-gap-signal-spec.md 全部 sweep
    • terminology-spec.md 加 §5"CI 在 omk 里只指 Confidence Interval"显式规则

    为什么改名"gate"而不是别的:业界 vocabulary(SonarQube Quality Gate / Azure release gates / Spinnaker pipeline gates),"gate" 在 CI/CD 圈是通用名词。codebase 内本来满地是 gate(three-layer gate / gate.allPass / layer-gate check),命令名也叫 gate 后,代码 / 文档 / commit 讲同一个词,可搜索性升一级。

    同步行为变更:gate 内核统一为 verdict——之前 bench ci 只看三层平均分阈值(evaluateCiGates),用户花钱跑 --bootstrap 但 ci 退出码完全忽略 bootstrap diff CI、saturation、Krippendorff α——是个隐性漏洞。本版把 handleCi 重写为 runEvaluation + computeVerdict + formatVerdictText,exit code 与 bench verdict 对齐:只有 PROGRESS / SOLO-pass 才 0;NOISE / UNDERPOWERED / CAUTIOUS / REGRESS 全 1。这是行为变更:之前三层都过 3.5 即 PASS 的 underpowered run 现在会 FAIL——这正是 gate 应有的语义(数据不显著就不该进 deploy)。--threshold 继续生效作为三层 gate 阈值,新增 --trivial-diff 调"实际可忽略的小差距"门限。两个 CLI 表层(gate 一句话跑+判 / verdict 离线判已有报告)继续保留,内核共用。这一改与下面的 single-run verdict rationale 是同一回路:underpowered 数据自动 FAIL,堵住"单轮过 PASS 就 deploy"的漏洞。

    迁移指南(用户面):GitHub Actions / GitLab CI / 任何 shell pipeline 把 omk bench ci 替换为 omk bench gate,其余 flag 不变。omk 还在 0.x,主动放弃兼容层,不留 deprecation alias。内部代码引用 evaluateCiGates / ciThreshold 的请相应改名。

  • single-run 盲区在用户旅程三处可见(三处一致信号):之前用户跑单轮(--repeat=1)评测,没有任何一个面提醒"稳定性测不到"——单轮报告读起来就像满分,容易误读为"稳"。本版在用户接触 omk 的三个时间点都加显眼信号,单轮的盲区不会再被默默忽略:

    1. 进门(bench run / --dry-run 跑前 stderr)——pre-flight 结构性预警,N<5 / N<20 / repeat=1 三档:

      • N < 5 → ⚠ exploration-only, any conclusion is unreliable, CI will be uselessly wide
      • 5 ≤ N < 20 → ⚠ large-effect-only (Cohen's d > 0.8), medium effects hard to detect
      • --repeat=1 → ⚠ single-run cannot measure stability (CV will be marked "not measured")

      不预测 MDE 数值 — σ 跑前不知道,拍脑袋写"CI 半宽 ±0.4"是 hand-wave。所以纯结构性 hard-floor,严肃 power 判定交给 bench verdict + saturation 曲线 post-hoc。buildPowerWarnings(n, repeat): string[] 抽为纯函数,9 个单测覆盖各档边界。

    2. 决策(bench verdict / bench gate)——computeVerdict 加 rationale.stability 字段,三态:

      • --repeat ≥ 2 + variance 数据齐:报 CV=X.X% (稳定/中等/不稳, runs=N) 主指标(阈值参考 terminology-spec §5)
      • --repeat ≥ 2 但 variance 缺失:标"variance 数据缺失"
      • --repeat < 2:显式说「稳定性未测量(单轮评测,需 --repeat ≥ 2 才能测 CV)」

      formatVerdictText 同步打印 Stability 行,SOLO 单 variant 路径走同一逻辑。之前 verdict 不报告稳定性,导致单轮用户无法感知盲区。

    3. 复盘(HTML 报告稳定性列)——--repeat=1 时从灰色 — + 灰色"需 --repeat ≥ 2"改成红色 ⚠ 未测量 + 红字引导文案(英文 ⚠ Not measured / single-run; needs --repeat ≥ 2 to measure CV)。之前太弱容易被误读为"无显示=没问题",改红让缺失可见。zh + en snapshot 同步重生,UI 结构 0 改动。

    无论用户是 CLI pipeline、verdict 用户、还是只看 HTML 的用户,都能在最自然的地方看到这个盲区。

  • user-facing 中文文案统一用「用例」,不用「样本」:docs/terminology-spec.md §6 加显式规则——代码 / API / 文件名 / CLI flag(Sample / sample_id / eval-samples.json / --samples)继续用 sample(开源 API + 英文圈通用术语),只 user-facing zh 切换。理由:omk 的 eval-samples 是开发者手挑的测试用例,不是从某分布随机抽样的统计样本——「样本」会暗示"再多跑就能扩大样本量"误导用户,实际是要补设计、补用例。

    本版同步把 src/cli/i18n-dict.ts(15 处 zh CLI 输出)/ src/renderer/{summary,layout}.ts(报告 UI zh)/ src/grading/{debias-validate,gold-cli}.ts(5 处 stderr)/ src/analysis/{report,sample}-diagnostics.ts(22 处 diagnostic message)/ src/authoring/{generator,evolver}.ts(7 处 LLM prompt zh) / src/types/report.ts + src/analysis/gap-analyzer.ts + src/eval-core/schema.ts 注释 / docs/{knowledge-gap-signal-spec,zh/comparison}.md 全部 sweep。HTML 报告 zh 快照同步重生。

    例外:统计学术语场景保留「样本」——Cohen's d / Hedges' g 的"小样本修正"、"样本均值"、"样本量"、bootstrap "重采样" 等是 stats 领域固定提法(对应英文 small-sample correction / sample mean / sample size / resampling),硬翻成「用例」反让懂统计的读者多一拍。判定准则:这个词指的是对总体的一次随机抽样(stats 概念,用「样本」),还是开发者手挑的一条测试用例(用「用例」)——两者不混用,上下文清晰。本版当前涉及 4 处统计语境(Cohen's d 多重比较 disclaimer / Hedges' g 小样本修正版描述 / t-test 正态假设小样本提示)保留「样本」。

  • CLI 默认输出从英文混搭中文改为彻底双语化:之前 omk bench run / omk --help / 进度反馈混合中英文(例如 "评测完成 done"),用户每次 review 报告或调试都要"切语境"。本版整体重写:中文用户读到的全是中文,英文用户读到的全是英文,无任何中英混搭。

  • lib 层(非 cli)user-facing 错误统一英文:遵循"对客表达层 i18n / 内部实现层统一英文"分层原则,把 src/inputs/eval-config.ts(16 处)/ skill-loader.ts(5 处)/ load-samples.ts(4 处)/ eval-workflows/run-evaluation.ts(3 处)/ inputs/url-fetcher.ts(2 处)/ inputs/mcp-resolver.ts(4 处)/ executors/{anthropic,openai}-api.ts(2 处)/ eval-core/evaluation-execution.ts(1 处)/ server/report-server.ts(2 处)/ authoring/{generator,evolver}.ts(6 处)/ grading/gold-cli.ts(1 处)的中文 throw new Error 和 process.stderr.write 改英文。zh 用户看到的最终输出形如"错误: skill file not found: /path"——前缀本地化(由 cli 层负责),内部错误细节是英文工程内容。

  • unknown 提示文案更准:未知模块 → 未知顶层命令,未知 bench 子命令 → 未知子命令: bench {command}(中文语序更自然)。

  • Skill 健康度日报 中英混搭 bug 修复:之前 HELP 主常量中文版混杂了中文短语 "skill 健康度日报",现在英文版改为 skill health report。

Fixed

  • directory-skill 路径解析(SKILL.md 约定):符号链接或非 cwd 子目录里的 directory-skill(例如 ~/.claude/skills/foo/SKILL.md 引用 assets/references/... 相对路径)在评测时:

    1. preflight 把所有 artifact 的文件依赖 fold 进单一 cwd 检查,不同 skill 的 assets/foo.md 互相覆盖,会产生大量 false-positive missing。
    2. 运行时 executor cwd = process.cwd() 而非 skill 根,LLM 的 Read 工具按 SKILL.md 的相对路径找文件全部失败,触发反复 retry / 模型放弃 / 长时间超时。

    修复:Artifact 加 skillRoot?: string,在 src/inputs/skill-loader.ts 对 SKILL.md 约定的 directory-skill 设值(单文件 file-skill 维持 process.cwd() 语义不变)。src/eval-core/task-planner.ts cwd fallback 链改为 artifact.cwd > artifact.skillRoot > sample.cwd > null,src/eval-core/dependency-checker.ts preflightDependencies 文件依赖按 artifact 分桶解析(每个 skill 用各自 skillRoot 当 base)。WCC skill 端到端验证:bug-fix 前 41 个 false-positive missing + 1 个 sample 180s 超时;fix 后 preflight 通过、tool failure 减半、不再超时,wcc 平均分从 4.25 拉回 4.62,与 baseline diff CI 不再显著负向。

  • 依赖文件提取 regex 收紧:之前 FILE_PATH_REGEX 把 SKILL.md 里"查看 .d.ts / index.ts 文件"这种示例性扩展名提及 / bare 文件名提及误识别为依赖。新增过滤:跳过以 . 开头的路径(扩展名讨论)和不含 / 的 bare 文件名(通用文件名几乎都是示例)。要声明 package.json / README.md 等 bare 文件作为真依赖请走显式 requires:。

  • (已知漏洞)CLI 中英混搭:历史上 cli.ts / lib 层中混有大量"中文 stderr 嵌入英文 token / 英文 console.error 嵌入中文短语"。grep -E "console\\.(log|error|warn).*[一-鿿]|process\\.stderr\\.write.*[一-鿿]|throw new Error.*[一-鿿]" src/ 现为 0 残留(除 judge.ts 测量学锚点不动)。

Internal

  • publish.yml 自动从 CHANGELOG 抽 release notes 创建 GitHub Release:push tag v* 触发后,workflow 在 npm publish 之后自动找 CHANGELOG.md ## [VERSION] section,用作 GitHub Release 的 body。维护者只需 bump package.json + 改 CHANGELOG [Unreleased] → [VERSION] - YYYY-MM-DD,merge release PR 后打 tag + push tag 即可,Release notes 不再手动写。
  • 协作者入场文档 CLAUDE.md 精简(61 → 39 行,-36%):删除与 CONTRIBUTING.md 重复内容,目标"AI / 新人 90 秒读完不踩雷"。
  • src/cli.ts 顶部 const HELP 142 行原英文模板字符串删除,内容完整迁到 dict。HELP 现通过 tCli('cli.help.main', lang).trim() 取得。
  • 13 处 parseArgs options 块统一 spread COMMON_OPTIONS = { lang: { type: 'string' } },所有子命令都接收 --lang flag。
  • defaultOnProgress 改为 makeOnProgress(lang) factory:evaluation engine 异步回调时拿不到 argv,通过 closure 闭住 lang。每个 handler 入口通过 langFromArgv(argv) 一行拿到 lang 并传 factory。
  • 测量学不变量未受影响:src/grading/judge.ts prompt 文本字节级未动,test/grading/judge-hash-frozen.test.ts 仍冻结 v2-cot=fdc81b19c721 / v3-cot-length=629bf3b8c41d 两个 hash。
  • 10 处测试 assertion regex 同步从中文更新为英文(test/eval-config.test.ts / test/runner.test.ts / test/inputs/{load-samples,skill-loader}.test.ts / test/grading/gold-cli.test.ts)。

What's Changed

  • docs: 加 CLAUDE.md(AI 协作者 / 新人入场必读) by @lizhiyao in #7
  • ci: publish.yml 自动创建 GitHub Release by @lizhiyao in #6
  • 特性(v0.21 D.1+D.4): CLI 双语 i18n + lib 层 user-facing 文本统一英文 by @lizhiyao in #8
  • release: v0.20.2 — CLI 双语 i18n + publish.yml 自动化 by @lizhiyao in #9
  • docs(claude-md): commit message 规则改为英文前缀 + 中文正文 by @lizhiyao in #10
  • refactor(types): 删 facade src/types.ts, import 统一指向 types/index.js by @lizhiyao in #11
  • fix(ci): publish.yml release 创建改用 softprops/action-gh-release, 修 yaml 解析失败 by @lizhiyao in #12
  • fix(skill,preflight): directory-skill cwd 默认锚到 SKILL.md 所在目录 by @lizhiyao in #13
  • chore(terminology): user-facing 中文统一用「用例」, 不用「样本」 by @lizhiyao in #14
  • feat(verdict-stability): single-run 盲区在用户旅程三处可见 by @lizhiyao in #18
  • chore(sync): bench gate 改名同步到 develop (PR #19 漏 sync 修复) by @lizhiyao in #20
  • release: v0.21.0 by @lizhiyao in #21

Full Changelog: v0.20.1...v0.21.0

Contributors

lizhiyao
Assets 2
Loading