oh-my-knowledge 0.27.0 → 0.29.0

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

@@ -16,9 +16,7 @@
  * 2. **保留原文的白名单 (产品术语 / 命令 / 文件名)**
  *    以下 token 在两种语言里都保留原文, 不翻译:
  *    - 产品名: omk, oh-my-knowledge, Claude, npm
- *    - 子命令空间和命令名: init, doctor, eval, observe, improve, export,
- *      studio, samples, skill, plan, failures, gold, debias, diff, verdict,
- *      saturation
+ *    - 命令名: init, doctor, eval, observe, evolve, sample, studio, gold
  *    - omk 核心业务术语: skill, variant, sample, judge, executor (出现在产品
  *      UI 里时首字母可大写如 "Skill 评测", 描述句中保持小写)
  *    - 技术参数: --lang, --control, --treatment, --bootstrap, --judge-repeat,
@@ -73,7 +71,7 @@ export const CLI_DICT = {
         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。',
+        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。',
         en: '\nNote: during omk evaluation the full SKILL.md (frontmatter included) is injected as the system prompt — uniformly across executors (claude / codex / openai-api / gemini all take the same path; omk does not rely on any executor\'s native skill auto-discovery or Skill tool). Frontmatter has no measurable impact on model behavior in this position.\nThe template ships with Claude Code-compatible frontmatter (name + description) so the same directory-skill can also be deployed to Claude Code: copy the whole directory to ~/.claude/skills/code-review-v1/ (the directory, not just SKILL.md) so Claude SDK can recognize it. That is a bonus beyond omk evaluation — one source, two-way dogfood.',
     },
     'cli.update.new_version_available': {
@@ -213,8 +211,8 @@ export const CLI_DICT = {
         en: '\n💡 Non-interactive environment, skipping report server\n',
     },
     'cli.run.no_serve_view_hint': {
-        zh: '   导出报告：omk export {id} --reports-dir {dir}\n',
-        en: '   Export report: omk export {id} --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',
@@ -260,18 +258,6 @@ export const CLI_DICT = {
         zh: '⚠ 加载 samples 文件失败 ({path}): {message}\n',
         en: '⚠ Failed to load samples file ({path}): {message}\n',
     },
-    'cli.export.unsupported_format': {
-        zh: '不支持的导出格式：{format}。可用格式：html / markdown / github-summary。',
-        en: 'Unsupported export format: {format}. Available: html / markdown / github-summary.',
-    },
-    'cli.export.html_done': {
-        zh: '已导出 HTML：{path}',
-        en: 'HTML exported to: {path}',
-    },
-    'cli.export.done': {
-        zh: '已导出：{path}',
-        en: 'Exported to: {path}',
-    },
     'cli.studio.started': {
         zh: 'studio 已启动：{url}',
         en: 'Studio running at {url}',
@@ -309,8 +295,8 @@ export const CLI_DICT = {
         en: '\nGenerated {n} eval-samples files. Review them, then run: omk eval --batch',
     },
     'cli.gen.specify_skill_path': {
-        zh: '请指定 skill 文件路径, 例如: omk improve samples skills/my-skill.md',
-        en: 'Please specify a skill file path, e.g.: omk improve 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 已存在。如需覆盖请先删除该文件。',
@@ -333,8 +319,8 @@ export const CLI_DICT = {
         en: 'Generation failed: {message}',
     },
     'cli.evolve.specify_skill_path': {
-        zh: '请指定 skill 文件路径, 例如: omk improve skill skills/my-skill.md',
-        en: 'Please specify a skill file path, e.g.: omk improve skill 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=== Improve skill: {path} ===\n',
@@ -365,28 +351,27 @@ export const CLI_DICT = {
         en: 'All versions saved at: {dir}/\n',
     },
     'cli.evolve.report_link': {
-        zh: '📊 评测报告：omk export {id} --format html\n',
-        en: '📊 Report: omk export {id} --format html\n',
+        zh: '📊 查看报告：omk studio（报告 ID：{id}）\n',
+        en: '📊 View report: omk studio (report id: {id})\n',
     },
     'cli.help.product_main': {
         zh: `
-oh-my-knowledge — 知识载体工作台
+oh-my-knowledge——知识载体工作台
 
 用法：
   omk init [dir]                      初始化一个 skill 评测项目
-  omk doctor [path]                   静态健康检查：结构、依赖、样本、配置、污染风险
+  omk doctor [path]                   LLM 健康度审计（7 内置维度 + 可扩展）；--static-only 切离线静态模式
   omk eval [options]                  离线评测：比较版本，输出 verdict + report
   omk observe <sessions-dir>          线上观测：真实 session、gap、失败率、inbox
-  omk improve <report-id>             改进建议：样本质量、失败聚类、skill patch 线索
-  omk export <report-id> [options]    证据导出：PR / CI / audit
-  omk studio                          打开本地工作台
+  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 improve <report-id>
-  omk export <report-id> --format github-summary
+  omk evolve skills/code-review-v2/SKILL.md
   omk studio
 
 通用选项：
@@ -399,19 +384,18 @@ oh-my-knowledge — Knowledge Artifact Workbench
 
 Usage:
   omk init [dir]                      Scaffold a skill evaluation project
-  omk doctor [path]                   Static health check: structure, deps, samples, config, contamination risk
+  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 improve <report-id>             Improvement advice: sample quality, failure clusters, skill patch hints
-  omk export <report-id> [options]    Evidence export for PR / CI / audit
-  omk studio                          Open the local workbench
+  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 improve <report-id>
-  omk export <report-id> --format github-summary
+  omk evolve skills/code-review-v2/SKILL.md
   omk studio
 
 Common options:
@@ -422,7 +406,7 @@ Run 'omk <command> --help' for command-specific options.
     },
     'cli.help.init_usage': {
         zh: `
-omk init — 初始化 skill 评测项目
+omk init——初始化 skill 评测项目
 
 用法：
   omk init [dir]
@@ -456,12 +440,11 @@ Next steps:
     },
     'cli.help.eval': {
         zh: `
-omk eval — 离线评测 skill 版本，并给出 ship/no-ship verdict
+omk eval——离线评测 skill 版本，并给出 ship/no-ship verdict
 
 用法：
   omk eval --control <variant> --treatment <variant> [options]
   omk eval gold <init|validate|compare> ...
-  omk eval debias length <report-id> ...
 
 常用选项：
   --samples <path>                    用例文件（默认：eval-samples.json）
@@ -482,7 +465,8 @@ omk eval — 离线评测 skill 版本，并给出 ship/no-ship verdict
   --no-serve                          评测后不自动启动报告 server
 
 示例：
-  omk eval --control code-review-v1 --treatment code-review-v2
+  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
 `,
@@ -492,7 +476,6 @@ omk eval — run offline skill evaluation and emit a ship/no-ship verdict
 Usage:
   omk eval --control <variant> --treatment <variant> [options]
   omk eval gold <init|validate|compare> ...
-  omk eval debias length <report-id> ...
 
 Common options:
   --samples <path>                    Sample file (default: eval-samples.json)
@@ -513,14 +496,15 @@ Common options:
   --no-serve                          Do not auto-start report server after evaluation
 
 Examples:
-  omk eval --control code-review-v1 --treatment code-review-v2
+  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 标注集
+omk eval gold——管理 human-gold 标注集
 
 用法：
   omk eval gold init [--out <dir>] [--annotator <name>]
@@ -544,42 +528,17 @@ 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.eval_debias': {
-        zh: `
-omk eval debias — 验证 length-debias 是否降低评委长度偏差
-
-用法：
-  omk eval debias length <reportId> [options]
-
-选项：
-  --samples <path>                    用例文件；默认从 report.meta.request 读取
-  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-  --variant <name>                    只验证指定 variant
-  --judge-models <executor:model>     指定单评委
-  --bootstrap-samples <n>             bootstrap 重采样次数
-`,
-        en: `
-omk eval debias — validate whether length-debias reduces judge length bias
-
-Usage:
-  omk eval debias length <reportId> [options]
-
-Options:
-  --samples <path>                    Sample file; defaults to report.meta.request
-  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-  --variant <name>                    Validate only one variant
-  --judge-models <executor:model>     Single judge to use
-  --bootstrap-samples <n>             Bootstrap resamples
 `,
     },
     'cli.help.observe': {
         zh: `
-omk observe — 分析真实 session trace，生成 skill 健康度日报
+omk observe——分析真实 session trace，生成 skill 健康度日报
 
 用法：
   omk observe <sessions-dir> [options]
+  omk observe ingest <sessions-dir> [options]
+  omk observe inbox [options]
+  omk observe show <inbox_id> [options]
 
 选项：
   --kb <path>                         知识库根路径（默认：从 trace cwd 推断）
@@ -588,12 +547,26 @@ omk observe — 分析真实 session trace，生成 skill 健康度日报
   --to <iso>                          窗口终点，优先级高于 --last
   --skills <n1,n2,...>                只分析指定 skill
   --output-dir <path>                 输出目录（默认：~/.oh-my-knowledge/analyses）
+
+Inbox:
+  ingest --output-dir <path>           写入 observe inbox 数据（默认：.omk/observations；读取时兜底到 ~/.oh-my-knowledge/observations）
+  inbox --input-dir <path>             读取 observe inbox 数据
+  inbox --limit <n>                    展示 top N（默认：20）
+  inbox --skill <name>                 只看指定 skill
+  inbox --explore <n>                  从最近 50 条 medium/low 问题里抽样查看长尾
+  inbox --include-noise                --explore 时显式包含 noise 桶
+  inbox --by-skill                     按 skill 输出资产看板
+  inbox --json                         输出 JSON
+  show <inbox_id> --input-dir <path>    查看单条 observation 的前后上下文
 `,
         en: `
 omk observe — analyze production session traces and produce skill health reports
 
 Usage:
   omk observe <sessions-dir> [options]
+  omk observe ingest <sessions-dir> [options]
+  omk observe inbox [options]
+  omk observe show <inbox_id> [options]
 
 Options:
   --kb <path>                         Knowledge base root (default: infer from trace cwd)
@@ -602,303 +575,185 @@ Options:
   --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.improve': {
-        zh: `
-omk improve — 从报告或 trace 中得到下一步改进建议
-
-用法：
-  omk improve <report-id>             输出样本质量诊断和改进计划
-  omk improve plan <report-id>        同上，显式 plan 子命令
-  omk improve failures <report-id>    聚类失败用例，生成根因和修复方向
-  omk improve samples [skill]         为 skill 生成或补齐 eval samples
-  omk improve skill <skill>           基于评测循环尝试改进 skill
 
-示例：
-  omk improve v1-vs-v2-20260505-1200
-  omk improve samples skills/code-review/SKILL.md
-  omk improve failures v1-vs-v2-20260505-1200
-`,
-        en: `
-omk improve — get next-step improvement advice from reports or traces
-
-Usage:
-  omk improve <report-id>             Print sample diagnostics and repair plan
-  omk improve plan <report-id>        Same as above, explicit plan subcommand
-  omk improve failures <report-id>    Cluster failed cases into root causes and fixes
-  omk improve samples [skill]         Generate or fill eval samples for a skill
-  omk improve skill <skill>           Try to improve a skill through evaluation loops
-
-Examples:
-  omk improve v1-vs-v2-20260505-1200
-  omk improve samples skills/code-review/SKILL.md
-  omk improve failures v1-vs-v2-20260505-1200
+Inbox:
+  ingest --output-dir <path>           Write observe inbox data (default: .omk/observations; read fallback: ~/.oh-my-knowledge/observations)
+  inbox --input-dir <path>             Read observe inbox data
+  inbox --limit <n>                    Show top N (default: 20)
+  inbox --skill <name>                 Only show one skill
+  inbox --explore <n>                  Sample long-tail issues from the latest 50 medium/low items
+  inbox --include-noise                Explicitly include the noise bucket with --explore
+  inbox --by-skill                     Print the skill-level asset board
+  inbox --json                         Print JSON
+  show <inbox_id> --input-dir <path>    Show context around one observation
 `,
     },
-    'cli.help.improve_plan': {
-        zh: [
-            '',
-            '用法: omk improve <reportId> [options]',
-            '      omk improve plan <reportId> [options]',
-            '',
-            '诊断用例集本身的质量问题: 区分度低 / 重复 / 歧义 / 成本异常 / 全 fail。',
-            '回答 "评测结论是否被坏用例污染"。',
-            '',
-            '选项:',
-            '  --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 improve <reportId> [options]',
-            '       omk improve plan <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?".',
-            '',
-            '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.improve_failures': {
-        zh: [
-            '',
-            '用法: omk improve 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 improve 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'),
-    },
-    'cli.help.improve_samples': {
+    'cli.help.observe_ingest': {
         zh: `
-omk improve samples — 生成或补齐 eval-samples 评测用例
+omk observe ingest — 读取真实 session trace，写入 observe inbox 数据
 
 用法：
-  omk improve samples <skill-path> [options]
-  omk improve samples --batch [--skill-dir <dir>] [options]
+  omk observe ingest <sessions-dir-or-file> [options]
 
 选项：
-  --count <n>                         生成用例数量（默认：5）
-  --model <name>                      生成模型（默认：sonnet）
-  --batch                             为 skill 目录下缺少 eval-samples 的 skill 批量生成
-  --skill-dir <path>                  skill 目录（batch 使用，默认：skills）
+  --output-dir <path>                输出目录（默认：.omk/observations；读取时兜底到 ~/.oh-my-knowledge/observations）
+
+支持：
+  Claude Code JSONL
+  Markdown 对话日志（.log）
 `,
         en: `
-omk improve samples — generate or fill eval-samples test cases
+omk observe ingest — read real session traces and write observe inbox data
 
 Usage:
-  omk improve samples <skill-path> [options]
-  omk improve samples --batch [--skill-dir <dir>] [options]
+  omk observe ingest <sessions-dir-or-file> [options]
 
 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)
+  --output-dir <path>                Output directory (default: .omk/observations; read fallback: ~/.oh-my-knowledge/observations)
+
+Supported:
+  Claude Code JSONL
+  Markdown conversation logs (.log)
 `,
     },
-    'cli.help.improve_skill': {
+    'cli.help.observe_inbox': {
         zh: `
-omk improve skill — 基于评测循环迭代改进 skill
+omk observe inbox — 查看已写入的 observe inbox 问题列表
 
 用法：
-  omk improve skill <skill-path> [options]
+  omk observe inbox [options]
 
 选项：
-  --rounds <n>                        迭代轮数（默认：3）
-  --target <score>                    目标分数
-  --model <name>                      改进模型
-  --judge-models <executor:model>     单评委配置
+  --input-dir <path>                 读取目录（默认：.omk/observations；兜底到 ~/.oh-my-knowledge/observations）
+  --limit <n>                        展示 top N（默认：20）
+  --skill <name>                     只看指定 skill
+  --explore <n>                      从最近 50 条 medium/low 问题里抽样查看长尾
+  --include-noise                    --explore 时显式包含 noise 桶
+  --by-skill                         按 skill 输出资产看板
+  --json                             输出 JSON
 `,
         en: `
-omk improve skill — improve a skill through evaluation loops
+omk observe inbox — inspect previously ingested observe inbox items
 
 Usage:
-  omk improve skill <skill-path> [options]
+  omk observe inbox [options]
 
 Options:
-  --rounds <n>                        Iteration rounds (default: 3)
-  --target <score>                    Target score
-  --model <name>                      Improvement model
-  --judge-models <executor:model>     Single judge config
+  --input-dir <path>                 Input directory (default: .omk/observations; fallback: ~/.oh-my-knowledge/observations)
+  --limit <n>                        Show top N (default: 20)
+  --skill <name>                     Only show one skill
+  --explore <n>                      Sample long-tail issues from the latest 50 medium/low items
+  --include-noise                    Explicitly include the noise bucket with --explore
+  --by-skill                         Print the skill-level asset board
+  --json                             Print JSON
 `,
     },
-    'cli.help.export': {
+    'cli.help.observe_show': {
         zh: `
-omk export — 导出可贴到 PR / CI / audit 的证据包
-
-	用法：
-	  omk export <report-id> [options]
-	  omk export diff <report-id> [report-id] [options]
-	  omk export verdict <report-id> [options]
-	  omk export saturation <report-id> [options]
-
-选项：
-	  --format <format>                   html / markdown / github-summary（默认：html）
-	  --out <path>                        输出文件；markdown / github-summary 未指定时输出到 stdout
-	  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-
-示例：
-	  omk export v1-vs-v2-20260505-1200 --format github-summary
-	  omk export v1-vs-v2-20260505-1200 --format markdown --out report.md
-	  omk export diff v1-vs-v2-20260505-1200 --regressions-only
-	  omk export verdict v1-vs-v2-20260505-1200
-`,
-        en: `
-omk export — export evidence packs for PR / CI / audit
-
-	Usage:
-	  omk export <report-id> [options]
-	  omk export diff <report-id> [report-id] [options]
-	  omk export verdict <report-id> [options]
-	  omk export saturation <report-id> [options]
-
-Options:
-	  --format <format>                   html / markdown / github-summary (default: html)
-	  --out <path>                        Output file; markdown / github-summary print to stdout by default
-	  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-
-Examples:
-	  omk export v1-vs-v2-20260505-1200 --format github-summary
-	  omk export v1-vs-v2-20260505-1200 --format markdown --out report.md
-	  omk export diff v1-vs-v2-20260505-1200 --regressions-only
-	  omk export verdict v1-vs-v2-20260505-1200
-`,
-    },
-    'cli.help.export_diff': {
-        zh: `
-omk export diff — 导出样本级或报告级差异
+omk observe show — 查看单条 observation 的原始上下文
 
 用法：
-  omk export diff <report-id> [--variant <name>] [--regressions-only] [--top <n>]
-  omk export diff <report-id-a> <report-id-b>
+  omk observe show <inbox_id> [options]
 
 选项：
-  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-  --variant <name>                    样本级 diff 的实验组 variant
-  --regressions-only                  只显示回退用例
-  --top <n>                           最多显示 N 条
+  --input-dir <path>                 读取目录（默认：.omk/observations；兜底到 ~/.oh-my-knowledge/observations）
 `,
         en: `
-omk export diff — export sample-level or cross-report differences
+omk observe show — inspect the raw context around one observation
 
 Usage:
-  omk export diff <report-id> [--variant <name>] [--regressions-only] [--top <n>]
-  omk export diff <report-id-a> <report-id-b>
+  omk observe show <inbox_id> [options]
 
 Options:
-  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-  --variant <name>                    Treatment variant for sample-level diff
-  --regressions-only                  Show regressions only
-  --top <n>                           Show at most N rows
+  --input-dir <path>                 Input directory (default: .omk/observations; fallback: ~/.oh-my-knowledge/observations)
 `,
     },
-    'cli.help.export_verdict': {
+    'cli.help.evolve': {
         zh: `
-omk export verdict — 输出已有报告的一行 ship/no-ship verdict
+omk evolve——多轮自动迭代改进 skill
 
 用法：
-  omk export verdict <report-id> [options]
+  omk evolve <skill-path> [options]
 
 选项：
-  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-  --threshold <number>                三层 gate 阈值
-  --trivial-diff <number>             实际可忽略 diff
-  --verbose                           输出完整 verdict 解释
+  --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 export verdict — print a one-line ship/no-ship verdict for an existing report
+omk evolve — auto-iterate a skill through multi-round evaluation loops
 
 Usage:
-  omk export verdict <report-id> [options]
+  omk evolve <skill-path> [options]
 
 Options:
-  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-  --threshold <number>                Three-layer gate threshold
-  --trivial-diff <number>             Practically negligible diff
-  --verbose                           Print the full verdict explanation
+  --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)
+
+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.export_saturation': {
+    'cli.help.sample': {
         zh: `
-omk export saturation — 输出重复评测的饱和度证据
+omk sample——生成或补齐 eval-samples 评测用例
 
 用法：
-  omk export saturation <report-id> [--variant <name>]
+  omk sample <skill-path> [options]
+  omk sample --batch [--skill-dir <dir>] [options]
 
 选项：
-  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-  --variant <name>                    只输出指定 variant
+  --count <n>                         生成用例数量（默认：5）
+  --model <name>                      生成模型（默认：sonnet）
+  --batch                             为 skill 目录下缺少 eval-samples 的 skill 批量生成
+  --skill-dir <path>                  skill 目录（batch 使用，默认：skills）
 `,
         en: `
-omk export saturation — print saturation evidence from repeated evaluations
+omk sample — generate or fill eval-samples test cases
 
 Usage:
-  omk export saturation <report-id> [--variant <name>]
+  omk sample <skill-path> [options]
+  omk sample --batch [--skill-dir <dir>] [options]
 
 Options:
-  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-  --variant <name>                    Print only one variant
+  --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——打开本地知识工作台
 
 用法：
   omk studio [options]
 
 选项：
   --port <n>                          本地服务端口（默认：7799）
+  --host <host>                       监听地址（默认：127.0.0.1；局域网访问可用 0.0.0.0）
   --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
   --analyses-dir <path>               观测分析目录
+  --observations-dir <path>           observe inbox 数据目录（默认：.omk/observations）
   --no-open                           只启动服务，不自动打开浏览器
   --dev                               开发模式：文件变化时自动重启
 
 示例：
   omk studio
   omk studio --port 7798
+  omk studio --host 0.0.0.0 --observations-dir .omk/observations
   omk studio --no-open
 `,
         en: `
@@ -909,38 +764,20 @@ Usage:
 
 Options:
   --port <n>                          Local server port (default: 7799)
+  --host <host>                       Listen address (default: 127.0.0.1; use 0.0.0.0 for LAN access)
   --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
   --analyses-dir <path>               Observation analyses directory
+  --observations-dir <path>           Observe inbox data directory (default: .omk/observations)
   --no-open                           Start the server without opening a browser
   --dev                               Dev mode: restart on file changes
 
 Examples:
   omk studio
   omk studio --port 7798
+  omk studio --host 0.0.0.0 --observations-dir .omk/observations
   omk studio --no-open
 `,
     },
-    // 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 文件可读',
@@ -958,6 +795,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} 字符',
@@ -1072,10 +970,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)批量跑
 
 参数:
@@ -1083,62 +981,70 @@ oh-my-knowledge — omk doctor 健康检查
 
 选项:
   --json                 把 DoctorReport 打到 stdout(CI 消费用)
-  --gate                 静默模式: 通过 exit 0 / 不通过 exit 1, 仅 stderr 出问题摘要
-  --executor <name>      executor 名(仅向后兼容, doctor 不直接打 LLM)
-  --model <name>         model 名(同上)
+  --gate                 静默模式: fatal 问题 exit 1; warnings_only 仍 exit 0, 仅 stderr 出摘要
+  --executor <name>      LLM executor (默认 claude, 可换 anthropic-api/codex 等)
+  --model <name>         模型 (默认 sonnet)
   --samples <path>       显式指定评测用例文件
-  --timeout <seconds>    rule 执行超时(默认 8)
+  --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 eval 内置 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)
+  --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>    per-rule timeout (default 8)
+  --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 eval runs 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': {
@@ -1150,7 +1056,7 @@ checks cost nothing to run. LLM connectivity can be skipped with --skip-connecti
         en: '✓ Using eval samples file: {path}',
     },
     'cli.doctor.gate_blocked': {
-        zh: 'skill 健康检查未通过, 评测已中止。doctor 是评测必经环节, 无 skip 选项 — 请修复上述问题后重跑。',
+        zh: 'skill 健康检查未通过，评测已中止。doctor 是评测必经环节，无 skip 选项——请修复上述问题后重跑。',
         en: 'skill health check failed; evaluation aborted. doctor is mandatory and not skippable — fix the issues above and re-run.',
     },
     'cli.run.skip_connectivity_warning': {