oh-my-knowledge 0.42.0 → 0.44.0

package/dist/server/skill-index.js

@@ -9,30 +9,32 @@
  *     因为同一份 EvaluationReport 同时驱动两个 view tab。
  *   - observe 报告(analysesDir, SkillHealthReport):data.bySkill[name] 每个键作为
  *     一个 skill 的 observe snapshot,取最新 generatedAt。
- *   - doctor:暂无独立持久化路径(omk doctor --html 写指定路径,默认不存盘),
- *     该字段保留 null,渲染层显示"未独立运行 omk doctor"。后续 commit 加默认
- *     ~/.oh-my-knowledge/doctors/ 持久化路径再回填。
+ *   - doctor:读取 `.omk/doctors/*.report.json`,按 skill 名聚合体检历史。
  *
  * 综合 band:eval / observe 任一红 → 红,任一黄 → 黄,全绿 → 绿,皆未跑 → gray。
  */
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, isAbsolute, basename, dirname } from 'node:path';
+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';
 let _indexCache = null;
 /**
  * Sync 版 dir-content fingerprint helper,仿 `src/server/report-store.ts:80-92`
- * 的 async `computeListFingerprint` — 把目录本身的 mtime 跟目录下每个 `.json`
+ * 的 async `computeListFingerprint` — 把目录本身的 mtime 跟目录下每个 `.report.json`
  * 文件的 "filename:mtimeMs:size" 三元组排序拼接成 stable 字符串作为 dir-level
  * 的 content-aware fingerprint。
  *
- * - 目录下任何 .json 文件**新增 / 删除 / 重命名** → 目录 mtime 跟着变,且
+ * - 目录下任何 .report.json 文件**新增 / 删除 / 重命名** → 目录 mtime 跟着变,且
  *   sorted-filenames 列表变,字符串变 → cache invalidate。
- * - 任何**已有同名 .json 文件被外部进程原地覆写内容** → 该文件自己的 mtimeMs
+ * - 任何**已有同名 .report.json 文件被外部进程原地覆写内容** → 该文件自己的 mtimeMs
  *   跟通常情况下 size 都变(byte 长度跟内容相关),字符串里那一 entry 的后缀
  *   变,整体字符串变 → cache invalidate。这是 pre-fix 的 fingerprint(只看
  *   dir mtime+文件数)漏掉的信号(reviewer 2026-05-11 P2-a)。
@@ -48,7 +50,7 @@ function safeDirJsonContentFingerprint(dir) {
     let jsonFiles;
     try {
         dirMtimeMs = statSync(dir).mtimeMs;
-        jsonFiles = readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+        jsonFiles = readdirSync(dir).filter(isReportFileName).sort();
     }
     catch {
         return `missing:${dir}`;
@@ -64,13 +66,68 @@ 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}" 双标量升级成
     // safeDirJsonContentFingerprint 返回的 "{dir-mtime}|{file1}:{m}:{s},..."
     // content-aware 字符串。
     const reportIds = reports.map((r) => `${r.id}:${r.meta?.timestamp ?? ''}:${r.kind === 'evaluation' ? r.meta.evolve?.skillName ?? '' : ''}`).join(',');
+    migrateLegacyReportFiles(doctorsDir, 'doctor');
+    migrateLegacyReportFiles(analysesDir, 'observe-health');
+    migrateLegacyReportFiles(observationsDir, 'observe-inbox');
     const doctorsFp = safeDirJsonContentFingerprint(doctorsDir);
     const analysesFp = safeDirJsonContentFingerprint(analysesDir);
     const observationsFp = safeDirJsonContentFingerprint(observationsDir);
@@ -80,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() {
@@ -224,14 +281,322 @@ function latestEvalSnapshot(list) {
         return null;
     return list[list.length - 1];
 }
-/** 扫 doctorsDir/*.json,按 skill 名分桶,**返回该 skill 的所有历史 snapshot**(asc 时序)。
+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 {
+        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 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,
+        },
+        ...(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) {
     const out = {};
+    migrateLegacyReportFiles(dir, 'doctor');
     if (!existsSync(dir))
         return out;
     for (const file of readdirSync(dir)) {
-        if (!file.endsWith('.json'))
+        if (!isReportFileName(file))
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
@@ -261,8 +626,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;
     }
@@ -288,16 +660,17 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
         list.sort((a, b) => evalSnapshotSortKey(a).localeCompare(evalSnapshotSortKey(b)));
     // ── observe 聚合(历史 list)──────────────────────────────
     const observeBy = {};
+    migrateLegacyReportFiles(analysesDir, 'observe-health');
     if (existsSync(analysesDir)) {
         for (const file of readdirSync(analysesDir)) {
-            if (!file.endsWith('.json'))
+            const id = reportFileStem(file);
+            if (!id)
                 continue;
             try {
                 const data = JSON.parse(readFileSync(join(analysesDir, file), 'utf-8'));
                 if (!data?.bySkill || !data.meta)
                     continue;
                 const generatedAt = data.meta.generatedAt;
-                const id = file.replace(/\.json$/, '');
                 for (const [skill, h] of Object.entries(data.bySkill)) {
                     const snap = {
                         analysisId: id, generatedAt,
@@ -404,6 +777,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

@@ -0,0 +1,93 @@
+export interface ArtifactGraphDocument {
+    documentKind: 'artifact-graph';
+    schemaVersion: 1;
+    graphId: string;
+    generatedAt: string;
+    source: ArtifactGraphSource;
+    scope: ArtifactGraphScope;
+    nodes: ArtifactGraphNode[];
+    edges: ArtifactGraphEdge[];
+    summaries?: ArtifactGraphSummary[];
+}
+export type ArtifactGraphSourceKind = 'doctor' | 'eval' | 'observe';
+export interface ArtifactGraphSource {
+    sourceKind: ArtifactGraphSourceKind;
+    sourceId: string;
+    sourcePath?: string;
+    cliVersion?: string;
+}
+export interface ArtifactGraphScope {
+    cwd: string;
+    artifactKind?: 'skill' | 'prompt' | 'agent' | 'workflow';
+    skillName?: string;
+    artifactHash?: string;
+    sourceLocator?: string;
+    sampleSetHash?: string;
+}
+export type ArtifactGraphLayer = 'definition' | 'measurement' | 'production';
+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';
+    keys: Record<string, string>;
+}
+export interface ArtifactGraphAttrs {
+    display?: Record<string, unknown>;
+    producer?: Record<string, unknown>;
+    experimental?: Record<string, unknown>;
+}
+export interface ArtifactGraphNode {
+    id: string;
+    stableKey: string;
+    nodeKind: ArtifactGraphNodeKind;
+    nodeRole: ArtifactGraphNodeRole;
+    layer: ArtifactGraphLayer;
+    label: string;
+    status?: ArtifactGraphStatus;
+    confidence?: number;
+    binding?: ArtifactGraphBinding;
+    metrics?: Record<string, number>;
+    attrs?: ArtifactGraphAttrs;
+    evidenceRefs?: ArtifactGraphEvidenceRef[];
+}
+export type ArtifactGraphEdgeKind = 'contains' | 'declares' | 'requires' | 'references' | 'defines_workflow' | 'next_step' | 'covers' | 'evaluates' | 'passes' | 'fails' | 'diagnoses' | 'invokes' | 'calls_tool' | 'observes' | 'signals_gap' | 'derived_from';
+export interface ArtifactGraphEdge {
+    id: string;
+    fromNodeId: string;
+    toNodeId: string;
+    edgeKind: ArtifactGraphEdgeKind;
+    layer: ArtifactGraphLayer;
+    label?: string;
+    status?: ArtifactGraphStatus;
+    confidence?: number;
+    weight?: number;
+    binding?: ArtifactGraphBinding;
+    metrics?: Record<string, number>;
+    attrs?: ArtifactGraphAttrs;
+    evidenceRefs?: ArtifactGraphEvidenceRef[];
+}
+export type ArtifactGraphEvidenceSourceKind = 'skill-file' | 'doctor-report' | 'eval-report' | 'observe-report' | 'trace' | 'sample' | 'managed-record';
+export type ArtifactGraphEvidenceSelectorKind = 'json-pointer' | 'line-range' | 'sample-id' | 'rule-id' | 'trace-event-id' | 'node-id';
+export interface ArtifactGraphEvidenceSelector {
+    selectorKind: ArtifactGraphEvidenceSelectorKind;
+    value: string;
+}
+export interface ArtifactGraphEvidenceRef {
+    sourceKind: ArtifactGraphEvidenceSourceKind;
+    sourceId?: string;
+    path?: string;
+    selector?: ArtifactGraphEvidenceSelector;
+    contentHash?: string;
+    label?: string;
+    snippet?: string;
+    redaction?: 'none' | 'truncated' | 'redacted';
+}
+export interface ArtifactGraphSummary {
+    summaryKind: 'structure' | 'coverage' | 'risk' | 'gap' | 'workflow' | 'collection';
+    title: string;
+    severity: 'info' | 'low' | 'medium' | 'high';
+    nodeIds?: string[];
+    edgeIds?: string[];
+    evidenceRefs?: ArtifactGraphEvidenceRef[];
+}

package/dist/types/artifact-graph.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from './report.js';
 export * from './storage.js';
 export * from './doctor.js';
 export * from './diagnosis.js';
+export * from './artifact-graph.js';
 export * from './dependencies.js';
 export * from './skill-index.js';
 export * from './observability.js';

package/dist/types/index.js

@@ -6,6 +6,7 @@ export * from './report.js';
 export * from './storage.js';
 export * from './doctor.js';
 export * from './diagnosis.js';
+export * from './artifact-graph.js';
 export * from './dependencies.js';
 export * from './skill-index.js';
 export * from './observability.js';

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

@@ -42,6 +42,42 @@ export interface SkillObserveSnapshot {
      *  历史快照缺此字段时由 segmentCount 兜底推导。 */
     confidence: 'high' | 'low' | 'underpowered';
 }
+export interface SkillGraphStageSnapshot {
+    sourceKind: 'doctor' | 'eval' | 'observe';
+    sourceId: string;
+    graphId: string;
+    generatedAt: string;
+    graphPath?: string;
+    nodeCount: number;
+    edgeCount: number;
+}
+export interface SkillGraphNodePreview {
+    nodeKind: string;
+    label: string;
+    status?: string;
+}
+export interface SkillGraphSnapshot {
+    /** Studio 聚合 graph sidecar 时实际采用的绑定强度。 */
+    bindingStrength: 'content-hash' | 'source-locator' | 'name-only' | 'mixed';
+    artifactHash?: string;
+    sourceLocator?: string;
+    doctor?: SkillGraphStageSnapshot & {
+        references: number;
+        scripts: number;
+        workflows: number;
+        workflowNodes: number;
+        hardRules: number;
+        definitionNodes: SkillGraphNodePreview[];
+    };
+    eval?: SkillGraphStageSnapshot & {
+        variantName?: string;
+        samples: number;
+        assertions: number;
+        failedAssertionEdges: number;
+        diagnostics: number;
+        measurementNodes: SkillGraphNodePreview[];
+    };
+}
 export interface SkillIndexEntry {
     skillName: string;
     /** 当前(最新)snapshot — 等价于对应 history 的最后一项,空时为 null。renderer
@@ -56,6 +92,8 @@ export interface SkillIndexEntry {
     /** 综合健康灯。doctor / eval / observe 任一红 → red;任一黄 → yellow;
      *  全绿 → green;皆未跑 → gray。 */
     band: 'green' | 'yellow' | 'red' | 'gray';
+    /** doctor/eval/observe graph sidecar 的轻量 Studio 投影。 */
+    graph?: SkillGraphSnapshot;
 }
 export interface SkillIndexSummary {
     totalSkills: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.42.0",
+  "version": "0.44.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",