oh-my-knowledge 0.35.0 → 0.37.0

package/README.md

@@ -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`. [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

@@ -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`。[规范 →](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|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|observe|sample|studio> [options
 npm i oh-my-knowledge -g
 ```
 
-omk CLI 顶层命令包括：`init` / `install` / `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` / `doctor` / `eval` / `observe`
 | 体检 skill 写法 | → `omk doctor` |
 | 查看 / 浏览报告 | → `omk studio`（启动本地报告浏览器） |
 | 看真实使用 trace | → `omk observe` |
+| 查看受管 skill 状态 | → `omk list` |
+| 按证据接受 / 回退某版本 | → `omk promote` / `omk rollback` |
 
 如果用户意图不明确，先扫描当前项目结构（skills/ 目录和 eval-samples 文件），然后推荐最合适的操作。
 

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

@@ -20,7 +20,7 @@ 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。
@@ -222,7 +222,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）
@@ -348,6 +348,42 @@ omk install git:main:skills/review
 omk install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review
 ```
 
+## omk list
+
+列出受管 skill 及其证据状态：生命周期（installed / measurable / promoted / stale）、最新 verdict、证据数、源。
+
+**用法:**
+
+```bash
+omk list [flags]
+```
+
+**Flags:**
+
+- `--global` `boolean`:看全局受管目录（~/.oh-my-knowledge/managed）而非项目 .omk/managed
+- `--json` `boolean`:输出 JSON（含完整可比性 marker），供脚本消费
+- `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
+
+**示例:**
+
+> 列出当前项目的受管 skill
+
+```bash
+omk list
+```
+
+> 列出全局受管 skill
+
+```bash
+omk list --global
+```
+
+> 机器可读 JSON 输出
+
+```bash
+omk list --json
+```
+
 ## omk observe
 
 分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。
@@ -443,6 +479,88 @@ omk observe show <inboxId> [flags]
 - `--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 四种模式。
@@ -461,6 +579,7 @@ 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。

package/dist/authoring/evolver.js

@@ -546,7 +546,7 @@ export function mergeEvolveReports(roundReports, skillName, totalCostUSD, sample
     }
     const runId = `evolve-${skillName}-${generateRunId([skillName]).split('-').slice(-2).join('-')}`;
     const report = {
-        reportKind: 'evaluation',
+        kind: 'evaluation',
         id: runId,
         meta: {
             ...firstReport.meta,

package/dist/cli/commands/doctor.js

@@ -7,6 +7,7 @@ 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';
 const DEFAULT_SAMPLE_FILENAMES = ['eval-samples.json', 'eval-samples.yaml', 'eval-samples.yml'];
 function findSamplesInDir(dir) {
     for (const name of DEFAULT_SAMPLE_FILENAMES) {
@@ -136,8 +137,8 @@ export default class Doctor extends BaseCommand {
         }),
         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 +206,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 +228,7 @@ export default class Doctor extends BaseCommand {
                     rules: rulesOverride,
                     samples,
                     requires,
+                    onProgress,
                 });
             }
             catch (err) {
@@ -275,9 +283,16 @@ function persistDoctorReport(report, outputDir) {
     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,
@@ -300,7 +315,8 @@ export function pruneDoctorHistory(dir, skillName, maxKeep) {
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            if (data?.reportKind !== 'doctor' || !Array.isArray(data.skills) || data.skills.length !== 1)
+            const kind = data?.kind === 'doctor' ? data.kind : null;
+            if (!kind || !Array.isArray(data.skills) || data.skills.length !== 1)
                 continue;
             if (data.skills[0].skillName !== skillName)
                 continue;

package/dist/cli/commands/eval/index.js

@@ -8,6 +8,7 @@ import { parseRunConfig } from '../../lib/parse-run-config.js';
 import { makeOnProgress } from '../../lib/progress.js';
 import { computeRunTally } from '../../lib/run-tally.js';
 import { DEFAULT_BOOTSTRAP_SAMPLES } from '../../../eval-core/bootstrap.js';
+import { EVALUATION_REPORT_SCHEMA_VERSION } from '../../../eval-core/evaluation-reporting.js';
 function isDryRunReport(report) {
     return Boolean(report && typeof report === 'object' && report.dryRun === true);
 }
@@ -65,16 +66,16 @@ async function recordEvidenceSafely(report, verdict, values, lang) {
 }
 function batchItemFallbackReport(batch, item) {
     return {
-        reportKind: 'evaluation',
+        kind: 'evaluation',
         id: item.reportId,
         meta: {
             ...batch.meta,
             variants: ['baseline', item.name],
             sampleCount: item.sampleCount,
             totalCostUSD: item.totalCostUSD,
-            // item.artifactHash 来自子报告(走 aggregateReport 的整树哈),故 fallback 与之一致标 schemaVersion 3,
-            // 避免「树哈 artifactHashes + 错位 schemaVersion」的错配。
-            schemaVersion: 3,
+            // item.artifactHash 来自子报告(走 aggregateReport 的整树哈),故 fallback 与之一致标当前 eval
+            // report schemaVersion,避免「树哈 artifactHashes + 错位 schemaVersion」的错配。
+            schemaVersion: EVALUATION_REPORT_SCHEMA_VERSION,
             artifactHashes: item.artifactHash ? { [item.name]: item.artifactHash } : {},
         },
         summary: item.summary,
@@ -88,7 +89,7 @@ async function loadBatchChildReports(batch, reportsDir, lang) {
     const reports = [];
     for (const item of batch.items) {
         const loaded = await store.get(item.reportId);
-        if (loaded?.reportKind === 'evaluation') {
+        if (loaded?.kind === 'evaluation') {
             reports.push(loaded);
         }
         else {
@@ -128,7 +129,7 @@ async function emitBatchVerdict(report, reportsDir, values, lang) {
 }
 async function announceSavedReport({ report, filePath, reportsDir, values, lang, }) {
     const tally = computeRunTally(report);
-    process.stderr.write(tCli(report.reportKind === 'batch-evaluation' ? 'cli.run.batch_complete' : 'cli.run.eval_complete', lang));
+    process.stderr.write(tCli(report.kind === 'batch-evaluation' ? 'cli.run.batch_complete' : 'cli.run.eval_complete', lang));
     process.stderr.write(tCli('cli.run.tally', lang, tally));
     process.stderr.write(tCli('cli.run.report_saved', lang, { path: filePath }));
     if (!values['no-serve'] && process.stdout.isTTY) {

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

@@ -1,6 +1,17 @@
 import { BaseCommand } from '../oclif/base-command.js';
 import { type CliLang } from '../lib/i18n.js';
 import type { EvolveArgs, EvolveFlags } from '../lib/cmd-flags.js';
+/** 路径处是否已存在「用例源」:按 statSync 判型 —— 文件(含无扩展名)直接算存在;
+ *  目录看是否含候选用例文件(排除 report/health/_ 前缀,对齐 sample.ts 的发现约定)。
+ *  用于区分「损坏文件(存在但解析失败 → 报错不覆盖)」与「确实没有用例(可生成)」。
+ *  不能用 extname 猜文件/目录:无扩展名的损坏样本文件会绕过守卫被覆盖,
+ *  带点的目录名(如 samples.v2/)会被误当文件。 */
+export declare function sampleSourceExists(p: string): boolean;
+/** 自动生成时的落盘目标:已存在的目录(含带点目录名,如 samples.v2/)→ 写进目录内的
+ *  samples.json;已存在的文件 → 覆盖该文件;不存在 → 按扩展名(有扩展名当文件,无扩展名
+ *  当目录,落 samples.json)。与 sampleSourceExists 同用 statSync 判型,不被带点目录名
+ *  误当成文件(否则 writeFileSync 撞 EISDIR)。 */
+export declare function resolveSampleOutFile(samplesAbs: string): string;
 export declare function runEvolve(args: EvolveArgs, flags: EvolveFlags, lang: CliLang): Promise<void>;
 export default class Evolve extends BaseCommand {
     static description: string;

package/dist/cli/commands/evolve.js

@@ -1,5 +1,5 @@
-import { resolve, join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { resolve, join, dirname, extname } from 'node:path';
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, statSync } from 'node:fs';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../oclif/i18n.js';
 import { BaseCommand } from '../oclif/base-command.js';
@@ -18,6 +18,40 @@ function validateEvolveEffort(raw, lang) {
     }
     return raw;
 }
+/** 路径处是否已存在「用例源」:按 statSync 判型 —— 文件(含无扩展名)直接算存在;
+ *  目录看是否含候选用例文件(排除 report/health/_ 前缀,对齐 sample.ts 的发现约定)。
+ *  用于区分「损坏文件(存在但解析失败 → 报错不覆盖)」与「确实没有用例(可生成)」。
+ *  不能用 extname 猜文件/目录:无扩展名的损坏样本文件会绕过守卫被覆盖,
+ *  带点的目录名(如 samples.v2/)会被误当文件。 */
+export function sampleSourceExists(p) {
+    let st;
+    try {
+        st = statSync(p);
+    }
+    catch {
+        return false;
+    }
+    if (!st.isDirectory())
+        return true;
+    try {
+        return readdirSync(p).some((f) => /\.(json|ya?ml)$/i.test(f) && !/^(report|health|_)/i.test(f));
+    }
+    catch {
+        return false;
+    }
+}
+/** 自动生成时的落盘目标:已存在的目录(含带点目录名,如 samples.v2/)→ 写进目录内的
+ *  samples.json;已存在的文件 → 覆盖该文件;不存在 → 按扩展名(有扩展名当文件,无扩展名
+ *  当目录,落 samples.json)。与 sampleSourceExists 同用 statSync 判型,不被带点目录名
+ *  误当成文件(否则 writeFileSync 撞 EISDIR)。 */
+export function resolveSampleOutFile(samplesAbs) {
+    try {
+        return statSync(samplesAbs).isDirectory() ? join(samplesAbs, 'samples.json') : samplesAbs;
+    }
+    catch {
+        return extname(samplesAbs) ? samplesAbs : join(samplesAbs, 'samples.json');
+    }
+}
 // runEvolve module-level helper:cli-exit.test 测「skillPath 空 throw CliExit(1)」走
 // in-process import 验证业务,Command.run() body 直接调它。
 export async function runEvolve(args, flags, lang) {
@@ -47,13 +81,79 @@ export async function runEvolve(args, flags, lang) {
     if (samplesFile === 'eval-samples.json' && !existsSync(resolve(samplesFile))) {
         samplesFile = resolvedInput.samplesPath;
     }
-    const { evolveSkill } = await import('../../authoring/evolver.js');
+    // 参数校验必须早于任何昂贵副作用(自动生成用例 / LLM 调用)。
     const { parseJudgeModelsArgOrExit } = await import('../lib/parse-run-config.js');
     const evolveJudges = parseJudgeModelsArgOrExit(flags['judge-models']);
     if (evolveJudges.length > 1) {
         console.error(tCli('cli.common.judge_models_single_only', lang, { cmd: 'omk evolve' }));
         throw new CliExit(2);
     }
+    // 无用例时自动生成 —— 让 omk evolve 成为「检测(doctor) → 生成用例 → 自迭代」一键命令。
+    // 已有用例(且非空)则原样使用;生成失败按普通错误退出。
+    const samplesAbs = resolve(samplesFile);
+    let hasSamples = false;
+    let loadErr = null;
+    try {
+        const { loadSamples } = await import('../../inputs/load-samples.js');
+        hasSamples = loadSamples(samplesAbs).samples.length > 0;
+    }
+    catch (err) {
+        loadErr = err;
+    }
+    const sourceExists = sampleSourceExists(samplesAbs);
+    // 用例源已存在却解析失败(JSON/YAML 语法错、duplicate id 等)= 损坏文件,
+    // 绝不用 LLM 生成内容覆盖它 —— 报错退出,让用户先修。只有真的没有用例源(文件
+    // 不存在 / 目录无候选用例文件)才进入自动生成。
+    if (loadErr && sourceExists) {
+        console.error(lang === 'zh'
+            ? `评测用例文件解析失败，evolve 不会覆盖它，请先修复：${samplesAbs}\n  原因：${loadErr.message}`
+            : `Failed to parse the samples source; evolve will not overwrite it. Fix it first: ${samplesAbs}\n  reason: ${loadErr.message}`);
+        throw new CliExit(1);
+    }
+    if (!hasSamples) {
+        try {
+            const { generateSamples } = await import('../../authoring/generator.js');
+            const skillContent = readFileSync(resolve(skillPath), 'utf-8');
+            // outFile:已存在目录写进内部 samples.json,已存在文件覆盖,不存在按扩展名 —— statSync
+            // 判型,不被带点目录名(samples.v2/)骗。loadSamples 目录模式会自动发现生成的文件。
+            const outFile = resolveSampleOutFile(samplesAbs);
+            // sourceExists 为真 = 用例源存在但解析出 0 条(合法空 [])→ 明示"重新生成覆盖空文件",
+            // 不静默盖用户文件;为假 = 真没有用例源 → "未发现，生成"。
+            process.stderr.write(lang === 'zh'
+                ? (sourceExists
+                    ? `评测用例为空，正在重新生成并覆盖 ${outFile} …\n`
+                    : `未发现评测用例，正在自动生成到 ${outFile} …\n`)
+                : (sourceExists
+                    ? `Samples are empty; regenerating (overwriting) ${outFile} …\n`
+                    : `No samples found; auto-generating to ${outFile} …\n`));
+            const { samples, costUSD } = await generateSamples({
+                skillContent,
+                model: flags.model,
+                executorName: flags.executor,
+            });
+            // 模型可能保守返回 0 条 —— 不写空文件再空跑迭代,直接报错让用户改用
+            // `omk sample --focus` 引导生成或手写用例。
+            if (samples.length === 0) {
+                console.error(lang === 'zh'
+                    ? '自动生成返回 0 条用例，已中止。请用 `omk sample <skill> --focus "…"` 引导生成，或手写后重试。'
+                    : 'Auto-generation produced 0 samples; aborting. Use `omk sample <skill> --focus "…"` to guide generation, or write samples manually.');
+                throw new CliExit(1);
+            }
+            mkdirSync(dirname(outFile), { recursive: true });
+            writeFileSync(outFile, JSON.stringify(samples, null, 2));
+            const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
+            process.stderr.write(lang === 'zh'
+                ? `已生成 ${samples.length} 条用例${cost}，开始自迭代。\n`
+                : `Generated ${samples.length} samples${cost}; starting evolution.\n`);
+        }
+        catch (err) {
+            if (err instanceof CliExit)
+                throw err;
+            console.error(tCli('cli.common.error_prefix', lang, { message: err.message }));
+            throw new CliExit(1);
+        }
+    }
+    const { evolveSkill } = await import('../../authoring/evolver.js');
     process.stderr.write(tCli('cli.evolve.section_header', lang, { path: skillPath }));
     try {
         const result = await evolveSkill({
@@ -208,8 +308,8 @@ export default class Evolve extends BaseCommand {
         }),
         model: Flags.string({
             description: bilingual({
-                zh: '被评测的 LLM，默认 sonnet',
-                en: 'Evaluated LLM, default sonnet',
+                zh: '被评测的 LLM，默认 sonnet。无用例时也用作自动生成用例的出题模型。',
+                en: 'Evaluated LLM, default sonnet. Also used as the sample-generation model when no samples exist.',
             }),
             default: 'sonnet',
         }),

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

@@ -0,0 +1,25 @@
+import { BaseCommand } from '../oclif/base-command.js';
+import { probeSourceState } from '../lib/source-probe.js';
+import { sanitizeCell } from '../lib/cell-format.js';
+import { type ManagedListRow } from '../../managed/index.js';
+import type { CliLang } from '../lib/i18n.js';
+export { probeSourceState };
+/** CJK 全角字符按 2 列计宽,使含中文表头的列也能对齐。 */
+export declare function dispWidth(s: string): number;
+/** 按**显示宽度**截断(不是 code unit):逐码点累加 dispWidth,绝不切断 surrogate 对、CJK 也不溢出列。 */
+export declare function truncate(s: string, max: number): string;
+export { sanitizeCell };
+export declare function renderTable(rows: ManagedListRow[], lang: CliLang): string;
+export default class List extends BaseCommand {
+    static description: string;
+    static examples: {
+        description: string;
+        command: string;
+    }[];
+    static flags: {
+        lang: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}