oh-my-knowledge 0.43.0 → 0.45.0

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

@@ -134,13 +134,8 @@ function renderPanel(a, lang) {
 // renderSkillModal 已移除:首页点行直接进 skill 详情页(doctor/eval/observe 已在该页合一),弹框预览冗余。
 function renderRow(entry, insights, langQ, lang) {
     const h = assessHealth(entry, insights, lang);
-    // 点行直接进该 skill 最新 eval 报告(无 eval 则最新 doctor);跨维度/历史在报告页内切换。
-    const amp = lang === DEFAULT_LANG ? '' : `&lang=${lang}`;
-    const href = entry.eval
-        ? `/reports/${encodeURIComponent(entry.eval.reportId)}${langQ}`
-        : entry.doctor
-            ? `/doctors/${encodeURIComponent(entry.doctor.reportId)}?skill=${encodeURIComponent(entry.skillName)}${amp}`
-            : `/runs${langQ}`;
+    // 点行先进入 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;
     const eP = entry.eval?.compositeScore != null ? Math.round((entry.eval.compositeScore / 5) * 100) : null;

package/dist/server/report-server.js

@@ -6,13 +6,14 @@ import { renderReportDocumentDetail, renderTrendsPage, renderRunList } from '../
 import { renderSkillList } from '../renderer/skill-list-renderer.js';
 import { renderSkillHealthReport } from '../renderer/skill-health-renderer.js';
 import { renderDoctorDetail } from '../renderer/doctor-detail-renderer.js';
-import { assessHealth } from '../renderer/skill-detail-renderer.js';
+import { assessHealth, renderSkillDetail } from '../renderer/skill-detail-renderer.js';
 import { renderObservationInboxPage } from '../renderer/observation-inbox-renderer.js';
 import { DEFAULT_LANG, t, layout } from '../renderer/layout.js';
 import { loadAllManagedRecords, resolveManagedDir, managedDir as projectManagedDir, listManagedRows, buildVersionScores } from '../managed/index.js';
 import { renderManagedList, renderManagedHistory } from '../renderer/managed-history-renderer.js';
 import { DEFAULT_JOBS_DIR } from '../eval-core/default-dirs.js';
 import { resolveObserveHealthDir, projectObserveHealthDir, resolveDoctorsDir, projectDoctorsDir, projectReportsDir, globalReportsDir } from '../eval-core/measurement-dirs.js';
+import { evalGraphDirForReportOutput } from '../artifact-graph/eval.js';
 import { listObserveCards, listDoctorCards, listLiveObserveCards } from '../eval-core/artifact-index.js';
 import { isReportFileName, reportFilePath, reportFileStem } from '../eval-core/artifact-file-names.js';
 import { migrateLegacyReportFiles } from '../eval-core/report-file-migration.js';
@@ -602,6 +603,18 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
         : doctorsDir !== undefined
             ? () => doctorsDir
             : () => resolveDoctorsDir(projectDoctorsDir());
+    const includeReportCards = reportsDir === undefined && store == null;
+    const evalGraphDirs = reportsDir !== undefined
+        ? [evalGraphDirForReportOutput(reportsDir)]
+        : store
+            ? []
+            : [evalGraphDirForReportOutput(projectReportsDir()), evalGraphDirForReportOutput(globalReportsDir())];
+    const skillIndexOptions = () => ({
+        includeObserveCards,
+        includeDoctorCards,
+        includeReportCards,
+        evalGraphDirs,
+    });
     async function handleRequest(req, res) {
         try {
             const parsed = new URL(req.url || '/', 'http://127.0.0.1');
@@ -752,7 +765,7 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
             }
             if (path === '/api/observe-inbox/diagnostics') {
                 const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(JSON.stringify({
                     sourceCoverage: idx.diagnosisSummary.sourceCoverage,
@@ -838,7 +851,7 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
                 let ctx;
                 if (skillName) {
                     const runs = await reportStore.list();
-                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                     const entry = idx.entries.find((en) => en.skillName === skillName);
                     if (entry)
                         ctx = buildSkillContext(entry, 'doctor', id, idx.insightsBySkill.get(entry.skillName) ?? [], lang);
@@ -1000,7 +1013,7 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
                 let ctx;
                 if (report && report.kind === 'evaluation') {
                     const runs = await reportStore.list();
-                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                     // 按 evalHistory 匹配(非仅最新),历史 eval 报告也能定位到所属 skill。
                     const entry = idx.entries.find((en) => en.evalHistory.some((h) => h.reportId === reportId));
                     if (entry)
@@ -1022,14 +1035,14 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
             // list renderer 直接消费,不再每请求 N×detectInsights 重算。
             if (path === '/') {
                 const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
                 res.end(renderSkillList(idx, lang));
                 return;
             }
             if (path === '/api/skills') {
                 const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(JSON.stringify({
                     entries: idx.entries.map((entry) => ({
@@ -1042,15 +1055,36 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
                 }));
                 return;
             }
-            // 注:/skills/<name> 详情页(hub)已下线 — 首页点行直接进 eval/doctor 报告,跨维度靠
-            // 报告页 chip 条 +「全部历史」弹框,不再有中间汇总页。该路由不做兼容重定向:Studio
-            // 是本地临时服务器、端口每次启动都变,跨会话书签 localhost:<port> 本就失效,且 PR 内
-            // 已无任何链接指向它。未匹配的 /skills/<name> 直接落到下方通用 404。
+            const skillHubMatch = path.match(/^\/skills\/(.+)$/);
+            if (skillHubMatch) {
+                let skillName;
+                try {
+                    skillName = decodeURIComponent(skillHubMatch[1]);
+                }
+                catch {
+                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(lang === 'en' ? 'skill not found' : '未找到该 skill');
+                    return;
+                }
+                const runs = await reportStore.list();
+                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
+                const entry = idx.entries.find((en) => en.skillName === skillName);
+                if (!entry) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(lang === 'en' ? 'skill not found' : '未找到该 skill');
+                    return;
+                }
+                const report = entry.eval ? await queryRun(reportStore, entry.eval.reportId) : null;
+                const evalReport = report?.kind === 'evaluation' ? report : null;
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(renderSkillDetail(entry, evalReport, lang, idx.insightsBySkill.get(entry.skillName) ?? []));
+                return;
+            }
             const skillDiagnosticsApiMatch = path.match(/^\/api\/skills\/(.+)\/diagnostics$/);
             if (skillDiagnosticsApiMatch) {
                 const skillName = decodeURIComponent(skillDiagnosticsApiMatch[1]);
                 const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, { includeObserveCards, includeDoctorCards });
+                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir, skillIndexOptions());
                 const diagnostics = idx.diagnosticsBySkill.get(skillName);
                 if (!diagnostics) {
                     res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });

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

@@ -13,6 +13,12 @@ export interface BuildSkillIndexOptions {
     includeObserveCards?: boolean;
     /** 合并别项目 doctor 卡片(机器级模式)。固定 --doctors-dir / --global 时为 false,只看该目录。 */
     includeDoctorCards?: boolean;
+    /** 合并别项目 eval report 卡片对应的 graph sidecar。 */
+    includeReportCards?: boolean;
+    /** 当前可见 eval graph sidecar 目录。 */
+    evalGraphDirs?: string[];
+    /** 当前可见 doctor graph sidecar 目录。默认跟随 doctorsDir 推导。 */
+    doctorGraphDirs?: string[];
 }
 export declare function buildSkillIndex(reports: ReportDocument[], analysesDir: string, doctorsDir: string, observationsDir?: string, opts?: BuildSkillIndexOptions): SkillIndex;
 /** 单 skill 详情查询(用于 /skills/<name> 详情页)— 复用 buildSkillIndex 的扫描结果。 */

package/dist/server/skill-index.js

@@ -15,11 +15,13 @@
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, isAbsolute, basename, dirname } from 'node:path';
-import { isReportFileName, reportFileStem } from '../eval-core/artifact-file-names.js';
+import { GRAPH_FILE_SUFFIX, graphFileName, isReportFileName, reportFileStem } from '../eval-core/artifact-file-names.js';
 import { migrateLegacyReportFiles } from '../eval-core/report-file-migration.js';
+import { doctorGraphDirForDoctorOutput } from '../artifact-graph/doctor.js';
+import { evalGraphDirForReportOutput } from '../artifact-graph/eval.js';
 import { confidenceOf } from '../observability/skill-health-analyzer.js';
 import { computeVerdict } from '../eval-core/verdict.js';
-import { artifactIndexDir, listLiveDoctorCards, cardToDoctorSnapshot, listLiveObserveCards, cardTargetSentinel } from '../eval-core/artifact-index.js';
+import { artifactIndexDir, listLiveDoctorCards, cardToDoctorSnapshot, listLiveObserveCards, listLiveReportCards, cardTargetSentinel } from '../eval-core/artifact-index.js';
 import { detectInsights } from './skill-insights.js';
 import { DEFAULT_OBSERVATIONS_DIR, loadLatestObservationInboxReports } from '../observability/inbox.js';
 import { buildStudioDiagnosisSummary, mergeDiagnosisBundles } from '../diagnosis/studio-projection.js';
@@ -64,7 +66,59 @@ function safeDirJsonContentFingerprint(dir) {
     });
     return `${dir}|${dirMtimeMs}|${fileParts.join(',')}`;
 }
-function buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir, includeObserveCards, includeDoctorCards) {
+function safeDirGraphContentFingerprint(dir) {
+    let dirMtimeMs;
+    let graphFiles;
+    try {
+        dirMtimeMs = statSync(dir).mtimeMs;
+        graphFiles = readdirSync(dir).filter((f) => f.endsWith(GRAPH_FILE_SUFFIX)).sort();
+    }
+    catch {
+        return `missing:${dir}`;
+    }
+    const fileParts = graphFiles.map((f) => {
+        try {
+            const fStat = statSync(join(dir, f));
+            return `${f}:${fStat.mtimeMs}:${fStat.size}`;
+        }
+        catch {
+            return `${f}:?`;
+        }
+    });
+    return `${dir}|${dirMtimeMs}|${fileParts.join(',')}`;
+}
+function fileFingerprint(path) {
+    try {
+        const stat = statSync(path);
+        return `${path}:${stat.mtimeMs}:${stat.size}`;
+    }
+    catch {
+        return `${path}:missing`;
+    }
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(Boolean))].sort();
+}
+function graphSidecarPathForReportPath(reportPath, reportId) {
+    return join(evalGraphDirForReportOutput(dirname(reportPath)), graphFileName(reportId));
+}
+function graphSidecarPathForDoctorCard(cardPath, cardId) {
+    return join(doctorGraphDirForDoctorOutput(dirname(cardPath)), graphFileName(cardId));
+}
+function buildGraphFingerprint(evalGraphDirs, doctorGraphDirs, includeReportCards, includeDoctorCards) {
+    const dirPart = [
+        ...uniqueStrings(evalGraphDirs).map((dir) => `eg:${safeDirGraphContentFingerprint(dir)}`),
+        ...uniqueStrings(doctorGraphDirs).map((dir) => `dg:${safeDirGraphContentFingerprint(dir)}`),
+    ].join('|');
+    const reportCardPart = includeReportCards
+        ? listLiveReportCards().map((card) => fileFingerprint(graphSidecarPathForReportPath(card.path, card.id))).sort().join('|')
+        : '';
+    const doctorCardPart = includeDoctorCards
+        ? listLiveDoctorCards().map((card) => fileFingerprint(graphSidecarPathForDoctorCard(card.path, card.id))).sort().join('|')
+        : '';
+    return `${dirPart}|erc:${reportCardPart}|drc:${doctorCardPart}`;
+}
+function buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir, includeObserveCards, includeDoctorCards, graphFingerprint) {
     // `d:` 跟 `o:` 前缀("d for doctors / o for observability analyses")沿用 pre-fix
     // 字面格式,避免外部 logging / debug 时 grep fingerprint 字符串的格式漂移。
     // 每一段的 right-hand-side 从旧的 "{dir-mtime}-{file-count}" 双标量升级成
@@ -83,7 +137,7 @@ function buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir
     // 卡片目录指纹 + 真身存在性 sentinel 都纳入:后者使「卡片真身被带外删」也能让缓存失效(否则悬空卡片继续展示)。
     const doctorCardsFp = includeDoctorCards ? `${safeDirJsonContentFingerprint(artifactIndexDir('doctor'))}|t:${cardTargetSentinel('doctor')}` : '';
     const observeCardsFp = includeObserveCards ? `${safeDirJsonContentFingerprint(artifactIndexDir('observe-health'))}|t:${cardTargetSentinel('observe-health')}` : '';
-    return `${reportIds}|d:${doctorsFp}|o:${analysesFp}|obs:${observationsFp}|dc:${doctorCardsFp}|oc:${observeCardsFp}|inc:${includeObserveCards ? 'o' : ''}${includeDoctorCards ? 'd' : ''}`;
+    return `${reportIds}|d:${doctorsFp}|o:${analysesFp}|obs:${observationsFp}|dc:${doctorCardsFp}|oc:${observeCardsFp}|g:${graphFingerprint}|inc:${includeObserveCards ? 'o' : ''}${includeDoctorCards ? 'd' : ''}`;
 }
 /** 测试 / 调试用:强制清掉 in-process skill-index 缓存。 */
 export function _resetSkillIndexCache() {
@@ -227,6 +281,334 @@ function latestEvalSnapshot(list) {
         return null;
     return list[list.length - 1];
 }
+function isArtifactGraphDocument(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const graph = value;
+    return graph.documentKind === 'artifact-graph'
+        && graph.schemaVersion === 1
+        && typeof graph.graphId === 'string'
+        && !!graph.source
+        && (graph.source.sourceKind === 'doctor' || graph.source.sourceKind === 'eval' || graph.source.sourceKind === 'observe')
+        && Array.isArray(graph.nodes)
+        && Array.isArray(graph.edges);
+}
+function readArtifactGraph(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!isArtifactGraphDocument(parsed))
+            return null;
+        return { graph: parsed, path };
+    }
+    catch {
+        return null;
+    }
+}
+function scanGraphDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const file of readdirSync(dir).sort()) {
+        if (!file.endsWith(GRAPH_FILE_SUFFIX))
+            continue;
+        const loaded = readArtifactGraph(join(dir, file));
+        if (loaded)
+            out.push(loaded);
+    }
+    return out;
+}
+function loadGraphsForSkillIndex(options) {
+    const byPath = new Map();
+    const add = (loaded) => {
+        if (loaded)
+            byPath.set(loaded.path, loaded);
+    };
+    for (const dir of uniqueStrings(options.evalGraphDirs)) {
+        for (const graph of scanGraphDir(dir))
+            add(graph);
+    }
+    for (const dir of uniqueStrings(options.doctorGraphDirs)) {
+        for (const graph of scanGraphDir(dir))
+            add(graph);
+    }
+    if (options.includeReportCards) {
+        for (const card of listLiveReportCards()) {
+            add(readArtifactGraph(graphSidecarPathForReportPath(card.path, card.id)));
+        }
+    }
+    if (options.includeDoctorCards) {
+        for (const card of listLiveDoctorCards()) {
+            add(readArtifactGraph(graphSidecarPathForDoctorCard(card.path, card.id)));
+        }
+    }
+    return [...byPath.values()];
+}
+function graphSkillNodes(graph) {
+    return graph.nodes.filter((node) => node.nodeKind === 'skill');
+}
+function graphSkillNames(graph) {
+    return uniqueStrings([
+        graph.scope.skillName ?? '',
+        ...graphSkillNodes(graph).map((node) => node.label),
+    ]);
+}
+function nodeArtifactHash(node) {
+    const hash = node?.binding?.keys?.artifactHash;
+    return hash && hash !== 'no-skill' ? hash : undefined;
+}
+function nodeSourceLocator(node) {
+    const locator = node?.attrs?.display?.sourceLocator;
+    return typeof locator === 'string' && locator.trim() ? locator : undefined;
+}
+function graphSourceLocator(graph, skillNode) {
+    if (graph.source.sourceKind === 'eval') {
+        // Eval graph 的 scope.sourceLocator 是 samplesPath；skill 路径在 skill node 上。
+        return nodeSourceLocator(skillNode);
+    }
+    return graph.scope.sourceLocator ?? nodeSourceLocator(skillNode);
+}
+function graphNodeMap(graph) {
+    return new Map(graph.nodes.map((node) => [node.id, node]));
+}
+function graphHasSkill(graph, entry) {
+    const names = graphSkillNames(graph);
+    return names.includes(entry.skillName) || (entry.eval ? names.includes(entry.eval.variantName) : false);
+}
+function graphMatchesDoctorEntry(graph, entry) {
+    return graphHasSkill(graph, entry);
+}
+function evalVariantName(entry) {
+    return entry.eval?.variantName ?? null;
+}
+function evalVariantNode(graph, entry) {
+    const variantName = evalVariantName(entry);
+    if (!variantName)
+        return undefined;
+    return graph.nodes.find((node) => node.nodeKind === 'variant' && node.label === variantName);
+}
+function evalSkillNodeForVariant(graph, variantNode) {
+    const nodesById = graphNodeMap(graph);
+    return graph.edges
+        .filter((edge) => edge.fromNodeId === variantNode.id && edge.edgeKind === 'derived_from')
+        .map((edge) => nodesById.get(edge.toNodeId))
+        .find((node) => node?.nodeKind === 'skill');
+}
+function graphMatchesEvalEntry(graph, entry) {
+    return evalVariantNode(graph, entry) !== undefined;
+}
+function pickLatestGraph(graphs) {
+    if (graphs.length === 0)
+        return null;
+    return [...graphs].sort((a, b) => {
+        const at = a.graph.generatedAt || '';
+        const bt = b.graph.generatedAt || '';
+        if (at !== bt)
+            return at.localeCompare(bt);
+        return a.graph.graphId.localeCompare(b.graph.graphId);
+    })[graphs.length - 1];
+}
+function countGraphNodes(graph, nodeKind) {
+    return graph.nodes.filter((node) => node.nodeKind === nodeKind).length;
+}
+function graphNodePreview(node) {
+    return {
+        stableKey: node.stableKey,
+        nodeKind: node.nodeKind,
+        label: node.label,
+        ...(node.status ? { status: node.status } : {}),
+    };
+}
+function graphNodePreviews(graph, nodeKinds, nodeIds) {
+    const kinds = new Set(nodeKinds);
+    return graph.nodes
+        .filter((node) => kinds.has(node.nodeKind) && (!nodeIds || nodeIds.has(node.id)))
+        .map(graphNodePreview);
+}
+function projectDoctorStage(graph, path) {
+    if (graph.source.sourceKind !== 'doctor')
+        return undefined;
+    const skillNode = graphSkillNodes(graph)[0];
+    const sourceLocator = graphSourceLocator(graph, skillNode);
+    const base = {
+        sourceKind: 'doctor',
+        sourceId: graph.source.sourceId,
+        graphId: graph.graphId,
+        generatedAt: graph.generatedAt,
+        graphPath: path,
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+    };
+    return {
+        stage: {
+            ...base,
+            references: countGraphNodes(graph, 'reference'),
+            scripts: countGraphNodes(graph, 'script'),
+            workflows: countGraphNodes(graph, 'workflow'),
+            workflowNodes: countGraphNodes(graph, 'workflow_node'),
+            hardRules: countGraphNodes(graph, 'hard_rule'),
+            definitionNodes: graphNodePreviews(graph, [
+                'skill_file',
+                'frontmatter',
+                'reference',
+                'script',
+                'preflight',
+                'tool',
+                'hard_rule',
+                'workflow',
+                'workflow_node',
+                'doctor_rule_result',
+            ]),
+        },
+        ...(graph.scope.artifactHash ? { artifactHash: graph.scope.artifactHash } : {}),
+        ...(sourceLocator ? { sourceLocator } : {}),
+    };
+}
+function projectEvalStage(graph, path, entry) {
+    if (graph.source.sourceKind !== 'eval')
+        return undefined;
+    const variantNode = evalVariantNode(graph, entry);
+    if (!variantNode)
+        return undefined;
+    const skillNode = evalSkillNodeForVariant(graph, variantNode);
+    const artifactHash = nodeArtifactHash(variantNode) ?? nodeArtifactHash(skillNode);
+    const sourceLocator = graphSourceLocator(graph, skillNode);
+    const nodesById = graphNodeMap(graph);
+    const projectedNodeIds = new Set([variantNode.id]);
+    const projectedEdgeIds = new Set();
+    if (skillNode)
+        projectedNodeIds.add(skillNode.id);
+    const addEdge = (edge) => {
+        projectedEdgeIds.add(edge.id);
+        projectedNodeIds.add(edge.fromNodeId);
+        projectedNodeIds.add(edge.toNodeId);
+    };
+    for (const edge of graph.edges) {
+        if (edge.fromNodeId === variantNode.id && (edge.edgeKind === 'evaluates' || edge.edgeKind === 'derived_from')) {
+            addEdge(edge);
+        }
+    }
+    const evalResultNodes = graph.edges
+        .filter((edge) => edge.toNodeId === variantNode.id && edge.edgeKind === 'derived_from')
+        .map((edge) => nodesById.get(edge.fromNodeId))
+        .filter((node) => node?.nodeKind === 'eval_result');
+    for (const node of evalResultNodes)
+        projectedNodeIds.add(node.id);
+    for (const edge of graph.edges) {
+        if (!evalResultNodes.some((node) => node.id === edge.fromNodeId || node.id === edge.toNodeId))
+            continue;
+        if (edge.edgeKind === 'derived_from' || edge.edgeKind === 'evaluates' || edge.edgeKind === 'passes' || edge.edgeKind === 'fails' || edge.edgeKind === 'diagnoses') {
+            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();
+    let failedAssertionEdges = 0;
+    for (const edge of graph.edges) {
+        if (!projectedEdgeIds.has(edge.id))
+            continue;
+        const from = nodesById.get(edge.fromNodeId);
+        const to = nodesById.get(edge.toNodeId);
+        if (from?.nodeKind === 'sample')
+            sampleIds.add(from.id);
+        if (to?.nodeKind === 'sample')
+            sampleIds.add(to.id);
+        if (from?.nodeKind === 'assertion')
+            assertionIds.add(from.id);
+        if (to?.nodeKind === 'assertion')
+            assertionIds.add(to.id);
+        if (from?.nodeKind === 'diagnostic')
+            diagnosticIds.add(from.id);
+        if (to?.nodeKind === 'diagnostic')
+            diagnosticIds.add(to.id);
+        if (edge.edgeKind === 'fails')
+            failedAssertionEdges += 1;
+    }
+    const measurementNodes = graphNodePreviews(graph, [
+        'sample',
+        'assertion',
+        'eval_result',
+        'diagnostic',
+    ], projectedNodeIds);
+    return {
+        stage: {
+            sourceKind: 'eval',
+            sourceId: graph.source.sourceId,
+            graphId: graph.graphId,
+            generatedAt: graph.generatedAt,
+            graphPath: path,
+            nodeCount: projectedNodeIds.size,
+            edgeCount: projectedEdgeIds.size,
+            variantName: variantNode.label,
+            samples: sampleIds.size,
+            assertions: assertionIds.size,
+            failedAssertionEdges,
+            diagnostics: diagnosticIds.size,
+            measurementNodes,
+            coverageEdges,
+            declaredCoverageStableKeys: [...declaredCoverageStableKeys].sort(),
+        },
+        ...(artifactHash ? { artifactHash } : {}),
+        ...(sourceLocator ? { sourceLocator } : {}),
+    };
+}
+function graphSnapshotBinding(stages) {
+    const hashes = uniqueStrings(stages.map((stage) => stage.artifactHash ?? ''));
+    const locators = uniqueStrings(stages.map((stage) => stage.sourceLocator ?? ''));
+    if (stages.length > 0 && hashes.length === 1 && stages.every((stage) => stage.artifactHash === hashes[0])) {
+        return { bindingStrength: 'content-hash', artifactHash: hashes[0], ...(locators[0] ? { sourceLocator: locators[0] } : {}) };
+    }
+    if (hashes.length > 0) {
+        return { bindingStrength: 'mixed', ...(locators[0] ? { sourceLocator: locators[0] } : {}) };
+    }
+    if (locators.length > 0) {
+        return { bindingStrength: 'source-locator', sourceLocator: locators[0] };
+    }
+    return { bindingStrength: 'name-only' };
+}
+function graphSnapshotForEntry(entry, graphs) {
+    const doctorCandidates = graphs.filter(({ graph }) => graph.source.sourceKind === 'doctor'
+        && (!entry.doctor || graph.source.sourceId === entry.doctor.reportId)
+        && graphMatchesDoctorEntry(graph, entry));
+    const evalCandidates = graphs.filter(({ graph }) => graph.source.sourceKind === 'eval'
+        && (!entry.eval || graph.source.sourceId === entry.eval.reportId)
+        && graphMatchesEvalEntry(graph, entry));
+    const doctor = pickLatestGraph(doctorCandidates);
+    const evalGraph = pickLatestGraph(evalCandidates);
+    if (!doctor && !evalGraph)
+        return undefined;
+    const doctorStage = doctor ? projectDoctorStage(doctor.graph, doctor.path) : undefined;
+    const evalStage = evalGraph ? projectEvalStage(evalGraph.graph, evalGraph.path, entry) : undefined;
+    const projectedStages = [];
+    if (doctorStage)
+        projectedStages.push(doctorStage);
+    if (evalStage)
+        projectedStages.push(evalStage);
+    const binding = graphSnapshotBinding(projectedStages);
+    return {
+        ...binding,
+        ...(doctorStage ? { doctor: doctorStage.stage } : {}),
+        ...(evalStage ? { eval: evalStage.stage } : {}),
+    };
+}
 /** 扫 doctorsDir/*.report.json,按 skill 名分桶,**返回该 skill 的所有历史 snapshot**(asc 时序)。
  *  renderer 用最后一项做"当前",前面项画 sparkline。 */
 function scanDoctorReports(dir) {
@@ -265,8 +647,15 @@ function scanDoctorReports(dir) {
 export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDir = DEFAULT_OBSERVATIONS_DIR, opts = {}) {
     const includeObserveCards = opts.includeObserveCards ?? false;
     const includeDoctorCards = opts.includeDoctorCards ?? false;
+    const includeReportCards = opts.includeReportCards ?? false;
+    const evalGraphDirs = uniqueStrings(opts.evalGraphDirs ?? []);
+    const doctorGraphDirs = uniqueStrings([
+        doctorGraphDirForDoctorOutput(doctorsDir),
+        ...(opts.doctorGraphDirs ?? []),
+    ]);
+    const graphFingerprint = buildGraphFingerprint(evalGraphDirs, doctorGraphDirs, includeReportCards, includeDoctorCards);
     // 命中缓存就直接返回(fingerprint 覆盖 reports + 两个 dir + 卡片 include 模式的变化信号)
-    const fp = buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir, includeObserveCards, includeDoctorCards);
+    const fp = buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir, includeObserveCards, includeDoctorCards, graphFingerprint);
     if (_indexCache && _indexCache.fingerprint === fp) {
         return _indexCache.result;
     }
@@ -409,6 +798,17 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
         else if (hasMed)
             ent.band = 'yellow';
     }
+    const graphs = loadGraphsForSkillIndex({
+        evalGraphDirs,
+        doctorGraphDirs,
+        includeReportCards,
+        includeDoctorCards,
+    });
+    for (const ent of entries) {
+        const graph = graphSnapshotForEntry(ent, graphs);
+        if (graph)
+            ent.graph = graph;
+    }
     summary.red = entries.filter((e) => e.band === 'red').length;
     summary.yellow = entries.filter((e) => e.band === 'yellow').length;
     summary.green = entries.filter((e) => e.band === 'green').length;

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;