oh-my-knowledge 0.36.0 → 0.38.0

package/README.md

@@ -29,7 +29,7 @@ That's it — no editing required. `omk init` scaffolds two skill variants and t
 
 Walkthrough: [5-minute quickstart guide](docs/quickstart-skill-eval.md) (recommended for first-time users).
 
-Deeper: [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
+Deeper: [who omk is for](docs/explanation/who-omk-is-for.md) · [CLI reference](docs/reference/cli.md) · [how it works](docs/explanation/architecture.md) · [eval sample format](docs/reference/eval-sample-format.md) · [executors](docs/reference/executors.md) · [artifact layout](docs/reference/artifact-layout.md)
 
 ## Use inside AI Coding Agents
 
@@ -59,12 +59,14 @@ Codex does not support Claude Code style `/omk ...` slash commands. Ask the agen
 
 ```bash
 omk eval
-omk evolve skills/my-skill.md
+omk evolve skills/my-skill.md   # one-shot: doctor → (auto-generate samples if missing) → self-iterate
 omk sample skills/my-skill.md
 ```
 
 You can also describe the goal in natural language, such as "compare v1 vs v2" or "generate test cases for this skill".
 
+> `omk evolve` is a one-shot loop: it runs the doctor gate first, auto-generates eval samples when the target skill has none, then self-iterates. For a brand-new skill, just run `omk evolve skills/foo.md`.
+
 ## Why this tool
 
 Teams doing knowledge engineering produce lots of knowledge artifacts (skills today, but also prompts, agents, workflows…). When someone asks "why is v2 better than v1", you need objective data instead of gut feeling. `oh-my-knowledge` solves this with controlled experiments: **same model, same test samples, only the knowledge artifact changes.**
@@ -101,7 +103,7 @@ RAG-specific evals: see RAGAS (separate niche, complementary to omk). Full compa
 | **Knowledge-gap detection** | severity-weighted signals quantify risk exposure instead of claiming completeness |
 | **Construct-validity isolation** | `--strict-baseline` (default ON) cuts three contamination channels so baseline doesn't silently see the skill it's being compared against |
 | **Git & remote sources** | install / eval from a local git ref or a remote git URL (`--git-url`); directory-skills run in a content-addressed **isolated copy** so `references/` assets are real measured input, not just `SKILL.md` |
-| **Evidence-gated management** | `omk install` registers a managed record; `omk eval` auto-writes evidence bound by content fingerprint, moving a skill `installed → measurable`; `omk list` surfaces each managed skill's status (installed / measurable / stale). [spec →](docs/specs/evidence-gated-management.md) |
+| **Evidence-gated management** | `omk install` registers a managed record; `omk eval` auto-writes evidence bound by content fingerprint, moving a skill `installed → measurable`; `omk list` surfaces each managed skill's status (installed / measurable / promoted / stale); `omk promote` accepts a version once its evidence passes the gate (default PROGRESS only); `omk rollback` revokes that acceptance, returning the skill to `measurable`. [spec →](docs/specs/evidence-gated-management.md) |
 | **Sample design science** | sample schema with `capability` / `difficulty` / `construct` / `provenance` metadata (HF Dataset Cards style); studio surfaces coverage breakdown plus `rubric_clarity_low` / `capability_thin` flags. [docs/specs/sample-design-spec.md](docs/specs/sample-design-spec.md) |
 | **Multi-judge ensemble** | `--judge-models claude:opus,openai:gpt-4o` cross-vendor scoring + agreement metrics |
 | **Blind A/B** | `--blind` hides variant names; HTML report has a reveal button |
@@ -124,7 +126,7 @@ The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowl
 - **[Sample design spec](docs/specs/sample-design-spec.md)** — capability / construct / provenance metadata; industry-gap mapping
 - **[Statistical rigor](docs/explanation/statistical-rigor.md)** — why bootstrap CI / α / length-debias / saturation matter
 - **[Comparison with 7 tools](docs/reference/comparison.md)** — 25+ dimensions across promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai
-- **[Evidence-gated management](docs/specs/evidence-gated-management.md)** — managed records, lifecycle states (installed / measurable / stale), install → eval → measurable
+- **[Evidence-gated management](docs/specs/evidence-gated-management.md)** — managed records, lifecycle states (installed / measurable / promoted / stale), install → eval → measurable → promote → rollback
 
 ## Environment variables
 

package/README.zh.md

@@ -29,7 +29,7 @@ omk eval --control code-review-v1 --treatment code-review-v2
 
 手把手教程：[5 分钟快速上手](docs/zh/quickstart-skill-eval.md)（推荐第一次跑评测的用户）。
 
-深入：[CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [artifact 布局](docs/zh/reference/artifact-layout.md)
+深入：[为谁、解决什么](docs/zh/explanation/who-omk-is-for.md) · [CLI 参考](docs/zh/reference/cli.md) · [工作原理](docs/zh/explanation/architecture.md) · [评测用例格式](docs/zh/reference/eval-sample-format.md) · [执行器](docs/zh/reference/executors.md) · [artifact 布局](docs/zh/reference/artifact-layout.md)
 
 ## 在 AI Coding Agent 中使用
 
@@ -59,12 +59,14 @@ Codex 默认不支持 `/omk ...` 这种 Claude Code 风格的 slash command。
 
 ```bash
 omk eval
-omk evolve skills/my-skill.md
+omk evolve skills/my-skill.md   # 一键:体检 →(无用例则自动生成)→ 自迭代
 omk sample skills/my-skill.md
 ```
 
 也可以直接用自然语言描述目标，例如「比较 v1 和 v2 的评测差异」、「为这个 skill 生成评测用例」。
 
+> `omk evolve` 是一键闭环：默认先跑 doctor 体检，目标 skill 没有评测用例时会自动生成一批，再进入多轮自迭代。全新 skill 直接 `omk evolve skills/foo.md` 即可。
+
 ## 为什么需要这个工具
 
 做知识工程的团队会产出大量知识载体（当前常见是 skill，也包括 prompt、agent、workflow 等）。当被问到「v2 比 v1 好在哪」时，需要客观数据而非主观判断。`oh-my-knowledge` 通过控制变量实验解决这个问题：**相同模型、相同评测用例，只改变知识载体。**
@@ -101,7 +103,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 | **知识缺口识别** | 严重度加权的信号量化风险敞口，不宣称完备性 |
 | **用例隔离 (construct validity)** | `--strict-baseline`（默认开）三堵 baseline 拿到被测 skill 的污染路径 |
 | **Git / 远端源** | install / eval 支持本地 git ref 或远端 git URL（`--git-url`）；目录-skill 在内容寻址**隔离副本**里执行，`references/` 资产是真实测量输入，不只是 `SKILL.md` |
-| **证据门控管理** | `omk install` 登记受管记录；`omk eval` 按内容指纹自动写入证据，把 skill 从 `installed` 推到 `measurable`；`omk list` 查看各受管 skill 的状态（installed / measurable / stale）。[规范 →](docs/zh/specs/evidence-gated-management.md) |
+| **证据门控管理** | `omk install` 登记受管记录；`omk eval` 按内容指纹自动写入证据，把 skill 从 `installed` 推到 `measurable`；`omk list` 查看各受管 skill 的状态（installed / measurable / promoted / stale）；`omk promote` 在证据过门禁（默认仅 PROGRESS）后把该版本接受为当前版本；`omk rollback` 撤销这次接受，让 skill 回到 `measurable`。[规范 →](docs/zh/specs/evidence-gated-management.md) |
 | **用例设计科学性** | Sample schema 加 `capability` / `difficulty` / `construct` / `provenance` 元数据字段（HF Dataset Cards 风），studio 输出 coverage 分桶 + `rubric_clarity_low` / `capability_thin` issue。[docs/zh/specs/sample-design-spec.md](docs/zh/specs/sample-design-spec.md) |
 | **多评委 ensemble** | `--judge-models claude:opus,openai:gpt-4o` 跨厂商评分 + agreement 度量 |
 | **盲测 A/B** | `--blind` 隐藏变体名称，HTML 报告有揭晓按钮 |
@@ -124,7 +126,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 - **[用例设计规范](docs/zh/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射
 - **[统计严谨性](docs/zh/explanation/statistical-rigor.md)** —— 为什么 Bootstrap CI / α / 长度去偏 / 饱和曲线重要
 - **[7 工具对比](docs/zh/reference/comparison.md)** —— promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai 等 25+ 维度横评
-- **[证据门控管理](docs/zh/specs/evidence-gated-management.md)** —— 受管记录、生命周期状态（installed / measurable / stale）、install → eval → measurable
+- **[证据门控管理](docs/zh/specs/evidence-gated-management.md)** —— 受管记录、生命周期状态（installed / measurable / promoted / stale）、install → eval → measurable → promote → rollback
 
 ## 环境变量
 

package/dist/assets/agent-skills/omk/SKILL.md

@@ -4,7 +4,7 @@ description: |
   oh-my-knowledge 知识载体评测工具的智能代理。评测 skill（系统提示词）质量，对比不同版本效果，自动迭代改进。
   Use when: 用户提到"评测"、"测评"、"eval"、"benchmark"、"对比 skill"、"改进 skill"、"evolve"、"生成测试用例"、"gen-samples"、"omk"。
 user-invocable: true
-argument-hint: "<doctor|eval|evolve|init|install|list|observe|sample|studio> [options]"
+argument-hint: "<doctor|eval|evolve|init|install|list|observe|promote|rollback|sample|studio> [options]"
 ---
 
 # OMK — 知识载体评测
@@ -19,7 +19,7 @@ argument-hint: "<doctor|eval|evolve|init|install|list|observe|sample|studio> [op
 npm i oh-my-knowledge -g
 ```
 
-omk CLI 顶层命令包括：`init` / `install` / `list` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
+omk CLI 顶层命令包括：`init` / `install` / `list` / `promote` / `rollback` / `doctor` / `eval` / `observe` / `evolve` / `sample` / `studio`。没有 `bench` / `improve` / `gen-samples` 这些旧子命令名 —— 如果你在历史 SKILL / 文档里看到了，那是 v0.30 命令树重构之前的写法。
 
 ## 第二步：理解用户意图
 
@@ -33,6 +33,8 @@ omk CLI 顶层命令包括：`init` / `install` / `list` / `doctor` / `eval` / `
 | 体检 skill 写法 | → `omk doctor` |
 | 查看 / 浏览报告 | → `omk studio`（启动本地报告浏览器） |
 | 看真实使用 trace | → `omk observe` |
+| 查看受管 skill 状态 | → `omk list` |
+| 按证据接受 / 回退某版本 | → `omk promote` / `omk rollback` |
 
 如果用户意图不明确，先扫描当前项目结构（skills/ 目录和 eval-samples 文件），然后推荐最合适的操作。
 
@@ -140,7 +142,7 @@ omk studio --host 0.0.0.0                 # 局域网访问（默认 127.0.0.1
 omk studio --no-open                      # 不自动开浏览器
 ```
 
-Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observations/inbox` 查看 observe inbox 看板。
+Studio 是 skill-centric：列表页（`/`）按 skill 卡片展示健康等级 / 0-100 参考分 / 待优化数 / 趋势；详情页（`/skills/<name>`）左栏列关键问题清单，右栏画健康趋势 + 三档阶段卡（doctor / eval / observe）。访问 `/observe-inbox` 查看 observe inbox 看板。
 
 ## 第五步：解读结果
 

package/dist/assets/agent-skills/omk/references/commands.md

@@ -20,15 +20,16 @@ omk doctor [target] [flags]
 
 **Flags:**
 
-- `--dimensions` `option`:自定义维度配置文件（YAML），追加到内置 7 维度之后。
+- `--dimensions` `option`:自定义维度配置文件（YAML），追加到内置 7 维度之后。每条维度二选一：promptSection（走 LLM 体检）或 endpoint（POST skill 快照给接口判定）。注意：endpoint 会把 SKILL.md 全文 + 子文件发到该地址，仅对可信配置/可信地址启用。
 - `--effort` `option`:LLM 推理 effort：low / medium / high / xhigh / max。
 - `--executor` `option`:执行器名，默认 claude。指定为测试 fixture 路径可在测试里跑（同 omk doctor）。
 - `--fix` `boolean`:交互式修复：根据 doctor 报告问题，用 LLM agent 修复 skill。
 - `--gate` `boolean`:静默模式，只在 fail 时输出 stderr 摘要，exit code 标识结果。
+- `--global` `boolean`:写全局 ~/.oh-my-knowledge/doctors，而非项目 .omk/doctors
 - `--json` `boolean`:JSON 输出到 stdout，适合 CI / 外部脚本消费。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--model` `option`:LLM model 名，默认 sonnet。
-- `--output-dir` `option`:报告输出目录，默认 ~/.oh-my-knowledge/doctors。
+- `--output-dir` `option`:报告输出目录，默认项目级 .omk/doctors（--global 写全局）。
 - `--samples` `option`:用例文件路径（.json/.yaml）。不传则按 target / cwd 顺序自动发现。
 - `--static-only` `boolean`:离线静态模式，只跑 4 条静态 rule(skill_readable / skill_metadata / dependencies_present / samples_contract_aligned），不调 LLM。
 - `--timeout` `option`:单次 LLM 会话超时秒数，默认 600(10 分钟）。
@@ -79,6 +80,7 @@ omk eval [flags]
 - `--dry-run` `boolean`:只 plan 不实跑
 - `--effort` `option`:被测 LLM 扩展思考预算 low/medium/high/xhigh/max（默认 low；跨 effort 报告不严格可比）。
 - `--executor` `option`:执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。
+- `--global` `boolean`:报告写全局 ~/.oh-my-knowledge/reports，而非项目 .omk/
 - `--gold-dir` `option`:gold dataset 目录
 - `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
 - `--judge-repeat` `option`:每个 dim 评 N 次
@@ -94,7 +96,7 @@ omk eval [flags]
 - `--no-judge` `boolean`:跳过 LLM judge
 - `--no-serve` `boolean`:不启 report server
 - `--no-strict-baseline` `boolean`:关闭 baseline 隔离
-- `--output-dir` `option`:报告输出目录
+- `--output-dir` `option`:报告输出目录（默认项目级 .omk/reports）
 - `--repeat` `option`:每个 sample 重复跑 N 次
 - `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
 - `--resume` `option`:从某次失败 run 续跑
@@ -222,7 +224,7 @@ omk evolve <skillPath> [flags]
 - `--improve-model` `option` (默认 `sonnet`):负责重写 skill 的 LLM，默认 sonnet
 - `--judge-models` `option` (默认 `claude:haiku`):评委 model（单评委约束），格式 executor:model。默认 claude:haiku
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--model` `option` (默认 `sonnet`):被评测的 LLM，默认 sonnet
+- `--model` `option` (默认 `sonnet`):被评测的 LLM，默认 sonnet。无用例时也用作自动生成用例的出题模型。
 - `--no-diagnostic` `boolean`:关 LLM diagnostic 调用
 - `--no-edit-budget` `boolean`:关掉 edit budget 约束（允许任意大小的单轮改动）
 - `--no-reject-memory` `boolean`:关掉 rejected-edit 记忆（不把被拒改法回灌下一轮 prompt）
@@ -234,6 +236,7 @@ omk evolve <skillPath> [flags]
 - `--significance-alpha` `option` (默认 `0.05`):显著性门的 diff CI 显著性水平（默认 0.05 = 95% CI）
 - `--skip-connectivity` `boolean`:跳过 LLM 连通性预检
 - `--skip-doctor` `boolean`:跳过 doctor 门禁（escape hatch，自负 garbage-in 风险）
+- `--snapshot-only` `boolean`:只产候选、不写回 source：胜出版本留在 evolve/<skillName>.r{N}.md 供你挑选，再 omk promote 接受。受管 skill 默认会写回 source 并记证据（measurable）。
 - `--stop-on-assertions-pass` `boolean`:普通用例断言全过时提前停止
 - `--target` `option`:目标 composite 分数，达到即停。不传则跑满 rounds
 - `--test-ratio` `option` (默认 `0`):锁定 test 集比例（0..1，默认 0=关），需配 --holdout-ratio。全程不参与选择，收尾读一次给无偏泛化分
@@ -255,7 +258,7 @@ omk evolve skills/my-skill/SKILL.md --target 4.5 --model opus --improve-model op
 
 ## omk init
 
-初始化 omk 项目脚手架（skills/ + eval-samples.json 模板）。
+初始化一个 omk 项目：在目标目录铺好待测知识载体（skills/）与评测用例（eval-samples.json），供 omk eval / doctor / evolve / observe / list 操作。默认是两版 code-review skill 的 A/B 起步模板。
 
 **用法:**
 
@@ -273,13 +276,13 @@ omk init [targetDir] [flags]
 
 **示例:**
 
-> 在当前目录初始化
+> 在当前目录初始化一个 omk 项目
 
 ```bash
 omk init
 ```
 
-> 在指定目录初始化
+> 在指定目录初始化一个 omk 项目
 
 ```bash
 omk init my-project
@@ -350,7 +353,7 @@ omk install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/re
 
 ## omk list
 
-列出受管 skill 及其证据状态：生命周期（installed / measurable / stale）、最新 verdict、证据数、源。
+列出受管 skill 及其证据状态：生命周期（installed / measurable / promoted / stale）、最新 verdict、证据数、源。
 
 **用法:**
 
@@ -401,10 +404,11 @@ omk observe [sessionsDir] [flags]
 **Flags:**
 
 - `--from` `option`:起始时间 ISO，优先级高于 --last
+- `--global` `boolean`:写全局 ~/.oh-my-knowledge/observe-health，而非项目 .omk/observe-health
 - `--kb` `option`:知识库 root，启用 KB-aware 分析
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--last` `option`:时间窗(7d / 24h / 30m）
-- `--output-dir` `option`:分析结果输出目录
+- `--output-dir` `option`:健康报告输出目录，默认项目级 .omk/observe-health（--global 写全局）
 - `--skills` `option`:只看指定 skill，逗号分隔
 - `--to` `option`:结束时间 ISO
 
@@ -431,8 +435,9 @@ omk observe inbox [flags]
 - `--by-skill` `boolean`:按 skill 聚合输出
 - `--executor` `option`:LLM 增强复盘使用的执行器
 - `--explore` `option`:抽样 N 条 medium/low 长尾（replaces limit）
+- `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。
 - `--include-noise` `boolean`:explore 时也包含 noise 桶
-- `--input-dir` `option`:inbox 数据目录，默认 .omk/observations（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observations。
+- `--input-dir` `option`:inbox 数据目录，默认 .omk/observe-inbox（项目级，相对于 cwd）；目录不存在时兜底读 ~/.oh-my-knowledge/observe-inbox。
 - `--json` `boolean`:JSON 格式输出
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--limit` `option`:限制条数，默认 20
@@ -457,8 +462,9 @@ omk observe ingest <traceDir> [flags]
 
 **Flags:**
 
+- `--global` `boolean`:写入全局 ~/.oh-my-knowledge/observe-inbox，而非项目 .omk/observe-inbox。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
-- `--output-dir` `option`:输出目录，默认 .omk/observations（项目级，相对于 cwd）。
+- `--output-dir` `option`:输出目录，默认 .omk/observe-inbox（项目级，相对于 cwd；--global 写全局）。
 
 ## omk observe show
 
@@ -476,9 +482,92 @@ omk observe show <inboxId> [flags]
 
 **Flags:**
 
+- `--global` `boolean`:直接读取全局 ~/.oh-my-knowledge/observe-inbox（跳过项目级与兜底）。
 - `--input-dir` `option`:inbox 数据目录
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 
+## omk promote
+
+把受管 skill 的当前版本按证据门禁「接受」为 promoted：默认仅放行 verdict=PROGRESS,在记录里追加一条带证据指针的人工决定。
+
+**用法:**
+
+```bash
+omk promote <name> [flags]
+```
+
+**参数:**
+
+- `name`(必填):受管 skill 名（omk list 里的 NAME）
+
+**Flags:**
+
+- `--accept-cautious` `boolean`:把 CAUTIOUS 也算可接受（默认仅 PROGRESS）
+- `--actor` `option`:决定的 actor（默认取 git config user.name）
+- `--force` `boolean`:越过可越门拦截强制 promote，记为人工 override 决定（无当前证据或源 hash 已变时仍拒）
+- `--global` `boolean`:操作全局受管目录而非项目 .omk/managed
+- `--json` `boolean`:输出 JSON（版本化信封）供脚本消费
+- `--kind` `option` (默认 `skill`):artifact 类型（当前仅 skill）
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--reason` `option`:promote / 越门的理由（写入决定）
+
+**示例:**
+
+> promote 一个证据达标的 skill
+
+```bash
+omk promote review
+```
+
+> 接受 CAUTIOUS 结果（显式放宽门禁）
+
+```bash
+omk promote review --accept-cautious
+```
+
+> 越门 promote 并记录理由（人工 override）
+
+```bash
+omk promote review --force --reason "已人工复核"
+```
+
+## omk rollback
+
+回退受管 skill 当前版本的 promoted 接受：撤销最近一次 promote，在记录里追加一条 rollback 决定（源未漂移则状态回到 measurable，源已漂移则仍 stale）。
+
+**用法:**
+
+```bash
+omk rollback <name> [flags]
+```
+
+**参数:**
+
+- `name`(必填):受管 skill 名（omk list 里的 NAME）
+
+**Flags:**
+
+- `--actor` `option`:决定的 actor（默认取 git config user.name）
+- `--global` `boolean`:操作全局受管目录而非项目 .omk/managed
+- `--json` `boolean`:输出 JSON（版本化信封）供脚本消费
+- `--kind` `option` (默认 `skill`):artifact 类型（当前仅 skill）
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+- `--reason` `option`:回退的理由（写入决定）
+
+**示例:**
+
+> 回退一个已 promoted 的 skill
+
+```bash
+omk rollback review
+```
+
+> 回退并记录理由
+
+```bash
+omk rollback review --reason "线上发现回归"
+```
+
 ## omk sample
 
 为指定 skill 生成评测用例（eval-samples），支持 batch / single / fix / from-traces 四种模式。
@@ -497,13 +586,14 @@ omk sample [skillPath] [flags]
 
 - `--batch` `boolean`:批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
 - `--count` `option`:生成用例条数。不传由 LLM 按 skill 类型自动决定。
+- `--executor` `option`:执行器名，默认 claude（同 omk eval / doctor / evolve）。指定 codex 等其它执行器时，记得连带传一个该执行器能识别的 --model。
 - `--fix` `boolean`:fix 模式：基于最近评测报告自动修复 sample_design 类型失败。
 - `--focus` `option`:生成焦点（自然语言提示）。控制 LLM 偏向哪类用例。
 - `--from-traces` `boolean`:from-traces 模式：从 observe inbox 的失败信号回流生成回归用例草稿（provenance: production-trace），落草稿待人工 review。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--model` `option` (默认 `sonnet`):生成 LLM model 名，默认 sonnet。
 - `--no-mock` `boolean`:不生成 mocks，eval 时所有工具调用真实执行。
-- `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observations。
+- `--observations-dir` `option`:observe inbox 目录（from-traces 模式用），默认项目 .omk/observe-inbox。
 - `--reports-dir` `option`:报告目录（fix 模式用），默认 ~/.oh-my-knowledge/reports。
 - `--skill-dir` `option` (默认 `skills`):skill 根目录，默认 skills。batch 模式扫此目录。
 - `--treatment` `option`:指定 treatment 名（fix 模式用），默认推断自 skill 路径。
@@ -546,14 +636,16 @@ omk studio [flags]
 
 **Flags:**
 
-- `--analyses-dir` `option`:分析数据目录（可选）
+- `--analyses-dir` `option`:观测健康报告目录（可选，默认项目级 .omk/observe-health，空则全局兜底）
 - `--dev` `boolean`:dev 模式：子进程启动 + 热更新
+- `--doctors-dir` `option`:体检报告目录（可选，默认项目级 .omk/doctors，空则全局兜底）
+- `--global` `boolean`:只看全局 reports / observe-health / doctors / observe-inbox 目录（~/.oh-my-knowledge/*），而非机器级聚合 / 项目优先；managed 不受影响
 - `--host` `option`:监听 host，默认 localhost。改为 0.0.0.0 暴露给局域网
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--no-open` `boolean`:不自动打开浏览器
-- `--observations-dir` `option`:观测数据目录（可选）
+- `--observations-dir` `option`:观测收件箱数据目录（可选，默认 .omk/observe-inbox）
 - `--port` `option` (默认 `7799`):监听端口，默认 7799。传 0 让 OS 分配
-- `--reports-dir` `option`:报告目录，默认 ~/.oh-my-knowledge/reports
+- `--reports-dir` `option`:只看指定报告目录（可选；默认机器级聚合：当前项目 + 全局 + 别项目索引）
 
 **示例:**
 

package/dist/authoring/evolver.d.ts

@@ -182,6 +182,9 @@ interface EvolveOptions {
     /** Feed rejected candidate edits back into the next round's improvement prompt
      *  ("these were tried and did not help — don't repeat them"). Default true. */
     rejectMemory?: boolean;
+    /** 是否把胜出版本写回原 source 文件。默认 true（保「一键化」：evolve 跑完源即更新）。
+     *  `--snapshot-only` 置 false → 不写 source，候选仍落在 `evolve/<skillName>.r{N}.md` 供人工挑选 / promote。 */
+    writeBackToSource?: boolean;
     onProgress?: ProgressCallback | null;
     onRoundProgress?: ((progress: EvolveRoundProgressInfo) => void) | null;
 }
@@ -263,5 +266,5 @@ export interface RoundReport {
     report: Report;
 }
 export declare function mergeEvolveReports(roundReports: RoundReport[], skillName: string, totalCostUSD: number, samples?: Sample[], skillPath?: string): Report;
-export declare function evolveSkill({ skillPath, samplesPath, rounds, target, stopOnAssertionsPass, autoFixSamples, sampleFixMaxAttempts, reuseLatestEval, model, judgeModels, improveModel, improveMode, executorName, concurrency, timeoutMs, skipConnectivity, effort, noDiagnostic, skipDoctor, holdoutRatio, significanceGate, significanceAlpha, testRatio, editBudget, rejectMemory, onProgress, onRoundProgress, }: EvolveOptions): Promise<EvolveResult>;
+export declare function evolveSkill({ skillPath, samplesPath, rounds, target, stopOnAssertionsPass, autoFixSamples, sampleFixMaxAttempts, reuseLatestEval, model, judgeModels, improveModel, improveMode, executorName, concurrency, timeoutMs, skipConnectivity, effort, noDiagnostic, skipDoctor, holdoutRatio, significanceGate, significanceAlpha, testRatio, editBudget, rejectMemory, writeBackToSource, onProgress, onRoundProgress, }: EvolveOptions): Promise<EvolveResult>;
 export {};

package/dist/authoring/evolver.js

@@ -2,8 +2,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join, dirname, basename } from 'node:path';
 import { runEvaluation } from '../eval-workflows/run-evaluation.js';
 import { createExecutor, DEFAULT_MODEL, JUDGE_MODEL } from '../executors/index.js';
-import { persistReport, DEFAULT_OUTPUT_DIR, generateRunId, hashString } from '../eval-core/evaluation-reporting.js';
-import { createFileStore } from '../server/report-store.js';
+import { persistReport, DEFAULT_OUTPUT_DIR, runIdSuffix, hashString } from '../eval-core/evaluation-reporting.js';
+import { createOverlayReportStore } from '../server/report-store.js';
+import { projectReportsDir, globalReportsDir } from '../eval-core/measurement-dirs.js';
 import { analyzeResults } from '../analysis/report-diagnostics.js';
 import { loadSamples } from '../inputs/load-samples.js';
 import { hashArtifactSource } from '../inputs/content-hash.js';
@@ -87,7 +88,9 @@ function singleVariantReport(report, variantKey) {
     };
 }
 async function findReusableBaselineReport(opts) {
-    const store = createFileStore(DEFAULT_OUTPUT_DIR);
+    // baseline 复用读 overlay(项目 .omk/reports ∪ 全局):eval 写默认翻项目后,复用既能命中 eval 新写的项目
+    // baseline,又继续覆盖全局(含 evolve 自身写到全局的合并报告),复用命中率与报告数字不降。
+    const store = createOverlayReportStore(projectReportsDir(), globalReportsDir());
     const { samples } = loadSamples(opts.samplesPath);
     const artifactHash = opts.artifactHash;
     const reports = await store.findByArtifactHash(artifactHash);
@@ -544,7 +547,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
         if (originalKey)
             artifactHashes[variantLabels[i]] = hashes[originalKey];
     }
-    const runId = `evolve-${skillName}-${generateRunId([skillName]).split('-').slice(-2).join('-')}`;
+    const runId = `evolve-${skillName}-${runIdSuffix()}`;
     const report = {
         kind: 'evaluation',
         id: runId,
@@ -570,7 +573,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
     report.analysis = analyzeResults(report, { samples });
     return report;
 }
-export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target = null, stopOnAssertionsPass = false, autoFixSamples = false, sampleFixMaxAttempts = 2, reuseLatestEval = false, model = DEFAULT_MODEL, judgeModels, improveModel = DEFAULT_MODEL, improveMode = 'agent', executorName = 'claude', concurrency = 1, timeoutMs, skipConnectivity = false, effort, noDiagnostic, skipDoctor, holdoutRatio = 0, significanceGate = true, significanceAlpha = DEFAULT_BOOTSTRAP_ALPHA, testRatio = 0, editBudget = 0.2, rejectMemory = true, onProgress = null, onRoundProgress = null, }) {
+export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target = null, stopOnAssertionsPass = false, autoFixSamples = false, sampleFixMaxAttempts = 2, reuseLatestEval = false, model = DEFAULT_MODEL, judgeModels, improveModel = DEFAULT_MODEL, improveMode = 'agent', executorName = 'claude', concurrency = 1, timeoutMs, skipConnectivity = false, effort, noDiagnostic, skipDoctor, holdoutRatio = 0, significanceGate = true, significanceAlpha = DEFAULT_BOOTSTRAP_ALPHA, testRatio = 0, editBudget = 0.2, rejectMemory = true, writeBackToSource = true, onProgress = null, onRoundProgress = null, }) {
     if (judgeModels && judgeModels.length > 1) {
         throw new Error('evolveSkill does not support multi-judge ensemble (received '
             + `${judgeModels.length} judges). Pass a single-judge array, e.g. `
@@ -712,7 +715,8 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
         onRoundProgress({ round: 0, totalRounds: rounds, phase: 'baseline', score: bestScore, costUSD: baselineCost, costReported: baselineCostReported, reused: baselineReused });
     if (stopOnAssertionsPass && allNonTripwireAssertionsPass(baselineReport, baselineVariantKey)) {
         stopReason = 'assertions-pass';
-        writeFileSync(absSkillPath, currentBest);
+        if (writeBackToSource)
+            writeFileSync(absSkillPath, currentBest);
         const { samples } = loadSamples(absSamplesPath);
         const mergedReport = mergeEvolveReports(roundReports, skillName, totalCostUSD, samples, absSkillPath);
         persistReport(mergedReport, DEFAULT_OUTPUT_DIR);
@@ -908,8 +912,9 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
             break;
         }
     }
-    // Write best version back to original file only if an improvement was accepted
-    if (bestRound > 0) {
+    // Write best version back to original file only if an improvement was accepted.
+    // `--snapshot-only`（writeBackToSource=false）跳过写回:候选仍在 evolve/<skillName>.r{N}.md,源不动。
+    if (bestRound > 0 && writeBackToSource) {
         writeFileSync(absSkillPath, currentBest);
     }
     // Merge all round reports into one and persist

package/dist/cli/commands/doctor.d.ts

@@ -17,6 +17,7 @@ export default class Doctor extends BaseCommand {
         samples: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         timeout: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'output-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         dimensions: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'static-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         fix: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/cli/commands/doctor.js

@@ -1,4 +1,3 @@
-import { homedir } from 'node:os';
 import { existsSync, statSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Args, Flags } from '@oclif/core';
@@ -7,6 +6,10 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { numberStringParser } from '../oclif/parsers.js';
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
+import { makeDoctorProgress } from '../lib/progress.js';
+import { DEFAULT_DOCTORS_DIR } from '../../eval-core/default-dirs.js';
+import { indexDoctorWrite, removeDoctorCard } from '../../eval-core/artifact-index.js';
+import { projectDoctorsDir, globalDoctorsDir } from '../../eval-core/measurement-dirs.js';
 const DEFAULT_SAMPLE_FILENAMES = ['eval-samples.json', 'eval-samples.yaml', 'eval-samples.yml'];
 function findSamplesInDir(dir) {
     for (const name of DEFAULT_SAMPLE_FILENAMES) {
@@ -130,14 +133,20 @@ export default class Doctor extends BaseCommand {
         }),
         'output-dir': Flags.string({
             description: bilingual({
-                zh: '报告输出目录，默认 ~/.oh-my-knowledge/doctors。',
-                en: 'Report output dir, default ~/.oh-my-knowledge/doctors.',
+                zh: '报告输出目录，默认项目级 .omk/doctors（--global 写全局）。',
+                en: 'Report output dir, default project-level .omk/doctors (--global for global).',
+            }),
+        }),
+        global: Flags.boolean({
+            description: bilingual({
+                zh: '写全局 ~/.oh-my-knowledge/doctors，而非项目 .omk/doctors',
+                en: 'Write to global ~/.oh-my-knowledge/doctors instead of project .omk/doctors',
             }),
         }),
         dimensions: Flags.string({
             description: bilingual({
-                zh: '自定义维度配置文件（YAML），追加到内置 7 维度之后。',
-                en: 'Custom dimensions config file (YAML), appended after builtin 7 dimensions.',
+                zh: '自定义维度配置文件（YAML），追加到内置 7 维度之后。每条维度二选一：promptSection（走 LLM 体检）或 endpoint（POST skill 快照给接口判定）。注意：endpoint 会把 SKILL.md 全文 + 子文件发到该地址，仅对可信配置/可信地址启用。',
+                en: 'Custom dimensions config file (YAML), appended after builtin 7. Each is either promptSection (LLM audit) or endpoint (POST skill snapshot to your service). Note: endpoint sends the full SKILL.md + sub-files to that URL — only enable for trusted configs/URLs.',
             }),
         }),
         'static-only': Flags.boolean({
@@ -205,9 +214,15 @@ export default class Doctor extends BaseCommand {
             const { renderDoctorReportText, renderDoctorReportJson } = await import('../../doctor/renderer.js');
             const { getRegisteredRules } = await import('../../doctor/rules.js');
             const { isComposerRule } = await import('../../types/doctor.js');
+            // 在线检查(LLM health composer + endpoint 自定义维度)默认跑;--static-only
+            // 离线模式只跑纯静态的内置 rule(无网络 / LLM)。endpoint rule 标了 external=true。
+            const isOnline = (r) => isComposerRule(r) || r.external === true;
             const rulesOverride = staticOnly
-                ? getRegisteredRules().filter((r) => !isComposerRule(r))
-                : getRegisteredRules().filter(isComposerRule);
+                ? getRegisteredRules().filter((r) => !isOnline(r))
+                : getRegisteredRules().filter(isOnline);
+            // 批量体检进度(per-skill,写 stderr)。--gate 是静默模式,不报进度;
+            // --json 进度走 stderr 不污染 stdout 的 JSON。
+            const onProgress = flags.gate ? undefined : makeDoctorProgress(lang);
             let report;
             try {
                 report = await runDoctor({
@@ -221,6 +236,7 @@ export default class Doctor extends BaseCommand {
                     rules: rulesOverride,
                     samples,
                     requires,
+                    onProgress,
                 });
             }
             catch (err) {
@@ -252,7 +268,9 @@ export default class Doctor extends BaseCommand {
                 }
                 renderDoctorReportText(report, lang);
             }
-            persistDoctorReport(report, flags['output-dir'] ? resolve(flags['output-dir']) : undefined);
+            persistDoctorReport(report, flags['output-dir']
+                ? resolve(flags['output-dir'])
+                : (flags.global ? globalDoctorsDir() : projectDoctorsDir()));
             if (flags.fix) {
                 const existing = report;
                 if (existing.outcome !== 'failed') {
@@ -271,13 +289,20 @@ export default class Doctor extends BaseCommand {
 // scanDoctorReports 扫盘成本)。50 = ~每天 1 跑撑 1.5 个月 sparkline,够用。
 const DOCTOR_HISTORY_MAX_PER_SKILL = 50;
 function persistDoctorReport(report, outputDir) {
-    const dir = outputDir ?? join(homedir(), '.oh-my-knowledge', 'doctors');
+    const dir = outputDir ?? DEFAULT_DOCTORS_DIR;
     mkdirSync(dir, { recursive: true });
     const safeId = report.id.replace(/[/\\:*?"<>|]/g, '_');
     for (const skill of report.skills) {
+        const counts = { pass: 0, warn: 0, fail: 0, skipped: 0 };
+        for (const r of skill.results) {
+            const s = r.status;
+            if (s in counts)
+                counts[s]++;
+        }
         const perSkill = {
             ...report,
             skills: [skill],
+            ruleStats: { ...counts, total: skill.results.length },
             totals: {
                 pass: skill.status === 'pass' ? 1 : 0,
                 warn: skill.status === 'warn' ? 1 : 0,
@@ -286,7 +311,14 @@ function persistDoctorReport(report, outputDir) {
             outcome: skill.status === 'fail' ? 'failed' : skill.status === 'warn' ? 'warnings_only' : 'passed',
         };
         const safeName = skill.skillName.replace(/[/\\:*?"<>|]/g, '_');
-        writeFileSync(join(dir, `${safeName}-${safeId}.json`), JSON.stringify(perSkill, null, 2), 'utf8');
+        const cardId = `${safeName}-${safeId}`;
+        const filePath = join(dir, `${cardId}.json`);
+        writeFileSync(filePath, JSON.stringify(perSkill, null, 2), 'utf8');
+        // 产物发现索引:per-skill 报告落项目本地后,best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+        indexDoctorWrite({
+            id: cardId, path: filePath, skillName: skill.skillName, reportId: report.id, timestamp: report.timestamp,
+            status: skill.status, passCount: counts.pass, warnCount: counts.warn, failCount: counts.fail,
+        }, dir);
         pruneDoctorHistory(dir, skill.skillName, DOCTOR_HISTORY_MAX_PER_SKILL);
     }
 }
@@ -317,5 +349,8 @@ export function pruneDoctorHistory(dir, skillName, maxKeep) {
             unlinkSync(join(dir, file));
         }
         catch { /* ignore */ }
+        // 连带删卡片:否则被 prune 掉的报告会经 listDoctorCards 合并在本项目 studio「复活」(正文已删、卡片还在)。
+        // 卡片 id = 文件 stem(`{name}-{id}`),与 indexDoctorWrite 写入口径一致。
+        removeDoctorCard(file.replace(/\.json$/, ''));
     }
 }

package/dist/cli/commands/eval/gold/compare.js

@@ -4,7 +4,7 @@ import { BaseCommand } from '../../../oclif/base-command.js';
 import { LANG_FLAG, bilingual } from '../../../oclif/i18n.js';
 import { integerStringParser } from '../../../oclif/parsers.js';
 import { CliExit } from '../../../lib/cli-exit.js';
-import { DEFAULT_REPORTS_DIR } from '../../../lib/parse-run-config.js';
+import { projectReportsDir, globalReportsDir } from '../../../../eval-core/measurement-dirs.js';
 import { requireEvaluationReport } from '../../../lib/shared.js';
 export default class EvalGoldCompare extends BaseCommand {
     static description = bilingual({
@@ -62,7 +62,7 @@ export default class EvalGoldCompare extends BaseCommand {
             }
             const { loadGoldDataset } = await import('../../../../grading/gold-dataset.js');
             const { compareGoldToReport, formatGoldCompare } = await import('../../../../grading/gold-cli.js');
-            const { createFileStore } = await import('../../../../server/report-store.js');
+            const { createFileStore, createOverlayReportStore } = await import('../../../../server/report-store.js');
             const { dataset, issues } = loadGoldDataset(goldDir);
             if (!dataset) {
                 console.error('Cannot load gold dataset:');
@@ -72,8 +72,11 @@ export default class EvalGoldCompare extends BaseCommand {
             }
             for (const i of issues)
                 console.error(`warn: ${i.message}`);
-            const reportsDir = flags['reports-dir'] ?? DEFAULT_REPORTS_DIR;
-            const store = createFileStore(resolve(reportsDir));
+            // 显式 --reports-dir 固定该目录;默认 overlay(项目 .omk/reports 盖全局),get(reportId) 项目→全局兜底,
+            // 不因 eval 写默认翻项目而对比落空。
+            const store = flags['reports-dir']
+                ? createFileStore(resolve(flags['reports-dir']))
+                : createOverlayReportStore(projectReportsDir(), globalReportsDir());
             const report = requireEvaluationReport(await store.get(reportId), reportId, lang);
             const samples = Math.max(100, Number(flags['bootstrap-samples'] ?? 1000) || 1000);
             const seedVal = flags.seed != null ? Number(flags.seed) : undefined;

package/dist/cli/commands/eval/index.d.ts

@@ -18,6 +18,7 @@ export default class Eval extends BaseCommand {
         executor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'judge-models': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'output-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-judge': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-cache': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;