oh-my-knowledge 0.42.0 → 0.44.0

package/dist/artifact-graph/eval.js

@@ -0,0 +1,351 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { graphFileName } from '../eval-core/artifact-file-names.js';
+function shortHash(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, 12);
+}
+function jsonPointerToken(value) {
+    return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function sampleSetHash(sampleHashes) {
+    if (!sampleHashes || Object.keys(sampleHashes).length === 0)
+        return undefined;
+    const canonical = Object.entries(sampleHashes)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([id, hash]) => `${id}:${hash}`)
+        .join('|');
+    return shortHash(canonical);
+}
+function statusFromScore(score) {
+    // Display band only. This is not the verdict gate and intentionally does not
+    // reference DEFAULT_GATE_THRESHOLD or statistical significance decisions.
+    if (score === undefined || !Number.isFinite(score))
+        return 'unknown';
+    if (score >= 4)
+        return 'ok';
+    if (score >= 3)
+        return 'warning';
+    return 'failed';
+}
+function assertionStatus(result) {
+    // Assertion topology status only. Pure LLM-scored samples have no assertion
+    // pass/fail edge, so they stay unknown here even when compositeScore is high.
+    if (result.error || !result.ok)
+        return 'failed';
+    const details = result.assertions?.details;
+    if (!details || details.length === 0)
+        return 'unknown';
+    return details.every((detail) => detail.passed) ? 'ok' : 'failed';
+}
+function artifactBinding(variant, hash) {
+    if (hash && hash !== 'no-skill') {
+        return { bindingStrength: 'content-hash', keys: { artifactHash: hash } };
+    }
+    return { bindingStrength: 'name-only', keys: { variantName: variant } };
+}
+function sampleBinding(sampleId, hash) {
+    if (hash) {
+        return { bindingStrength: 'content-hash', keys: { sampleHash: hash } };
+    }
+    return { bindingStrength: 'name-only', keys: { sampleId } };
+}
+function variantConfigByName(report) {
+    return new Map((report.meta.variantConfigs ?? []).map((config) => [config.variant, config]));
+}
+function scopeArtifactKind(report) {
+    const kinds = new Set((report.meta.variantConfigs ?? [])
+        .map((config) => config.artifactKind)
+        .filter((kind) => kind !== 'baseline'));
+    return kinds.size === 1 ? [...kinds][0] : undefined;
+}
+function sampleEvidence(report, sampleId) {
+    return [{
+            sourceKind: 'sample',
+            sourceId: sampleId,
+            selector: { selectorKind: 'sample-id', value: sampleId },
+            contentHash: report.meta.sampleHashes?.[sampleId],
+            label: sampleId,
+        }];
+}
+function evalResultEvidence(report, resultIndex, variant) {
+    return [{
+            sourceKind: 'eval-report',
+            sourceId: report.id,
+            selector: {
+                selectorKind: 'json-pointer',
+                value: `/results/${resultIndex}/variants/${jsonPointerToken(variant)}`,
+            },
+            label: `${variant} result`,
+        }];
+}
+function assertionEvidence(report, sampleId, index, resultIndex, variant) {
+    if (report.sampleSnapshots?.[sampleId]?.assertions?.[index]) {
+        return [{
+                sourceKind: 'sample',
+                sourceId: sampleId,
+                selector: {
+                    selectorKind: 'json-pointer',
+                    value: `/sampleSnapshots/${jsonPointerToken(sampleId)}/assertions/${index}`,
+                },
+                contentHash: report.meta.sampleHashes?.[sampleId],
+                label: `assertion ${index + 1}`,
+            }];
+    }
+    if (resultIndex !== undefined && variant !== undefined) {
+        return [{
+                sourceKind: 'eval-report',
+                sourceId: report.id,
+                selector: {
+                    selectorKind: 'json-pointer',
+                    value: `/results/${resultIndex}/variants/${jsonPointerToken(variant)}/assertions/details/${index}`,
+                },
+                label: `${variant} assertion ${index + 1}`,
+            }];
+    }
+    return [{
+            sourceKind: 'sample',
+            sourceId: sampleId,
+            contentHash: report.meta.sampleHashes?.[sampleId],
+            label: `assertion ${index + 1}`,
+        }];
+}
+function sampleStableKey(report, sampleId) {
+    const hash = report.meta.sampleHashes?.[sampleId];
+    return hash ? `v1:sample:${hash}` : `v1:sample:${report.id}:${sampleId}`;
+}
+function assertionStableKey(report, sampleId, index) {
+    return `${sampleStableKey(report, sampleId)}:assertion:${index}`;
+}
+function sampleAttrs(snapshot) {
+    if (!snapshot)
+        return undefined;
+    const display = {};
+    if (snapshot.capability?.length)
+        display.capability = snapshot.capability;
+    if (snapshot.construct)
+        display.construct = snapshot.construct;
+    if (snapshot.difficulty)
+        display.difficulty = snapshot.difficulty;
+    if (snapshot.provenance)
+        display.provenance = snapshot.provenance;
+    if (snapshot.tripwire)
+        display.tripwire = true;
+    if (snapshot.assertions?.length)
+        display.assertionCount = snapshot.assertions.length;
+    return Object.keys(display).length > 0 ? { display } : undefined;
+}
+export function evalGraphDirForReportOutput(reportOutputDir) {
+    return basename(reportOutputDir) === 'reports'
+        ? join(dirname(reportOutputDir), 'graphs', 'eval')
+        : join(reportOutputDir, 'graphs', 'eval');
+}
+export function buildEvalArtifactGraph(options) {
+    const { report, sourcePath } = options;
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const nodes = [];
+    const edges = [];
+    const nodeIdsByStableKey = new Map();
+    const configs = variantConfigByName(report);
+    const addNode = (stableKey, nodeKind, nodeRole, label, extra = {}) => {
+        const existing = nodeIdsByStableKey.get(stableKey);
+        if (existing)
+            return existing;
+        const id = `node:${shortHash(stableKey)}`;
+        nodeIdsByStableKey.set(stableKey, id);
+        nodes.push({
+            id,
+            stableKey,
+            nodeKind,
+            nodeRole,
+            layer: 'measurement',
+            label,
+            ...extra,
+        });
+        return id;
+    };
+    const addEdge = (fromNodeId, toNodeId, edgeKind, extra = {}) => {
+        const id = `edge:${shortHash(`${fromNodeId}|${edgeKind}|${toNodeId}|${edges.length}`)}`;
+        edges.push({
+            id,
+            fromNodeId,
+            toNodeId,
+            edgeKind,
+            layer: 'measurement',
+            ...extra,
+        });
+    };
+    const variantNodeIds = new Map();
+    for (const variant of report.meta.variants) {
+        const artifactHash = report.meta.artifactHashes?.[variant];
+        const config = configs.get(variant);
+        const variantNodeId = addNode(`v1:variant:${report.id}:${variant}`, 'variant', 'entity', variant, {
+            status: statusFromScore(report.summary?.[variant]?.avgCompositeScore),
+            binding: artifactBinding(variant, artifactHash),
+            metrics: {
+                ...(report.summary?.[variant]?.avgCompositeScore !== undefined
+                    ? { avgCompositeScore: report.summary[variant].avgCompositeScore }
+                    : {}),
+                ...(report.summary?.[variant]?.totalSamples !== undefined
+                    ? { totalSamples: report.summary[variant].totalSamples }
+                    : {}),
+            },
+            attrs: {
+                display: {
+                    ...(config ? {
+                        artifactKind: config.artifactKind,
+                        artifactSource: config.artifactSource,
+                        experimentRole: config.experimentRole,
+                        executionStrategy: config.executionStrategy,
+                    } : {}),
+                },
+            },
+            evidenceRefs: [{
+                    sourceKind: 'eval-report',
+                    sourceId: report.id,
+                    selector: { selectorKind: 'json-pointer', value: `/summary/${jsonPointerToken(variant)}` },
+                    label: `${variant} summary`,
+                }],
+        });
+        variantNodeIds.set(variant, variantNodeId);
+        if (config?.artifactKind === 'skill' && artifactHash && artifactHash !== 'no-skill') {
+            const skillNodeId = addNode(`v1:skill:${artifactHash}`, 'skill', 'entity', variant, {
+                binding: { bindingStrength: 'content-hash', keys: { artifactHash } },
+                attrs: {
+                    display: {
+                        variant,
+                        sourceLocator: config.locator,
+                    },
+                },
+                evidenceRefs: [{
+                        sourceKind: 'eval-report',
+                        sourceId: report.id,
+                        selector: { selectorKind: 'json-pointer', value: `/meta/artifactHashes/${jsonPointerToken(variant)}` },
+                        contentHash: artifactHash,
+                        label: `${variant} artifact hash`,
+                    }],
+            });
+            addEdge(variantNodeId, skillNodeId, 'derived_from');
+        }
+    }
+    for (const [sampleId, snapshot] of Object.entries(report.sampleSnapshots ?? {})) {
+        const sampleNodeId = addNode(sampleStableKey(report, sampleId), 'sample', 'entity', sampleId, {
+            binding: sampleBinding(sampleId, report.meta.sampleHashes?.[sampleId]),
+            attrs: sampleAttrs(snapshot),
+            evidenceRefs: sampleEvidence(report, sampleId),
+        });
+        snapshot.assertions?.forEach((assertion, index) => {
+            const assertionNodeId = addNode(assertionStableKey(report, sampleId, index), 'assertion', 'entity', `assertion: ${assertion.type}`, {
+                attrs: { display: { type: assertion.type, weight: assertion.weight ?? 1 } },
+                evidenceRefs: assertionEvidence(report, sampleId, index),
+            });
+            addEdge(sampleNodeId, assertionNodeId, 'contains');
+        });
+    }
+    for (const [resultIndex, result] of report.results.entries()) {
+        const sampleNodeId = addNode(sampleStableKey(report, result.sample_id), 'sample', 'entity', result.sample_id, {
+            binding: sampleBinding(result.sample_id, report.meta.sampleHashes?.[result.sample_id]),
+            attrs: sampleAttrs(report.sampleSnapshots?.[result.sample_id]),
+            evidenceRefs: sampleEvidence(report, result.sample_id),
+        });
+        for (const [variant, variantResult] of Object.entries(result.variants)) {
+            const variantNodeId = variantNodeIds.get(variant);
+            if (!variantNodeId)
+                continue;
+            addEdge(variantNodeId, sampleNodeId, 'evaluates', {
+                status: assertionStatus(variantResult),
+                evidenceRefs: evalResultEvidence(report, resultIndex, variant),
+            });
+            const evalResultNodeId = addNode(`v1:eval-result:${report.id}:${variant}:${result.sample_id}`, 'eval_result', 'observation', `${variant} / ${result.sample_id}`, {
+                status: assertionStatus(variantResult),
+                metrics: {
+                    durationMs: variantResult.durationMs,
+                    costUSD: variantResult.costUSD,
+                    ...(variantResult.compositeScore !== undefined ? { compositeScore: variantResult.compositeScore } : {}),
+                    ...(variantResult.llmScore !== undefined ? { llmScore: variantResult.llmScore } : {}),
+                    ...(variantResult.assertions ? { assertionScore: variantResult.assertions.score } : {}),
+                },
+                attrs: {
+                    display: {
+                        ok: variantResult.ok,
+                        ...(variantResult.error ? { error: variantResult.error } : {}),
+                    },
+                },
+                evidenceRefs: evalResultEvidence(report, resultIndex, variant),
+            });
+            addEdge(evalResultNodeId, variantNodeId, 'derived_from');
+            addEdge(evalResultNodeId, sampleNodeId, 'evaluates');
+            variantResult.assertions?.details.forEach((detail, index) => {
+                const assertionNodeId = addNode(assertionStableKey(report, result.sample_id, index), 'assertion', 'entity', `assertion: ${detail.type}`, {
+                    attrs: { display: { type: detail.type, weight: detail.weight } },
+                    evidenceRefs: assertionEvidence(report, result.sample_id, index, resultIndex, variant),
+                });
+                addEdge(evalResultNodeId, assertionNodeId, detail.passed ? 'passes' : 'fails', {
+                    status: detail.passed ? 'ok' : 'failed',
+                    evidenceRefs: evalResultEvidence(report, resultIndex, variant),
+                });
+            });
+            for (const [dimension, dimensionResult] of Object.entries(variantResult.dimensions ?? {})) {
+                const dimensionNodeId = addNode(`v1:judge-dimension:${report.id}:${variant}:${result.sample_id}:${dimension}`, 'judge_dimension', 'observation', dimension, {
+                    status: statusFromScore(dimensionResult.score),
+                    metrics: { score: dimensionResult.score },
+                    attrs: { display: { reason: dimensionResult.reason } },
+                    evidenceRefs: evalResultEvidence(report, resultIndex, variant),
+                });
+                addEdge(dimensionNodeId, evalResultNodeId, 'derived_from');
+            }
+            if (variantResult.diagnostic) {
+                const diagnosticNodeId = addNode(`v1:diagnostic:${report.id}:${variant}:${result.sample_id}`, 'diagnostic', 'observation', `diagnostic: ${variant} / ${result.sample_id}`, {
+                    status: variantResult.diagnostic.ok ? 'warning' : 'failed',
+                    attrs: {
+                        display: {
+                            rootCause: variantResult.diagnostic.rootCause,
+                            failureModes: variantResult.diagnostic.failureModes ?? [],
+                        },
+                    },
+                    evidenceRefs: evalResultEvidence(report, resultIndex, variant),
+                });
+                addEdge(diagnosticNodeId, evalResultNodeId, 'diagnoses', {
+                    status: variantResult.diagnostic.ok ? 'warning' : 'failed',
+                });
+            }
+        }
+    }
+    return {
+        documentKind: 'artifact-graph',
+        schemaVersion: 1,
+        graphId: `eval:${report.id}`,
+        generatedAt,
+        source: {
+            sourceKind: 'eval',
+            sourceId: report.id,
+            sourcePath,
+            cliVersion: report.meta.cliVersion,
+        },
+        scope: {
+            cwd: process.cwd(),
+            artifactKind: scopeArtifactKind(report),
+            sourceLocator: report.meta.request?.samplesPath,
+            sampleSetHash: sampleSetHash(report.meta.sampleHashes),
+        },
+        nodes,
+        edges,
+        summaries: [{
+                summaryKind: 'coverage',
+                title: 'Eval measurement graph',
+                severity: report.results.some((result) => Object.values(result.variants).some((variant) => assertionStatus(variant) === 'failed'))
+                    ? 'medium'
+                    : 'info',
+            }],
+    };
+}
+export function persistEvalGraphSidecar(options) {
+    const graphDir = evalGraphDirForReportOutput(options.outputDir);
+    if (!existsSync(graphDir))
+        mkdirSync(graphDir, { recursive: true });
+    const fileStem = options.fileStem ?? options.report.id;
+    const graphPath = join(graphDir, graphFileName(fileStem));
+    const graph = buildEvalArtifactGraph(options);
+    writeFileSync(graphPath, JSON.stringify(graph, null, 2));
+    return { graphPath };
+}

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

@@ -36,20 +36,20 @@ omk CLI 顶层命令包括：`init` / `install` / `list` / `promote` / `rollback
 | 查看受管 skill 状态 | → `omk list` |
 | 按证据接受 / 回退某版本 | → `omk promote` / `omk rollback` |
 
-如果用户意图不明确，先扫描当前项目结构（skills/ 目录和 eval-samples 文件），然后推荐最合适的操作。
+如果用户意图不明确，先扫描当前项目结构（skills/ 目录、项目级 eval-samples 文件、skill 私有 `.omk/samples.*`），然后推荐最合适的操作。
 
 ## 第三步：检测项目结构
 
 使用 Glob 和 Read 工具检查：
 
 1. `skills/` 目录下有哪些 skill 文件（`.md` 或 `*/SKILL.md`）
-2. 是否存在 `eval-samples.json` / `eval-samples.yaml` / `eval-samples.yml` / `<skill>/.omk/samples.json`（推荐的标准位置）
-3. 是否有 `skills/*.eval-samples.json`（每 skill 配对文件 → `--batch` 模式）
+2. 是否存在项目级 `eval-samples.json` / `eval-samples.yaml` / `eval-samples.yml`，或目录 skill 私有的 `<skill>/.omk/samples.json`
+3. 是否有 `skills/*.eval-samples.json`（扁平 skill 的每 skill 配对文件 → `--batch` 模式）
 
 根据检测结果决定：
 
-- 多个 skill + 各自的 eval-samples → 建议 `--batch` 批量模式
-- 多个 skill + 共享 eval-samples → 建议版本对比模式
+- 多个 skill + 各自的 `.omk/samples.*` 或扁平 skill paired eval-samples → 建议 `--batch` 批量模式
+- 多个 skill + 共享项目级 eval-samples → 建议版本对比模式
 - 只有一个 skill → 建议 `baseline` 对照（`omk eval --control baseline --treatment <skill>`）或 `omk evolve` 改进
 - 没有 eval-samples → 先 `omk sample <skill>` 生成
 
@@ -104,19 +104,19 @@ evolve 默认开**显著性接受门**：候选只在相对当前最优**统计
 
 ```bash
 # 为单个 skill 生成
-omk sample skills/my-skill.md
+omk sample skills/my-skill/SKILL.md
 
 # 显式指定数量（不指定时 LLM 根据 skill 类型自动决定 4-8 条）
-omk sample skills/my-skill.md --count 8
+omk sample skills/my-skill/SKILL.md --count 8
 
 # 自然语言指定重点覆盖场景
-omk sample skills/my-skill.md --focus "重点覆盖搜索失败 / 权限拒绝 / 跨工具 fallback 路径"
+omk sample skills/my-skill/SKILL.md --focus "重点覆盖搜索失败 / 权限拒绝 / 跨工具 fallback 路径"
 
 # 为 skill 目录下所有缺测试集的 skill 批量生成
 omk sample --batch
 ```
 
-输出位置：`<skill>/SKILL.md` 风格 → `<skill>/.omk/samples.json`（标准），其他 `.md` 路径 → 当前目录 `eval-samples.json`（兜底）。
+输出位置：目录 skill（`<skill>/SKILL.md`）→ `<skill>/.omk/samples.json`（标准）；扁平 `.md` 单次生成 → 当前目录 `eval-samples.json`（项目级兜底）；扁平 `.md` 的 `--batch` 兼容生成 `<skill-dir>/<name>.eval-samples.json`。
 
 ### 体检 skill 写法
 

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

@@ -101,7 +101,7 @@ omk eval [flags]
 - `--report-only` `boolean`:生成报告并打印 verdict，但始终 exit 0(不参与 CI gate）。
 - `--resume` `option`:从某次失败 run 续跑
 - `--retry` `option`:失败 sample 重试次数
-- `--samples` `option`:用例文件路径。默认 eval-samples.json，也接受 .yaml/.yml；自动发现 --skill-dir 下的 <skill>/.omk/samples.json。
+- `--samples` `option`:用例文件路径。默认项目级 eval-samples.json，也接受 .yaml/.yml；单 treatment 时可自动发现 <skill>/.omk/。
 - `--skill-dir` `option`:skill 目录，默认 skills
 - `--skip-connectivity` `boolean`:跳 LLM 连通性预检
 - `--skip-doctor` `boolean`:escape hatch:跳 doctor 健康检查门禁（默认强制启用）。沙箱 mock 提供依赖时绕开 doctor 物理路径误报；garbage-in 风险自负。

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/