oh-my-knowledge 0.30.0 → 0.31.0

package/README.md

@@ -27,6 +27,8 @@ omk init my-eval && cd my-eval
 omk eval --control code-review-v1 --treatment code-review-v2    # → HTML report with verdict in 5 minutes
 ```
 
+Walkthrough: [5-minute quickstart guide](docs/quickstart-skill-eval.md) (recommended for first-time users).
+
 Deeper: [use inside Claude Code / Codex](#use-inside-ai-coding-agents) · [`omk eval` flags](#omk-eval) · [artifact directory layout](#artifact-directory-layout) · [`--lang` / `OMK_LANG`](#environment-variables)
 
 ## Use inside AI Coding Agents
@@ -365,6 +367,18 @@ omk exposes a workflow CLI for knowledge artifacts. Seven top-level commands cov
 omk init [dir]
 ```
 
+<!-- omk:cli:init:flags:start -->
+
+**Flags:**
+
+```text
+  --lang <value>  Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+```
+
+For full descriptions: `omk init --help`.
+
+<!-- omk:cli:init:flags:end -->
+
 Scaffolds an evaluation project with two starter skill variants and an `eval-samples.json` file.
 
 ### `omk doctor`
@@ -378,6 +392,28 @@ omk doctor --gate; echo $?              # silent gate; exit 1 on fatal failures,
 omk doctor --static-only                # offline mode: static checks only, no LLM call
 ```
 
+<!-- omk:cli:doctor:flags:start -->
+
+**Flags:**
+
+```text
+  --effort <value>    LLM reasoning effort: low / medium / high / xhigh / max.
+  --executor <value>  Executor name, default claude. Pass a test fixture path to use in tests.
+  --fix               Interactive fix: use LLM agent to fix skill issues reported by doctor.
+  --gate              Silent mode: only emit stderr summary on fail. Exit code carries the signal.
+  --html <value>      HTML report output path. Coexists with --json / --gate.
+  --json              JSON output to stdout, for CI / external script consumption.
+  --lang <value>      Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --model <value>     LLM model name, default sonnet.
+  --samples <value>   Samples file path (.json/.yaml). Auto-detects from target / cwd if omitted.
+  --static-only       Offline static mode: only 4 static rules, no LLM call.
+  --timeout <value>   Single-session LLM timeout sec, default 600 (10 min).
+```
+
+For full descriptions: `omk doctor --help`.
+
+<!-- omk:cli:doctor:flags:end -->
+
 LLM health audit: a single LLM session emits per-dimension grades, findings, and suggestions for the 7 builtin dimensions; the HTML report sorts dimensions fail→warn→pass→skipped with errors first within each dim. Dimensions are extensible — call `registerHealthDimension` in your own code and the new section is folded into the same LLM call's prompt and report (order = registration order).
 
 Static-only mode (`--static-only`): for CI nodes without claude / codex installed, or local debugging without network — runs the four static rules (readability / metadata / dependencies / samples contract) with zero LLM calls and zero cost. Output goes through the same `DoctorReport` shape and combines with `--json` / `--gate` / `--html`.
@@ -396,36 +432,59 @@ omk eval gold compare <report-id> --gold-dir gold-dataset
 
 Runs the offline evaluation, applies the verdict gate, persists the report, and returns a ship/no-ship exit code. Bootstrap CI is enabled by default on this workflow.
 
-Common options:
+<!-- omk:cli:eval:flags:start -->
+
+**Flags:**
 
 ```text
-  --samples <path>       sample file (default: eval-samples.json, also detects .yaml/.yml; auto-discovers <skill>/.omk/samples.json under --skill-dir)
-  --skill-dir <path>     artifact dir (default: skills)
-  --control <expr>       control variant expression
-  --treatment <v1,v2>    treatment variants, comma-separated
-  --config <path>        YAML/JSON evaluation config
-  --model <name>         task execution model (default: opus alias)
-  --effort <level>       reasoning effort for executor LLM: low/medium/high/xhigh/max (default: low; reports across efforts not strictly comparable)
-  --judge-models <list>  judge config, e.g. claude:haiku or claude:opus,openai:gpt-4o
-  --executor <name>      claude / claude-sdk / codex / codex-sdk / openai-api / gemini / custom
-  --no-judge             skip LLM judge subjective scoring
-  --no-diagnostic        skip the diagnostic LLM call (default: on; emits "what went wrong + how to fix" advice for failed samples)
-  --skip-doctor          escape hatch: bypass the doctor health-check gate (default: on). Use when sandbox mocks supply deps and doctor's path/env checks misfire; caller owns garbage-in risk
-  --dry-run              preview only
-  --blind                blind A/B mode
-  --concurrency <n>      parallel tasks
-  --timeout <sec>        per-task timeout
-  --repeat <n>           repeat N times for variance analysis
-  --batch                evaluate each artifact independently vs baseline
-  --bootstrap-samples N  bootstrap resample count (default 1000)
-  --threshold <number>   verdict layer-gate threshold (default 3.5)
-  --trivial-diff <num>   practically tiny diff cutoff (default 0.1)
-  --report-only          produce the report and print verdict, but always exit 0
-  --no-gate              alias for --report-only
-  --skip-connectivity    skip model connectivity check (internal static gates still run)
-  --no-serve             do not auto-start the report server after evaluation
+  --batch                         Batch mode: baseline vs each skill
+  --blind                         Blind judge mode
+  --bootstrap                     Add bootstrap CI
+  --bootstrap-samples <value>     Bootstrap resamples, default 1000
+  --budget-per-sample-ms <value>  Per-sample time cap ms (must be > 0; omit for no cap)
+  --budget-per-sample-usd <value> Per-sample budget cap USD (must be > 0; omit for no cap)
+  --budget-usd <value>            Total budget cap USD (must be > 0; omit for no cap)
+  --concurrency <value>           Concurrency, default 1
+  --config <value>                eval.yaml path
+  --control <value>               Control variant expr
+  --dry-run                       Plan only, no real exec
+  --effort <value>                Executor LLM reasoning effort low/medium/high/xhigh/max (default low; reports across efforts not strictly comparable).
+  --executor <value>              Executor: claude / claude-sdk / codex / codex-sdk / openai-api / gemini / custom (default claude).
+  --gold-dir <value>              Gold dataset dir
+  --judge-models <value>          Judge config: executor:model[,...]. e.g. claude:haiku or claude:opus,openai:gpt-4o (≥ 2 = ensemble). Default <executor>:haiku.
+  --judge-repeat <value>          Judge each dim N times
+  --lang <value>                  Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --layered-stats                 Emit layered stats
+  --mcp-config <value>            MCP config path
+  --model <value>                 Evaluated model
+  --no-cache                      Skip executor cache
+  --no-debias-length              Disable length-debias (default on)
+  --no-diagnostic                 Disable diagnostic LLM call (on by default; emits "what went wrong + how to fix" advice for failed samples).
+  --no-gate                       Disable verdict gate
+  --no-judge                      Skip LLM judge
+  --no-serve                      Do not start report server
+  --no-strict-baseline            Disable baseline isolation
+  --output-dir <value>            Report output dir
+  --repeat <value>                Repeat each sample N times
+  --report-only                   Produce the report and print verdict, but always exit 0 (no CI gate).
+  --resume <value>                Resume a previous failed run
+  --retry <value>                 Per-sample retry count
+  --samples <value>               Samples file path. Defaults to eval-samples.json (also .yaml/.yml); auto-discovers <skill>/.omk/samples.json under --skill-dir.
+  --skill-dir <value>             Skill dir, default skills
+  --skip-connectivity             Skip LLM connectivity preflight
+  --skip-doctor                   Escape hatch: skip the doctor health-check gate (on by default). Use when sandbox mocks supply deps; caller owns garbage-in risk.
+  --strict-baseline               Force baseline isolation (default true)
+  --threshold <value>             Verdict threshold, default 3.5
+  --timeout <value>               Per-sample timeout sec, default 120
+  --treatment <value>             Treatment variants, comma-separated
+  --trivial-diff <value>          Trivial diff tolerance; 0 disables tolerance
+  --verbose                       Verbose logging
 ```
 
+For full descriptions: `omk eval --help`.
+
+<!-- omk:cli:eval:flags:end -->
+
 The HTML report has two tabs:
 - **📊 Score view** — the verdict-driven A/B comparison (fact / behavior / judge layers, bootstrap CI, length-debias).
 - **✅ Functional view** — each sample as a unit test: design (prompt / rubric / mocks / environment) + execution trace + assertion results + actionable diagnostic. Diagnostic emits root cause (skill_doc_unclear / llm_misread / sample_design / tripwire_intentional / ...), workflow checks (rubric step ✓/✗ with evidence), and failure-mode tags (工作流跳步 / 硬编码值 / 幻觉输出 / 工具误用 / 环境拦截 / 误读约束 / 其他). For the sandbox-mock semantics behind `mocks` / `environment` / `tripwire` / `mocksStrict`, see [docs/sample-design-spec.md §三](./docs/sample-design-spec.md).
@@ -444,6 +503,24 @@ omk observe ~/.claude/projects/my-project --skills audit,polish
 omk observe ~/.claude/projects/my-project --kb /path/to/project
 ```
 
+<!-- omk:cli:observe:flags:start -->
+
+**Flags:**
+
+```text
+  --from <value>        Start time ISO, overrides --last
+  --kb <value>          KB root, enables KB-aware analysis
+  --lang <value>        Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --last <value>        Time window (7d / 24h / 30m)
+  --output-dir <value>  Analysis output directory
+  --skills <value>      Filter to specific skills, comma-separated
+  --to <value>          End time ISO
+```
+
+For full descriptions: `omk observe --help`.
+
+<!-- omk:cli:observe:flags:end -->
+
 Turns real Claude Code session traces into skill-health reports: knowledge usage, gap signals, execution stability, tokens, and latency. This is production observation, not production scoring.
 
 #### B. observe inbox: reviewer loop
@@ -462,6 +539,7 @@ omk observe inbox --skill audit                    # filter by skill
 omk observe inbox --by-skill                       # rollup view (one row per skill)
 omk observe inbox --explore 10                     # sample 10 long-tail items from medium/low
 omk observe inbox --explore 10 --include-noise     # explicitly include the noise bucket
+omk observe inbox --llm-enhanced-review          # run LLM enhanced chain review explicitly
 omk observe inbox --json                           # JSON output for automation
 
 # 3. Inspect a single observation with its event triplet (surrounding messages)
@@ -477,6 +555,30 @@ Every observation carries:
 
 Supported trace formats: Claude Code session JSONL (`.jsonl`), OpenClaw session JSONL (`.jsonl`), and markdown conversation logs (`.log`).
 
+### `omk skill-extract`
+
+```bash
+omk skill-extract demo-create --review soft-xxx --status author_confirmed
+omk skill-extract demo-create --review soft-xxx --status rejected --reason "not a real standard"
+```
+
+<!-- omk:cli:skill-extract:flags:start -->
+
+**Flags:**
+
+```text
+  --input-dir <value>  Observation data directory
+  --json               JSON output
+  --lang <value>       Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --reason <value>     Manual review reason
+  --review <value>     Soft standard id to review
+  --status <value>     Review status: author_confirmed / rejected / pending_review (also accepts aliases: confirm / confirmed / reject / pending)
+```
+
+For full descriptions: `omk skill-extract --help`.
+
+<!-- omk:cli:skill-extract:flags:end -->
+
 ### `omk evolve`
 
 ```bash
@@ -484,6 +586,36 @@ omk evolve <skill>                  # multi-round auto-iteration on a skill
 omk evolve skills/foo.md --rounds 10 --target 4.5
 ```
 
+<!-- omk:cli:evolve:flags:start -->
+
+**Flags:**
+
+```text
+  --auto-fix-samples              Fix the skill, then fix samples, then evaluate the combined candidate
+  --concurrency <value>           Eval concurrency, default 1
+  --effort <value>                Reasoning effort: low/medium/high/xhigh/max
+  --executor <value>              Executor name, default claude
+  --improve-mode <agent|rewrite>  Improvement strategy (default: agent)
+  --improve-model <value>         LLM that rewrites the skill, default sonnet
+  --judge-models <value>          Judge model (single judge required), executor:model format. Default claude:haiku
+  --lang <value>                  Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --model <value>                 Evaluated LLM, default sonnet
+  --no-diagnostic                 Disable diagnostic LLM call
+  --reuse-latest-eval             Reuse the latest comparable eval report as round-0
+  --rounds <value>                Max iteration rounds, default 5
+  --sample-fix-max-attempts <value>Max auto-fix attempts per sample (default: 2)
+  --samples <value>               Samples file, default eval-samples.json
+  --skip-connectivity             Skip LLM connectivity preflight
+  --skip-doctor                   Skip doctor gate (escape hatch; user takes garbage-in risk)
+  --stop-on-assertions-pass       Stop early when normal samples pass assertions
+  --target <value>                Target composite score; stop when reached. If omitted, runs all rounds.
+  --timeout <value>               Per-sample timeout sec, default 120
+```
+
+For full descriptions: `omk evolve --help`.
+
+<!-- omk:cli:evolve:flags:end -->
+
 Auto-iterates a skill through repeated eval → judge → rewrite loops until it hits `--target` or exhausts `--rounds`. Cost scales with `rounds × samples × variants`; a typical run takes minutes to tens of minutes. Original skill files are versioned under `skills/evolve/*.r0.md`.
 
 ### `omk sample`
@@ -493,6 +625,27 @@ omk sample <skill>                  # generate or fill eval-samples test cases f
 omk sample --batch                  # generate for skills missing eval-samples
 ```
 
+<!-- omk:cli:sample:flags:start -->
+
+**Flags:**
+
+```text
+  --batch                Batch mode: scan --skill-dir, generate samples for any skill missing them.
+  --count <value>        Number of samples to generate. Defaults to LLM auto-selection by skill type.
+  --fix                  Fix mode: auto-fix sample_design failures using the latest eval report.
+  --focus <value>        Generation focus (NL hint). Steers LLM toward certain sample types.
+  --lang <value>         Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --model <value>        Generation LLM model name, default opus.
+  --no-mock              Skip mock generation; all tool calls execute for real during eval.
+  --reports-dir <value>  Reports dir (fix mode), default ~/.oh-my-knowledge/reports.
+  --skill-dir <value>    Skill root dir, default skills. Used by batch mode.
+  --treatment <value>    Treatment name (fix mode), defaults to skill-path inference.
+```
+
+For full descriptions: `omk sample --help`.
+
+<!-- omk:cli:sample:flags:end -->
+
 One-shot generation. Auto-stamps `provenance` on generated cases. Generated assertions use English, numbers, or code tokens so they compare cleanly across bilingual outputs.
 
 ### `omk studio`
@@ -506,6 +659,25 @@ omk studio --observations-dir .omk/observations    # observe inbox data director
 omk studio --no-open
 ```
 
+<!-- omk:cli:studio:flags:start -->
+
+**Flags:**
+
+```text
+  --analyses-dir <value>      Analyses dir (optional)
+  --dev                       Dev mode: child process with hot reload
+  --host <value>              Listen host, default localhost. Use 0.0.0.0 to expose to LAN
+  --lang <value>              Output language zh|en. Priority: CLI > OMK_LANG env > zh.
+  --no-open                   Do not auto-open browser
+  --observations-dir <value>  Observations dir (optional)
+  --port <value>              Listen port, default 7799. Pass 0 for OS-assigned
+  --reports-dir <value>       Reports dir, default ~/.oh-my-knowledge/reports
+```
+
+For full descriptions: `omk studio --help`.
+
+<!-- omk:cli:studio:flags:end -->
+
 Starts the local knowledge workbench for browsing reports and observation analyses. Verdict, sample diffs, regressions, saturation curves, and per-sample drill-downs all live in the studio UI — there is no CLI export / analysis subcommand. For CI gates, use `omk eval`'s exit code (0 on `PROGRESS`, non-zero otherwise) or `jq` over the report JSON.
 
 Studio is skill-centric — the list page (`/`) shows skill cards with health band / 0-100 reference score / open-issue count / trend; the detail page (`/skills/<name>`) puts a prioritized issue checklist on the left (skill issues / sample issues / tool advisories), and a chart.js health trend plus three compact stage cards (doctor / eval / observe) on the right, with modals for deeper drill-down. The legacy run list moved to `/runs`. Visit `/observations/inbox` for the observe inbox dashboard: per-skill rollup view, reviewer action list, observability funnel, and a per-observation detail panel with the event triplet (surrounding messages).

package/README.zh.md

@@ -27,6 +27,8 @@ omk init my-eval && cd my-eval
 omk eval --control code-review-v1 --treatment code-review-v2    # → 5 分钟出 HTML 报告 + verdict
 ```
 
+手把手教程：[5 分钟快速上手](docs/zh/quickstart-skill-eval.md)（推荐第一次跑评测的用户）。
+
 深入：[在 Claude Code / Codex 中调用](#在-ai-coding-agent-中使用) · [`omk eval` 全 flag](#omk-eval) · [artifact 目录结构](#artifact-目录结构) · [`--lang` / `OMK_LANG`](#环境变量)
 
 ## 在 AI Coding Agent 中使用
@@ -365,6 +367,18 @@ omk 的公开 CLI 由 7 个顶层命令构成完整闭环：`init`（脚手架
 omk init [目录]
 ```
 
+<!-- omk:cli:init:flags:start -->
+
+**Flags:**
+
+```text
+  --lang <value>  输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+```
+
+完整描述见 `omk init --help`。
+
+<!-- omk:cli:init:flags:end -->
+
 生成一个评测项目脚手架，包含两版 starter skill 和 `eval-samples.json`。
 
 ### `omk doctor`
@@ -378,6 +392,28 @@ omk doctor --gate; echo $?              # 静默门禁，fatal 问题 exit 1，
 omk doctor --static-only                # 离线模式：只跑静态检查，不调 LLM
 ```
 
+<!-- omk:cli:doctor:flags:start -->
+
+**Flags:**
+
+```text
+  --effort <value>    LLM 推理 effort：low / medium / high / xhigh / max。
+  --executor <value>  执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。
+  --fix               交互式修复：根据 doctor 报告问题，用 LLM agent 修复 skill。
+  --gate              静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
+  --html <value>      HTML 报告输出路径。可跟 --json / --gate 共存。
+  --json              JSON 输出到 stdout，适合 CI / 外部脚本消费。
+  --lang <value>      输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --model <value>     LLM model 名，默认 sonnet。
+  --samples <value>   样本文件路径（.json/.yaml）。不传则按 target / cwd 顺序自动发现。
+  --static-only       离线静态模式，只跑 4 条静态 rule(skill_readable / skill_metadata / dependencies_present / samples_contract_aligned），不调 LLM。
+  --timeout <value>   单次 LLM 会话超时秒数，默认 600(10 分钟）。
+```
+
+完整描述见 `omk doctor --help`。
+
+<!-- omk:cli:doctor:flags:end -->
+
 LLM 健康度审计：单次 LLM 会话产出 7 个内置维度的健康度评分 + findings + 改进建议；HTML 报告按 fail→warn→pass→skipped 排序，错误 finding 优先。维度可扩展（在自己代码里调 `registerHealthDimension`，自动并入同一次 LLM 调用的 prompt 与报告，顺序 = 注册顺序）。
 
 离线静态模式（`--static-only`）：CI 节点没装 claude / codex、本地断网调试等场景下跑 4 条静态 rule（可读性 / 元数据 / 依赖 / samples 契约），零 LLM 调用、零成本。结果同样进 `DoctorReport`，可与 `--json` / `--gate` / `--html` 组合。
@@ -396,36 +432,59 @@ omk eval gold compare <report-id> --gold-dir gold-dataset
 
 运行离线评测，应用 verdict gate，持久化报告，并用 exit code 表示 ship/no-ship。这个工作流默认开启 bootstrap CI。
 
-常用选项：
+<!-- omk:cli:eval:flags:start -->
+
+**Flags:**
 
 ```text
-  --samples <路径>       样本文件（默认：eval-samples.json，也自动检测 .yaml/.yml；--skill-dir 下的 <skill>/.omk/samples.json 会被自动发现）
-  --skill-dir <路径>     artifact 目录（默认：skills）
-  --control <expr>       对照组 variant 表达式
-  --treatment <v1,v2>    实验组 variants，逗号分隔
-  --config <路径>        YAML/JSON 评测配置
-  --model <名称>         任务执行模型（默认：opus alias）
-  --effort <level>       执行模型扩展思考预算 low/medium/high/xhigh/max（默认：low；高 effort 跨报告不可严格比较）
-  --judge-models <list>  评委配置，例如 claude:haiku 或 claude:opus,openai:gpt-4o
-  --executor <名称>      claude / claude-sdk / codex / codex-sdk / openai-api / gemini / custom
-  --no-judge             跳过 LLM 评委主观评分
-  --no-diagnostic        关闭 diagnostic 诊断 LLM 调用（默认开启，给 failed sample 出"哪错了 + 怎么改"建议）
-  --skip-doctor          escape hatch：跳过 doctor 健康检查门禁（默认强制启用）。沙箱 mock 提供依赖时绕开 doctor 物理路径误报；garbage-in 风险由调用方承担
-  --dry-run              仅预览
-  --blind                盲测模式
-  --concurrency <n>      并行任务数
-  --timeout <秒>         单任务超时
-  --repeat <n>           重复 N 次做方差分析
-  --batch                每个 artifact 独立和 baseline 对比
-  --bootstrap-samples N  bootstrap 重采样次数（默认 1000）
-  --threshold <number>   verdict 分层门禁阈值（默认 3.5）
-  --trivial-diff <num>   实际可忽略 diff 阈值（默认 0.1）
-  --report-only          生成报告并打印 verdict，但始终 exit 0
-  --no-gate              --report-only 的别名
-  --skip-connectivity    跳过模型连通性检查（内部静态 gate 仍强制执行）
-  --no-serve             评测后不自动启动报告服务
+  --batch                         batch 模式:baseline vs 每个 skill
+  --blind                         judge blind 模式
+  --bootstrap                     加 bootstrap CI
+  --bootstrap-samples <value>     bootstrap 重采样次数，默认 1000
+  --budget-per-sample-ms <value>  单 sample 时长上限 ms（必须 > 0，不传则无上限）
+  --budget-per-sample-usd <value> 单 sample 预算上限 USD（必须 > 0，不传则无上限）
+  --budget-usd <value>            总预算上限 USD（必须 > 0，不传则无上限）
+  --concurrency <value>           并发数，默认 1
+  --config <value>                eval.yaml 路径
+  --control <value>               control variant 表达式
+  --dry-run                       只 plan 不实跑
+  --effort <value>                被测 LLM 扩展思考预算 low/medium/high/xhigh/max（默认 low；跨 effort 报告不严格可比）。
+  --executor <value>              执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。
+  --gold-dir <value>              gold dataset 目录
+  --judge-models <value>          评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
+  --judge-repeat <value>          每个 dim 评 N 次
+  --lang <value>                  输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --layered-stats                 输出分层统计
+  --mcp-config <value>            MCP 配置文件路径
+  --model <value>                 被测模型
+  --no-cache                      跳过 executor cache
+  --no-debias-length              关 length-debias（默认开）
+  --no-diagnostic                 关闭 diagnostic 诊断 LLM 调用（默认开，给 failed sample 出「哪错了 + 怎么改」建议）。
+  --no-gate                       关 verdict gate
+  --no-judge                      跳过 LLM judge
+  --no-serve                      不启 report server
+  --no-strict-baseline            关闭 baseline 隔离
+  --output-dir <value>            报告输出目录
+  --repeat <value>                每个 sample 重复跑 N 次
+  --report-only                   生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
+  --resume <value>                从某次失败 run 续跑
+  --retry <value>                 失败 sample 重试次数
+  --samples <value>               样本文件路径。默认 eval-samples.json，也接受 .yaml/.yml；自动发现 --skill-dir 下的 <skill>/.omk/samples.json。
+  --skill-dir <value>             skill 目录，默认 skills
+  --skip-connectivity             跳 LLM 连通性预检
+  --skip-doctor                   escape hatch:跳 doctor 健康检查门禁（默认强制启用）。沙箱 mock 提供依赖时绕开 doctor 物理路径误报；garbage-in 风险自负。
+  --strict-baseline               强制 baseline 隔离（default true）
+  --threshold <value>             verdict 阈值，默认 3.5
+  --timeout <value>               单样本超时秒，默认 120
+  --treatment <value>             treatment variant 列表，逗号分隔
+  --trivial-diff <value>          可忽略 diff 容差，0 表示不启用容差
+  --verbose                       详细日志
 ```
 
+完整描述见 `omk eval --help`。
+
+<!-- omk:cli:eval:flags:end -->
+
 HTML 报告有两个 tab：
 - **📊 评分视角** — verdict 驱动的 A/B 对比（事实/行为/judge 三层、bootstrap CI、length-debias）。
 - **✅ 功能视角** — 每条 sample 当一条单测看：用例设计（prompt / rubric / 工具调用 mock / environment）+ 执行轨迹 + 断言结果 + 可操作的 diagnostic 建议。诊断给出归因（skill 文档模糊 / LLM 误读 / sample 设计 bug / 诱错样本 / ...）、工作流校验（rubric 每步 ✓/✗ + 证据）和失败模式标签（工作流跳步 / 硬编码值 / 幻觉输出 / 工具误用 / 环境拦截 / 误读约束 / 其他）。沙箱 mock 字段语义（`mocks` / `environment` / `tripwire` / `mocksStrict`）见 [docs/sample-design-spec.md §三](./docs/sample-design-spec.md)。
@@ -444,6 +503,24 @@ omk observe ~/.claude/projects/my-project --skills audit,polish
 omk observe ~/.claude/projects/my-project --kb /path/to/project
 ```
 
+<!-- omk:cli:observe:flags:start -->
+
+**Flags:**
+
+```text
+  --from <value>        起始时间 ISO，优先级高于 --last
+  --kb <value>          知识库 root，启用 KB-aware 分析
+  --lang <value>        输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --last <value>        时间窗(7d / 24h / 30m）
+  --output-dir <value>  分析结果输出目录
+  --skills <value>      只看指定 skill，逗号分隔
+  --to <value>          结束时间 ISO
+```
+
+完整描述见 `omk observe --help`。
+
+<!-- omk:cli:observe:flags:end -->
+
 把真实 Claude Code session trace 转成 skill 健康度报告：知识使用、gap 信号、执行稳定性、token 和耗时。这是生产观测，不是生产评分。
 
 #### B. observe inbox：reviewer 闭环
@@ -462,6 +539,7 @@ omk observe inbox --skill audit                    # 只看某个 skill
 omk observe inbox --by-skill                       # 按 skill 资产视图
 omk observe inbox --explore 10                     # 从 medium / low 桶抽 10 条长尾
 omk observe inbox --explore 10 --include-noise     # 显式包含 noise 桶
+omk observe inbox --llm-enhanced-review          # 显式调用模型进行链路增强复盘
 omk observe inbox --json                           # JSON 输出，便于自动化消费
 
 # 3. 反向查单条 observation 的事件三元组（前后 message 上下文）
@@ -477,6 +555,30 @@ omk observe show <inbox_id>
 
 支持 trace 格式：Claude Code session JSONL（`.jsonl`）、OpenClaw session JSONL（`.jsonl`）、markdown 对话日志（`.log`）。
 
+### `omk skill-extract`
+
+```bash
+omk skill-extract demo-create --review soft-xxx --status author_confirmed
+omk skill-extract demo-create --review soft-xxx --status rejected --reason "不是有效标准"
+```
+
+<!-- omk:cli:skill-extract:flags:start -->
+
+**Flags:**
+
+```text
+  --input-dir <value>  observation 数据目录
+  --json               JSON 格式输出
+  --lang <value>       输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --reason <value>     人工判断原因
+  --review <value>     要确认或否决的软标准 ID
+  --status <value>     确认状态：author_confirmed / rejected / pending_review（也接受 confirm / confirmed / reject / pending 别名）
+```
+
+完整描述见 `omk skill-extract --help`。
+
+<!-- omk:cli:skill-extract:flags:end -->
+
 ### `omk evolve`
 
 ```bash
@@ -484,6 +586,36 @@ omk evolve <skill>                  # 多轮自动迭代 skill
 omk evolve skills/foo.md --rounds 10 --target 4.5
 ```
 
+<!-- omk:cli:evolve:flags:start -->
+
+**Flags:**
+
+```text
+  --auto-fix-samples              每轮先修 skill，再修 sample，随后一起评估候选结果
+  --concurrency <value>           评测并发数，默认 1
+  --effort <value>                reasoning effort: low/medium/high/xhigh/max
+  --executor <value>              执行器名，默认 claude
+  --improve-mode <agent|rewrite>  改写策略（默认：agent）
+  --improve-model <value>         负责重写 skill 的 LLM，默认 sonnet
+  --judge-models <value>          评委 model（单评委约束），格式 executor:model。默认 claude:haiku
+  --lang <value>                  输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --model <value>                 被评测的 LLM，默认 sonnet
+  --no-diagnostic                 关 LLM diagnostic 调用
+  --reuse-latest-eval             复用可比的最新 eval 报告作为 round-0
+  --rounds <value>                最大迭代轮数，默认 5
+  --sample-fix-max-attempts <value>每条 sample 自动修复最多尝试次数（默认：2）
+  --samples <value>               样本文件路径，默认 eval-samples.json
+  --skip-connectivity             跳过 LLM 连通性预检
+  --skip-doctor                   跳过 doctor 门禁（escape hatch，自负 garbage-in 风险）
+  --stop-on-assertions-pass       普通样本断言全过时提前停止
+  --target <value>                目标 composite 分数，达到即停。不传则跑满 rounds
+  --timeout <value>               单样本超时秒，默认 120
+```
+
+完整描述见 `omk evolve --help`。
+
+<!-- omk:cli:evolve:flags:end -->
+
 让 skill 跑 eval → judge → 改写 SKILL.md 的多轮闭环，直到达到 `--target` 或 `--rounds` 上限。耗时按 `轮数 × 样本 × 变体` 累加，几分钟到几十分钟级别。原始 skill 文件版本保存在 `skills/evolve/*.r0.md`。
 
 ### `omk sample`
@@ -493,6 +625,27 @@ omk sample <skill>                  # 为单个 skill 生成或补齐评测用
 omk sample --batch                  # 为目录下缺评测集的 skill 批量生成
 ```
 
+<!-- omk:cli:sample:flags:start -->
+
+**Flags:**
+
+```text
+  --batch                批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
+  --count <value>        生成样本条数。不传由 LLM 按 skill 类型自动决定。
+  --fix                  fix 模式：基于最近评测报告自动修复 sample_design 类型失败。
+  --focus <value>        生成焦点（自然语言提示）。控制 LLM 偏向哪类用例。
+  --lang <value>         输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --model <value>        生成 LLM model 名，默认 opus。
+  --no-mock              不生成 mocks，eval 时所有工具调用真实执行。
+  --reports-dir <value>  报告目录（fix 模式用），默认 ~/.oh-my-knowledge/reports。
+  --skill-dir <value>    skill 根目录，默认 skills。batch 模式扫此目录。
+  --treatment <value>    指定 treatment 名（fix 模式用），默认推断自 skill 路径。
+```
+
+完整描述见 `omk sample --help`。
+
+<!-- omk:cli:sample:flags:end -->
+
 一次性生成。自动给生成的用例打 `provenance`。生成的 assertions 使用英文 / 数字 / 代码 token，便于跨中英文输出对比。
 
 ### `omk studio`
@@ -506,6 +659,25 @@ omk studio --observations-dir .omk/observations    # observe inbox 数据目录
 omk studio --no-open
 ```
 
+<!-- omk:cli:studio:flags:start -->
+
+**Flags:**
+
+```text
+  --analyses-dir <value>      分析数据目录（可选）
+  --dev                       dev 模式：子进程启动 + 热更新
+  --host <value>              监听 host，默认 localhost。改为 0.0.0.0 暴露给局域网
+  --lang <value>              输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+  --no-open                   不自动打开浏览器
+  --observations-dir <value>  观测数据目录（可选）
+  --port <value>              监听端口，默认 7799。传 0 让 OS 分配
+  --reports-dir <value>       报告目录，默认 ~/.oh-my-knowledge/reports
+```
+
+完整描述见 `omk studio --help`。
+
+<!-- omk:cli:studio:flags:end -->
+
 启动本地知识工作台浏览报告。verdict、样本回退、跨样本 diff、饱和曲线、单样本 drill-down 全部在 studio UI 里 —— omk 不提供 CLI 导出 / 分析子命令。CI gate 用 `omk eval` 的 exit code（PROGRESS 退 0、其他非 0），需要文字摘要自己 `jq` report JSON。
 
 Studio 是 skill-centric 信息架构 — 列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势，详情页（`/skills/<name>`）左栏列关键问题清单（skill 优化 / 用例优化 / 工具反馈三档），右栏画 chart.js 健康趋势 + 三个紧凑阶段卡（doctor / eval / observe），细节走 modal。旧的 run 列表挪到 `/runs`。访问 `/observations/inbox` 查看 observe inbox 看板：按 skill 资产视图（rollup）+ reviewer 待办建议 + 当前可观测漏斗 + 单 observation 详情面板（含事件三元组）。