oh-my-knowledge 0.26.0 → 0.28.0

package/dist/src/cli/i18n-dict.js

@@ -16,9 +16,7 @@
  * 2. **保留原文的白名单 (产品术语 / 命令 / 文件名)**
  *    以下 token 在两种语言里都保留原文, 不翻译:
  *    - 产品名: omk, oh-my-knowledge, Claude, npm
- *    - 子命令空间和命令名: bench, analyze, run, report, init, evolve, gold,
- *      diff, ci, gen-samples, debias-validate, saturation, verdict,
- *      diagnose, failures
+ *    - 命令名: init, doctor, eval, observe, evolve, sample, studio, gold
  *    - omk 核心业务术语: skill, variant, sample, judge, executor (出现在产品
  *      UI 里时首字母可大写如 "Skill 评测", 描述句中保持小写)
  *    - 技术参数: --lang, --control, --treatment, --bootstrap, --judge-repeat,
@@ -48,21 +46,9 @@
  * Record 类型自动强制每 key 加新语言版本。
  */
 export const CLI_DICT = {
-    'cli.common.lang_invalid_silent': {
-        zh: '无效的语言代码: {value} (仅支持 zh / en, 已使用默认 zh)',
-        en: 'Invalid language code: {value} (supported: zh / en, using default zh)',
-    },
-    'cli.common.help_hint': {
-        zh: "运行 'omk --help' 查看用法",
-        en: "Run 'omk --help' to see usage",
-    },
     'cli.common.unknown_domain': {
-        zh: "未知顶层命令: {domain} (请用 'omk bench <command>'、'omk doctor [path]' 或 'omk analyze <dir>')",
-        en: "Unknown domain: {domain} (use 'omk bench <command>', 'omk doctor [path]' or 'omk analyze <dir>')",
-    },
-    'cli.common.unknown_bench_command': {
-        zh: "未知子命令: bench {command} (运行 'omk --help' 查看可用列表)",
-        en: "Unknown bench command: {command} (run 'omk --help' to see all commands)",
+        zh: "未知命令：{domain}。运行 'omk --help' 查看可用命令。",
+        en: "Unknown command: {domain}. Run 'omk --help' to see available commands.",
     },
     'cli.init.scaffolded': {
         zh: '已初始化测评项目: {dir}',
@@ -73,7 +59,7 @@ export const CLI_DICT = {
         en: 'Next steps:',
     },
     'cli.init.next_step_edit_samples': {
-        zh: '  1. 编辑 eval-samples.json, 加入你要测的测评用例',
+        zh: '  1. 编辑 eval-samples.json，加入你要测的评测用例',
         en: '  1. Edit eval-samples.json to add your test cases',
     },
     'cli.init.next_step_edit_skills': {
@@ -81,8 +67,8 @@ export const CLI_DICT = {
         en: '  2. Edit skills/code-review-v1/SKILL.md and skills/code-review-v2/SKILL.md with your skill versions',
     },
     'cli.init.next_step_run': {
-        zh: '  3. 运行: omk bench run --control code-review-v1 --treatment code-review-v2',
-        en: '  3. Run: omk bench run --control code-review-v1 --treatment code-review-v2',
+        zh: '  3. 运行: omk eval --control code-review-v1 --treatment code-review-v2',
+        en: '  3. Run: omk eval --control code-review-v1 --treatment code-review-v2',
     },
     'cli.init.note_codex_executor': {
         zh: '\n注: omk 评测时把 SKILL.md 整文(含 frontmatter)作为 system prompt 注入 — 跨 executor 一致(claude / codex / openai-api / gemini 都走同一条路径,不依赖任何 executor 的 native skill auto-discovery 或 Skill 工具机制)。frontmatter 在 prompt 头部对 model 行为无显著影响。\n模板带 Claude Code 兼容的 frontmatter(name + description)是为了让同一份 directory-skill 也能 deploy 到 Claude Code:把整个目录复制到 ~/.claude/skills/code-review-v1/(整目录,不是单个 SKILL.md),Claude SDK 才能识别。这是 omk 评测之外的 bonus,一份文件双向 dogfood。',
@@ -92,6 +78,22 @@ export const CLI_DICT = {
         zh: '\n💡 新版本可用: {old} → {new}, 运行 npm update {pkg} -g 升级\n\n',
         en: '\n💡 New version available: {old} → {new}, run npm update {pkg} -g to upgrade\n\n',
     },
+    'cli.run.power_warning_tiny_n': {
+        zh: '⚠ N={n} < 5：仅适合探索，任何结论都不可靠，CI 会很宽。需要决策时建议 ≥20 条评测用例。',
+        en: '⚠ N={n} < 5 (exploration-only): any conclusion is unreliable, CI will be uselessly wide. Decisions need ≥20 cases.',
+    },
+    'cli.run.power_warning_small_n': {
+        zh: '⚠ N={n} < 20：只能识别很大的效果（Cohen\'s d > 0.8），中等效果（d ≈ 0.5）很难检出。要做可靠决策建议 ≥20 条评测用例。',
+        en: '⚠ N={n} < 20 (large-effect-only, Cohen\'s d > 0.8): medium effects (d ≈ 0.5) hard to detect. For confident decisions consider ≥20 cases.',
+    },
+    'cli.run.power_warning_repeat_one': {
+        zh: '⚠ --repeat=1：单轮评测无法测稳定性（CV 会标记为未测量）。用 --repeat 3+ 检测同一 variant 内部方差。',
+        en: '⚠ --repeat=1: single-run cannot measure stability (CV will be marked "not measured"). Use --repeat 3+ to detect within-variant variance.',
+    },
+    'cli.run.dry_run_no_scores': {
+        zh: 'eval dry-run：仅预览任务，不检查分数',
+        en: 'Eval dry-run: no scores to check',
+    },
     'cli.progress.preflight_starting': {
         zh: '⏳ 正在预检模型连通性...\n',
         en: '⏳ Preflight: checking model connectivity...\n',
@@ -168,6 +170,14 @@ export const CLI_DICT = {
         zh: '\n✅ 批量评测完成\n',
         en: '\n✅ Batch evaluation done\n',
     },
+    'cli.run.batch_verdict_header': {
+        zh: '批量评测结论：{status}（{passed}/{total} 通过）',
+        en: 'Batch verdict: {status} ({passed}/{total} passed)',
+    },
+    'cli.run.batch_child_report_missing': {
+        zh: '⚠ 子报告缺失：{id}，将按不可 ship 处理。\n',
+        en: '⚠ Child report missing: {id}; treating it as not shippable.\n',
+    },
     'cli.run.eval_complete': {
         zh: '\n✅ 评测完成\n',
         en: '\n✅ Evaluation done\n',
@@ -180,6 +190,10 @@ export const CLI_DICT = {
         zh: '📄 报告已保存到: {path}\n',
         en: '📄 Report saved to: {path}\n',
     },
+    'cli.run.report_only_gate_skipped': {
+        zh: 'ℹ 已启用 report-only 模式：保留 verdict 输出，但本次不使用 verdict 改写 exit code。\n',
+        en: 'ℹ Report-only mode enabled: verdict is still printed, but it will not affect the exit code.\n',
+    },
     'cli.run.report_server_running': {
         zh: '\n📊 报告服务已启动: {url}\n',
         en: '\n📊 Report server running at {url}\n',
@@ -197,8 +211,8 @@ export const CLI_DICT = {
         en: '\n💡 Non-interactive environment, skipping report server\n',
     },
     'cli.run.no_serve_view_hint': {
-        zh: '   查看报告: omk bench report --reports-dir {dir}\n',
-        en: '   View report: omk bench report --reports-dir {dir}\n',
+        zh: '   查看报告：omk studio --reports-dir {dir}（报告 ID：{id}）\n',
+        en: '   View report: omk studio --reports-dir {dir} (report id: {id})\n',
     },
     'cli.run.gold_load_failed': {
         zh: '\n⚠ gold dataset 加载失败 ({dir}):\n',
@@ -216,9 +230,9 @@ export const CLI_DICT = {
         zh: '❌ 错误: {message}',
         en: '❌ Error: {message}',
     },
-    'cli.analyze.view_in_browser': {
-        zh: "在浏览器查看: omk bench report  # 打开后点首页的 \"📊 Skill 健康度日报\"",
-        en: "View in browser: omk bench report  # then click \"📊 Skill health report\" on the home page",
+    'cli.observe.view_hint': {
+        zh: '分析 JSON 已写入 output-dir；后续可用 omk observe 持续生成日报。',
+        en: 'Analysis JSON written to output-dir; use omk observe to keep producing health reports.',
     },
     'cli.common.skill_dir_not_found': {
         zh: '未找到 skill 目录: {path}',
@@ -237,23 +251,31 @@ export const CLI_DICT = {
         en: 'No judge configured. Pass --judge-models <executor:model> or ensure the report has meta.judgeModels.',
     },
     'cli.common.judge_models_single_only': {
-        zh: 'bench {cmd} 仅支持单评委。--judge-models 只能传一个 executor:model entry。',
-        en: 'bench {cmd} only supports a single judge. --judge-models accepts exactly one executor:model entry.',
-    },
-    'cli.common.usage_gold_validate': {
-        zh: '用法: omk bench gold validate <dir>',
-        en: 'Usage: omk bench gold validate <dir>',
+        zh: '{cmd} 仅支持单评委。--judge-models 只能传一个 executor:model entry。',
+        en: '{cmd} only supports a single judge. --judge-models accepts exactly one executor:model entry.',
     },
     'cli.common.warn_load_samples_failed': {
         zh: '⚠ 加载 samples 文件失败 ({path}): {message}\n',
         en: '⚠ Failed to load samples file ({path}): {message}\n',
     },
+    'cli.studio.started': {
+        zh: 'studio 已启动：{url}',
+        en: 'Studio running at {url}',
+    },
+    'cli.studio.stop_hint': {
+        zh: '按 Ctrl+C 停止服务',
+        en: 'Press Ctrl+C to stop',
+    },
+    'cli.studio.open_failed': {
+        zh: '⚠ 无法自动打开浏览器（{command}）：{message}\n',
+        en: '⚠ Failed to open browser automatically ({command}): {message}\n',
+    },
     'cli.gen.skill_skipped_existing': {
         zh: '⏭️  {name}: eval-samples 已存在, 跳过\n',
         en: '⏭️  {name}: eval-samples already exists, skipping\n',
     },
     'cli.gen.skill_generating': {
-        zh: '🔄 {name}: 正在生成 {count} 条测评用例...\n',
+        zh: '🔄 {name}: 正在生成 {count} 条评测用例...\n',
         en: '🔄 {name}: generating {count} test cases...\n',
     },
     'cli.gen.skill_done': {
@@ -269,19 +291,19 @@ export const CLI_DICT = {
         en: 'No eval-samples need generating (all skills already have paired files)',
     },
     'cli.gen.batch_summary': {
-        zh: '\n共生成 {n} 份 eval-samples, 请审查后运行: omk bench run --batch',
-        en: '\nGenerated {n} eval-samples files. Review them, then run: omk bench run --batch',
+        zh: '\n共生成 {n} 份 eval-samples, 请审查后运行: omk eval --batch',
+        en: '\nGenerated {n} eval-samples files. Review them, then run: omk eval --batch',
     },
     'cli.gen.specify_skill_path': {
-        zh: '请指定 skill 文件路径, 例如: omk bench gen-samples skills/my-skill.md',
-        en: 'Please specify a skill file path, e.g.: omk bench gen-samples skills/my-skill.md',
+        zh: '请指定 skill 文件路径, 例如: omk sample skills/my-skill.md',
+        en: 'Please specify a skill file path, e.g.: omk sample skills/my-skill.md',
     },
     'cli.gen.samples_already_exists': {
         zh: 'eval-samples.json 已存在。如需覆盖请先删除该文件。',
         en: 'eval-samples.json already exists. Delete it first if you want to overwrite.',
     },
     'cli.gen.single_generating': {
-        zh: '🔄 正在生成 {count} 条测评用例...\n',
+        zh: '🔄 正在生成 {count} 条评测用例...\n',
         en: '🔄 Generating {count} test cases...\n',
     },
     'cli.gen.single_done': {
@@ -289,20 +311,20 @@ export const CLI_DICT = {
         en: '✅ Generated {n} samples → {path}{cost}\n',
     },
     'cli.gen.review_hint': {
-        zh: '\n请审查生成的测评用例后运行: omk bench run',
-        en: '\nReview the generated test cases, then run: omk bench run',
+        zh: '\n请审查生成的评测用例后运行: omk eval',
+        en: '\nReview the generated test cases, then run: omk eval',
     },
     'cli.gen.failed': {
         zh: '生成失败: {message}',
         en: 'Generation failed: {message}',
     },
     'cli.evolve.specify_skill_path': {
-        zh: '请指定 skill 文件路径, 例如: omk bench evolve skills/my-skill.md',
-        en: 'Please specify a skill file path, e.g.: omk bench evolve skills/my-skill.md',
+        zh: '请指定 skill 文件路径, 例如: omk evolve skills/my-skill.md',
+        en: 'Please specify a skill file path, e.g.: omk evolve skills/my-skill.md',
     },
     'cli.evolve.section_header': {
-        zh: '\n=== Evolution: {path} ===\n',
-        en: '\n=== Evolution: {path} ===\n',
+        zh: '\n=== Improve skill: {path} ===\n',
+        en: '\n=== Improve skill: {path} ===\n',
     },
     'cli.evolve.round_baseline': {
         zh: '第 0 轮 (基线): score={score} ({cost})\n',
@@ -329,630 +351,319 @@ export const CLI_DICT = {
         en: 'All versions saved at: {dir}/\n',
     },
     'cli.evolve.report_link': {
-        zh: '📊 评测报告: omk bench report (ID: {id})\n',
-        en: '📊 Report: omk bench report (ID: {id})\n',
-    },
-    'cli.gold.created_files': {
-        zh: '已在 {dir} 创建 {n} 个文件:',
-        en: 'Created {n} files in {dir}:',
-    },
-    'cli.gold.next_step_edit_annotations': {
-        zh: '\n下一步: 编辑 annotations.yaml 加入真实标注 → 跑 omk bench gold validate',
-        en: '\nNext step: edit annotations.yaml with real annotations → run omk bench gold validate',
-    },
-    'cli.gold.validate_ok': {
-        zh: '✓ gold dataset OK — 共 {n} 条标注',
-        en: '✓ gold dataset OK — {n} annotations',
-    },
-    'cli.debias.warn_cost_doubles': {
-        zh: '\n⚠ debias-validate 会重判所有 (sample × variant), judge 成本大约翻倍。\n',
-        en: '\n⚠ debias-validate will re-judge all (sample × variant) pairs; judge cost will roughly double.\n',
-    },
-    'cli.saturation.no_data': {
-        zh: '该 report 没有 saturation 数据 (需要 --repeat ≥ 2 才会记录)。',
-        en: 'This report has no saturation data (requires --repeat ≥ 2 to record).',
-    },
-    'cli.saturation.verdict_header': {
-        zh: '\n  Saturation verdict (复述持久化结果)\n',
-        en: '\n  Saturation verdict (replaying persisted result)\n',
-    },
-    'cli.saturation.variant_no_trace': {
-        zh: '  {variant}: 没有 trace 数据',
-        en: '  {variant}: no trace data',
-    },
-    'cli.saturation.variant_label': {
-        zh: '  {variant}:',
-        en: '  {variant}:',
-    },
-    'cli.saturation.checkpoints': {
-        zh: '    检查点: {n} (N={list})',
-        en: '    checkpoints: {n} (N={list})',
+        zh: '📊 查看报告：omk studio（报告 ID：{id}）\n',
+        en: '📊 View report: omk studio (report id: {id})\n',
     },
-    'cli.saturation.last_point': {
-        zh: '    最后一点 mean={mean}, CI=[{lo}, {hi}]',
-        en: '    last point mean={mean}, CI=[{lo}, {hi}]',
-    },
-    'cli.saturation.persisted_verdict': {
-        zh: '    持久化判定 ({method}): {result} - {reason}',
-        en: '    persisted verdict ({method}): {result} - {reason}',
-    },
-    'cli.saturation.persisted_verdict_saturated': {
-        zh: '已饱和@N={n}',
-        en: 'saturated@N={n}',
-    },
-    'cli.saturation.persisted_verdict_unsaturated': {
-        zh: '未饱和',
-        en: 'not saturated',
-    },
-    'cli.saturation.skipped_too_few_points': {
-        zh: '    判定: 数据点数 {n} < 5, 跳过 (需要跑 --repeat 5 以上才会输出)',
-        en: '    verdict: only {n} data points (< 5), skipping (need --repeat 5 or more)',
+    'cli.help.product_main': {
+        zh: `
+oh-my-knowledge — 知识载体工作台
+
+用法：
+  omk init [dir]                      初始化一个 skill 评测项目
+  omk doctor [path]                   LLM 健康度审计（7 内置维度 + 可扩展）；--static-only 切离线静态模式
+  omk eval [options]                  离线评测：比较版本，输出 verdict + report
+  omk observe <sessions-dir>          线上观测：真实 session、gap、失败率、inbox
+  omk evolve <skill>                  多轮自动迭代改进 skill
+  omk sample <skill>                  生成或补齐 eval-samples 评测用例（或 --batch 批量模式）
+  omk studio                          打开本地工作台浏览报告
+
+主路径：
+  omk doctor
+  omk eval --control code-review-v1 --treatment code-review-v2
+  omk observe ~/.claude/projects/<project>
+  omk evolve skills/code-review-v2/SKILL.md
+  omk studio
+
+通用选项：
+  --lang <zh|en>                      CLI 输出语言（默认：zh，也可设 OMK_LANG）
+
+运行 'omk <command> --help' 查看单个命令的参数。
+`,
+        en: `
+oh-my-knowledge — Knowledge Artifact Workbench
+
+Usage:
+  omk init [dir]                      Scaffold a skill evaluation project
+  omk doctor [path]                   LLM health audit (7 builtin dimensions, extensible); --static-only for offline static checks
+  omk eval [options]                  Offline evaluation: compare versions, emit verdict + report
+  omk observe <sessions-dir>          Production observation: sessions, gaps, failure rate, inbox
+  omk evolve <skill>                  Auto-iterate a skill through multi-round eval loops
+  omk sample <skill>                  Generate or fill eval-samples test cases (or --batch for all skills)
+  omk studio                          Open the local workbench to browse reports
+
+Main workflow:
+  omk doctor
+  omk eval --control code-review-v1 --treatment code-review-v2
+  omk observe ~/.claude/projects/<project>
+  omk evolve skills/code-review-v2/SKILL.md
+  omk studio
+
+Common options:
+  --lang <zh|en>                      CLI output language (default: zh, or set OMK_LANG)
+
+Run 'omk <command> --help' for command-specific options.
+`,
     },
-    'cli.help.main': {
+    'cli.help.init_usage': {
         zh: `
-oh-my-knowledge — 知识工件评测工具集
+omk init — 初始化 skill 评测项目
 
-用法:
-  omk bench run [options]              跑一轮评测
-  omk bench report [options]           启动报告 server
-  omk bench gate [options]             跑评测 + 应用 gate, exit code 0/1 (CI/CD 用)
-  omk bench init [dir]                 初始化一个评测项目
-  omk bench gen-samples [skill]        从 skill 内容生成 eval-samples
-  omk bench diff <id1> <id2>           对比两份评测报告
-  omk bench evolve <skill>             通过迭代评测自我改进 skill
+用法：
+  omk init [dir]
 
-  omk doctor [path]                    skill 健康检查(评测前置门禁)
-  omk analyze <dir>                    分析 cc session trace, 生成 skill 健康度日报 (v0.18)
+生成内容：
+  eval-samples.json                  示例评测用例
+  skills/code-review-v1/SKILL.md     基线 skill
+  skills/code-review-v2/SKILL.md     实验组 skill
 
-bench run 选项:
+下一步：
+  1. 编辑 eval-samples.json，替换成你的真实评测用例
+  2. 编辑两个 SKILL.md，填入要对比的 skill 版本
+  3. 运行 omk eval --control code-review-v1 --treatment code-review-v2
+`,
+        en: `
+omk init — scaffold a skill evaluation project
 
-  --samples <path>       用例文件 (默认: eval-samples.json)
-  --skill-dir <path>     skill 定义目录 (默认: skills)
-  --control <expr>       对照组 variant 表达式 (实验角色 = control)
-  --treatment <v1,v2>    实验组 variant 表达式 (逗号分隔; 角色 = treatment)
-                         每个 variant 表达式解析为一个 artifact 加上可选运行时上下文:
-                           "baseline"       — 裸模型, 不注入 artifact
-                           "git:name"       — 来自最后一次 commit 的 artifact
-                           "git:ref:name"   — 来自指定 commit 的 artifact
-                           带 "/" 的路径    — 直接来自文件 (例如 ./v1.md)
-                           "name@/cwd"      — 附加运行时上下文 / cwd
-                         --control 和 --treatment 至少要给一个。
-  --config <path>        YAML/JSON 配置文件 (evaluation-as-code)。
-                         在一个文件里声明 samples + variants + model + executor。
-                         CLI flag 会覆盖配置文件中的同名字段。
-                         配置中的相对路径相对于配置文件所在目录解析。
-  --model <name>         任务执行模型 (默认: sonnet)
-  --output-dir <path>    报告输出目录 (默认: ~/.oh-my-knowledge/reports/)
-  --no-judge             跳过 LLM 评委
-  --no-cache             禁用结果缓存
-  --dry-run              预览任务但不执行
-  --blind                双盲 A/B 模式: 报告里隐藏 variant 名称
-  --concurrency <n>      并发任务数 (默认: 1)
-  --timeout <seconds>    单任务执行超时 (秒, 默认: 120)
-  --repeat <n>           跑 N 轮做方差分析 (默认: 1)
-  --judge-repeat <n>     每个 (sample × dimension) 调 LLM 评委 N 次评估
-                         自洽性 (默认: 1)。多轮间高 stddev = 评委在该评分维度
-                         上不稳定, 分数有噪声。
-  --judge-models <list>  评委配置, 逗号分隔的 executor:model, 如
-                         claude:haiku 或 claude:opus,openai:gpt-4o。
-                         1 条 = 单评委 (默认 claude:haiku); ≥ 2 条 = ensemble,
-                         每个评委对所有 (sample × dimension) 打分, 报告
-                         含每评委分布 + Pearson / MAD 评委间一致性。能反驳
-                         "Claude 评委评 Claude 同模态偏置" 的质疑。可与
-                         --judge-repeat 组合。成本 ~ N_judges × N_repeat × N_samples。
-  --bootstrap            计算 bootstrap 置信区间 (无分布假设, 对 LLM 序数评分
-                         比 t 区间更靠谱)。给出每个 variant 均值 CI + treatment
-                         vs control 差值的 pairwise CI (CI 不跨 0 即显著)。
-                         同时报告 t 区间和 bootstrap, 旧工具仍可用。
-  --bootstrap-samples <n>  bootstrap 重采样次数 (默认 1000)。N>10000 触发
-                         stderr 警告提示耗时。
-  --retry <n>            失败任务最多重试 N 次, 指数退避 (默认: 0)
-  --resume <report-id>   从历史报告恢复, 跳过已完成任务
-  --executor <name>      执行器: claude / claude-sdk / codex / openai / gemini /
-                         anthropic-api / openai-api, 或任意 shell 命令 (例如 "python my_provider.py")
-  --batch                批量评测:每个 skill 独立 vs baseline
-                         需要每个 skill 有配对的 {name}.eval-samples.json
-  --skip-connectivity    跳过 LLM 模型连通性检测 (--resume 时自动跳过)
-  --mcp-config <path>    通过 MCP server 抓 URL 用的 MCP 配置文件
-                         (默认: 当前目录下的 .mcp.json)
-  --no-serve             评测后不自动启动报告 server
-  --verbose              打印每个用例的详细进度 (执行结果 / 评分阶段)
-  --layered-stats        默认在 HTML 报告里展开三层 (fact/behavior/judge) 独立
-                         显著性细分。不加这个 flag 时, 细分会折叠在每个对比下
-                         的 click-to-expand summary 里。
-  --strict-baseline      (默认开启) 对 baseline-kind variant 强制隔离 skill 自动
-                         发现 + Skill 工具调用, 切断 ~/.claude/skills/ 污染路径,
-                         保证 skill 评测的 construct validity。eval.yaml 显式
-                         allowedSkills 优先。
-  --no-strict-baseline   显式关闭 strict-baseline (baseline 走默认 SDK skill
-                         全发现)。少数场景下可能想要这个 (例如评测 skill 文档
-                         对默认全发现行为的增量影响)。开启时 pre-flight 会
-                         stderr 提醒, 因为 verdict / Δ 易受污染。
+Usage:
+  omk init [dir]
 
-bench gate 选项:
-  (与 bench run 相同, 额外加:)
-  --threshold <number>   三层 gate 阈值 (fact / behavior / LLM judge), 独立应用
-                         到每一层。任一层低于阈值即失败 — 防止合成均值掩盖单层
-                         崩塌。默认: 3.5。如果三层全空 (没有 assertion 也没在
-                         eval-samples 里定义 rubric), gate 失败并提示配置问题,
-                         不走合成 fallback。
-  --trivial-diff <num>   实际可忽略的最小 diff (默认 0.1)。bootstrap diff CI
-                         显著但 |Δ| 小于此值视为"统计有效但实际无意义",标
-                         CAUTIOUS 不给 PROGRESS。
+Generated files:
+  eval-samples.json                  Example test cases
+  skills/code-review-v1/SKILL.md     Baseline skill
+  skills/code-review-v2/SKILL.md     Treatment skill
+
+Next steps:
+  1. Edit eval-samples.json with your real test cases
+  2. Edit both SKILL.md files with the skill versions to compare
+  3. Run omk eval --control code-review-v1 --treatment code-review-v2
+`,
+    },
+    'cli.help.eval': {
+        zh: `
+omk eval — 离线评测 skill 版本，并给出 ship/no-ship verdict
+
+用法：
+  omk eval --control <variant> --treatment <variant> [options]
+  omk eval gold <init|validate|compare> ...
+
+常用选项：
+  --samples <path>                    用例文件（默认：eval-samples.json）
+  --skill-dir <path>                  skill 目录（默认：skills）
+  --control <expr>                    对照组 variant
+  --treatment <v1,v2>                 实验组 variant，逗号分隔
+  --config <path>                     eval.yaml / JSON 配置
+  --executor <name>                   执行器：claude / claude-sdk / codex / openai / gemini / custom
+  --model <name>                      任务执行模型（默认：sonnet）
+  --judge-models <list>               评委配置，例如 claude:haiku 或 claude:opus,openai:gpt-4o
+  --dry-run                           预览任务，不调用模型
+  --batch                             批量评测：每个 skill 独立 vs baseline
+  --bootstrap                         显式开启 bootstrap CI；omk eval 默认会自动开启
+  --bootstrap-samples <n>             bootstrap 重采样次数（默认：1000）
+  --threshold <number>                三层 gate 阈值（默认：3.5）
+  --trivial-diff <number>             实际可忽略 diff（默认：0.1）
+  --report-only / --no-gate           生成报告并打印 verdict，但始终 exit 0
+  --no-serve                          评测后不自动启动报告 server
+
+示例：
+  omk eval --control baseline --treatment my-skill                # 单 skill 必要性测试（baseline 是保留 variant 名，代表「不注入 skill 的裸基线」）
+  omk eval --control code-review-v1 --treatment code-review-v2    # 多版本 A/B
+  omk eval --config eval.yaml
+  omk eval gold compare v1-vs-v2-20260505-1200 --gold-dir gold-dataset
+`,
+        en: `
+omk eval — run offline skill evaluation and emit a ship/no-ship verdict
 
-  内部 = bench run + bench verdict, exit code 与 bench verdict 对齐:
-  PROGRESS / SOLO-PASS → 0; NOISE / UNDERPOWERED / CAUTIOUS / REGRESS → 1。
-  数据 underpowered 时直接 FAIL, 堵住"单轮过 PASS 就 deploy"漏洞。
+Usage:
+  omk eval --control <variant> --treatment <variant> [options]
+  omk eval gold <init|validate|compare> ...
 
-bench report 选项:
-  --port <number>        server 端口 (默认: 7799)
-  --reports-dir <path>   报告目录 (默认: ~/.oh-my-knowledge/reports/)
-  --export <id>          把报告导出为独立 HTML 文件
-  --dev                  开发模式: lib/ 文件改动时自动重启
+Common options:
+  --samples <path>                    Sample file (default: eval-samples.json)
+  --skill-dir <path>                  Skill directory (default: skills)
+  --control <expr>                    Control variant
+  --treatment <v1,v2>                 Treatment variants, comma-separated
+  --config <path>                     eval.yaml / JSON config
+  --executor <name>                   Executor: claude / claude-sdk / codex / openai / gemini / custom
+  --model <name>                      Task execution model (default: sonnet)
+  --judge-models <list>               Judge config, e.g. claude:haiku or claude:opus,openai:gpt-4o
+  --dry-run                           Preview tasks without model calls
+  --batch                             Batch evaluation: each skill independently against baseline
+  --bootstrap                         Enable bootstrap CI explicitly; omk eval turns it on by default
+  --bootstrap-samples <n>             Bootstrap resamples (default: 1000)
+  --threshold <number>                Three-layer gate threshold (default: 3.5)
+  --trivial-diff <number>             Practically negligible diff (default: 0.1)
+  --report-only / --no-gate           Produce the report and print verdict, but always exit 0
+  --no-serve                          Do not auto-start report server after evaluation
 
-bench gen-samples 选项:
-  --batch                为所有还没 eval-samples 的 skill 生成
-  --count <n>            每个 skill 生成多少条用例 (默认: 5)
-  --model <name>         生成用的模型 (默认: sonnet)
-  --skill-dir <path>     skill 目录 (默认: skills), 配合 --batch 用
+Examples:
+  omk eval --control baseline --treatment my-skill                # Single-skill necessity test (baseline is a reserved variant — "no skill injected")
+  omk eval --control code-review-v1 --treatment code-review-v2    # Multi-variant A/B
+  omk eval --config eval.yaml
+  omk eval gold compare v1-vs-v2-20260505-1200 --gold-dir gold-dataset
+`,
+    },
+    'cli.help.eval_gold': {
+        zh: `
+omk eval gold — 管理 human-gold 标注集
 
-analyze 选项:
-  <dir>                  输入: cc session JSONL 文件 / 目录
-                         (例如 ~/.claude/projects/<slug>)
-  --kb <path>            知识库根路径 (默认: 从 trace cwd 自动推断)
-  --last <duration>      时间窗口, 例如 "7d" / "30d" (默认: 全部)
-  --from <iso>           窗口起点 (ISO8601), 优先级高于 --last
-  --to <iso>             窗口终点 (ISO8601), 优先级高于 --last
-  --skills <n1,n2,...>   白名单要分析的 skill (默认: 全部)
-  --output-dir <path>    输出目录 (默认: ~/.oh-my-knowledge/analyses/)
+用法：
+  omk eval gold init [--out <dir>] [--annotator <name>]
+  omk eval gold validate <dir>
+  omk eval gold compare <reportId> --gold-dir <dir>
 
-bench evolve 选项:
-  --rounds <n>           最大演化轮数 (默认: 5)
-  --target <score>       达到该分数即提前停止
-  --samples <path>       用例文件 (默认: eval-samples.json)
-  --model <name>         任务执行模型 (默认: sonnet)
-  --judge-models <executor:model>  评委 (默认: claude:haiku, evolve 仅支持单评委)
-  --improve-model <name> 生成改进版的模型 (默认: sonnet)
-  --concurrency <n>      并发评测任务数 (默认: 1)
-  --timeout <seconds>    单任务执行超时 (秒, 默认: 120)
-  --executor <name>      执行器 (默认: claude)
+选项：
+  --reports-dir <path>                报告目录（compare 使用，默认：~/.oh-my-knowledge/reports）
+  --variant <name>                    指定 report 中要对比的 variant
+  --bootstrap-samples <n>             bootstrap 重采样次数（compare 使用）
+`,
+        en: `
+omk eval gold — manage human-gold annotation datasets
 
-通用选项:
-  --lang <zh|en>         CLI 输出语言 (默认: zh, 也可设 OMK_LANG 环境变量)
+Usage:
+  omk eval gold init [--out <dir>] [--annotator <name>]
+  omk eval gold validate <dir>
+  omk eval gold compare <reportId> --gold-dir <dir>
 
-示例:
-  omk bench run --control v1 --treatment v2
-  omk bench run --control baseline --treatment my-skill
-  omk bench run --control git:my-skill --treatment my-skill
-  omk bench run --control ./old-skill.md --treatment ./new-skill.md
-  omk bench run --control baseline --treatment v1,v2,v3
-  omk bench run --config eval.yaml
-  omk bench run --config eval.yaml --model sonnet-4.6   # CLI 覆盖配置
-  omk bench run --batch
-  omk bench run --dry-run
-  omk bench report --port 8080
-  omk bench report --export v1-vs-v2-20260326-1832
-  omk bench init my-eval
-  omk bench gen-samples skills/my-skill.md
+Options:
+  --reports-dir <path>                Reports directory for compare (default: ~/.oh-my-knowledge/reports)
+  --variant <name>                    Variant in the report to compare
+  --bootstrap-samples <n>             Bootstrap resamples for compare
+`,
+    },
+    'cli.help.observe': {
+        zh: `
+omk observe — 分析真实 session trace，生成 skill 健康度日报
+
+用法：
+  omk observe <sessions-dir> [options]
+
+选项：
+  --kb <path>                         知识库根路径（默认：从 trace cwd 推断）
+  --last <duration>                   时间窗口，例如 7d / 24h / 30m
+  --from <iso>                        窗口起点，优先级高于 --last
+  --to <iso>                          窗口终点，优先级高于 --last
+  --skills <n1,n2,...>                只分析指定 skill
+  --output-dir <path>                 输出目录（默认：~/.oh-my-knowledge/analyses）
 `,
         en: `
-oh-my-knowledge — Knowledge artifact evaluation toolkit
+omk observe — analyze production session traces and produce skill health reports
 
 Usage:
-  omk bench run [options]              Run an evaluation
-  omk bench report [options]           Start the report server
-  omk bench gate [options]             Run evaluation + apply gate, exit 0/1 (for CI/CD)
-  omk bench init [dir]                 Scaffold a new eval project
-  omk bench gen-samples [skill]        Generate eval-samples from skill content
-  omk bench diff <id1> <id2>           Compare two evaluation reports
-  omk bench evolve <skill>             Self-improve a skill through iterative evaluation
+  omk observe <sessions-dir> [options]
 
-  omk doctor [path]                    skill health check (pre-eval gate)
-  omk analyze <dir>                    Analyze cc session trace(s), produce skill health report (v0.18)
+Options:
+  --kb <path>                         Knowledge base root (default: infer from trace cwd)
+  --last <duration>                   Time window, e.g. 7d / 24h / 30m
+  --from <iso>                        Window start, overrides --last
+  --to <iso>                          Window end, overrides --last
+  --skills <n1,n2,...>                Only analyze selected skills
+  --output-dir <path>                 Output directory (default: ~/.oh-my-knowledge/analyses)
+`,
+    },
+    'cli.help.evolve': {
+        zh: `
+omk evolve — 多轮自动迭代改进 skill
+
+用法：
+  omk evolve <skill-path> [options]
+
+选项：
+  --rounds <n>                        迭代轮数（默认：5）
+  --target <score>                    目标分数
+  --model <name>                      任务执行模型，每轮跑 eval samples 的被测模型（默认：sonnet）
+  --improve-model <name>              skill 改写模型，每轮根据反馈改写 skill 的模型（默认：sonnet）
+  --judge-models <executor:model>     单评委配置（默认：claude:haiku）
+
+示例：
+  omk evolve skills/code-review/SKILL.md
+  omk evolve skills/code-review/SKILL.md --rounds 10 --target 4.5
+  omk evolve skills/code-review/SKILL.md --model sonnet --improve-model opus
+`,
+        en: `
+omk evolve — auto-iterate a skill through multi-round evaluation loops
 
-Options for "bench run":
+Usage:
+  omk evolve <skill-path> [options]
 
-  --samples <path>       Sample file (default: eval-samples.json)
-  --skill-dir <path>     Skill definitions directory (default: skills)
-  --control <expr>       Control-group variant expression (experiment role = control)
-  --treatment <v1,v2>    Treatment-group variant expressions (comma-separated; role = treatment)
-                         Each variant expression resolves to an artifact and optional runtime context:
-                           "baseline"       — bare model, no artifact injected
-                           "git:name"       — artifact from last commit
-                           "git:ref:name"   — artifact from specific commit
-                           path with "/"    — artifact from file directly (e.g. ./v1.md)
-                           "name@/cwd"      — attach runtime context / cwd
-                         At least one of --control / --treatment must be provided.
-  --config <path>        YAML/JSON config file (evaluation-as-code).
-                         Declares samples + variants + model + executor in one file.
-                         CLI flags override config fields when both are provided.
-                         Relative paths inside the config are resolved against its directory.
-  --model <name>         Task execution model (default: sonnet)
-  --output-dir <path>    Report output directory (default: ~/.oh-my-knowledge/reports/)
-  --no-judge             Skip LLM judging
-  --no-cache             Disable result caching
-  --dry-run              Preview tasks without executing
-  --blind                Blind A/B mode: hide variant names in report
-  --concurrency <n>      Number of parallel tasks (default: 1)
-  --timeout <seconds>    Executor timeout per task in seconds (default: 120)
-  --repeat <n>           Run evaluation N times for variance analysis (default: 1)
-  --judge-repeat <n>     Call LLM judge N times per (sample × dimension) for self-
-                         consistency (default: 1). High stddev across runs = the
-                         judge is unstable on this rubric and the score is noisy.
-  --judge-models <list>  Judge configuration. Comma-separated executor:model pairs,
-                         e.g. claude:haiku or claude:opus,openai:gpt-4o.
-                         1 entry = single judge (default claude:haiku); ≥ 2 entries
-                         = ensemble — every judge scores each (sample × dimension);
-                         the report includes per-judge breakdown + Pearson/MAD
-                         inter-judge agreement, which refutes "Claude judges Claude
-                         same-modality bias" critique. Combines with --judge-repeat.
-                         Cost ~ N_judges × N_repeat × N_samples.
-  --bootstrap            Compute bootstrap confidence intervals (distribution-free,
-                         preferred over t-interval for ordinal LLM scores). Adds
-                         per-variant CI on the mean + pairwise CI on treatment-vs-
-                         control difference (significant=0 outside CI). Reports both
-                         t-interval and bootstrap so old tooling still works.
-  --bootstrap-samples <n>  Number of bootstrap resamples (default 1000). N>10000
-                         triggers a stderr warning about runtime cost.
-  --retry <n>            Retry failed tasks up to N times with exponential backoff (default: 0)
-  --resume <report-id>   Resume from a previous report, skipping completed tasks
-  --executor <name>      Executor: claude, claude-sdk, codex, openai, gemini,
-                         anthropic-api, openai-api, or any shell command (e.g. "python my_provider.py")
-  --batch                Batch evaluation: each skill independently against baseline
-                         Requires {name}.eval-samples.json paired with each skill
-  --skip-connectivity    Skip LLM model connectivity check (auto-skipped when --resume)
-  --mcp-config <path>    MCP config file for URL fetching via MCP servers
-                         (default: .mcp.json in current directory)
-  --no-serve             Skip auto-starting report server after evaluation
-  --verbose              Print detailed progress for each sample (exec result, grading phases)
-  --layered-stats        Expand the three-layer (fact/behavior/judge) independent
-                         significance breakdown in the HTML report by default.
-                         Without this flag, the breakdown is collapsed behind a
-                         click-to-expand summary under each comparison.
-  --strict-baseline      (default ON) Isolate skill auto-discovery + Skill tool
-                         use for baseline-kind variants. Cuts the ~/.claude/skills/
-                         contamination path so skill evaluations have valid
-                         construct validity. Explicit eval.yaml allowedSkills
-                         takes precedence.
-  --no-strict-baseline   Explicitly turn strict-baseline OFF (baseline sees all
-                         auto-discovered skills). Use only in narrow scenarios
-                         (e.g. measuring how much a skill doc adds on top of
-                         full default discovery). Pre-flight emits a stderr
-                         warning when this flag is set, because
-                         verdict / Δ are vulnerable to skill contamination.
+Options:
+  --rounds <n>                        Iteration rounds (default: 5)
+  --target <score>                    Target score
+  --model <name>                      Task executor model — runs eval samples each round (default: sonnet)
+  --improve-model <name>              Skill rewriter model — rewrites the skill each round (default: sonnet)
+  --judge-models <executor:model>     Single judge config (default: claude:haiku)
 
-Options for "bench gate":
-  (same as "bench run", plus:)
-  --threshold <number>   Three-layer gate threshold (fact / behavior / LLM judge),
-                         applied INDEPENDENTLY to each layer. ANY layer below
-                         threshold fails the gate — prevents composite averaging
-                         from masking a single-layer collapse. Default: 3.5.
-                         If all three layers are absent (no
-                         assertions and no rubric defined in eval-samples), the
-                         gate FAILS with a configuration hint — no composite fallback.
-  --trivial-diff <num>   Smallest diff to treat as practically meaningful
-                         (default 0.1). Bootstrap diff CI may be statistically
-                         significant but with |Δ| < this value, treated as
-                         CAUTIOUS rather than PROGRESS.
+Examples:
+  omk evolve skills/code-review/SKILL.md
+  omk evolve skills/code-review/SKILL.md --rounds 10 --target 4.5
+  omk evolve skills/code-review/SKILL.md --model sonnet --improve-model opus
+`,
+    },
+    'cli.help.sample': {
+        zh: `
+omk sample — 生成或补齐 eval-samples 评测用例
 
-  Internally = bench run + bench verdict. Exit code aligns with bench verdict:
-  PROGRESS / SOLO-PASS → 0; NOISE / UNDERPOWERED / CAUTIOUS / REGRESS → 1.
-  Underpowered runs fail directly — closes the "single-run PASS = deploy" loophole.
+用法：
+  omk sample <skill-path> [options]
+  omk sample --batch [--skill-dir <dir>] [options]
 
-Options for "bench report":
-  --port <number>        Server port (default: 7799)
-  --reports-dir <path>   Reports directory (default: ~/.oh-my-knowledge/reports/)
-  --export <id>          Export report as standalone HTML file
-  --dev                  Dev mode: auto-restart on lib/ file changes
+选项：
+  --count <n>                         生成用例数量（默认：5）
+  --model <name>                      生成模型（默认：sonnet）
+  --batch                             为 skill 目录下缺少 eval-samples 的 skill 批量生成
+  --skill-dir <path>                  skill 目录（batch 使用，默认：skills）
+`,
+        en: `
+omk sample — generate or fill eval-samples test cases
 
-Options for "bench gen-samples":
-  --batch                Generate for all skills missing eval-samples
-  --count <n>            Number of samples to generate per skill (default: 5)
-  --model <name>         Model for generation (default: sonnet)
-  --skill-dir <path>     Skill directory (default: skills), used with --batch
+Usage:
+  omk sample <skill-path> [options]
+  omk sample --batch [--skill-dir <dir>] [options]
 
-Options for "analyze":
-  <dir>                  Input: cc session JSONL file / dir (e.g. ~/.claude/projects/<slug>)
-  --kb <path>            Knowledge base root (default: auto-infer from trace cwd)
-  --last <duration>      Time window like "7d" / "30d" (default: all)
-  --from <iso>           Window start (ISO8601), takes precedence over --last
-  --to <iso>             Window end (ISO8601), takes precedence over --last
-  --skills <n1,n2,...>   Whitelist skills to analyze (default: all)
-  --output-dir <path>    Output dir (default: ~/.oh-my-knowledge/analyses/)
+Options:
+  --count <n>                         Number of test cases to generate (default: 5)
+  --model <name>                      Generation model (default: sonnet)
+  --batch                             Generate for skills that are missing eval-samples
+  --skill-dir <path>                  Skill directory for batch mode (default: skills)
+`,
+    },
+    'cli.help.studio': {
+        zh: `
+omk studio — 打开本地知识工作台
+
+用法：
+  omk studio [options]
+
+选项：
+  --port <n>                          本地服务端口（默认：7799）
+  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
+  --analyses-dir <path>               观测分析目录
+  --no-open                           只启动服务，不自动打开浏览器
+  --dev                               开发模式：文件变化时自动重启
+
+示例：
+  omk studio
+  omk studio --port 7798
+  omk studio --no-open
+`,
+        en: `
+omk studio — open the local knowledge workbench
 
-Options for "bench evolve":
-  --rounds <n>           Maximum evolution rounds (default: 5)
-  --target <score>       Stop early when score reaches this threshold
-  --samples <path>       Sample file (default: eval-samples.json)
-  --model <name>         Task execution model (default: sonnet)
-  --judge-models <executor:model>  Judge config (default: claude:haiku; evolve is single-judge only)
-  --improve-model <name> Model for generating improvements (default: sonnet)
-  --concurrency <n>      Parallel eval tasks (default: 1)
-  --timeout <seconds>    Executor timeout per task in seconds (default: 120)
-  --executor <name>      Executor to use (default: claude)
+Usage:
+  omk studio [options]
 
-Common options:
-  --lang <zh|en>         CLI output language (default: zh, also via OMK_LANG env)
+Options:
+  --port <n>                          Local server port (default: 7799)
+  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
+  --analyses-dir <path>               Observation analyses directory
+  --no-open                           Start the server without opening a browser
+  --dev                               Dev mode: restart on file changes
 
 Examples:
-  omk bench run --control v1 --treatment v2
-  omk bench run --control baseline --treatment my-skill
-  omk bench run --control git:my-skill --treatment my-skill
-  omk bench run --control ./old-skill.md --treatment ./new-skill.md
-  omk bench run --control baseline --treatment v1,v2,v3
-  omk bench run --config eval.yaml
-  omk bench run --config eval.yaml --model sonnet-4.6   # CLI overrides config
-  omk bench run --batch
-  omk bench run --dry-run
-  omk bench report --port 8080
-  omk bench report --export v1-vs-v2-20260326-1832
-  omk bench init my-eval
-  omk bench gen-samples skills/my-skill.md
+  omk studio
+  omk studio --port 7798
+  omk studio --no-open
 `,
     },
-    'cli.help.diff_usage': {
-        zh: [
-            '用法:',
-            '  omk bench diff <reportId>                     单 report 内 sample 级 diff',
-            '  omk bench diff <reportId1> <reportId2>        跨 report variant 级 diff',
-            '',
-            '选项:',
-            '  --regressions-only          只列 treatment < control 的用例',
-            '  --threshold <num>           回退判定阈值 (默认 0, 即任何负 Δ 都算回退)',
-            '  --variant <name>            within-report 模式下指定要钻取的 variant (默认: variants[1])',
-            '  --top <n>                   只列差距最大的前 N 个用例',
-        ].join('\n'),
-        en: [
-            'Usage:',
-            '  omk bench diff <reportId>                     within-report per-sample diff',
-            '  omk bench diff <reportId1> <reportId2>        cross-report variant-level diff',
-            '',
-            'Options:',
-            '  --regressions-only          show only samples where treatment < control',
-            '  --threshold <num>           regression threshold (default 0, any negative Δ counts)',
-            '  --variant <name>            within-report mode: which variant to drill (default: variants[1])',
-            '  --top <n>                   only show top N samples by absolute diff',
-        ].join('\n'),
-    },
-    'cli.help.analyze_usage': {
-        zh: '用法: omk analyze <dir> [--kb <path>] [--last 7d] [--from ISO] [--to ISO] [--skills name1,name2]',
-        en: 'Usage: omk analyze <dir> [--kb <path>] [--last 7d] [--from ISO] [--to ISO] [--skills name1,name2]',
-    },
-    'cli.help.gold': {
-        zh: [
-            '',
-            '用法: omk bench gold <subcommand>',
-            '',
-            '子命令:',
-            '  init [--out <dir>] [--annotator <id>]    生成空白 gold dataset 模板',
-            '  validate <dir>                           校验数据集结构',
-            '  compare <reportId> --gold-dir <dir>      与已有 report 计算 α / κ / Pearson',
-            '    [--variant <name>] [--reports-dir <d>]',
-            '    [--bootstrap-samples N] [--seed N]',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench gold <subcommand>',
-            '',
-            'Subcommands:',
-            '  init [--out <dir>] [--annotator <id>]    create a blank gold dataset template',
-            '  validate <dir>                           validate dataset structure',
-            '  compare <reportId> --gold-dir <dir>      compute α / κ / Pearson against an existing report',
-            '    [--variant <name>] [--reports-dir <d>]',
-            '    [--bootstrap-samples N] [--seed N]',
-            '',
-        ].join('\n'),
-    },
-    'cli.help.debias_validate': {
-        zh: [
-            '',
-            '用法: omk bench debias-validate <kind> <reportId> [options]',
-            '',
-            '类别:',
-            '  length    用相反的长度去偏设置重新评判, 并对分数差出 bootstrap CI。',
-            '            judge 成本约为原评判的两倍。',
-            '',
-            '选项:',
-            '  --reports-dir <dir>          报告存储目录 (默认: ~/.oh-my-knowledge/reports)',
-            '  --samples <path>             覆盖用例文件 (默认: 从 report.meta.request 读)',
-            '  --variant <name>             校验哪个 variant (默认: 第一个)',
-            '  --judge-models <executor:model>  评委 (默认: 沿用 report.meta.judgeModels[0]; debias-validate 仅支持单评委)',
-            '  --bootstrap-samples N        bootstrap 迭代次数 (默认 1000)',
-            '  --seed N                     固定 CI 随机种子',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench debias-validate <kind> <reportId> [options]',
-            '',
-            'Kinds:',
-            '  length    re-judge with the opposite length-debias setting and bootstrap CI',
-            '            on the score diff. Cost ~doubles vs the original judge pass.',
-            '',
-            'Options:',
-            '  --reports-dir <dir>          report store dir (default: ~/.oh-my-knowledge/reports)',
-            '  --samples <path>             override samples file (default: from report.meta.request)',
-            '  --variant <name>             which variant to validate (default: first)',
-            '  --judge-models <executor:model>  Judge (default: from report.meta.judgeModels[0]; debias-validate is single-judge only)',
-            '  --bootstrap-samples N        bootstrap iterations (default 1000)',
-            '  --seed N                     deterministic CI seed',
-            '',
-        ].join('\n'),
-    },
-    'cli.help.saturation': {
-        zh: [
-            '',
-            '用法: omk bench saturation <reportId> [options]',
-            '',
-            '回答 "我跑够用例了吗?"。复述已有 report 中持久化的饱和判定。',
-            '',
-            '注: 本命令读取 run 时跑出的 verdict (运行时已用 method=bootstrap-ci-width',
-            '默认阈值 + 3 窗口持续条件)。如要换 method/threshold 重新计算, 需要重跑',
-            '`omk bench run --repeat ≥ 5` (运行时持久化的 trace 不含原始分数, 无法',
-            '在事后用其他参数复算)。',
-            '',
-            '选项:',
-            '  --reports-dir <dir>   报告存储目录 (默认: ~/.oh-my-knowledge/reports)',
-            '  --variant <name>      只看一个 variant (默认: 全部)',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench saturation <reportId> [options]',
-            '',
-            'Answers "do I have enough samples?". Replays the saturation verdict',
-            'persisted in an existing report.',
-            '',
-            'Note: this command reads the verdict computed at run time (which used',
-            'method=bootstrap-ci-width with default threshold + 3-window sustained',
-            'condition). To re-compute with a different method/threshold, re-run',
-            '`omk bench run --repeat ≥ 5` (the persisted trace does not include raw',
-            'scores, so post-hoc parameter sweeps are not possible here).',
-            '',
-            'Options:',
-            '  --reports-dir <dir>   report store dir (default: ~/.oh-my-knowledge/reports)',
-            '  --variant <name>      only show one variant (default: all)',
-            '',
-        ].join('\n'),
-    },
-    'cli.help.verdict': {
-        zh: [
-            '',
-            '用法: omk bench verdict <reportId> [options]',
-            '',
-            '聚合 bootstrap CI / 三层 ci-gate / saturation / human α, 给出一行结论。',
-            '',
-            'Verdict 等级:',
-            '  PROGRESS      显著改进 + 三层全过',
-            '  CAUTIOUS      改进真实但有警告 (gate 破 / 幅度太小 / 控制组本身崩)',
-            '  REGRESS       显著回退 — 不要 ship',
-            '  NOISE         CI 跨 0, 无法判定',
-            '  UNDERPOWERED  用例不足, 需要扩 N 重测',
-            '  SOLO          单 variant 报告, 没有对比对象',
-            '',
-            '选项:',
-            '  --reports-dir <dir>      报告存储目录 (默认: ~/.oh-my-knowledge/reports)',
-            '  --threshold <num>        三层 gate 阈值 (默认 3.5, 与 omk bench gate 对齐)',
-            '  --trivial-diff <num>     "幅度太小" 阈值 (默认 0.1)',
-            '  --verbose                展开每个 pair 的详情',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench verdict <reportId> [options]',
-            '',
-            'Aggregates bootstrap CI / 3-layer ci-gate / saturation / human α into a one-line verdict.',
-            '',
-            'Verdict levels:',
-            '  PROGRESS      significant improvement + all 3 layers pass',
-            '  CAUTIOUS      real improvement but with warnings (gate fails / diff too small / control collapsed)',
-            '  REGRESS       significant regression — do not ship',
-            '  NOISE         CI crosses 0, no verdict',
-            '  UNDERPOWERED  not enough samples, expand N and re-run',
-            '  SOLO          single-variant report, nothing to compare against',
-            '',
-            'Options:',
-            '  --reports-dir <dir>      report store dir (default: ~/.oh-my-knowledge/reports)',
-            '  --threshold <num>        3-layer gate threshold (default 3.5, matches omk bench gate)',
-            '  --trivial-diff <num>     "diff too small" threshold (default 0.1)',
-            '  --verbose                expand per-pair details',
-            '',
-        ].join('\n'),
-    },
-    'cli.help.diagnose': {
-        zh: [
-            '',
-            '用法: omk bench diagnose <reportId> [options]',
-            '',
-            '诊断用例集本身的质量问题: 区分度低 / 重复 / 歧义 / 成本异常 / 全 fail。',
-            '回答 "测评结论是否被坏用例污染" — 与 omk bench verdict 互补。',
-            '',
-            '选项:',
-            '  --reports-dir <dir>      报告存储目录',
-            '  --samples <path>         用例文件路径 (用于 near-duplicate 检测; 默认从 report.meta.request 读)',
-            '  --top <n>                每类只显示前 N 个 (默认 10, 0=全部)',
-            '  --duplicate-rouge <num>  near-duplicate ROUGE-1 阈值 (默认 0.7)',
-            '  --ambiguous-stddev <num> 歧义阈值, judge stddev (默认 1.0, 需要 --judge-repeat ≥ 2 数据)',
-            '  --cost-k <num>           成本异常倍数 vs 中位数 (默认 3)',
-            '  --latency-k <num>        耗时异常倍数 vs 中位数 (默认 3)',
-            '  --flat <num>             flat_scores 分差阈值 (默认 0.5)',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench diagnose <reportId> [options]',
-            '',
-            'Diagnose quality issues in the sample set itself: low discrimination /',
-            'duplicates / ambiguity / cost anomalies / all-fail. Answers "is the verdict',
-            'tainted by bad samples?" — complements omk bench verdict.',
-            '',
-            'Options:',
-            '  --reports-dir <dir>      report store dir',
-            '  --samples <path>         sample file path (for near-duplicate detection; defaults to report.meta.request)',
-            '  --top <n>                top N per category (default 10, 0=all)',
-            '  --duplicate-rouge <num>  near-duplicate ROUGE-1 threshold (default 0.7)',
-            '  --ambiguous-stddev <num> ambiguity threshold, judge stddev (default 1.0, requires --judge-repeat ≥ 2)',
-            '  --cost-k <num>           cost-outlier multiplier vs median (default 3)',
-            '  --latency-k <num>        latency-outlier multiplier vs median (default 3)',
-            '  --flat <num>             flat_scores spread threshold (default 0.5)',
-            '',
-        ].join('\n'),
-    },
-    'cli.help.failures': {
-        zh: [
-            '',
-            '用法: omk bench failures <reportId> [options]',
-            '',
-            '把已有 report 的失败用例喂给一次 LLM 调用, 自动聚类并给出修复建议。',
-            '失败定义: compositeScore < threshold 或 ok=false。',
-            '',
-            '选项:',
-            '  --reports-dir <dir>      报告存储目录',
-            '  --judge-models <executor:model>  评委 (默认: 沿用 report.meta.judgeModels[0]; failures 仅支持单评委)',
-            '  --max-clusters <n>       最多聚成几类 (默认 5)',
-            '  --threshold <num>        compositeScore < threshold 算失败 (默认 3)',
-            '  --max-feed <n>           最多喂给 LLM 多少条 (默认 50, 超出取最差)',
-            '',
-        ].join('\n'),
-        en: [
-            '',
-            'Usage: omk bench failures <reportId> [options]',
-            '',
-            'Feed failing samples from an existing report to a single LLM call, auto-cluster',
-            'them, and produce per-cluster fix suggestions.',
-            'Failure definition: compositeScore < threshold or ok=false.',
-            '',
-            'Options:',
-            '  --reports-dir <dir>      report store dir',
-            '  --judge-models <executor:model>  Judge (default: from report.meta.judgeModels[0]; failures is single-judge only)',
-            '  --max-clusters <n>       max number of clusters (default 5)',
-            '  --threshold <num>        compositeScore < threshold counts as failure (default 3)',
-            '  --max-feed <n>           max samples to feed the LLM (default 50, takes the worst)',
-            '',
-        ].join('\n'),
-    },
-    // sample design coverage block strings
-    'cli.diagnose.coverage_header': {
-        zh: '用例设计覆盖度 (Sample design coverage):',
-        en: 'Sample design coverage:',
-    },
-    'cli.diagnose.coverage_unspecified': {
-        zh: '(未声明)',
-        en: '(unspecified)',
-    },
-    'cli.diagnose.coverage_chars': {
-        zh: '字符',
-        en: 'chars',
-    },
-    'cli.diagnose.coverage_hint_empty': {
-        zh: 'ℹ 该用例集未声明任何 capability / difficulty / construct / provenance 元数据。详见 docs/sample-design-spec.md',
-        en: 'ℹ No samples in this set declare capability / difficulty / construct / provenance metadata. See docs/sample-design-spec.md',
-    },
-    'cli.diagnose.coverage_declared': {
-        zh: '声明',
-        en: 'declared',
-    },
     // ============ omk doctor 健康检查 ============
     'cli.doctor.rule.skill_readable': {
         zh: 'skill 文件可读',
@@ -970,6 +681,67 @@ Examples:
         zh: '用例 ↔ skill 输入约定',
         en: 'samples ↔ skill contract',
     },
+    'cli.doctor.rule.skill_health_check': {
+        zh: '健康度体检',
+        en: 'Health check',
+    },
+    // ============ skill_health composer (CLI default; --static-only disables it) ============
+    'cli.doctor.health.skipped': {
+        zh: '健康度体检已跳过(runHealthCheck=false)',
+        en: 'health check skipped (runHealthCheck=false)',
+    },
+    'cli.doctor.health.no_dimensions': {
+        zh: '没有注册任何健康度维度,跳过',
+        en: 'no health dimensions registered, skipped',
+    },
+    'cli.doctor.health.fail.executor': {
+        zh: 'LLM 调用失败: {error}',
+        en: 'LLM call failed: {error}',
+    },
+    'cli.doctor.health.fail.parse': {
+        zh: 'LLM 输出解析失败: {error}',
+        en: 'failed to parse LLM output: {error}',
+    },
+    'cli.doctor.health.fail.empty_output': {
+        zh: 'LLM 返回了空输出',
+        en: 'LLM returned empty output',
+    },
+    'cli.doctor.health.hint.executor': {
+        zh: '检查 executor 配置(--executor / --model)与网络连通,或调大 --timeout',
+        en: 'Verify executor config (--executor / --model) and connectivity, or raise --timeout',
+    },
+    'cli.doctor.health.hint.parse': {
+        zh: 'LLM 没返回合法 JSON;原文存在 detail.rawOutput 截断片段,可重跑或换 model',
+        en: 'LLM did not return valid JSON; raw snippet stored in detail.rawOutput. Re-run or switch model',
+    },
+    'cli.doctor.health.dim.message': {
+        zh: '{level}: 错误 {err}/警告 {warn}/建议 {sug}',
+        en: '{level}: error {err}/warn {warn}/suggest {sug}',
+    },
+    'cli.doctor.health.dim.missing': {
+        zh: 'LLM 未输出此维度({dim}),已置不适用',
+        en: 'LLM omitted dimension ({dim}); treated as N/A',
+    },
+    'cli.doctor.health.summary.label': {
+        zh: '健康度总览',
+        en: 'Health summary',
+    },
+    'cli.doctor.health.summary.message': {
+        zh: '{overall} | 维度: 健康 {h}/亚健康 {sh}/不健康 {bad}/不适用 {na} | finding: 错误 {err}/警告 {warn}/建议 {sug}',
+        en: '{overall} | dims: healthy {h}/sub {sh}/unhealthy {bad}/n-a {na} | findings: err {err}/warn {warn}/sug {sug}',
+    },
+    'cli.doctor.health.summary.no_top': {
+        zh: '完整详情见 --json 输出或 --html 报告',
+        en: 'Full detail in --json output or --html report',
+    },
+    // 7 内置维度 labelKey (id-based)
+    'cli.doctor.health.dim.trigger-boundary': { zh: '触发与边界', en: 'Trigger & boundary' },
+    'cli.doctor.health.dim.doc-clarity': { zh: '文档清晰', en: 'Documentation clarity' },
+    'cli.doctor.health.dim.instr-precision': { zh: '指令精确性', en: 'Instruction precision' },
+    'cli.doctor.health.dim.dependency': { zh: '依赖检查', en: 'Dependency check' },
+    'cli.doctor.health.dim.tool-conventions': { zh: '工具规范', en: 'Tool conventions' },
+    'cli.doctor.health.dim.security': { zh: '安全与合规', en: 'Security & compliance' },
+    'cli.doctor.health.dim.examples': { zh: '示例完备', en: 'Example completeness' },
     // pass
     'cli.doctor.skill_readable.pass': {
         zh: 'skill 内容长度 {length} 字符',
@@ -1084,10 +856,10 @@ Examples:
     // ============ omk doctor CLI level ============
     'cli.help.doctor_usage': {
         zh: `
-oh-my-knowledge — omk doctor 健康检查
+oh-my-knowledge — omk doctor 健康度体检 (LLM-judge)
 
 用法:
-  omk doctor [path]                    在 path 上跑评测前置健康检查
+  omk doctor [path]                    在 path 上跑深度健康度体检
   omk doctor                           在当前目录(或 ./skills)批量跑
 
 参数:
@@ -1095,66 +867,80 @@ oh-my-knowledge — omk doctor 健康检查
 
 选项:
   --json                 把 DoctorReport 打到 stdout(CI 消费用)
-  --gate                 静默模式: 通过 exit 0 / 不通过 exit 1, 仅 stderr 出问题摘要
-  --executor <name>      executor 名(仅向后兼容, doctor 不直接打 LLM)
-  --model <name>         model 名(同上)
-  --timeout <seconds>    rule 执行超时(默认 8)
+  --gate                 静默模式: fatal 问题 exit 1; warnings_only 仍 exit 0, 仅 stderr 出摘要
+  --executor <name>      LLM executor (默认 claude, 可换 anthropic-api/codex 等)
+  --model <name>         模型 (默认 sonnet)
+  --samples <path>       显式指定评测用例文件
+  --timeout <seconds>    单次 LLM 会话超时 (默认 600)
+  --html <path>          产出可视化 HTML 报告到 <path> (可与 --json 同时用)
+  --static-only          离线模式: 只跑静态检查 (skill 可读性 / 元数据 / 依赖 / samples 契约), 不调 LLM
   --lang <zh|en>         切换输出语言
 
 示例:
-  omk doctor examples/code-review/skills/v1.md
-  omk doctor examples/code-review/skills --json | jq .outcome  # passed | warnings_only | failed
-  omk doctor --gate; echo $?
-
-doctor 检查项(纯静态 / 零 LLM 调用):
-  - skill 文件可读 + 内容有最小长度
-  - skill 元数据合法 (front-matter 若有)
-  - 前置依赖完整 (引用的 CLI 工具 / 文件 / 环境变量 / preflight 命令)
-  - 用例 ↔ skill 输入约定 (warn 级, 仅传 samples 时跑)
-
-executor / judge 连通性由 evaluation preflight 负责, 不在 doctor 范围内。
-omk bench run / omk bench gate 内置 doctor 强制门禁, 不可 skip — 静态检查
-零成本无理由跳过。LLM 连通性可用 --skip-connectivity 跳过 (--resume 时自动)。
+  omk doctor my-skill --html /tmp/report.html             # 深度体检 + HTML 报告 (默认)
+  omk doctor examples/code-review/skills --json > r.json   # JSON 给 CI / 外部工具消费
+  omk doctor --gate; echo $?                               # CI 模式: fatal 问题 exit 1, 警告不阻断
+  omk doctor --static-only                                 # 无 LLM 环境 (CI / 断网) 跑纯静态检查
+
+doctor = LLM 健康度体检 (单次 LLM 会话):
+  - 7 个内置维度: 触发与边界 / 文档清晰 / 指令精确性 / 依赖检查 / 工具规范 / 安全与合规 / 示例完备
+  - 用户可扩展: 在自己代码里 registerHealthDimension(spec) 加自定义维度,
+    会自动加入同一次 LLM 调用的 prompt + 报告 (顺序 = 注册顺序)
+  - 每维度独立给 健康/亚健康/不健康/不适用 + findings + 改进建议
+  - HTML 报告: 维度按 fail→warn→pass→skipped 排, 错误 finding 排前面
+
+注: omk eval 内部仍跑静态 skill-readability/metadata/dependency
+gate 保护评测质量, 不走 omk doctor 这条 LLM 路径 (角色分离: doctor=审计, eval=评测)。
+LLM 连通性可用 omk eval --skip-connectivity 跳过 (--resume 时自动)。
 `.trim() + '\n',
         en: `
-oh-my-knowledge — omk doctor health check
+oh-my-knowledge — omk doctor health audit (LLM-judge)
 
 Usage:
-  omk doctor [path]                    Run pre-evaluation health check on path
-  omk doctor                           Batch check current dir (or ./skills)
+  omk doctor [path]                    Run deep LLM-based health audit on path
+  omk doctor                           Batch audit current dir (or ./skills)
 
 Arguments:
-  path                   A .md file, directory, or omit (= cwd). Directory mode batches all skills.
+  path                   A .md file, directory, or omit (= cwd). Directory batches all skills.
 
 Options:
   --json                 Print DoctorReport JSON to stdout (CI-friendly)
-  --gate                 Silent mode: exit 0 if pass, exit 1 if fail; brief stderr summary only
-  --executor <name>      executor name (kept for compat; doctor does not call LLM)
-  --model <name>         model name (same)
-  --timeout <seconds>    per-rule timeout (default 8)
+  --gate                 Silent mode: exit 1 only on fatal failure; warnings_only exits 0
+  --executor <name>      LLM executor (default 'claude'; switchable to anthropic-api/codex etc)
+  --model <name>         model name (default 'sonnet')
+  --samples <path>       Explicit eval samples file
+  --timeout <seconds>    LLM session timeout (default 600)
+  --html <path>          Also write a visual HTML report to <path> (combines with --json)
+  --static-only          Offline mode: run only static checks (readability / metadata / deps / samples contract); no LLM call
   --lang <zh|en>         Output language
 
 Examples:
-  omk doctor examples/code-review/skills/v1.md
-  omk doctor examples/code-review/skills --json | jq .outcome  # passed | warnings_only | failed
-  omk doctor --gate; echo $?
-
-Checks (pure static / zero LLM calls):
-  - skill file readable + minimum content length
-  - skill metadata valid (front-matter if present)
-  - dependencies present (referenced CLI tools / files / env vars / preflight commands)
-  - samples ↔ skill contract (warn-level, only when samples provided)
-
-executor / judge connectivity is handled by evaluation preflight, not doctor.
-omk bench run / omk bench gate run doctor as mandatory; no skip flag — static
-checks cost nothing to run. LLM connectivity can be skipped with --skip-connectivity
-(auto-skipped on --resume).
+  omk doctor my-skill --html /tmp/report.html             # deep audit + HTML report (default)
+  omk doctor examples/code-review/skills --json > r.json   # JSON for CI / external tools
+  omk doctor --gate; echo $?                               # CI mode: fatal failures exit 1; warnings do not block
+  omk doctor --static-only                                 # offline (CI / no LLM) static checks only
+
+doctor = LLM health audit (single LLM session):
+  - 7 builtin dimensions: trigger & boundary / doc clarity / instruction precision /
+    dependency / tool conventions / security & compliance / example completeness
+  - User-extensible: call registerHealthDimension(spec) in your code to add custom
+    dimensions; they join the same LLM call's prompt + report (order = registration order)
+  - Each dim graded healthy / sub-healthy / unhealthy / N-A + findings + suggestions
+  - HTML report: dims sorted fail→warn→pass→skipped; errors first within each dim
+
+Note: omk eval still runs static skill-readability/metadata/dependency gates
+internally (separate from this doctor command). Roles: doctor=audit, eval=evaluate.
+LLM connectivity for omk eval can be skipped with --skip-connectivity (auto on --resume).
 `.trim() + '\n',
     },
     'cli.doctor.no_skill_found': {
         zh: '未在 {path} 下发现 skill 文件。\n  doctor 期望 .md 文件、目录(包含 .md 或 SKILL.md)或 cwd 下的 skills/ 子目录。',
         en: 'No skills found at {path}.\n  doctor expects a .md file, a directory (containing .md or SKILL.md), or skills/ under cwd.',
     },
+    'cli.doctor.samples_detected': {
+        zh: '✓ 使用评测用例文件：{path}',
+        en: '✓ Using eval samples file: {path}',
+    },
     'cli.doctor.gate_blocked': {
         zh: 'skill 健康检查未通过, 评测已中止。doctor 是评测必经环节, 无 skip 选项 — 请修复上述问题后重跑。',
         en: 'skill health check failed; evaluation aborted. doctor is mandatory and not skippable — fix the issues above and re-run.',