oh-my-knowledge 0.44.0 → 0.45.0

package/dist/artifact-graph/doctor.js

@@ -506,7 +506,7 @@ export function renderDoctorEvidenceCard(graph, skill, lang) {
         ];
     const hiddenStructure = renderStructureDetails(graph, lang);
     return [
-        `## ${zh ? 'Skill Evidence Card' : 'Skill Evidence Card'}：${skill.skillName}`,
+        `## ${zh ? '知识图谱摘要' : 'Skill Map Summary'}${zh ? '：' : ': '}${skill.skillName}`,
         '',
         statusSentence,
         '',

package/dist/artifact-graph/eval.js

@@ -133,8 +133,73 @@ function sampleAttrs(snapshot) {
         display.tripwire = true;
     if (snapshot.assertions?.length)
         display.assertionCount = snapshot.assertions.length;
+    if (snapshot.covers?.length)
+        display.declaredCoverageTargetCount = snapshot.covers.length;
     return Object.keys(display).length > 0 ? { display } : undefined;
 }
+const COVERAGE_TARGET_NODE_KIND = {
+    skill: 'skill',
+    skill_file: 'skill_file',
+    frontmatter: 'frontmatter',
+    reference: 'reference',
+    script: 'script',
+    hard_rule: 'hard_rule',
+    workflow: 'workflow',
+    workflow_node: 'workflow_node',
+};
+function normalizeCoverageRef(target) {
+    const raw = target.ref.trim().replaceAll('\\', '/');
+    if (target.targetKind === 'reference' || target.targetKind === 'script' || target.targetKind === 'skill_file') {
+        return raw.replace(/^\/+/, '').replace(/^\.\//, '');
+    }
+    return raw;
+}
+function coverageTargetStableKey(target, artifactHash) {
+    const ref = normalizeCoverageRef(target);
+    switch (target.targetKind) {
+        case 'skill':
+            return `v1:skill:${artifactHash}`;
+        case 'skill_file':
+            return `v1:skill-file:${artifactHash}:${ref || 'SKILL.md'}`;
+        case 'frontmatter':
+            return `v1:frontmatter:${artifactHash}`;
+        case 'reference':
+            return `v1:reference:${artifactHash}:${ref}`;
+        case 'script':
+            return `v1:script:${artifactHash}:${ref}`;
+        case 'hard_rule':
+            return `v1:hard-rule:${artifactHash}:${ref}`;
+        case 'workflow':
+            return `v1:workflow:${artifactHash}:${ref}`;
+        case 'workflow_node':
+            return `v1:workflow-node:${artifactHash}:${ref}`;
+    }
+}
+function coverageTargetLabel(target) {
+    const ref = normalizeCoverageRef(target);
+    switch (target.targetKind) {
+        case 'skill':
+            return ref && ref !== 'skill' ? ref : 'SKILL.md';
+        case 'skill_file':
+            return ref || 'SKILL.md';
+        case 'frontmatter':
+            return 'frontmatter';
+        default:
+            return ref;
+    }
+}
+function coverageEvidence(report, sampleId, targetIndex, target) {
+    return [{
+            sourceKind: 'sample',
+            sourceId: sampleId,
+            selector: {
+                selectorKind: 'json-pointer',
+                value: `/sampleSnapshots/${jsonPointerToken(sampleId)}/covers/${targetIndex}`,
+            },
+            contentHash: report.meta.sampleHashes?.[sampleId],
+            label: `${sampleId} covers ${target.targetKind}:${normalizeCoverageRef(target)}`,
+        }];
+}
 export function evalGraphDirForReportOutput(reportOutputDir) {
     return basename(reportOutputDir) === 'reports'
         ? join(dirname(reportOutputDir), 'graphs', 'eval')
@@ -147,6 +212,16 @@ export function buildEvalArtifactGraph(options) {
     const edges = [];
     const nodeIdsByStableKey = new Map();
     const configs = variantConfigByName(report);
+    const skillArtifacts = report.meta.variants
+        .map((variant) => ({
+        variant,
+        artifactHash: report.meta.artifactHashes?.[variant],
+        config: configs.get(variant),
+    }))
+        .filter((item) => item.config?.artifactKind === 'skill'
+        && typeof item.artifactHash === 'string'
+        && item.artifactHash.length > 0
+        && item.artifactHash !== 'no-skill');
     const addNode = (stableKey, nodeKind, nodeRole, label, extra = {}) => {
         const existing = nodeIdsByStableKey.get(stableKey);
         if (existing)
@@ -175,6 +250,50 @@ export function buildEvalArtifactGraph(options) {
             ...extra,
         });
     };
+    const addCoverageEdges = (sampleId, sampleNodeId, snapshot) => {
+        if (!snapshot.covers?.length || skillArtifacts.length === 0)
+            return;
+        const seen = new Set();
+        snapshot.covers.forEach((target, targetIndex) => {
+            const targetRef = normalizeCoverageRef(target);
+            if (!targetRef && target.targetKind !== 'skill' && target.targetKind !== 'frontmatter')
+                return;
+            for (const artifact of skillArtifacts) {
+                const stableKey = coverageTargetStableKey(target, artifact.artifactHash);
+                const dedupeKey = `${sampleNodeId}|${stableKey}`;
+                if (seen.has(dedupeKey))
+                    continue;
+                seen.add(dedupeKey);
+                const evidenceRefs = coverageEvidence(report, sampleId, targetIndex, target);
+                const targetNodeId = addNode(stableKey, COVERAGE_TARGET_NODE_KIND[target.targetKind], 'entity', coverageTargetLabel(target), {
+                    binding: { bindingStrength: 'content-hash', keys: { artifactHash: artifact.artifactHash } },
+                    attrs: {
+                        display: {
+                            targetKind: target.targetKind,
+                            ref: targetRef,
+                            variant: artifact.variant,
+                            sourceLocator: artifact.config.locator,
+                        },
+                    },
+                    evidenceRefs,
+                });
+                addEdge(sampleNodeId, targetNodeId, 'covers', {
+                    confidence: 1,
+                    binding: {
+                        bindingStrength: 'explicit',
+                        keys: {
+                            sampleId,
+                            targetKind: target.targetKind,
+                            targetRef,
+                            artifactHash: artifact.artifactHash,
+                        },
+                    },
+                    attrs: { producer: { source: 'sample.covers' } },
+                    evidenceRefs,
+                });
+            }
+        });
+    };
     const variantNodeIds = new Map();
     for (const variant of report.meta.variants) {
         const artifactHash = report.meta.artifactHashes?.[variant];
@@ -241,6 +360,7 @@ export function buildEvalArtifactGraph(options) {
             });
             addEdge(sampleNodeId, assertionNodeId, 'contains');
         });
+        addCoverageEdges(sampleId, sampleNodeId, snapshot);
     }
     for (const [resultIndex, result] of report.results.entries()) {
         const sampleNodeId = addNode(sampleStableKey(report, result.sample_id), 'sample', 'entity', result.sample_id, {

package/dist/doctor/index.js

@@ -7,12 +7,14 @@
  * fatal-fail 不中断后续 rule 执行(让用户一次看到全貌),但 report.outcome='failed',
  * CLI 据此 exit 1 / abort eval。
  */
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { runFileSuffix } from '../eval-core/artifact-file-names.js';
 import { discoverVariants, resolveArtifacts } from '../inputs/skill-loader.js';
 import { DOCTOR_REPORT_SCHEMA_VERSION, isComposerRule } from '../types/doctor.js';
 import { getRegisteredRules } from './rules.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
 // ---------------------------------------------------------------------------
 // Target resolution
 // ---------------------------------------------------------------------------
@@ -167,9 +169,27 @@ function inferSkillPath(artifact, baseDir) {
 function nextReportId() {
     return `doctor-${runFileSuffix()}`;
 }
+function findPackageJson(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 5; i += 1) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        dir = dirname(dir);
+    }
+    return join(startDir, '..', 'package.json');
+}
 function readCliVersion() {
-    // 不依赖 package.json import(避免 type 解析复杂度);用环境变量或退回 'unknown'
-    return process.env.npm_package_version ?? '0.0.0';
+    const envVersion = process.env.npm_package_version;
+    if (envVersion)
+        return envVersion;
+    try {
+        const pkg = JSON.parse(readFileSync(findPackageJson(__dirname), 'utf-8'));
+        if (typeof pkg.version === 'string' && pkg.version.length > 0)
+            return pkg.version;
+    }
+    catch { /* fall through */ }
+    return '0.0.0';
 }
 export async function runDoctor(opts) {
     // 默认规则 = 内置 + registerRule() 注册的 custom。test 注入走 opts.rules。

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

@@ -273,6 +273,7 @@ export function aggregateReport({ runId, variants, model, judgeModel, noJudge, e
                 ...(s.difficulty ? { difficulty: s.difficulty } : {}),
                 ...(s.construct ? { construct: s.construct } : {}),
                 ...(s.provenance ? { provenance: s.provenance } : {}),
+                ...(s.covers && s.covers.length > 0 ? { covers: s.covers } : {}),
                 ...(s.tripwire ? { tripwire: true } : {}),
             }])),
     };

package/dist/inputs/load-samples.js

@@ -108,6 +108,16 @@ export function validateSamples(samples) {
     // Pure documentation/diagnostic fields; do NOT participate in grading/judge/verdict.
     const VALID_DIFFICULTY = new Set(['easy', 'medium', 'hard']);
     const VALID_PROVENANCE = new Set(['human', 'llm-generated', 'production-trace']);
+    const VALID_COVERAGE_TARGET_KIND = new Set([
+        'skill',
+        'skill_file',
+        'frontmatter',
+        'reference',
+        'script',
+        'hard_rule',
+        'workflow',
+        'workflow_node',
+    ]);
     for (const [i, sample] of samples.entries()) {
         if (!sample.sample_id || typeof sample.sample_id !== 'string') {
             throw new Error(`samples[${i}] missing or invalid required field: sample_id (must be a non-empty string)`);
@@ -135,6 +145,23 @@ export function validateSamples(samples) {
         if (sample.construct !== undefined && typeof sample.construct !== 'string') {
             throw new Error(`samples[${i}] (${sample.sample_id}) invalid construct: must be a string (got ${typeof sample.construct})`);
         }
+        if (sample.covers !== undefined) {
+            if (!Array.isArray(sample.covers)) {
+                throw new Error(`samples[${i}] (${sample.sample_id}) invalid covers: must be an array of coverage target objects`);
+            }
+            for (const [j, target] of sample.covers.entries()) {
+                if (!target || typeof target !== 'object' || Array.isArray(target)) {
+                    throw new Error(`samples[${i}] (${sample.sample_id}) covers[${j}] must be an object with targetKind/ref`);
+                }
+                const record = target;
+                if (typeof record.targetKind !== 'string' || !VALID_COVERAGE_TARGET_KIND.has(record.targetKind)) {
+                    throw new Error(`samples[${i}] (${sample.sample_id}) covers[${j}] invalid targetKind: ${JSON.stringify(record.targetKind)}, expected one of [${[...VALID_COVERAGE_TARGET_KIND].join(', ')}]`);
+                }
+                if (typeof record.ref !== 'string' || !record.ref.trim()) {
+                    throw new Error(`samples[${i}] (${sample.sample_id}) covers[${j}] invalid ref: must be a non-empty string`);
+                }
+            }
+        }
         // tools_called / tools_not_called: values 必须非空。空 values 在 grader 里
         // 永远 passed=true 但 weight=0,是无意义占位,污染断言计数(N/M 看上去比真实
         // 通过率高)+ 让 generator 输出可观测的 garbage 沉淀到磁盘。直接拒掉,作者

package/dist/renderer/skill-detail-renderer.js

@@ -433,6 +433,8 @@ details.si-pass-card[open] > summary > .si-pass-row1::before { content:'▾ ' }
 .sm-node--warning { border-color:rgba(217,119,6,.38);background:rgba(217,119,6,.07) }
 .sm-node--failed { border-color:rgba(220,38,38,.38);background:rgba(220,38,38,.06) }
 .sm-node--pending,.sm-node--more { border-style:dashed;background:rgba(248,249,251,.94);color:#637083 }
+.sm-node--coverage-declared { border-color:rgba(31,157,99,.42);box-shadow:0 10px 24px rgba(31,157,99,.08) }
+.sm-node--coverage-undeclared { border-style:dashed;background:rgba(248,249,251,.94);color:#637083 }
 .sm-node-title { font-size:12.2px;font-weight:700;color:#182033;line-height:1.28;word-break:break-word;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden }
 .sm-node--skill .sm-node-title { font-size:15px;line-height:1.2 }
 .sm-node-meta { font-size:10.5px;color:#637083;line-height:1.35;word-break:break-word }
@@ -1011,11 +1013,25 @@ const SKILL_MAP_INIT_SCRIPT = `
         var isLeaf = el.getAttribute('data-sm-leaf') === '1';
         var overflowGroup = el.getAttribute('data-sm-overflow-group');
         var shouldHide = !layers[layer] || (isLeaf && !showLeaves) || !overflowGroupExpanded(overflowGroup);
+        el.setAttribute('data-sm-filter-hidden', shouldHide ? '1' : '0');
         el.hidden = shouldHide;
         el.toggleAttribute('hidden', shouldHide);
         el.setAttribute('aria-hidden', shouldHide ? 'true' : 'false');
         el.style.display = shouldHide ? 'none' : '';
       });
+      map.querySelectorAll('[data-sm-edge-to]').forEach(function(edge){
+        var toId = edge.getAttribute('data-sm-edge-to');
+        var fromId = edge.getAttribute('data-sm-edge-from-node');
+        var toNode = toId ? graph.querySelector('[data-sm-node-id="' + toId + '"]') : null;
+        var fromNode = fromId ? graph.querySelector('[data-sm-node-id="' + fromId + '"]') : null;
+        var filterHidden = edge.getAttribute('data-sm-filter-hidden') === '1';
+        var endpointHidden = (toNode && toNode.hidden) || (fromNode && fromNode.hidden);
+        var shouldHideEdge = filterHidden || endpointHidden;
+        edge.hidden = shouldHideEdge;
+        edge.toggleAttribute('hidden', shouldHideEdge);
+        edge.setAttribute('aria-hidden', shouldHideEdge ? 'true' : 'false');
+        edge.style.display = shouldHideEdge ? 'none' : '';
+      });
     }
 
     function setMoreExpanded(toggle, expanded){
@@ -1653,12 +1669,27 @@ const SKILL_MAP_STATUS_CLASSES = new Set(['ok', 'warning', 'failed', 'skipped',
 function graphNodeStatusClass(node) {
     return node.status && SKILL_MAP_STATUS_CLASSES.has(node.status) ? ` sm-node--${node.status}` : '';
 }
+function graphNodeCoverageClass(node) {
+    if (node.coverage === 'declared')
+        return ' sm-node--coverage-declared';
+    if (node.coverage === 'undeclared')
+        return ' sm-node--coverage-undeclared';
+    return '';
+}
+function graphNodeCoverageLabel(node, lang) {
+    if (node.coverage === 'declared')
+        return lang === 'zh' ? '已由评测用例声明' : 'declared by eval samples';
+    if (node.coverage === 'undeclared')
+        return lang === 'zh' ? '尚未由评测用例声明' : 'not declared by eval samples';
+    return '';
+}
 function positionedNodeStyle(node) {
     return `left:${node.x}px;top:${node.y}px`;
 }
 function renderSkillMapNode(item, lang) {
     const title = graphNodeMapLabel(item.node);
-    const fullTitle = graphNodeDisplayLabel(item.node, lang);
+    const coverageLabel = graphNodeCoverageLabel(item.node, lang);
+    const fullTitle = [graphNodeDisplayLabel(item.node, lang), coverageLabel].filter(Boolean).join(' · ');
     const kindClass = item.node.nodeKind === 'more' ? ' sm-node--more' : '';
     const leaf = item.layer === 'definition' || item.layer === 'measurement' ? ' data-sm-leaf="1"' : '';
     const draggable = item.layer === 'definition' || item.layer === 'measurement' ? ' data-sm-draggable="1"' : '';
@@ -1666,7 +1697,7 @@ function renderSkillMapNode(item, lang) {
     const moreToggle = item.moreToggle
         ? ` data-sm-more-toggle="${item.moreToggle.group}" data-sm-collapsed-label="${e(item.moreToggle.collapsedLabel)}" data-sm-expanded-label="${e(item.moreToggle.expandedLabel)}" role="button" tabindex="0" aria-expanded="false"`
         : '';
-    return `<div class="sm-node sm-node--${item.layer}${kindClass}${graphNodeStatusClass(item.node)}" data-sm-node-id="${e(item.id)}" data-sm-layer="${item.layer}" data-sm-x="${item.x}" data-sm-y="${item.y}" data-sm-origin-x="${item.x}" data-sm-origin-y="${item.y}"${leaf}${draggable}${overflow}${moreToggle} style="${positionedNodeStyle(item)}" title="${e(fullTitle)}">
+    return `<div class="sm-node sm-node--${item.layer}${kindClass}${graphNodeStatusClass(item.node)}${graphNodeCoverageClass(item.node)}" data-sm-node-id="${e(item.id)}" data-sm-layer="${item.layer}" data-sm-x="${item.x}" data-sm-y="${item.y}" data-sm-origin-x="${item.x}" data-sm-origin-y="${item.y}"${leaf}${draggable}${overflow}${moreToggle} style="${positionedNodeStyle(item)}" title="${e(fullTitle)}">
     <div class="sm-node-kind">${e(nodeKindLabel(item.node.nodeKind, lang))}</div>
     <div class="sm-node-title">${e(title)}</div>
   </div>`;
@@ -1739,6 +1770,36 @@ function orderedPreviewNodes(nodes, allowedKinds, priority) {
         .sort((a, b) => (priority[a.node.nodeKind] ?? 99) - (priority[b.node.nodeKind] ?? 99) || a.index - b.index)
         .map(({ node }) => node);
 }
+function applyDefinitionCoverageDeclarations(nodes, declaredStableKeys) {
+    if (!nodes)
+        return undefined;
+    if (!declaredStableKeys || declaredStableKeys.length === 0)
+        return nodes;
+    const declared = new Set(declaredStableKeys);
+    return nodes.map((node) => {
+        if (!node.stableKey || !DEFINITION_PREVIEW_KINDS.has(node.nodeKind))
+            return node;
+        return { ...node, coverage: declared.has(node.stableKey) ? 'declared' : 'undeclared' };
+    });
+}
+function skillMapCoverageDeclarationSummary(doctor, evalGraph, lang) {
+    const declaredKeys = new Set(evalGraph?.declaredCoverageStableKeys ?? []);
+    if (!doctor || declaredKeys.size === 0)
+        return null;
+    const coverable = doctor.definitionNodes.filter((node) => node.stableKey && DEFINITION_PREVIEW_KINDS.has(node.nodeKind));
+    if (coverable.length === 0)
+        return null;
+    const declaredCount = coverable.filter((node) => node.stableKey && declaredKeys.has(node.stableKey)).length;
+    const samples = evalGraph?.samples ?? 0;
+    return lang === 'zh'
+        ? `${samples} 条评测用例声明了 ${declaredCount}/${coverable.length} 个结构节点`
+        : `${samples} eval samples declared ${declaredCount}/${coverable.length} structure nodes`;
+}
+function skillMapCoverageDeclarationHint(lang) {
+    return lang === 'zh'
+        ? '这些关系来自 sample.covers，表示评测用例显式标注的主要触达节点；尚未声明只表示还没有被评测用例显式标注，不应直接视为测试缺口。'
+        : 'These relationships come from sample.covers and show the main nodes explicitly annotated by eval samples; not declared only means not explicitly annotated yet, not necessarily a test gap.';
+}
 function renderSkillEvidenceMarkdown(entry, lang) {
     const zh = lang === 'zh';
     const graph = entry.graph;
@@ -1758,7 +1819,8 @@ function renderSkillEvidenceMarkdown(entry, lang) {
         !entry.eval ? `- ${zh ? '测量效果' : 'Measure impact'}${stepSeparator} \`omk eval --control baseline --treatment ${sourceArg}\`` : '',
         !entry.observe ? `- ${zh ? '接入观察' : 'Add observation'}${stepSeparator} \`omk observe ingest <trace-dir>\`` : '',
     ].filter(Boolean);
-    const definitionPreview = previewNodes(doctor?.definitionNodes, DEFINITION_PREVIEW_KINDS, 8);
+    const coverageSummary = skillMapCoverageDeclarationSummary(doctor, evalGraph, lang);
+    const definitionPreview = previewNodes(applyDefinitionCoverageDeclarations(doctor?.definitionNodes, evalGraph?.declaredCoverageStableKeys), DEFINITION_PREVIEW_KINDS, 8);
     const measurementPreview = previewNodes(evalGraph?.measurementNodes, MEASUREMENT_PREVIEW_KINDS, 8);
     const previewMermaidLines = [
         ...definitionPreview.visible.flatMap((node, index) => [
@@ -1771,7 +1833,7 @@ function renderSkillEvidenceMarkdown(entry, lang) {
         ]),
     ];
     return [
-        `## Skill Evidence Card：${entry.skillName}`,
+        `## ${zh ? '知识图谱摘要' : 'Skill Map Summary'}${zh ? '：' : ': '}${entry.skillName}`,
         '',
         summary,
         '',
@@ -1793,6 +1855,7 @@ function renderSkillEvidenceMarkdown(entry, lang) {
         `| doctor | ${doctorStatus} | ${doctor ? `${doctor.nodeCount} nodes / ${doctor.edgeCount} edges` : (zh ? '无 graph' : 'no graph')} |`,
         `| eval | ${evalStatus} | ${evalGraph ? `${zh ? 'variant 子图' : 'variant subgraph'}: ${evalGraph.nodeCount} nodes / ${evalGraph.edgeCount} edges` : (zh ? '无 graph' : 'no graph')} |`,
         `| observe | ${observeStatus} | ${zh ? '未接 production graph' : 'production graph not connected'} |`,
+        ...(coverageSummary ? ['', zh ? '### 声明锚点' : '### Declared Anchors', '', coverageSummary, '', skillMapCoverageDeclarationHint(lang)] : []),
         '',
         zh ? '### 关键计数' : '### Key Counts',
         '',
@@ -1820,7 +1883,9 @@ function renderSkillMapSection(entry, lang) {
     const evalGraph = graph.eval;
     const band = skillMapBand(entry);
     const markdown = renderSkillEvidenceMarkdown(entry, lang);
-    const definitionCandidates = orderedPreviewNodes(doctor?.definitionNodes, DEFINITION_PREVIEW_KINDS, {
+    const definitionNodesWithCoverageDeclarations = applyDefinitionCoverageDeclarations(doctor?.definitionNodes, evalGraph?.declaredCoverageStableKeys);
+    const coverageSummary = skillMapCoverageDeclarationSummary(doctor, evalGraph, lang);
+    const definitionCandidates = orderedPreviewNodes(definitionNodesWithCoverageDeclarations, DEFINITION_PREVIEW_KINDS, {
         reference: 1,
         script: 2,
         workflow: 3,
@@ -1897,10 +1962,15 @@ function renderSkillMapSection(entry, lang) {
     ];
     const mapNodes = [...definitionNodes, ...measurementNodes];
     const mapDimensions = skillMapDimensions(mapNodes);
+    const topMeta = [
+        coverageSummary,
+        !coverageSummary && doctor ? `${doctor.nodeCount} ${zh ? '结构节点' : 'definition nodes'}` : '',
+        !coverageSummary && evalGraph ? `${evalGraph.samples} ${zh ? '用例' : 'samples'}` : '',
+    ].filter(Boolean).join(' · ');
     return `<section id="section-skill-map" class="si-sect si-sect--${band} sm-sect">
     <div class="si-sect-h">
       <span class="si-sect-title">🗺 ${zh ? 'Skill Map' : 'Skill Map'}</span>
-      <span class="si-sect-meta">${doctor ? `${doctor.nodeCount} definition nodes` : (zh ? 'definition 未生成' : 'definition missing')} · ${evalGraph ? `${evalGraph.nodeCount} variant subgraph nodes` : (zh ? 'measurement 未生成' : 'measurement missing')}</span>
+      <span class="si-sect-meta">${e(topMeta || (zh ? '图谱数据未生成' : 'graph data missing'))}</span>
     </div>
     <div class="sm-body" data-sm-map data-sm-base-width="${mapDimensions.width}" data-sm-base-height="${mapDimensions.height}" data-sm-root-x="${SKILL_MAP_ROOT.x}" data-sm-root-y="${SKILL_MAP_ROOT.y}">
       ${renderSkillStageRail(entry, lang)}
@@ -1930,7 +2000,7 @@ function renderSkillMapSection(entry, lang) {
         </div>
       </div>
       <details class="sm-card">
-        <summary>${zh ? '复制 Markdown Evidence Card' : 'Copy Markdown Evidence Card'}</summary>
+        <summary>${zh ? '复制图谱摘要' : 'Copy Skill Map Summary'}</summary>
         <textarea readonly>${e(markdown)}</textarea>
       </details>
     </div>

package/dist/renderer/skill-list-renderer.js

@@ -134,7 +134,7 @@ function renderPanel(a, lang) {
 // renderSkillModal 已移除:首页点行直接进 skill 详情页(doctor/eval/observe 已在该页合一),弹框预览冗余。
 function renderRow(entry, insights, langQ, lang) {
     const h = assessHealth(entry, insights, lang);
-    // 点行先进入 skill hub：Skill Map / 三阶段状态 / Evidence Card 是用户第一视角。
+    // 点行先进入 skill hub：Skill Map / 三阶段状态 / 图谱摘要是用户第一视角。
     const href = `/skills/${encodeURIComponent(entry.skillName)}${langQ}`;
     const dT = entry.doctor ? entry.doctor.passCount + entry.doctor.warnCount + entry.doctor.failCount : 0;
     const dP = dT > 0 ? Math.round(((entry.doctor.passCount + entry.doctor.warnCount * 0.5) / dT) * 100) : null;

package/dist/server/skill-index.js

@@ -412,6 +412,7 @@ function countGraphNodes(graph, nodeKind) {
 }
 function graphNodePreview(node) {
     return {
+        stableKey: node.stableKey,
         nodeKind: node.nodeKind,
         label: node.label,
         ...(node.status ? { status: node.status } : {}),
@@ -499,6 +500,24 @@ function projectEvalStage(graph, path, entry) {
             addEdge(edge);
         }
     }
+    const declaredCoverageStableKeys = new Set();
+    let coverageEdges = 0;
+    for (const edge of graph.edges) {
+        if (edge.edgeKind !== 'covers')
+            continue;
+        const from = nodesById.get(edge.fromNodeId);
+        const to = nodesById.get(edge.toNodeId);
+        if (from?.nodeKind !== 'sample' || !to)
+            continue;
+        if (!projectedNodeIds.has(from.id))
+            continue;
+        if (artifactHash && nodeArtifactHash(to) !== artifactHash)
+            continue;
+        addEdge(edge);
+        coverageEdges += 1;
+        if (to.stableKey)
+            declaredCoverageStableKeys.add(to.stableKey);
+    }
     const sampleIds = new Set();
     const assertionIds = new Set();
     const diagnosticIds = new Set();
@@ -544,6 +563,8 @@ function projectEvalStage(graph, path, entry) {
             failedAssertionEdges,
             diagnostics: diagnosticIds.size,
             measurementNodes,
+            coverageEdges,
+            declaredCoverageStableKeys: [...declaredCoverageStableKeys].sort(),
         },
         ...(artifactHash ? { artifactHash } : {}),
         ...(sourceLocator ? { sourceLocator } : {}),

package/dist/types/artifact-graph.d.ts

@@ -29,7 +29,7 @@ export type ArtifactGraphNodeRole = 'entity' | 'observation' | 'aggregate';
 export type ArtifactGraphNodeKind = 'skill' | 'skill_file' | 'frontmatter' | 'reference' | 'script' | 'tool' | 'env' | 'preflight' | 'hard_rule' | 'workflow' | 'workflow_node' | 'sample' | 'assertion' | 'variant' | 'doctor_rule_result' | 'eval_result' | 'judge_dimension' | 'diagnostic' | 'trace_session' | 'skill_invocation' | 'tool_call' | 'gap_signal';
 export type ArtifactGraphStatus = 'ok' | 'warning' | 'failed' | 'skipped' | 'unknown' | 'not_measured';
 export interface ArtifactGraphBinding {
-    bindingStrength: 'content-hash' | 'source-locator' | 'runtime-trace' | 'name-only' | 'aggregate';
+    bindingStrength: 'content-hash' | 'source-locator' | 'runtime-trace' | 'name-only' | 'aggregate' | 'explicit';
     keys: Record<string, string>;
 }
 export interface ArtifactGraphAttrs {

package/dist/types/eval.d.ts

@@ -27,6 +27,14 @@ export interface Assertion {
 export type SampleProvenance = 'human' | 'llm-generated' | 'production-trace';
 /** sample 难度等级。简单分桶,跟 IRT 风格 fine-grained difficulty 不同。 */
 export type SampleDifficulty = 'easy' | 'medium' | 'hard';
+/** Sample 可选声明的 skill 结构锚点。用于 Skill Map / 诊断，不参与 grading / judge / verdict。 */
+export type SampleCoverageTargetKind = 'skill' | 'skill_file' | 'frontmatter' | 'reference' | 'script' | 'hard_rule' | 'workflow' | 'workflow_node';
+export interface SampleCoverageTarget {
+    /** 目标类型。避免裸 kind，保持 Artifact.kind 语义唯一。 */
+    targetKind: SampleCoverageTargetKind;
+    /** 稳定引用：路径或 ID。reference/script 用 skill 根相对路径，workflow_node 用 workflowId.nodeId。 */
+    ref: string;
+}
 /** Sample 评测环境前置:声明性"已就绪"清单,LLM 看到后跳过环境探测,直接进入工作流。
  *  类比 unit test 的 fixture / setup —— 评测是测 skill 工作流,不是测环境探测能力。 */
 export interface SampleEnvironment {
@@ -112,6 +120,8 @@ export interface Sample {
      *  curated 用 `'human'`,production trace 抽样用 `'production-trace'`。
      *  纯文档 / 诊断用。 */
     provenance?: SampleProvenance;
+    /** 该 sample 可选声明的 skill 结构锚点。纯文档 / 图谱诊断用，不进入评分、评委或 verdict。 */
+    covers?: SampleCoverageTarget[];
     /** 诱错样本(tripwire)标记。true = 此 sample 故意设计成 LLM 应该 fail 的诱导陷阱
      *  (如:用户用错误前提诱导 / 跳步骤 / 用错参数类型),用于测 skill 是否能让 LLM
      *  识破并纠正。Diagnostic 看到 tripwire:true 时会建议"无需改 skill"(rootCause:

package/dist/types/report.d.ts

@@ -346,6 +346,7 @@ export interface ResultEntry {
  *   - assertions: 期望(运行后的 pass/fail 结果在 VariantResult.assertions.details 里)
  *   - mocks: 工具调用模拟返回(LLM 调到匹配的 tool/参数时拿到这段假返回,而不是真去调外部系统)
  *   - capability / construct / difficulty: 元数据
+ *   - covers: sample 可选声明的 skill 结构锚点
  *   - context: 附加上下文(代码片段等)
  *
  * 旧 report 没有这个字段,renderer 据此 fallback(隐藏单测 tab 或提示"无设计快照")。
@@ -361,6 +362,7 @@ export interface SampleSnapshot {
     difficulty?: import('./eval.js').SampleDifficulty;
     construct?: string;
     provenance?: import('./eval.js').SampleProvenance;
+    covers?: import('./eval.js').SampleCoverageTarget[];
     /** Diagnostic 用 — tripwire sample 不该建议改 skill。 */
     tripwire?: boolean;
 }
@@ -476,7 +478,7 @@ export interface AnalysisResult {
     coverage?: Record<string, KnowledgeCoverage>;
     /** Per-variant knowledge gap reports. See docs/specs/knowledge-gap-signal-spec.md */
     gapReports?: Record<string, GapReport>;
-    /** Sample design science aggregate. Built from sample metadata
+    /** Sample design science aggregate. Built from measurement metadata
      *  (capability / difficulty / construct / provenance); persisted on report
      *  for studio to surface coverage gaps. See docs/specs/sample-design-spec.md. */
     sampleQuality?: SampleQualityAggregate;

package/dist/types/skill-index.d.ts

@@ -52,9 +52,11 @@ export interface SkillGraphStageSnapshot {
     edgeCount: number;
 }
 export interface SkillGraphNodePreview {
+    stableKey?: string;
     nodeKind: string;
     label: string;
     status?: string;
+    coverage?: 'declared' | 'undeclared';
 }
 export interface SkillGraphSnapshot {
     /** Studio 聚合 graph sidecar 时实际采用的绑定强度。 */
@@ -76,6 +78,8 @@ export interface SkillGraphSnapshot {
         failedAssertionEdges: number;
         diagnostics: number;
         measurementNodes: SkillGraphNodePreview[];
+        coverageEdges: number;
+        declaredCoverageStableKeys: string[];
     };
 }
 export interface SkillIndexEntry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "packageManager": "yarn@4.16.0",
   "description": "Evaluation framework for LLM knowledge inputs — prompts, RAG corpora, skills, agent workflows. Fix the model, vary the artifact. Built-in statistical rigor: bootstrap CI, Krippendorff α, length-debias, saturation curves.",
   "type": "module",
@@ -92,11 +92,11 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
-    "@anthropic-ai/sdk": "^0.104.1",
+    "@anthropic-ai/sdk": "^0.105.0",
     "@inquirer/prompts": "^8.4.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@oclif/core": "^4",
-    "@openai/codex-sdk": "0.139.0",
+    "@openai/codex-sdk": "0.141.0",
     "ajv": "^8.18.0",
     "chart.js": "^4.5.1",
     "js-yaml": "^4.1.1",