oh-my-knowledge 0.41.0 → 0.43.0

package/dist/artifact-graph/doctor.js

@@ -0,0 +1,569 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { cardFileName, graphFileName, safeArtifactFileStem } from '../eval-core/artifact-file-names.js';
+import { hashArtifactSource } from '../inputs/content-hash.js';
+import { extractMarkdownStepWorkflows, extractSkillHardRules, extractSkillWorkflows, parseSkillFrontmatter, } from '../shared/hard-rules.js';
+function shortHash(input) {
+    return createHash('sha256').update(input).digest('hex').slice(0, 12);
+}
+function safeFileName(id) {
+    return safeArtifactFileStem(id);
+}
+export function doctorGraphDirForDoctorOutput(doctorOutputDir) {
+    return basename(doctorOutputDir) === 'doctors'
+        ? join(dirname(doctorOutputDir), 'graphs', 'doctor')
+        : join(doctorOutputDir, 'graphs', 'doctor');
+}
+function normalizeRelPath(path) {
+    return path.split(sep).join('/');
+}
+function resolveSkillSource(skill) {
+    const source = resolve(skill.skillPath);
+    if (!existsSync(source))
+        return null;
+    const stat = statSync(source);
+    const skillFilePath = stat.isDirectory() ? join(source, 'SKILL.md') : source;
+    if (!existsSync(skillFilePath))
+        return null;
+    const isDirectorySkill = basename(skillFilePath) === 'SKILL.md';
+    const skillRoot = dirname(skillFilePath);
+    const content = readFileSync(skillFilePath, 'utf-8');
+    let artifactHash;
+    try {
+        artifactHash = hashArtifactSource(isDirectorySkill ? skillRoot : skillFilePath, isDirectorySkill);
+    }
+    catch {
+        artifactHash = undefined;
+    }
+    return { skillFilePath, skillRoot, isDirectorySkill, content, artifactHash };
+}
+function listFiles(root, subdir) {
+    const start = join(root, subdir);
+    if (!existsSync(start))
+        return [];
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                out.push(normalizeRelPath(relative(root, full)));
+            }
+        }
+    };
+    walk(start);
+    out.sort();
+    return out;
+}
+function statusFromRule(status) {
+    switch (status) {
+        case 'pass':
+            return 'ok';
+        case 'warn':
+            return 'warning';
+        case 'fail':
+            return 'failed';
+        case 'skipped':
+            return 'skipped';
+    }
+}
+function sourceKey(snapshot, skill) {
+    return snapshot?.artifactHash ?? `locator:${shortHash(skill.skillPath)}`;
+}
+function contentBinding(snapshot, skill) {
+    if (snapshot?.artifactHash) {
+        return { bindingStrength: 'content-hash', keys: { artifactHash: snapshot.artifactHash } };
+    }
+    return { bindingStrength: 'source-locator', keys: { sourceLocatorHash: shortHash(skill.skillPath) } };
+}
+function skillEvidence(snapshot, skill) {
+    if (!snapshot) {
+        return [{
+                sourceKind: 'skill-file',
+                path: skill.skillPath,
+                label: 'skill source',
+            }];
+    }
+    return [{
+            sourceKind: 'skill-file',
+            path: snapshot.skillFilePath,
+            selector: { selectorKind: 'line-range', value: '1-1' },
+            contentHash: snapshot.artifactHash,
+            label: 'SKILL.md',
+        }];
+}
+function stringList(value) {
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+    if (typeof value === 'string' && value.trim())
+        return [value.trim()];
+    return [];
+}
+function nestedStringList(root, key) {
+    if (!root || typeof root !== 'object' || Array.isArray(root))
+        return [];
+    return stringList(root[key]);
+}
+function sampleCountFromDoctor(skill) {
+    for (const result of skill.results) {
+        if (result.ruleId !== 'samples_contract_aligned')
+            continue;
+        const count = result.detail?.count ?? result.detail?.totalCount;
+        return typeof count === 'number' && Number.isFinite(count) && count > 0 ? count : null;
+    }
+    return null;
+}
+export function buildDoctorArtifactGraph(options) {
+    const { report, skill, sourcePath } = options;
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const snapshot = resolveSkillSource(skill);
+    const keyBase = sourceKey(snapshot, skill);
+    const binding = contentBinding(snapshot, skill);
+    const evidence = skillEvidence(snapshot, skill);
+    const nodes = [];
+    const edges = [];
+    const nodeIdsByStableKey = new Map();
+    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: 'definition',
+            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: 'definition',
+            ...extra,
+        });
+    };
+    const skillNodeId = addNode(`v1:skill:${keyBase}`, 'skill', 'entity', skill.skillName, {
+        binding,
+        attrs: { display: { sourceLocator: skill.skillPath } },
+        evidenceRefs: evidence,
+    });
+    const skillFileNodeId = addNode(`v1:skill-file:${keyBase}:SKILL.md`, 'skill_file', 'entity', 'SKILL.md', {
+        binding,
+        attrs: { display: { path: snapshot ? normalizeRelPath(relative(snapshot.skillRoot, snapshot.skillFilePath)) : skill.skillPath } },
+        evidenceRefs: evidence,
+    });
+    addEdge(skillNodeId, skillFileNodeId, 'contains', { evidenceRefs: evidence });
+    if (snapshot) {
+        const parsedFrontmatter = parseSkillFrontmatter(snapshot.content);
+        if (parsedFrontmatter.hasFrontmatter) {
+            const frontmatterNodeId = addNode(`v1:frontmatter:${keyBase}`, 'frontmatter', 'entity', 'frontmatter', {
+                status: parsedFrontmatter.ok ? 'ok' : 'failed',
+                binding,
+                evidenceRefs: evidence,
+                attrs: parsedFrontmatter.ok
+                    ? { display: { fieldCount: Object.keys(parsedFrontmatter.data ?? {}).length } }
+                    : { display: { error: parsedFrontmatter.error } },
+            });
+            addEdge(skillNodeId, frontmatterNodeId, 'declares', { status: parsedFrontmatter.ok ? 'ok' : 'failed' });
+        }
+        for (const rel of listFiles(snapshot.skillRoot, 'references')) {
+            const nodeId = addNode(`v1:reference:${keyBase}:${rel}`, 'reference', 'entity', rel, {
+                binding,
+                attrs: { display: { path: rel } },
+                evidenceRefs: [{ sourceKind: 'skill-file', path: join(snapshot.skillRoot, rel), contentHash: snapshot.artifactHash, label: rel }],
+            });
+            addEdge(skillNodeId, nodeId, 'references');
+        }
+        for (const rel of listFiles(snapshot.skillRoot, 'scripts')) {
+            const nodeId = addNode(`v1:script:${keyBase}:${rel}`, 'script', 'entity', rel, {
+                binding,
+                attrs: { display: { path: rel } },
+                evidenceRefs: [{ sourceKind: 'skill-file', path: join(snapshot.skillRoot, rel), contentHash: snapshot.artifactHash, label: rel }],
+            });
+            addEdge(skillNodeId, nodeId, 'contains');
+        }
+        const frontmatterData = parsedFrontmatter.ok ? parsedFrontmatter.data ?? {} : {};
+        const preflight = [
+            ...stringList(frontmatterData.preflight),
+            ...nestedStringList(frontmatterData.requires, 'preflight'),
+        ];
+        preflight.forEach((cmd, index) => {
+            const nodeId = addNode(`v1:preflight:${keyBase}:${shortHash(cmd)}`, 'preflight', 'entity', cmd, { binding, attrs: { display: { index } }, evidenceRefs: evidence });
+            addEdge(skillNodeId, nodeId, 'requires');
+        });
+        const tools = [
+            ...stringList(frontmatterData.tools),
+            ...stringList(frontmatterData.allowedTools),
+            ...nestedStringList(frontmatterData.requires, 'tools'),
+        ];
+        tools.forEach((tool) => {
+            const nodeId = addNode(`v1:tool:${tool}`, 'tool', 'entity', tool, { binding: { bindingStrength: 'name-only', keys: { toolName: tool } }, evidenceRefs: evidence });
+            addEdge(skillNodeId, nodeId, 'requires', { binding: { bindingStrength: 'name-only', keys: { toolName: tool } } });
+        });
+        const env = [
+            ...stringList(frontmatterData.env),
+            ...nestedStringList(frontmatterData.requires, 'env'),
+        ];
+        env.forEach((name) => {
+            const nodeId = addNode(`v1:env:${name}`, 'env', 'entity', name, { binding: { bindingStrength: 'name-only', keys: { envName: name } }, evidenceRefs: evidence });
+            addEdge(skillNodeId, nodeId, 'requires', { binding: { bindingStrength: 'name-only', keys: { envName: name } } });
+        });
+        for (const hardRule of extractSkillHardRules(snapshot.content)) {
+            const nodeId = addNode(`v1:hard-rule:${keyBase}:${hardRule.id}`, 'hard_rule', 'entity', hardRule.id, {
+                binding,
+                attrs: { display: { rule: hardRule.rule, expectedBehavior: hardRule.expectedBehavior } },
+                evidenceRefs: evidence,
+            });
+            addEdge(skillNodeId, nodeId, 'declares');
+        }
+        const workflows = [
+            ...extractSkillWorkflows(snapshot.content),
+            ...extractMarkdownStepWorkflows(snapshot.content),
+        ];
+        for (const workflow of workflows) {
+            const workflowNodeId = addNode(`v1:workflow:${keyBase}:${workflow.id}`, 'workflow', 'entity', workflow.id, {
+                binding,
+                attrs: { display: { description: workflow.description, source: workflow.source ?? 'frontmatter' } },
+                evidenceRefs: evidence,
+            });
+            addEdge(skillNodeId, workflowNodeId, 'declares');
+            let prevNodeId = null;
+            for (const node of workflow.nodes) {
+                const stepNodeId = addNode(`v1:workflow-node:${keyBase}:${workflow.id}.${node.id}`, 'workflow_node', 'entity', node.action, {
+                    binding,
+                    attrs: { display: { workflowId: workflow.id, nodeId: node.id } },
+                    evidenceRefs: evidence,
+                });
+                addEdge(workflowNodeId, stepNodeId, 'defines_workflow');
+                if (prevNodeId)
+                    addEdge(prevNodeId, stepNodeId, 'next_step');
+                prevNodeId = stepNodeId;
+            }
+        }
+    }
+    skill.results.forEach((result, index) => {
+        const nodeId = addNode(`v1:doctor-result:${report.id}:${skill.skillName}:${result.ruleId}`, 'doctor_rule_result', 'observation', result.ruleId, {
+            status: statusFromRule(result.status),
+            metrics: { durationMs: result.durationMs },
+            attrs: {
+                display: {
+                    severity: result.severity,
+                    message: result.message,
+                    hint: result.hint,
+                    groupId: result.groupId,
+                },
+            },
+            evidenceRefs: [{
+                    sourceKind: 'doctor-report',
+                    sourceId: report.id,
+                    path: sourcePath,
+                    selector: { selectorKind: 'json-pointer', value: `/skills/0/results/${index}` },
+                    label: result.ruleId,
+                }],
+        });
+        addEdge(nodeId, skillNodeId, 'diagnoses', {
+            status: statusFromRule(result.status),
+            evidenceRefs: [{
+                    sourceKind: 'doctor-report',
+                    sourceId: report.id,
+                    path: sourcePath,
+                    selector: { selectorKind: 'rule-id', value: result.ruleId },
+                    label: result.ruleId,
+                }],
+        });
+    });
+    const structureCounts = countDoctorGraphStructure(nodes);
+    const severity = skill.status === 'fail' ? 'high' : skill.status === 'warn' ? 'medium' : 'info';
+    return {
+        documentKind: 'artifact-graph',
+        schemaVersion: 1,
+        graphId: `doctor:${report.id}:${skill.skillName}`,
+        generatedAt,
+        source: {
+            sourceKind: 'doctor',
+            sourceId: report.id,
+            sourcePath,
+            cliVersion: report.cliVersion,
+        },
+        scope: {
+            cwd: report.cwd,
+            artifactKind: 'skill',
+            skillName: skill.skillName,
+            ...(snapshot?.artifactHash ? { artifactHash: snapshot.artifactHash } : {}),
+            sourceLocator: skill.skillPath,
+        },
+        nodes,
+        edges,
+        summaries: [{
+                summaryKind: 'structure',
+                title: `references=${structureCounts.references}, scripts=${structureCounts.scripts}, workflows=${structureCounts.workflows}, workflowNodes=${structureCounts.workflowNodes}`,
+                severity: 'info',
+                nodeIds: [skillNodeId],
+            }, {
+                summaryKind: 'risk',
+                title: `doctor status: ${skill.status}`,
+                severity,
+                nodeIds: nodes.filter((node) => node.nodeKind === 'doctor_rule_result').map((node) => node.id),
+            }],
+    };
+}
+function countDoctorGraphStructure(nodes) {
+    return {
+        references: nodes.filter((node) => node.nodeKind === 'reference').length,
+        scripts: nodes.filter((node) => node.nodeKind === 'script').length,
+        workflows: nodes.filter((node) => node.nodeKind === 'workflow').length,
+        workflowNodes: nodes.filter((node) => node.nodeKind === 'workflow_node').length,
+        hardRules: nodes.filter((node) => node.nodeKind === 'hard_rule').length,
+    };
+}
+function doctorStatusLabel(skill, lang) {
+    if (lang === 'zh') {
+        if (skill.status === 'pass')
+            return '已通过';
+        if (skill.status === 'warn')
+            return '有警告';
+        return '未通过';
+    }
+    if (skill.status === 'pass')
+        return 'passed';
+    if (skill.status === 'warn')
+        return 'warnings';
+    return 'failed';
+}
+function mermaidLabel(label) {
+    const entities = {
+        '&': '&',
+        '\\': '\',
+        '"': '"',
+        '[': '[',
+        ']': ']',
+        '(': '(',
+        ')': ')',
+        '{': '{',
+        '}': '}',
+        '|': '|',
+        '#': '#',
+        ';': '&#59;',
+        '<': '&lt;',
+        '>': '&gt;',
+    };
+    return label
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/[&\\"[\](){}|#;<>]/g, (ch) => entities[ch] ?? ch);
+}
+function compactLabel(label, max = 56) {
+    const normalized = label.replace(/\s+/g, ' ').trim();
+    return normalized.length > max ? `${normalized.slice(0, max - 3)}...` : normalized;
+}
+function doctorProblemResults(skill) {
+    return skill.results.filter((result) => result.status === 'fail' || result.status === 'warn');
+}
+function doctorProblemLabel(result, lang) {
+    if (!result)
+        return null;
+    const zh = lang === 'zh';
+    const prefix = result.status === 'fail'
+        ? (zh ? '失败' : 'fail')
+        : (zh ? '警告' : 'warn');
+    return zh ? `${prefix}：${result.ruleId}` : `${prefix}: ${result.ruleId}`;
+}
+function addExpandedGroup(lines, parentNodeId, groupNodeId, groupLabel, items, lang, max = 3) {
+    if (items.length === 0)
+        return;
+    lines.push(`  ${groupNodeId}["${mermaidLabel(groupLabel)}"]`);
+    lines.push(`  ${parentNodeId} --> ${groupNodeId}`);
+    const visible = items.slice(0, max);
+    visible.forEach((item, index) => {
+        const itemNodeId = `${groupNodeId}_${index + 1}`;
+        lines.push(`  ${itemNodeId}["${mermaidLabel(compactLabel(item, 42))}"]`);
+        lines.push(`  ${groupNodeId} --> ${itemNodeId}`);
+    });
+    const rest = items.length - visible.length;
+    if (rest > 0) {
+        const moreLabel = lang === 'zh' ? `另有 ${rest} 项` : `+${rest} more`;
+        lines.push(`  ${groupNodeId}_more["${mermaidLabel(moreLabel)}"]`);
+        lines.push(`  ${groupNodeId} --> ${groupNodeId}_more`);
+    }
+}
+function renderMermaid(graph, skill, lang) {
+    const references = graphLabelsByKind(graph, 'reference');
+    const scripts = graphLabelsByKind(graph, 'script');
+    const workflows = graphLabelsByKind(graph, 'workflow');
+    const problemLabel = doctorProblemLabel(doctorProblemResults(skill)[0], lang);
+    const lines = [
+        '```mermaid',
+        'flowchart LR',
+        `  file["SKILL.md: ${mermaidLabel(skill.skillName)}"]`,
+        `  doctor["doctor / ${mermaidLabel(doctorStatusLabel(skill, lang))}"]`,
+    ];
+    addExpandedGroup(lines, 'file', 'refs', `references / ${references.length}`, references, lang);
+    addExpandedGroup(lines, 'file', 'scripts', `scripts / ${scripts.length}`, scripts, lang);
+    addExpandedGroup(lines, 'file', 'workflows', `workflows / ${workflows.length}`, workflows, lang);
+    lines.push('  file --> doctor');
+    if (problemLabel) {
+        lines.push(`  issue["${mermaidLabel(compactLabel(problemLabel))}"]`);
+        lines.push('  doctor --> issue');
+    }
+    lines.push(`  eval["${lang === 'zh' ? 'eval 未测量' : 'eval not measured'}"]`);
+    lines.push(`  observe["${lang === 'zh' ? 'observe 未接入' : 'observe not connected'}"]`);
+    lines.push('  doctor -. next .-> eval');
+    lines.push('  eval -. next .-> observe');
+    lines.push('  classDef pending fill:#f3f4f6,stroke:#9ca3af,color:#6b7280');
+    lines.push('  class eval,observe pending');
+    lines.push('```');
+    return lines.join('\n');
+}
+function graphLabelsByKind(graph, kind) {
+    return graph.nodes
+        .filter((node) => node.nodeKind === kind)
+        .map((node) => node.label)
+        .sort((a, b) => a.localeCompare(b));
+}
+function formatInlineItems(items, lang, max = 8) {
+    if (items.length === 0)
+        return lang === 'zh' ? '无' : 'none';
+    const visible = items.slice(0, max).map((item) => `\`${item}\``).join(lang === 'zh' ? '、' : ', ');
+    const rest = items.length - max;
+    if (rest <= 0)
+        return visible;
+    return lang === 'zh' ? `${visible}，另有 ${rest} 项` : `${visible}, plus ${rest} more`;
+}
+function renderStructureDetails(graph, lang) {
+    const zh = lang === 'zh';
+    const references = graphLabelsByKind(graph, 'reference');
+    const scripts = graphLabelsByKind(graph, 'script');
+    const workflows = graphLabelsByKind(graph, 'workflow');
+    if (references.length <= 3 && scripts.length <= 3 && workflows.length <= 3)
+        return [];
+    return [
+        zh ? '### 图中未展开的结构' : '### Hidden Structure',
+        '',
+        ...(references.length > 3 ? [`- references：${formatInlineItems(references.slice(3), lang)}`] : []),
+        ...(scripts.length > 3 ? [`- scripts：${formatInlineItems(scripts.slice(3), lang)}`] : []),
+        ...(workflows.length > 3 ? [`- workflows：${formatInlineItems(workflows.slice(3), lang)}`] : []),
+    ];
+}
+function renderDoctorFindings(skill, lang) {
+    const zh = lang === 'zh';
+    const problems = doctorProblemResults(skill).slice(0, 5);
+    if (problems.length === 0) {
+        return [
+            zh ? '### Doctor 发现' : '### Doctor Findings',
+            '',
+            zh ? '- 暂无失败或警告。' : '- No failures or warnings.',
+        ];
+    }
+    return [
+        zh ? '### Doctor 发现' : '### Doctor Findings',
+        '',
+        ...problems.map((result) => {
+            const label = doctorProblemLabel(result, lang) ?? result.ruleId;
+            const message = result.message ? `：${compactLabel(result.message, 160)}` : '';
+            const hint = result.hint ? (zh ? `；建议：${compactLabel(result.hint, 120)}` : `; hint: ${compactLabel(result.hint, 120)}`) : '';
+            return `- ${label}${message}${hint}`;
+        }),
+    ];
+}
+function shellQuotePath(path) {
+    if (/^[A-Za-z0-9_./:@%+-]+$/.test(path))
+        return path;
+    return JSON.stringify(path);
+}
+export function renderDoctorEvidenceCard(graph, skill, lang) {
+    const zh = lang === 'zh';
+    const counts = countDoctorGraphStructure(graph.nodes);
+    const sampleCount = sampleCountFromDoctor(skill);
+    const doctorStatus = doctorStatusLabel(skill, lang);
+    const sampleText = sampleCount == null ? (zh ? '未检测到 eval samples' : 'eval samples not detected') : `${sampleCount}`;
+    const source = graph.scope.sourceLocator ?? skill.skillPath;
+    const sourceCmd = shellQuotePath(source);
+    const statusSentence = zh
+        ? `这个 skill 有 ${counts.references} 个 references、${counts.scripts} 个 scripts、${counts.workflows} 个 workflows、${counts.workflowNodes} 个 workflow nodes，当前处于「doctor ${doctorStatus}，eval 未测量，observe 未观察」状态。`
+        : `This skill has ${counts.references} references, ${counts.scripts} scripts, ${counts.workflows} workflows, and ${counts.workflowNodes} workflow nodes. Current state: doctor ${doctorStatus}, eval not measured, observe not observed.`;
+    const nextSteps = zh
+        ? [
+            sampleCount == null ? `- 生成用例：\`omk sample ${sourceCmd}\`` : `- 复用当前 ${sampleCount} 条用例继续评测。`,
+            `- 测量效果：\`omk eval --control baseline --treatment ${sourceCmd}\``,
+            '- 接入生产观察：`omk observe ingest <trace-dir>`',
+        ]
+        : [
+            sampleCount == null ? `- Generate samples: \`omk sample ${sourceCmd}\`` : `- Reuse the current ${sampleCount} sample(s) for eval.`,
+            `- Measure impact: \`omk eval --control baseline --treatment ${sourceCmd}\``,
+            '- Add production observation: `omk observe ingest <trace-dir>`',
+        ];
+    const hiddenStructure = renderStructureDetails(graph, lang);
+    return [
+        `## ${zh ? 'Skill Evidence Card' : 'Skill Evidence Card'}：${skill.skillName}`,
+        '',
+        statusSentence,
+        '',
+        renderMermaid(graph, skill, lang),
+        '',
+        ...hiddenStructure,
+        ...(hiddenStructure.length > 0 ? [''] : []),
+        ...renderDoctorFindings(skill, lang),
+        '',
+        zh ? '### 三阶段状态' : '### Stage Status',
+        '',
+        `| ${zh ? '阶段' : 'Stage'} | ${zh ? '状态' : 'Status'} |`,
+        '| --- | --- |',
+        `| doctor | ${doctorStatus} |`,
+        `| eval | ${zh ? '未测量' : 'not measured'} |`,
+        `| observe | ${zh ? '未观察' : 'not observed'} |`,
+        '',
+        zh ? '### 关键计数' : '### Key Counts',
+        '',
+        `| references | scripts | workflows | workflow nodes | hard rules | samples | doctor warnings | doctor failures |`,
+        '| ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |',
+        `| ${counts.references} | ${counts.scripts} | ${counts.workflows} | ${counts.workflowNodes} | ${counts.hardRules} | ${sampleText} | ${skill.results.filter((r) => r.status === 'warn').length} | ${skill.results.filter((r) => r.status === 'fail').length} |`,
+        '',
+        zh ? '### 下一步' : '### Next Steps',
+        '',
+        ...nextSteps,
+        '',
+        zh ? '### 复现信息' : '### Reproduction',
+        '',
+        `- source：\`${source}\``,
+        `- artifactHash：\`${graph.scope.artifactHash ?? 'unknown'}\``,
+        `- doctorReportId：\`${graph.source.sourceId}\``,
+        `- graphId：\`${graph.graphId}\``,
+        `- generatedAt：\`${graph.generatedAt}\``,
+        '',
+    ].join('\n');
+}
+export function persistDoctorGraphSidecars(options) {
+    const dir = doctorGraphDirForDoctorOutput(options.outputDir);
+    mkdirSync(dir, { recursive: true });
+    const graph = buildDoctorArtifactGraph(options);
+    const fileStem = safeFileName(options.fileStem);
+    const graphPath = join(dir, graphFileName(fileStem));
+    const evidenceCardPath = join(dir, cardFileName(fileStem));
+    writeFileSync(graphPath, JSON.stringify(graph, null, 2), 'utf8');
+    writeFileSync(evidenceCardPath, renderDoctorEvidenceCard(graph, options.skill, options.lang), 'utf8');
+    return { graphPath, evidenceCardPath };
+}
+export function removeDoctorGraphSidecars(doctorOutputDir, fileStem) {
+    const dir = doctorGraphDirForDoctorOutput(doctorOutputDir);
+    const safeStem = safeFileName(fileStem);
+    for (const ext of ['graph.json', 'card.md']) {
+        try {
+            unlinkSync(join(dir, `${safeStem}.${ext}`));
+        }
+        catch {
+            // best-effort cleanup only
+        }
+    }
+}

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

@@ -81,6 +81,7 @@ omk eval [flags]
 - `--executor` `option`:执行器:claude / claude-sdk / codex / codex-sdk / openai-api / gemini / 自定义命令（默认 claude）。
 - `--global` `boolean`:报告写全局 ~/.oh-my-knowledge/reports，而非项目 .omk/
 - `--gold-dir` `option`:gold dataset 目录
+- `--holdout-ratio` `option`:留出比例 0-1（如 0.3）；切出 holdout 子集，对比 train/holdout 综合分检测过拟合
 - `--judge-models` `option`:评委配置，格式 executor:model[,...]，例 claude:haiku 或 claude:opus,openai-api:gpt-4o(≥ 2 个 = ensemble）。默认 <executor>:haiku。
 - `--judge-repeat` `option`:每个 dim 评 N 次
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
@@ -100,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/authoring/evolver.d.ts

@@ -16,14 +16,11 @@ interface WeakSample {
     };
 }
 export declare function extractWeakSamples(report: Report, variantKey: string, count?: number, sampleIdFilter?: Set<string>): WeakSample[];
-/** A train / holdout partition of a sample set. */
-interface HoldoutSplit {
-    trainIds: Set<string>;
-    holdoutIds: Set<string>;
-}
 /** A train / val / test partition. `val` drives the accept decision; `test` is
  *  locked — never seen during the loop, read once at the end for an unbiased
- *  generalization score. */
+ *  generalization score. Two-way holdout (`splitHoldout`), the stride picker
+ *  (`pickByStride`), `MIN_HOLDOUT_SUBSET`, and `subsetCompositeScore` live in
+ *  `src/eval-core/holdout.ts` so `omk eval --holdout-ratio` reuses them. */
 interface TrainValTestSplit {
     trainIds: Set<string>;
     valIds: Set<string>;
@@ -34,14 +31,6 @@ interface TrainValTestSplit {
  *  every candidate. Under that floor evolve degrades to the point-estimate accept
  *  and flags `gate.underpowered`. */
 export declare const MIN_GATE_SAMPLES = 8;
-/**
- * Deterministically split sample ids into train / holdout by `ratio` (fraction
- * held out). Holdout members are picked at an even stride so the partition is
- * representative of the ordering, and the split is stable across rounds and runs
- * (no RNG). Returns null when ratio ≤ 0 or either side would drop below
- * MIN_HOLDOUT_SUBSET — the caller then scores on the full set.
- */
-export declare function splitHoldout(sampleIds: string[], ratio: number): HoldoutSplit | null;
 /**
  * Deterministically split sample ids into train / val / test. `val` is carved
  * first at an even stride; `test` is carved at an even stride over what remains,