oh-my-knowledge 0.42.0 → 0.44.0

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

@@ -2,8 +2,8 @@ import { BaseCommand } from '../../oclif/base-command.js';
 import type { SkillHealthReport } from '../../../observability/skill-health-analyzer.js';
 /**
  * observe-health 报告落盘:id / 文件名加 4 位随机段,根治「同秒两次 omk observe 直接覆盖、数据丢失」的 bug。
- * 保留 `-observe-health.json` 后缀 —— resolveObserveHealthDir 靠它判项目优先、listAnalyses 靠它取 id stem、
- * loadAnalysis 靠 `${id}.json` 读真身。落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+ * 文件名统一为 `{run}.report.json`:目录表达 observe-health 域,文件表达这是可读报告。
+ * 落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
  */
 export declare function persistObserveHealthReport(report: SkillHealthReport, outDir: string): {
     id: string;

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

@@ -1,5 +1,5 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve } from 'node:path';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../../oclif/i18n.js';
 import { BaseCommand } from '../../oclif/base-command.js';
@@ -8,17 +8,18 @@ import { tCli } from '../../lib/i18n.js';
 import { parseLastWindow } from '../../lib/shared.js';
 import { projectObserveHealthDir, globalObserveHealthDir } from '../../../eval-core/measurement-dirs.js';
 import { indexObserveWrite } from '../../../eval-core/artifact-index.js';
+import { reportFilePath, runFileSuffix } from '../../../eval-core/artifact-file-names.js';
+import { migrateLegacyReportFiles } from '../../../eval-core/report-file-migration.js';
 /**
  * observe-health 报告落盘:id / 文件名加 4 位随机段,根治「同秒两次 omk observe 直接覆盖、数据丢失」的 bug。
- * 保留 `-observe-health.json` 后缀 —— resolveObserveHealthDir 靠它判项目优先、listAnalyses 靠它取 id stem、
- * loadAnalysis 靠 `${id}.json` 读真身。落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
+ * 文件名统一为 `{run}.report.json`:目录表达 observe-health 域,文件表达这是可读报告。
+ * 落盘后 best-effort 追加全局轻卡片,让 studio 跨项目聚合。
  */
 export function persistObserveHealthReport(report, outDir) {
     mkdirSync(outDir, { recursive: true });
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const rand = Math.random().toString(36).slice(2, 6);
-    const id = `${timestamp}-${rand}-observe-health`;
-    const jsonPath = join(outDir, `${id}.json`);
+    migrateLegacyReportFiles(outDir, 'observe-health');
+    const id = runFileSuffix();
+    const jsonPath = reportFilePath(outDir, id);
     writeFileSync(jsonPath, JSON.stringify(report, null, 2));
     indexObserveWrite(report, jsonPath, outDir, id);
     return { id, jsonPath };

package/dist/cli/commands/sample.js

@@ -9,6 +9,7 @@ import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
 import { loadSamples, parseYaml, listSampleFilesInDir } from '../../inputs/load-samples.js';
+import { defaultFlatSkillSamplesFile, defaultSkillLocalSamplesFile, findFlatSkillSamplesPath, findSkillSamplesPath, } from '../../inputs/sample-locator.js';
 import { hashSample } from '../../eval-core/evaluation-reporting.js';
 import { hashArtifactSource } from '../../inputs/content-hash.js';
 function isRecord(value) {
@@ -233,23 +234,23 @@ async function runSampleFix(args, flags, lang) {
         console.error(lang === 'zh' ? '请指定 skill 路径，如: omk sample skills/my-skill/SKILL.md --fix' : 'Specify skill path: omk sample skills/my-skill/SKILL.md --fix');
         throw new CliExit(1);
     }
-    const resolvedSkillPath = resolve(skillPath);
-    if (!existsSync(resolvedSkillPath)) {
-        console.error(lang === 'zh' ? `skill 文件不存在: ${resolvedSkillPath}` : `Skill file not found: ${resolvedSkillPath}`);
+    const { resolveSkillInput } = await import('../lib/resolve-skill-input.js');
+    let resolvedInput;
+    try {
+        resolvedInput = resolveSkillInput(skillPath, lang);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
         throw new CliExit(1);
     }
-    const isDir = basename(resolvedSkillPath) === 'SKILL.md';
-    const skillDir = isDir ? dirname(resolvedSkillPath) : dirname(resolvedSkillPath);
-    const samplesInput = isDir
-        ? join(skillDir, '.omk')
-        : resolve('eval-samples.json');
+    const samplesInput = resolvedInput.samplesPath;
     if (!existsSync(samplesInput)) {
         console.error(lang === 'zh' ? `samples 路径不存在: ${samplesInput}，先运行 omk sample 生成` : `Samples path not found: ${samplesInput}, run omk sample first`);
         throw new CliExit(1);
     }
-    const defaultTreatmentName = isDir
-        ? basename(skillDir)
-        : basename(resolvedSkillPath, extname(resolvedSkillPath));
+    const defaultTreatmentName = resolvedInput.isDirectorySkill
+        ? basename(resolvedInput.skillDir)
+        : basename(resolvedInput.skillPath, extname(resolvedInput.skillPath));
     const treatmentName = flags.treatment ?? defaultTreatmentName;
     process.stderr.write(lang === 'zh' ? `🔍 正在查找 ${treatmentName} 的最新评测报告...\n` : `🔍 Scanning latest report for ${treatmentName}...\n`);
     // 显式 --reports-dir 固定该目录;默认 overlay(项目 .omk/reports 盖全局),findByVariant 记录优先看项目、
@@ -277,7 +278,7 @@ async function runSampleFix(args, flags, lang) {
         throw new CliExit(1);
     }
     const samples = loadedSamples.samples;
-    const skillContent = readFileSync(resolvedSkillPath, 'utf-8');
+    const skillContent = readFileSync(resolvedInput.skillPath, 'utf-8');
     const sampleDesignIds = collectSampleDesignFailureIds(report, treatmentName);
     const sampleDesignCount = sampleDesignIds.size;
     if (sampleDesignCount === 0) {
@@ -286,7 +287,7 @@ async function runSampleFix(args, flags, lang) {
     }
     // 当前内容指纹走整树哈,与 eval 报告口径一致:dir-skill(用户传 .../SKILL.md)哈整棵 skill 目录、
     // 单文件 .md 哈单文件字节。
-    const currentContentHash = hashArtifactSource(isDir ? skillDir : resolvedSkillPath, isDir);
+    const currentContentHash = hashArtifactSource(resolvedInput.isDirectorySkill ? resolvedInput.skillDir : resolvedInput.skillPath, resolvedInput.isDirectorySkill);
     try {
         assertFixReportMatchesCurrentInputs({
             report,
@@ -435,24 +436,29 @@ async function runSample(args, flags, lang) {
             let name;
             let skillPath;
             let samplesPath;
+            let existingSamplesPath;
             const fullPath = join(skillDir, entry);
             if (entry.endsWith('.md') && !entry.endsWith('.eval-samples.json')) {
                 name = entry.slice(0, -3);
                 skillPath = fullPath;
-                samplesPath = join(skillDir, `${name}.eval-samples.json`);
+                samplesPath = defaultFlatSkillSamplesFile(skillDir, name);
+                existingSamplesPath = findFlatSkillSamplesPath(skillDir, name);
             }
             else if (statSync(fullPath).isDirectory()) {
                 const skillMd = join(fullPath, 'SKILL.md');
                 if (!existsSync(skillMd))
                     continue;
+                if (existsSync(join(skillDir, `${entry}.md`)))
+                    continue;
                 name = entry;
                 skillPath = skillMd;
-                samplesPath = join(fullPath, '.omk', 'samples.json');
+                samplesPath = defaultSkillLocalSamplesFile(fullPath);
+                existingSamplesPath = findSkillSamplesPath(fullPath);
             }
             else {
                 continue;
             }
-            if (existsSync(samplesPath)) {
+            if (existingSamplesPath) {
                 process.stderr.write(tCli('cli.gen.skill_skipped_existing', lang, { name }));
                 continue;
             }

package/dist/cli/lib/i18n-dict/common.d.ts

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type CommonMessageKey = 'cli.common.unknown_domain' | 'cli.common.error_prefix' | 'cli.common.skill_dir_not_found' | 'cli.common.skill_file_not_found' | 'cli.common.skill_dir_no_skill_md' | 'cli.common.report_not_found' | 'cli.common.no_judge_model' | 'cli.common.judge_models_single_only' | 'cli.common.warn_load_samples_failed' | 'cli.update.new_version_available' | 'cli.update.box_title' | 'cli.update.box_version_line' | 'cli.update.box_upgrade_line' | 'cli.update.box_silence_line' | 'cli.observe.view_hint' | 'cli.observe.observation_recorded' | 'cli.observe.production_gap' | 'cli.studio.started' | 'cli.studio.stop_hint' | 'cli.studio.open_failed' | 'cli.doctor.no_skill_found' | 'cli.doctor.samples_detected' | 'cli.doctor.progress_skill_start' | 'cli.doctor.progress_skill_done';
+export type CommonMessageKey = 'cli.common.unknown_domain' | 'cli.common.error_prefix' | 'cli.common.skill_dir_not_found' | 'cli.common.skill_file_not_found' | 'cli.common.skill_dir_no_skill_md' | 'cli.common.report_not_found' | 'cli.common.no_judge_model' | 'cli.common.judge_models_single_only' | 'cli.common.warn_load_samples_failed' | 'cli.common.deprecated_skill_samples_path' | 'cli.common.samples_not_found' | 'cli.update.new_version_available' | 'cli.update.box_title' | 'cli.update.box_version_line' | 'cli.update.box_upgrade_line' | 'cli.update.box_silence_line' | 'cli.observe.view_hint' | 'cli.observe.observation_recorded' | 'cli.observe.production_gap' | 'cli.studio.started' | 'cli.studio.stop_hint' | 'cli.studio.open_failed' | 'cli.doctor.no_skill_found' | 'cli.doctor.samples_detected' | 'cli.doctor.progress_skill_start' | 'cli.doctor.progress_skill_done';
 export declare const commonDict: Record<CommonMessageKey, CliMessage>;

package/dist/cli/lib/i18n-dict/common.js

@@ -35,6 +35,14 @@ export const commonDict = {
         zh: '⚠ 加载 samples 文件失败 ({path}): {message}\n',
         en: '⚠ Failed to load samples file ({path}): {message}\n',
     },
+    'cli.common.deprecated_skill_samples_path': {
+        zh: '⚠ 发现旧的目录 skill 用例位置：{oldPath}。目录 skill 的私有用例已改放到 {newPath}，请迁移。\n',
+        en: '⚠ Found deprecated directory skill samples path: {oldPath}. Directory skill samples now live at {newPath}; please migrate.\n',
+    },
+    'cli.common.samples_not_found': {
+        zh: '未找到评测用例：{path}。请通过 --samples 指定文件，或创建项目级 eval-samples.json；单 treatment 目录 skill 请使用 <skill>/.omk/samples.json。',
+        en: 'Eval samples not found: {path}. Pass --samples, create project-level eval-samples.json, or use <skill>/.omk/samples.json for a single-treatment directory skill.',
+    },
     'cli.update.new_version_available': {
         zh: '\n💡 新版本可用：{old} → {new}，运行 npm i -g oh-my-knowledge@latest 升级\n\n',
         en: '\n💡 New version available: {old} → {new}, run npm i -g oh-my-knowledge@latest to upgrade\n\n',

package/dist/cli/lib/i18n-dict/help.js

@@ -170,20 +170,21 @@ omk sample——生成或补齐 eval-samples 评测用例
   omk sample --batch [--skill-dir <dir>] [options]
 
 输出位置（默认）：
-  <skill>/SKILL.md  → <skill>/.omk/samples.json（omk 标准约定）
-  其他 .md 路径    → 当前目录的 eval-samples.json（兜底）
+  目录 skill（<skill>/SKILL.md） → <skill>/.omk/samples.json（omk 标准约定）
+  扁平 .md（单次）               → 当前目录的 eval-samples.json（项目级兜底）
+  扁平 .md（--batch）            → <skill-dir>/<name>.eval-samples.json（兼容 paired 布局）
 
 选项：
   --count <n>                         强制生成 N 条（不指定时由 LLM 按 skill 类型自动判断：
                                        工作流型 6-8 条 / 原子型 4-6 条 / 混合型 5-7 条）
   --model <name>                      生成模型（默认：opus；lean+effort-low 已自动开,想省钱可改 sonnet/haiku）
   --focus <text>                      自然语言指定希望覆盖的场景（追加到 prompt，优先级高于自由发挥）
-  --batch                             为 skill 目录下缺少 eval-samples 的 skill 批量生成
+  --batch                             为 skill 目录下缺少 samples 的 skill 批量生成
   --skill-dir <path>                  skill 目录（batch 使用，默认：skills）
 
 示例：
-  omk improve samples skills/req-tool.md
-  omk improve samples skills/req-tool.md --count 8 \\
+  omk sample skills/req-tool.md
+  omk sample skills/req-tool.md --count 8 \\
     --focus "重点覆盖 tag 查询走 PROJECT 空 → WORKSPACE 兜底的多步流程，以及 search 失败的错误路径"
 `,
         en: `
@@ -194,20 +195,21 @@ Usage:
   omk sample --batch [--skill-dir <dir>] [options]
 
 Output path (default):
-  <skill>/SKILL.md  → <skill>/.omk/samples.json (omk standard layout)
-  other .md paths   → ./eval-samples.json in current directory (fallback)
+  directory skill (<skill>/SKILL.md) → <skill>/.omk/samples.json (omk standard layout)
+  flat .md (single)                  → ./eval-samples.json in current directory (project fallback)
+  flat .md (--batch)                 → <skill-dir>/<name>.eval-samples.json (compatible paired layout)
 
 Options:
   --count <n>                         Force N samples (omit to let LLM auto-decide by skill type:
                                        workflow 6-8 / atomic 4-6 / mixed 5-7)
   --model <name>                      Generation model (default: opus; lean+effort-low applied; pass --model sonnet/haiku to save cost)
   --focus <text>                      Natural-language scenario hints appended to the prompt (overrides freeform diversity)
-  --batch                             Generate for skills that are missing eval-samples
+  --batch                             Generate for skills that are missing samples
   --skill-dir <path>                  Skill directory for batch mode (default: skills)
 
 Examples:
-  omk improve samples skills/req-tool.md
-  omk improve samples skills/req-tool.md --count 8 \\
+  omk sample skills/req-tool.md
+  omk sample skills/req-tool.md --count 8 \\
     --focus "Cover PROJECT-empty → WORKSPACE-fallback multi-step tag lookup and the search-failure error path"
 `,
     },

package/dist/cli/lib/parse-run-config/samples-discovery.d.ts

@@ -1,18 +1,16 @@
 /**
  * 当 CLI 未传 `--samples` 时,自动发现 sample 路径。
  *
- * 发现顺序(单 treatment 模式):
- *   1. treatment 是绝对 / 相对路径(文件 / 目录) → 找它所在目录的 `.omk/`
- *   2. fallback 找目录里的 `eval-samples.{json,yaml,yml}`
- *   3. fallback `<skillDir>/<treatmentName>/.omk/`
- *   4. 终极兜底 cwd 下的 `eval-samples.{json,yaml,yml}`
+ * 发现顺序:
+ *   1. 单 treatment → 找该 skill 私有 samples(`<skill>/.omk/`)或扁平 skill paired 文件
+ *   2. 终极兜底 cwd 下的项目级 `eval-samples.{json,yaml,yml}`
  *
  * `loadSamples` 在下游自己处理「文件 vs 目录」—— 目录模式 glob `*.{json,yaml,yml}`
  * 合并,跳过 reserved 前缀(`report-` / `health-` / `_`)。所以一个 skill 可以把
  * sample 拆到多文件(`workflow.json` + `platform.json`),也可以单 `samples.json`,
  * 两种都行。
  *
- * 多 treatment 评测必须显式传 `--samples`(因为「找哪个 skill 的 bundled samples」
- * 没有唯一答案)。本函数仅处理单 treatment 与零 treatment 情况。
+ * 多 treatment 评测不会触发 skill-local 自动发现(因为「找哪个 skill 的 bundled samples」
+ * 没有唯一答案),只回到项目级 samples 兜底。
  */
 export declare function discoverSamplesPath(values: Record<string, unknown>, skillDir: string): string;

package/dist/cli/lib/parse-run-config/samples-discovery.js

@@ -1,50 +1,28 @@
 /**
  * 当 CLI 未传 `--samples` 时,自动发现 sample 路径。
  *
- * 发现顺序(单 treatment 模式):
- *   1. treatment 是绝对 / 相对路径(文件 / 目录) → 找它所在目录的 `.omk/`
- *   2. fallback 找目录里的 `eval-samples.{json,yaml,yml}`
- *   3. fallback `<skillDir>/<treatmentName>/.omk/`
- *   4. 终极兜底 cwd 下的 `eval-samples.{json,yaml,yml}`
+ * 发现顺序:
+ *   1. 单 treatment → 找该 skill 私有 samples(`<skill>/.omk/`)或扁平 skill paired 文件
+ *   2. 终极兜底 cwd 下的项目级 `eval-samples.{json,yaml,yml}`
  *
  * `loadSamples` 在下游自己处理「文件 vs 目录」—— 目录模式 glob `*.{json,yaml,yml}`
  * 合并,跳过 reserved 前缀(`report-` / `health-` / `_`)。所以一个 skill 可以把
  * sample 拆到多文件(`workflow.json` + `platform.json`),也可以单 `samples.json`,
  * 两种都行。
  *
- * 多 treatment 评测必须显式传 `--samples`(因为「找哪个 skill 的 bundled samples」
- * 没有唯一答案)。本函数仅处理单 treatment 与零 treatment 情况。
+ * 多 treatment 评测不会触发 skill-local 自动发现(因为「找哪个 skill 的 bundled samples」
+ * 没有唯一答案),只回到项目级 samples 兜底。
  */
-import { resolve, join, dirname } from 'node:path';
-import { existsSync, statSync } from 'node:fs';
+import { findProjectSamplesFile, findSingleTreatmentSamplesPath } from '../../../inputs/sample-locator.js';
 export function discoverSamplesPath(values, skillDir) {
     const treatmentRaw = values.treatment;
     const treatments = treatmentRaw
         ? treatmentRaw.split(',').map((v) => v.trim()).filter(Boolean)
         : [];
     if (treatments.length === 1) {
-        const expr = treatments[0];
-        const resolved = resolve(expr);
-        if (existsSync(resolved)) {
-            const treatmentDir = statSync(resolved).isDirectory() ? resolved : dirname(resolved);
-            const omkDir = join(treatmentDir, '.omk');
-            if (existsSync(omkDir))
-                return omkDir;
-            for (const name of ['eval-samples.json', 'eval-samples.yaml', 'eval-samples.yml']) {
-                if (existsSync(join(treatmentDir, name)))
-                    return join(treatmentDir, name);
-            }
-        }
-        const omkDir = join(skillDir, expr, '.omk');
-        if (existsSync(omkDir))
-            return omkDir;
+        const samplesPath = findSingleTreatmentSamplesPath(treatments[0], skillDir, process.cwd());
+        if (samplesPath)
+            return samplesPath;
     }
-    let cwdFile = 'eval-samples.json';
-    if (!existsSync(resolve(cwdFile))) {
-        if (existsSync(resolve('eval-samples.yaml')))
-            cwdFile = 'eval-samples.yaml';
-        else if (existsSync(resolve('eval-samples.yml')))
-            cwdFile = 'eval-samples.yml';
-    }
-    return cwdFile;
+    return findProjectSamplesFile(process.cwd()) ?? 'eval-samples.json';
 }

package/dist/cli/lib/parse-run-config.js

@@ -41,10 +41,10 @@ export function parseRunConfig(values) {
         ? loadEvalConfig(values.config)
         : null;
     const skillDir = resolve(values['skill-dir'] ?? 'skills');
-    // 2) Resolve samples path: CLI > config > <skillDir>/<treatment>/.omk/ discovery > cwd default.
-    // The .omk/ discovery only fires when exactly one --treatment is given, so omk knows
-    // which skill's bundled samples to use. The dir form (loadSamples handles both file + dir)
-    // means a skill can split samples across multiple files (workflow.json / platform.json / ...).
+    // 2) Resolve samples path: CLI > config > single-treatment skill-local discovery > cwd project default.
+    // Skill-local discovery only fires when exactly one --treatment is given, so omk knows
+    // which skill's bundled samples to use. The `<skill>/.omk/` dir form (loadSamples handles
+    // both file + dir) means a skill can split samples across multiple files.
     const cliSamples = values.samples;
     let samplesFile;
     if (cliSamples) {

package/dist/cli/lib/resolve-skill-input.js

@@ -1,10 +1,11 @@
 import { resolve, join, dirname, basename } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import { tCli } from './i18n.js';
+import { findFlatSkillSamplesPath, findProjectSamplesFile, findSkillSamplesPath, skillLocalSamplesDir, } from '../../inputs/sample-locator.js';
 // 统一 skill 入参解析:既接受 SKILL.md 文件(老式 + flat skill),也接受 directory-skill
-// 目录(skills/foo/ 自动找 foo/SKILL.md)。samples 发现优先级:.omk/ 目录(loadSamples
-// 支持目录模式，自动 glob 多文件) > eval-samples.json > .yaml > .yml,fallback 是
-// .omk/ 目录路径(给上游 "samples 不存在" 的提示一个稳定路径)。
+// 目录(skills/foo/ 自动找 foo/SKILL.md)。目录-skill 以 `<skill>/.omk/` 为标准
+// samples 命名空间;扁平 .md 兼容 paired sidecar,找不到时回到项目级
+// `eval-samples.json`。
 //
 // 错误用 tCli 走 i18n,调用方直接 console.error err.message 给用户看,zh/en 都要正确。
 export function resolveSkillInput(input, lang) {
@@ -26,16 +27,13 @@ export function resolveSkillInput(input, lang) {
         skillPath = resolved;
         skillDir = dirname(resolved);
     }
-    const omkDir = join(skillDir, '.omk');
-    const candidates = [
-        ...(existsSync(omkDir) ? [omkDir] : []),
-        join(skillDir, 'eval-samples.json'),
-        join(skillDir, 'eval-samples.yaml'),
-        join(skillDir, 'eval-samples.yml'),
-    ];
-    // fallback 到 .omk/ 目录：上游会报 "no sample files found in directory" 引导用户创建
-    const samplesPath = candidates.find(existsSync) ?? omkDir;
     // 形态以解析后的 skillPath 命名为准:目录-skill 的 skillPath 总是 `.../SKILL.md`。
     const isDirectorySkill = basename(skillPath) === 'SKILL.md';
+    const flatSkillName = basename(skillPath).replace(/\.md$/i, '');
+    const samplesPath = isDirectorySkill
+        ? findSkillSamplesPath(skillDir) ?? skillLocalSamplesDir(skillDir)
+        : findFlatSkillSamplesPath(skillDir, flatSkillName)
+            ?? findProjectSamplesFile(process.cwd())
+            ?? 'eval-samples.json';
     return { skillPath, skillDir, samplesPath, isDirectorySkill };
 }

package/dist/doctor/index.js

@@ -9,6 +9,7 @@
  */
 import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { runFileSuffix } from '../eval-core/artifact-file-names.js';
 import { discoverVariants, resolveArtifacts } from '../inputs/skill-loader.js';
 import { DOCTOR_REPORT_SCHEMA_VERSION, isComposerRule } from '../types/doctor.js';
 import { getRegisteredRules } from './rules.js';
@@ -163,14 +164,8 @@ function inferSkillPath(artifact, baseDir) {
 // ---------------------------------------------------------------------------
 // Public entry
 // ---------------------------------------------------------------------------
-let reportIdCounter = 0;
 function nextReportId() {
-    reportIdCounter += 1;
-    const ts = new Date().toISOString().replace(/[-:.]/g, '').slice(0, 15);
-    // 进程内计数器只防同进程同秒撞;跨进程同秒(两个 omk doctor 并发 / 不同项目)仍会撞同 id,
-    // 经机器级卡片 dedup 当唯一键用时会静默并掉一份。加 4 位随机根治跨进程撞名(id 是标签非测量数)。
-    const rand = Math.random().toString(36).slice(2, 6);
-    return `doctor-${ts}-${reportIdCounter}-${rand}`;
+    return `doctor-${runFileSuffix()}`;
 }
 function readCliVersion() {
     // 不依赖 package.json import(避免 type 解析复杂度);用环境变量或退回 'unknown'

package/dist/doctor/messages.js

@@ -133,8 +133,8 @@ export const DOCTOR_MESSAGES = {
         en: 'directory-skill missing SKILL.md entry file',
     },
     'cli.doctor.skill_metadata.hint.frontmatter': {
-        zh: 'front-matter 用 YAML 语法,key: value 或 - item 形式。可参考 examples/multi-skills 下的 skill 写法',
-        en: 'front-matter uses YAML syntax (key: value or - item). See examples/multi-skills for reference',
+        zh: 'front-matter 用 YAML 语法，key: value 或 - item 形式。可参考 examples/skill-map-showcase/skills/release-readiness 的目录式 skill 写法',
+        en: 'front-matter uses YAML syntax (key: value or - item). See examples/skill-map-showcase/skills/release-readiness for a directory-skill reference',
     },
     'cli.doctor.skill_metadata.hint.hardrules': {
         zh: 'hardRules 必须写在 SKILL.md front-matter 中,格式为 hardRules: [{ id, rule, expectedBehavior }]；id 要稳定且唯一,expectedBehavior 写可观察行为。',

package/dist/eval-core/artifact-file-names.d.ts

@@ -0,0 +1,15 @@
+export declare const REPORT_FILE_SUFFIX = ".report.json";
+export declare const GRAPH_FILE_SUFFIX = ".graph.json";
+export declare const CARD_FILE_SUFFIX = ".card.md";
+export declare function safeArtifactFileStem(id: string): string;
+export declare function reportFileName(stem: string): string;
+export declare function reportFilePath(dir: string, stem: string): string;
+export declare function reportFileStem(fileName: string): string | null;
+export declare function isReportFileName(fileName: string): boolean;
+export declare function graphFileName(stem: string): string;
+export declare function cardFileName(stem: string): string;
+export declare function runTimestamp(date?: Date): string;
+export declare function randomRunToken(): string;
+export declare function runFileSuffix(): string;
+export declare function stripDomainPrefix(id: string, domain: string): string;
+export declare function doctorReportFileStem(skillName: string, reportId: string): string;

package/dist/eval-core/artifact-file-names.js

@@ -0,0 +1,45 @@
+import { join } from 'node:path';
+export const REPORT_FILE_SUFFIX = '.report.json';
+export const GRAPH_FILE_SUFFIX = '.graph.json';
+export const CARD_FILE_SUFFIX = '.card.md';
+export function safeArtifactFileStem(id) {
+    return id.replaceAll(/[/\\:*?"<>|]/g, '_');
+}
+export function reportFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${REPORT_FILE_SUFFIX}`;
+}
+export function reportFilePath(dir, stem) {
+    return join(dir, reportFileName(stem));
+}
+export function reportFileStem(fileName) {
+    return fileName.endsWith(REPORT_FILE_SUFFIX)
+        ? fileName.slice(0, -REPORT_FILE_SUFFIX.length)
+        : null;
+}
+export function isReportFileName(fileName) {
+    return reportFileStem(fileName) !== null;
+}
+export function graphFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${GRAPH_FILE_SUFFIX}`;
+}
+export function cardFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${CARD_FILE_SUFFIX}`;
+}
+export function runTimestamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+export function randomRunToken() {
+    return Math.random().toString(36).slice(2, 6);
+}
+export function runFileSuffix() {
+    return `${runTimestamp()}-${randomRunToken()}`;
+}
+export function stripDomainPrefix(id, domain) {
+    const safeId = safeArtifactFileStem(id);
+    const prefix = `${domain}-`;
+    return safeId.startsWith(prefix) ? safeId.slice(prefix.length) : safeId;
+}
+export function doctorReportFileStem(skillName, reportId) {
+    return `${safeArtifactFileStem(skillName)}-${stripDomainPrefix(reportId, 'doctor')}`;
+}

package/dist/eval-core/evaluation-reporting.d.ts

@@ -33,7 +33,7 @@ export interface PersistableReport {
 }
 export declare function persistReport(report: PersistableReport, outputDir: string | null): string | null;
 /**
- * run id 的时间戳后缀 `YYYYMMDD-HHmmss-rand4`。
+ * run id 的时间戳后缀 `YYYYMMDDTHHmmss-rand4`。
  * 含秒 + 4 位随机:id 是 run 标签(非测量数),但被 studio 机器级 dedup 与 managed 证据 (reportId,
  * contentHash) 去重当唯一键用。分钟级会让跨项目 / 同分钟重跑撞同 id → 索引静默顶掉一份、managed 错并一条。
  * 秒+随机根治撞名,保证每次 run 全局唯一。供 generateRunId 与 evolve 合并 id 共用,避免靠 split 反解格式。

package/dist/eval-core/evaluation-reporting.js

@@ -5,6 +5,8 @@ import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_REPORTS_DIR } from './default-dirs.js';
 import { indexReportWrite } from './artifact-index.js';
+import { randomRunToken, reportFilePath, runTimestamp } from './artifact-file-names.js';
+import { persistEvalGraphSidecar } from '../artifact-graph/eval.js';
 import { buildVariantSummary } from './schema.js';
 import { buildVariantConfig, resolveExecutionStrategy } from './execution-strategy.js';
 import { getJudgePromptHash } from '../grading/judge.js';
@@ -275,35 +277,53 @@ export function aggregateReport({ runId, variants, model, judgeModel, noJudge, e
             }])),
     };
 }
+function isEvaluationReport(report) {
+    return report['kind'] === 'evaluation';
+}
+function persistEvalGraphSidecarSafely(report, outputDir, sourcePath) {
+    if (!isEvaluationReport(report))
+        return;
+    try {
+        persistEvalGraphSidecar({ report, outputDir, sourcePath, fileStem: report.id });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[omk] 写入 eval 图谱失败：${message}\n`);
+    }
+}
 export function persistReport(report, outputDir) {
     if (!outputDir)
         return null;
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
-    const filePath = join(outputDir, `${report.id}.json`);
+    const filePath = reportFilePath(outputDir, report.id);
     writeFileSync(filePath, JSON.stringify(report, null, 2));
+    persistEvalGraphSidecarSafely(report, outputDir, filePath);
     // 产物发现索引:报告落项目本地后,best-effort 追加全局轻卡片,让 omk studio 跨项目聚合成机器级总览。
     // 永不抛、永不阻断报告落盘(正文是 source of truth)。
     indexReportWrite(report, filePath, outputDir);
     return filePath;
 }
 /**
- * run id 的时间戳后缀 `YYYYMMDD-HHmmss-rand4`。
+ * run id 的时间戳后缀 `YYYYMMDDTHHmmss-rand4`。
  * 含秒 + 4 位随机:id 是 run 标签(非测量数),但被 studio 机器级 dedup 与 managed 证据 (reportId,
  * contentHash) 去重当唯一键用。分钟级会让跨项目 / 同分钟重跑撞同 id → 索引静默顶掉一份、managed 错并一条。
  * 秒+随机根治撞名,保证每次 run 全局唯一。供 generateRunId 与 evolve 合并 id 共用,避免靠 split 反解格式。
  */
 export function runIdSuffix() {
-    const d = new Date();
-    const pad = (n) => String(n).padStart(2, '0');
-    const date = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
-    const time = `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
-    const rand = Math.random().toString(36).slice(2, 6);
-    return `${date}-${time}-${rand}`;
+    return `${runTimestamp()}-${randomRunToken()}`;
+}
+function safeRunSubject(subject) {
+    const sanitized = subject
+        .replaceAll(/[\\/:]/g, '-')
+        .replaceAll(/[^a-zA-Z0-9._@-]/g, '_')
+        .replace(/^-+|-+$/g, '');
+    return sanitized || 'run';
+}
+function primaryRunSubject(variants) {
+    const nonBaseline = variants.filter((variant) => variant !== 'baseline');
+    return nonBaseline.at(-1) ?? variants.at(-1) ?? 'run';
 }
 export function generateRunId(variants) {
-    const variantPart = variants
-        .map((variant) => variant.replaceAll(/[\\/:]/g, '-').replaceAll(/[^a-zA-Z0-9._@-]/g, '_'))
-        .join('-vs-');
-    return `${variantPart}-${runIdSuffix()}`;
+    return `${safeRunSubject(primaryRunSubject(variants))}-${runIdSuffix()}`;
 }

package/dist/eval-core/measurement-dirs.js

@@ -1,14 +1,16 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { DEFAULT_OBSERVE_HEALTH_DIR, DEFAULT_DOCTORS_DIR, DEFAULT_REPORTS_DIR } from './default-dirs.js';
+import { isReportFileName } from './artifact-file-names.js';
+import { migrateLegacyReportFiles } from './report-file-migration.js';
 /**
  * 测量产物的「项目优先 → 全局兜底」目录解析,镜像 managed 的 `resolveManagedDir`
  * (src/managed/store.ts)。测量产物绑用例集上下文(construct validity,不可全局化),
  * 默认落项目 `.omk/`,全局作显式 opt-in。
  *
- * 「记录优先」—— 目录里有匹配 `.json` 才算数(不是「目录存在」),与 managed 同口径,
- * 避免空项目目录遮蔽全局数据。项目目录按**调用时** `cwd()` 求值(函数,不是 import 时
- * 冻结的常量),studio 长会话 per-request 解析才正确。
+ * 「记录优先」—— 目录里有匹配 report 文件才算数（不是「目录存在」），与 managed 同口径，
+ * 避免空项目目录遮蔽全局数据。项目目录按**调用时** `cwd()` 求值（函数，不是 import 时
+ * 冻结的常量），studio 长会话 per-request 解析才正确。
  */
 /** dir 里是否有至少一个满足 match 的文件(短路,不读文件内容)。 */
 function hasMatchingFile(dir, match) {
@@ -22,7 +24,7 @@ function hasMatchingFile(dir, match) {
     }
 }
 // —— observe-health(skill 健康度报告)——
-// 文件名 `{timestamp}-observe-health.json`,匹配后缀避免别的 .json 误翻转 resolver。
+// 文件名 `{run}.report.json`,目录已表达 observe-health 域。
 /** 项目级 observe-health 目录(相对调用时 cwd)。 */
 export function projectObserveHealthDir(cwd = process.cwd()) {
     return join(cwd, '.omk', 'observe-health');
@@ -34,7 +36,9 @@ export function globalObserveHealthDir() {
 /** 权威 observe-health 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
  *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
 export function resolveObserveHealthDir(dir = projectObserveHealthDir(), global = globalObserveHealthDir()) {
-    const has = (d) => hasMatchingFile(d, (f) => f.endsWith('-observe-health.json'));
+    migrateLegacyReportFiles(dir, 'observe-health');
+    migrateLegacyReportFiles(global, 'observe-health');
+    const has = (d) => hasMatchingFile(d, isReportFileName);
     if (has(dir))
         return dir;
     if (dir !== global && has(global))
@@ -42,7 +46,7 @@ export function resolveObserveHealthDir(dir = projectObserveHealthDir(), global
     return dir;
 }
 // —— doctors(体检报告)——
-// 文件名 `{skill}-{id}.json`,谓词用「存在任意 .json」即可(真解析在下游 scanDoctorReports)。
+// 文件名 `{skill}-{run}.report.json`,谓词用 report 后缀即可(真解析在下游 scanDoctorReports)。
 /** 项目级 doctors 目录(相对调用时 cwd)。 */
 export function projectDoctorsDir(cwd = process.cwd()) {
     return join(cwd, '.omk', 'doctors');
@@ -54,7 +58,9 @@ export function globalDoctorsDir() {
 /** 权威 doctors 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
  *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
 export function resolveDoctorsDir(dir = projectDoctorsDir(), global = globalDoctorsDir()) {
-    const has = (d) => hasMatchingFile(d, (f) => f.endsWith('.json'));
+    migrateLegacyReportFiles(dir, 'doctor');
+    migrateLegacyReportFiles(global, 'doctor');
+    const has = (d) => hasMatchingFile(d, isReportFileName);
     if (has(dir))
         return dir;
     if (dir !== global && has(global))

package/dist/eval-core/report-file-migration.d.ts

@@ -0,0 +1,10 @@
+export type LegacyReportDomain = 'report' | 'doctor' | 'observe-health' | 'observe-inbox';
+/**
+ * One-shot migration for pre-`.report.json` run artifacts.
+ *
+ * This is deliberately scoped to measurement report directories. It does not make
+ * bare `.json` a normal reader format again; it just renames known legacy report
+ * files into the canonical name so old local data can be discovered, rotated, and
+ * eventually garbage-collected by the new code paths.
+ */
+export declare function migrateLegacyReportFiles(dir: string, domain: LegacyReportDomain): void;