oh-my-knowledge 0.42.0 → 0.43.0

package/dist/cli/commands/doctor.js

@@ -1,5 +1,5 @@
-import { existsSync, statSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, 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';
@@ -9,50 +9,11 @@ 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 { doctorReportFileStem, isReportFileName, reportFilePath } from '../../eval-core/artifact-file-names.js';
+import { migrateLegacyReportFiles } from '../../eval-core/report-file-migration.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) {
-        const candidate = join(dir, name);
-        if (existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
-function sampleSearchDirs(target, cwd) {
-    const dirs = [];
-    const add = (dir) => {
-        const abs = resolve(dir);
-        if (!dirs.includes(abs))
-            dirs.push(abs);
-    };
-    if (target) {
-        const absTarget = resolve(target);
-        if (existsSync(absTarget)) {
-            const stat = statSync(absTarget);
-            if (stat.isDirectory()) {
-                add(absTarget);
-                add(dirname(absTarget));
-                add(dirname(dirname(absTarget)));
-            }
-            else {
-                const parent = dirname(absTarget);
-                add(parent);
-                add(dirname(parent));
-            }
-        }
-    }
-    add(cwd);
-    return dirs;
-}
-function findDefaultSamplesPath(target, cwd) {
-    for (const dir of sampleSearchDirs(target, cwd)) {
-        const samplesPath = findSamplesInDir(dir);
-        if (samplesPath)
-            return samplesPath;
-    }
-    return null;
-}
+import { findDoctorDeprecatedSamplesHint, findDoctorSamplesPath } from '../../inputs/sample-locator.js';
+import { persistDoctorGraphSidecars, removeDoctorGraphSidecars } from '../../artifact-graph/doctor.js';
 export default class Doctor extends BaseCommand {
     static description = bilingual({
         zh: '体检 omk 工作目录，检查 skill 配置 / 依赖 / executor 连通性。',
@@ -186,7 +147,16 @@ export default class Doctor extends BaseCommand {
             const timeoutSec = flags.timeout != null ? Number(flags.timeout) : defaultTimeoutSec;
             const timeoutMs = Math.max(1000, Math.floor((Number.isFinite(timeoutSec) ? timeoutSec : defaultTimeoutSec) * 1000));
             const cwd = process.cwd();
-            const samplesPath = flags.samples ? resolve(flags.samples) : findDefaultSamplesPath(target, cwd);
+            const samplesPath = flags.samples ? resolve(flags.samples) : findDoctorSamplesPath(target, cwd);
+            const deprecatedSamplesHint = !flags.samples && !samplesPath
+                ? findDoctorDeprecatedSamplesHint(target, cwd)
+                : null;
+            if (deprecatedSamplesHint) {
+                process.stderr.write(tCli('cli.common.deprecated_skill_samples_path', lang, {
+                    oldPath: deprecatedSamplesHint.oldPath,
+                    newPath: deprecatedSamplesHint.newPath,
+                }));
+            }
             let samples;
             let requires;
             if (samplesPath) {
@@ -270,7 +240,7 @@ export default class Doctor extends BaseCommand {
             }
             persistDoctorReport(report, flags['output-dir']
                 ? resolve(flags['output-dir'])
-                : (flags.global ? globalDoctorsDir() : projectDoctorsDir()));
+                : (flags.global ? globalDoctorsDir() : projectDoctorsDir()), lang);
             if (flags.fix) {
                 const existing = report;
                 if (existing.outcome !== 'failed') {
@@ -288,47 +258,76 @@ export default class Doctor extends BaseCommand {
 // 每个 skill 最多保留多少份历史 doctor 报告(避免无界增长拖慢 studio 启动 +
 // scanDoctorReports 扫盘成本)。50 = ~每天 1 跑撑 1.5 个月 sparkline,够用。
 const DOCTOR_HISTORY_MAX_PER_SKILL = 50;
-function persistDoctorReport(report, outputDir) {
+function persistDoctorReport(report, outputDir, lang = 'zh') {
     const dir = outputDir ?? DEFAULT_DOCTORS_DIR;
     mkdirSync(dir, { recursive: true });
-    const safeId = report.id.replace(/[/\\:*?"<>|]/g, '_');
+    migrateLegacyReportFiles(dir, 'doctor');
     for (const skill of report.skills) {
-        const counts = { pass: 0, warn: 0, fail: 0, skipped: 0 };
+        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 outcome = skill.status === 'fail' ? 'failed' : skill.status === 'warn' ? 'warnings_only' : 'passed';
         const perSkill = {
             ...report,
             skills: [skill],
-            ruleStats: { ...counts, total: skill.results.length },
+            ruleStats: {
+                pass: counts.pass,
+                warn: counts.warn,
+                fail: counts.fail,
+                skipped: counts.skipped,
+                total: skill.results.length,
+            },
             totals: {
                 pass: skill.status === 'pass' ? 1 : 0,
                 warn: skill.status === 'warn' ? 1 : 0,
                 fail: skill.status === 'fail' ? 1 : 0,
             },
-            outcome: skill.status === 'fail' ? 'failed' : skill.status === 'warn' ? 'warnings_only' : 'passed',
+            outcome,
         };
-        const safeName = skill.skillName.replace(/[/\\:*?"<>|]/g, '_');
-        const cardId = `${safeName}-${safeId}`;
-        const filePath = join(dir, `${cardId}.json`);
+        const cardId = doctorReportFileStem(skill.skillName, report.id);
+        const filePath = reportFilePath(dir, cardId);
         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);
+        try {
+            persistDoctorGraphSidecars({
+                report: perSkill,
+                skill,
+                sourcePath: filePath,
+                outputDir: dir,
+                fileStem: cardId,
+                lang,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const warning = lang === 'zh'
+                ? `⚠️  doctor graph sidecar 写入失败：${message}\n`
+                : `⚠️  failed to write doctor graph sidecar: ${message}\n`;
+            process.stderr.write(warning);
+        }
         pruneDoctorHistory(dir, skill.skillName, DOCTOR_HISTORY_MAX_PER_SKILL);
     }
 }
-// 写入新报告后调用:扫 dir 里属于该 skill 的所有 single-skill doctor JSON,
+// 写入新报告后调用:扫 dir 里属于该 skill 的所有 single-skill doctor report,
 // 按 timestamp 倒排,保留 maxKeep 份最近的,其余删。按 content 匹配 skillName 不
-// 看文件名,所以同时清理新 `{name}-{id}.json` 与遗留 `{name}.json` 两种命名。
+// 看文件名,所以清理逻辑不依赖 readdir 顺序或 stem 推断 skill 名。
 export function pruneDoctorHistory(dir, skillName, maxKeep) {
+    migrateLegacyReportFiles(dir, 'doctor');
     const candidates = [];
     for (const file of readdirSync(dir)) {
-        if (!file.endsWith('.json'))
+        if (!isReportFileName(file))
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
@@ -337,20 +336,22 @@ export function pruneDoctorHistory(dir, skillName, maxKeep) {
                 continue;
             if (data.skills[0].skillName !== skillName)
                 continue;
-            candidates.push({ file, timestamp: data.timestamp });
+            candidates.push({ file, graphStem: doctorReportFileStem(skillName, data.id), timestamp: data.timestamp });
         }
         catch { /* skip corrupt / unrelated json */ }
     }
     if (candidates.length <= maxKeep)
         return;
     candidates.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-    for (const { file } of candidates.slice(maxKeep)) {
+    for (const { file, graphStem } of candidates.slice(maxKeep)) {
         try {
             unlinkSync(join(dir, file));
         }
         catch { /* ignore */ }
         // 连带删卡片:否则被 prune 掉的报告会经 listDoctorCards 合并在本项目 studio「复活」(正文已删、卡片还在)。
         // 卡片 id = 文件 stem(`{name}-{id}`),与 indexDoctorWrite 写入口径一致。
-        removeDoctorCard(file.replace(/\.json$/, ''));
+        const doctorStem = file.replace(/\.report\.json$/, '');
+        removeDoctorCard(doctorStem);
+        removeDoctorGraphSidecars(dir, graphStem);
     }
 }

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

@@ -10,6 +10,7 @@ import { computeRunTally } from '../../lib/run-tally.js';
 import { DEFAULT_BOOTSTRAP_SAMPLES } from '../../../eval-core/bootstrap.js';
 import { DEFAULT_GATE_THRESHOLD } from '../../../eval-core/verdict.js';
 import { EVALUATION_REPORT_SCHEMA_VERSION } from '../../../eval-core/evaluation-reporting.js';
+import { findSingleTreatmentDeprecatedSamplesHint, hasUsableSamplesPath, } from '../../../inputs/sample-locator.js';
 function isDryRunReport(report) {
     return Boolean(report && typeof report === 'object' && report.dryRun === true);
 }
@@ -180,6 +181,23 @@ async function announceSavedReport({ report, filePath, reportsDir, values, lang,
 }
 async function runEval(_args, flags, lang) {
     const { values, config, evalConfig } = parseRunConfig({ ...flags });
+    if (!values.batch && !hasUsableSamplesPath(config.samplesPath)) {
+        const treatmentRaw = typeof values.treatment === 'string' ? values.treatment : '';
+        const treatments = treatmentRaw.split(',').map((v) => v.trim()).filter(Boolean);
+        const deprecatedSamplesHint = !values.samples && !evalConfig?.samples && treatments.length === 1
+            ? findSingleTreatmentDeprecatedSamplesHint(treatments[0], config.skillDir, process.cwd())
+            : null;
+        if (deprecatedSamplesHint) {
+            process.stderr.write(tCli('cli.common.deprecated_skill_samples_path', lang, {
+                oldPath: deprecatedSamplesHint.oldPath,
+                newPath: deprecatedSamplesHint.newPath,
+            }));
+        }
+        console.error(tCli('cli.common.error_prefix', lang, {
+            message: tCli('cli.common.samples_not_found', lang, { path: config.samplesPath }),
+        }));
+        throw new CliExit(1);
+    }
     const { runEvaluation, runMultiple, runBatchEvaluation } = await import('../../../eval-workflows/run-evaluation.js');
     config.onProgress = makeOnProgress(lang);
     const repeatRaw = values.repeat;
@@ -377,8 +395,8 @@ export default class Eval extends BaseCommand {
         }),
         samples: Flags.string({
             description: bilingual({
-                zh: '用例文件路径。默认 eval-samples.json，也接受 .yaml/.yml；自动发现 --skill-dir 下的 <skill>/.omk/samples.json。',
-                en: 'Samples file path. Defaults to eval-samples.json (also .yaml/.yml); auto-discovers <skill>/.omk/samples.json under --skill-dir.',
+                zh: '用例文件路径。默认项目级 eval-samples.json，也接受 .yaml/.yml；单 treatment 时可自动发现 <skill>/.omk/。',
+                en: 'Samples path. Defaults to project-level eval-samples.json (also .yaml/.yml); single-treatment runs can auto-discover <skill>/.omk/.',
             }),
         }),
         'skill-dir': Flags.string({

package/dist/cli/commands/init.js

@@ -8,6 +8,7 @@ import { tCli } from '../lib/i18n.js';
 const INIT_OMK_GITIGNORE = `# omk 测量 bulk + doctor --fix 备份(项目本地)——不入库;前导 / 锚定 .omk/ 顶层,不误伤嵌套同名目录。
 /observe-health/
 /doctors/
+/graphs/
 /observe-inbox/
 /reports/
 /backups/

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/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 写可观察行为。',