oh-my-knowledge 0.48.0 → 0.49.0

package/dist/server/report-store.js

@@ -3,32 +3,18 @@
  * Default implementation: local file system.
  * Can be replaced with database, S3, etc.
  */
-import { readdir, readFile, writeFile, unlink, access, mkdir, rename, stat } from 'node:fs/promises';
+import { readdir, readFile, unlink, access, mkdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isReportFileName, reportFilePath, reportFileStem } from '../eval-core/artifact-file-names.js';
+import { isReportFileName, reportFileName, reportFilePath, reportFileStem, safeArtifactFileStem, } from '../eval-core/artifact-file-names.js';
 import { migrateLegacyReportFiles } from '../eval-core/report-file-migration.js';
-// Per-id in-memory mutex for safe read-modify-write.
-// Uses a queue to avoid the race window between checking and acquiring the lock.
-const locks = new Map();
-async function withLock(id, fn) {
-    // Chain onto any existing lock for this id, so requests are serialized
-    const prev = locks.get(id) ?? Promise.resolve();
-    let releaseLock;
-    const next = new Promise((r) => { releaseLock = r; });
-    locks.set(id, next);
-    await prev;
-    try {
-        return await fn();
-    }
-    finally {
-        locks.delete(id);
-        releaseLock();
-    }
-}
+import { parseReportDocument } from '../eval-core/report-document.js';
+import { writeJsonFileAtomicAsync } from '../shared/atomic-json.js';
+import { KeyedMutex } from '../shared/keyed-mutex.js';
 /**
  * Create a file-system-based report store.
  */
 export function createFileStore(dir) {
+    const mutations = new KeyedMutex();
     async function ensureDir() {
         try {
             await access(dir);
@@ -37,35 +23,6 @@ export function createFileStore(dir) {
             await mkdir(dir, { recursive: true });
         }
     }
-    function normalizeReportDocument(data, fallbackId) {
-        if (!data || typeof data !== 'object')
-            return null;
-        const record = data;
-        const kind = record.kind === 'evaluation' || record.kind === 'batch-evaluation'
-            ? record.kind
-            : undefined;
-        if (kind === 'evaluation') {
-            if (!record.meta || !record.summary || !Array.isArray(record.results))
-                return null;
-            return {
-                ...record,
-                kind,
-                id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
-            };
-        }
-        if (kind === 'batch-evaluation') {
-            if (!record.meta || !Array.isArray(record.items))
-                return null;
-            return {
-                ...record,
-                kind,
-                id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
-            };
-        }
-        // 只认 canonical 顶层 `kind`(evaluation / batch-evaluation)。不再为旧格式(顶层无该判别字段的
-        // 历史文件)做读兼容 —— 顶层 kind cutover 是硬切换,旧文件直接判脏丢弃。
-        return null;
-    }
     function isEvaluationReport(report) {
         return report.kind === 'evaluation';
     }
@@ -75,6 +32,13 @@ export function createFileStore(dir) {
     // 完全跳过 readFile。
     let cachedFingerprint = '';
     let cachedRuns = null;
+    function invalidateListCache() {
+        cachedFingerprint = '';
+        cachedRuns = null;
+    }
+    function cloneReports(reports) {
+        return structuredClone(reports);
+    }
     async function computeListFingerprint() {
         try {
             const dirStat = await stat(dir);
@@ -104,7 +68,7 @@ export function createFileStore(dir) {
         migrateLegacyReportFiles(dir, 'report');
         const fp = await computeListFingerprint();
         if (fp != null && fp === cachedFingerprint && cachedRuns)
-            return cachedRuns;
+            return cloneReports(cachedRuns);
         const files = (await readdir(dir))
             .filter(isReportFileName)
             .sort()
@@ -113,8 +77,8 @@ export function createFileStore(dir) {
         for (const file of files) {
             try {
                 const data = JSON.parse(await readFile(join(dir, file), 'utf-8'));
-                const report = normalizeReportDocument(data, reportFileStem(file) ?? file);
-                if (report)
+                const report = parseReportDocument(data, reportFileStem(file) ?? file);
+                if (report && reportFileName(report.id) === file)
                     runs.push(report);
             }
             catch { /* skip corrupt files */ }
@@ -127,63 +91,71 @@ export function createFileStore(dir) {
         if (fp != null) {
             cachedFingerprint = fp;
             cachedRuns = runs;
+            return cloneReports(runs);
         }
         return runs;
     }
     async function get(id) {
+        if (!id || safeArtifactFileStem(id) !== id)
+            return null;
         migrateLegacyReportFiles(dir, 'report');
         try {
             const data = JSON.parse(await readFile(reportFilePath(dir, id), 'utf-8'));
-            return normalizeReportDocument(data, id);
+            return parseReportDocument(data, id, id);
         }
         catch {
             return null;
         }
     }
-    async function save(id, report) {
+    async function saveUnlocked(id, report) {
+        if (!id
+            || safeArtifactFileStem(id) !== id
+            || report.id !== id
+            || !parseReportDocument(report, id, id)) {
+            throw new Error('invalid report');
+        }
         await ensureDir();
         migrateLegacyReportFiles(dir, 'report');
-        const targetPath = reportFilePath(dir, id);
-        const tmpPath = `${targetPath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
-        await writeFile(tmpPath, JSON.stringify(report, null, 2));
-        await rename(tmpPath, targetPath);
+        await writeJsonFileAtomicAsync(reportFilePath(dir, id), report);
+        invalidateListCache();
+    }
+    async function save(id, report) {
+        await mutations.run(id, () => saveUnlocked(id, report));
     }
     /**
      * Atomic read-modify-write with in-memory mutex.
      * Prevents concurrent updates from overwriting each other.
      */
     async function update(id, mutator) {
-        return withLock(id, async () => {
+        return mutations.run(id, async () => {
             const report = await get(id);
             if (!report)
                 return null;
             mutator(report);
-            await save(id, report);
+            await saveUnlocked(id, report);
             return report;
         });
     }
     async function remove(id) {
-        migrateLegacyReportFiles(dir, 'report');
-        try {
-            await unlink(reportFilePath(dir, id));
-            return true;
-        }
-        catch (err) {
-            const fsError = err;
-            if (fsError.code === 'ENOENT')
-                return false;
-            throw err;
-        }
+        if (!id || safeArtifactFileStem(id) !== id)
+            return false;
+        return mutations.run(id, async () => {
+            migrateLegacyReportFiles(dir, 'report');
+            try {
+                await unlink(reportFilePath(dir, id));
+                invalidateListCache();
+                return true;
+            }
+            catch (err) {
+                const fsError = err;
+                if (fsError.code === 'ENOENT')
+                    return false;
+                throw err;
+            }
+        });
     }
     async function exists(id) {
-        migrateLegacyReportFiles(dir, 'report');
-        try {
-            await access(reportFilePath(dir, id));
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return (await get(id)) !== null;
     }
     async function findByVariant(variantName) {
         const all = await list();
@@ -231,7 +203,12 @@ export function createOverlayReportStore(projectDir, globalDir) {
         return (await project.exists(id)) ? project.update(id, mutator) : global.update(id, mutator);
     }
     async function remove(id) {
-        return (await project.remove(id)) || global.remove(id);
+        // Migration windows can leave the same id in both roots. Always attempt both:
+        // short-circuiting after the project copy would make get() fall back to the
+        // surviving global copy and appear to resurrect a successfully deleted report.
+        const projectRemoved = await project.remove(id);
+        const globalRemoved = await global.remove(id);
+        return projectRemoved || globalRemoved;
     }
     async function findByVariant(variantName) {
         return (await projectHasReports()) ? project.findByVariant(variantName) : global.findByVariant(variantName);

package/dist/server/skill-index.js

@@ -19,12 +19,16 @@ import { GRAPH_FILE_SUFFIX, graphFileName, isReportFileName, reportFileStem } fr
 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 { parseSkillHealthReport } from '../observability/skill-health-report.js';
+import { confidenceOf, toolStabilityOf } from '../observability/skill-health-analyzer.js';
 import { computeVerdict } from '../eval-core/verdict.js';
-import { artifactIndexDir, listLiveDoctorCards, cardToDoctorSnapshot, listLiveObserveCards, listLiveReportCards, cardTargetSentinel } from '../eval-core/artifact-index.js';
+import { artifactIndexDir, listLiveDoctorCards, 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';
+import { parseDoctorReport } from '../shared/doctor-report.js';
+import { parseArtifactGraphDocument } from '../shared/artifact-graph.js';
+import { ownRecordValue } from '../shared/record-count.js';
 let _indexCache = null;
 /**
  * Sync 版 dir-content fingerprint helper,仿 `src/server/report-store.ts:80-92`
@@ -235,16 +239,39 @@ const PER_SKILL_BAND_RED_FAILURE_RATE = 0.4; // 工具失败率 ≥ 40% → red
 const PER_SKILL_BAND_YELLOW_FAILURE_RATE = 0.2; // ≥ 20% → yellow
 const PER_SKILL_BAND_YELLOW_GAP_RATE = 0.3; // 加权 gap ≥ 30% → yellow
 function bandFromObserveHealth(h) {
-    if (h.toolFailureRate >= PER_SKILL_BAND_RED_FAILURE_RATE)
+    const resolvedOutcomeCount = h.toolResolvedCount ?? h.toolCallCount;
+    const comparableOutcomeCount = resolvedOutcomeCount === undefined
+        ? undefined
+        : Math.max(0, resolvedOutcomeCount - (h.toolCancelledCount ?? 0));
+    const failureRateMeasured = comparableOutcomeCount === undefined || comparableOutcomeCount >= 5;
+    if (h.toolFailureRate >= PER_SKILL_BAND_RED_FAILURE_RATE
+        && failureRateMeasured)
         return 'red';
     const gap = h.gap?.weightedGapRate ?? 0;
-    if (gap >= PER_SKILL_BAND_YELLOW_GAP_RATE || h.toolFailureRate >= PER_SKILL_BAND_YELLOW_FAILURE_RATE)
+    if (gap >= PER_SKILL_BAND_YELLOW_GAP_RATE
+        || (h.toolFailureRate >= PER_SKILL_BAND_YELLOW_FAILURE_RATE
+            && failureRateMeasured))
         return 'yellow';
     return 'green';
 }
-function combineBand(doctor, evalSnap, _observe) {
-    if (!doctor && !evalSnap)
+function normalizedObserveStability(h) {
+    if (h.toolCallCount === undefined)
+        return h.stability;
+    const resolved = h.toolResolvedCount ?? h.toolCallCount;
+    const comparable = Math.max(0, resolved - (h.toolCancelledCount ?? 0));
+    return toolStabilityOf(h.toolFailureRate, comparable, h.toolCallCount);
+}
+function effectiveObserveSnapshotBand(observe) {
+    if (!observe || observe.confidence === 'underpowered')
+        return 'gray';
+    if (observe.healthBand === 'green'
+        && (observe.toolCallCount ?? 0) > 0
+        && Math.max(0, (observe.toolResolvedCount ?? observe.toolCallCount ?? 0)
+            - (observe.toolCancelledCount ?? 0)) < 5)
         return 'gray';
+    return observe.healthBand;
+}
+function combineBand(doctor, evalSnap, observe) {
     // doctor band: status fail → red, warn → yellow, pass → green
     const doctorBand = !doctor
         ? 'gray'
@@ -258,11 +285,13 @@ function combineBand(doctor, evalSnap, _observe) {
         : evalScore < 2.5 ? 'red'
             : evalScore < 3.5 ? 'yellow'
                 : 'green';
-    if (doctorBand === 'red' || evalBand === 'red')
+    // underpowered observe 的色带仅供参考，不参与聚合硬结论。
+    const observeBand = effectiveObserveSnapshotBand(observe);
+    if (doctorBand === 'red' || evalBand === 'red' || observeBand === 'red')
         return 'red';
-    if (doctorBand === 'yellow' || evalBand === 'yellow')
+    if (doctorBand === 'yellow' || evalBand === 'yellow' || observeBand === 'yellow')
         return 'yellow';
-    if (doctorBand === 'green' || evalBand === 'green')
+    if (doctorBand === 'green' || evalBand === 'green' || observeBand === 'green')
         return 'green';
     return 'gray';
 }
@@ -281,24 +310,11 @@ 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 };
+        const graph = parseArtifactGraphDocument(parsed);
+        return graph ? { graph, path } : null;
     }
     catch {
         return null;
@@ -477,6 +493,7 @@ function projectEvalStage(graph, path, entry) {
     const projectedEdgeIds = new Set();
     const sampleStatusByNodeId = new Map();
     const assertionStatusByNodeId = new Map();
+    const parentSampleStableKeyByNodeId = new Map();
     if (skillNode)
         projectedNodeIds.add(skillNode.id);
     const addEdge = (edge) => {
@@ -496,15 +513,45 @@ function projectEvalStage(graph, path, entry) {
         .filter((edge) => edge.toNodeId === variantNode.id && edge.edgeKind === 'derived_from')
         .map((edge) => nodesById.get(edge.fromNodeId))
         .filter((node) => node?.nodeKind === 'eval_result');
+    const evalResultNodeIds = new Set(evalResultNodes.map((node) => node.id));
     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))
+        if (!evalResultNodeIds.has(edge.fromNodeId) && !evalResultNodeIds.has(edge.toNodeId))
             continue;
         if (edge.edgeKind === 'derived_from' || edge.edgeKind === 'evaluates' || edge.edgeKind === 'passes' || edge.edgeKind === 'fails' || edge.edgeKind === 'diagnoses') {
             addEdge(edge);
         }
     }
+    for (const edge of graph.edges) {
+        if (edge.edgeKind !== 'contains')
+            continue;
+        const from = nodesById.get(edge.fromNodeId);
+        const to = nodesById.get(edge.toNodeId);
+        if (from?.nodeKind !== 'sample' || to?.nodeKind !== 'assertion' || !projectedNodeIds.has(from.id))
+            continue;
+        addEdge(edge);
+        if (from.stableKey)
+            parentSampleStableKeyByNodeId.set(to.id, from.stableKey);
+    }
+    const sampleStableKeyByEvalResultId = new Map();
+    for (const edge of graph.edges) {
+        if (edge.edgeKind !== 'evaluates' || !evalResultNodeIds.has(edge.fromNodeId))
+            continue;
+        const sample = nodesById.get(edge.toNodeId);
+        if (sample?.nodeKind === 'sample' && sample.stableKey) {
+            sampleStableKeyByEvalResultId.set(edge.fromNodeId, sample.stableKey);
+        }
+    }
+    for (const edge of graph.edges) {
+        if (edge.edgeKind !== 'diagnoses')
+            continue;
+        const diagnostic = nodesById.get(edge.fromNodeId);
+        const sampleStableKey = sampleStableKeyByEvalResultId.get(edge.toNodeId);
+        if (diagnostic?.nodeKind === 'diagnostic' && sampleStableKey) {
+            parentSampleStableKeyByNodeId.set(diagnostic.id, sampleStableKey);
+        }
+    }
     const declaredCoverageStableKeys = new Set();
     const declaredCoverageEdges = [];
     let coverageEdges = 0;
@@ -581,7 +628,17 @@ function projectEvalStage(graph, path, entry) {
             : sourceNode.nodeKind === 'assertion'
                 ? assertionStatusByNodeId.get(sourceNode.id)
                 : undefined;
-        return status ? { ...node, status } : node;
+        const parentSampleStableKey = parentSampleStableKeyByNodeId.get(sourceNode.id)
+            ?? (sourceNode.nodeKind === 'assertion'
+                ? graph.nodes.find((candidate) => candidate.nodeKind === 'sample'
+                    && candidate.stableKey
+                    && sourceNode.stableKey?.startsWith(`${candidate.stableKey}:assertion:`))?.stableKey
+                : undefined);
+        return {
+            ...node,
+            ...(status ? { status } : {}),
+            ...(parentSampleStableKey ? { parentSampleStableKey } : {}),
+        };
     });
     return {
         stage: {
@@ -648,7 +705,7 @@ function graphSnapshotForEntry(entry, graphs) {
 /** 扫 doctorsDir/*.report.json,按 skill 名分桶,**返回该 skill 的所有历史 snapshot**(asc 时序)。
  *  renderer 用最后一项做"当前",前面项画 sparkline。 */
 function scanDoctorReports(dir) {
-    const out = {};
+    const out = Object.create(null);
     migrateLegacyReportFiles(dir, 'doctor');
     if (!existsSync(dir))
         return out;
@@ -656,19 +713,13 @@ function scanDoctorReports(dir) {
         if (!isReportFileName(file))
             continue;
         try {
-            const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            const kind = data?.kind === 'doctor' ? data.kind : null;
-            if (!kind || !Array.isArray(data.skills))
+            const data = parseDoctorReport(JSON.parse(readFileSync(join(dir, file), 'utf-8')));
+            if (!data)
                 continue;
-            const ts = data.timestamp;
             for (const sr of data.skills) {
-                const passN = sr.results.filter((r) => r.status === 'pass').length;
-                const warnN = sr.results.filter((r) => r.status === 'warn').length;
-                const failN = sr.results.filter((r) => r.status === 'fail').length;
-                const snap = {
-                    reportId: data.id, timestamp: ts, status: sr.status,
-                    passCount: passN, warnCount: warnN, failCount: failN, results: sr.results,
-                };
+                const snap = doctorSnapshot(data, sr.skillName);
+                if (!snap)
+                    continue;
                 if (!out[sr.skillName])
                     out[sr.skillName] = [];
                 out[sr.skillName].push(snap);
@@ -680,6 +731,20 @@ function scanDoctorReports(dir) {
         list.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
     return out;
 }
+function doctorSnapshot(report, skillName) {
+    const skill = report.skills.find((entry) => entry.skillName === skillName);
+    if (!skill)
+        return null;
+    return {
+        reportId: report.id,
+        timestamp: report.timestamp,
+        status: skill.status,
+        passCount: skill.results.filter((result) => result.status === 'pass').length,
+        warnCount: skill.results.filter((result) => result.status === 'warn').length,
+        failCount: skill.results.filter((result) => result.status === 'fail').length,
+        results: skill.results,
+    };
+}
 export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDir = DEFAULT_OBSERVATIONS_DIR, opts = {}) {
     const includeObserveCards = opts.includeObserveCards ?? false;
     const includeDoctorCards = opts.includeDoctorCards ?? false;
@@ -696,7 +761,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
         return _indexCache.result;
     }
     // ── eval 聚合(历史 list)─────────────────────────────────
-    const evalBy = {};
+    const evalBy = Object.create(null);
     for (const r of reports) {
         if (r.kind !== 'evaluation')
             continue;
@@ -716,7 +781,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     for (const list of Object.values(evalBy))
         list.sort((a, b) => evalSnapshotSortKey(a).localeCompare(evalSnapshotSortKey(b)));
     // ── observe 聚合(历史 list)──────────────────────────────
-    const observeBy = {};
+    const observeBy = Object.create(null);
     migrateLegacyReportFiles(analysesDir, 'observe-health');
     if (existsSync(analysesDir)) {
         for (const file of readdirSync(analysesDir)) {
@@ -724,8 +789,8 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
             if (!id)
                 continue;
             try {
-                const data = JSON.parse(readFileSync(join(analysesDir, file), 'utf-8'));
-                if (!data?.bySkill || !data.meta)
+                const data = parseSkillHealthReport(JSON.parse(readFileSync(join(analysesDir, file), 'utf-8')));
+                if (!data)
                     continue;
                 const generatedAt = data.meta.generatedAt;
                 for (const [skill, h] of Object.entries(data.bySkill)) {
@@ -733,8 +798,13 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
                         analysisId: id, generatedAt,
                         healthBand: bandFromObserveHealth(h),
                         failureRate: h.toolFailureRate,
+                        toolCallCount: h.toolCallCount,
+                        toolResolvedCount: h.toolResolvedCount,
+                        toolCancelledCount: h.toolCancelledCount,
+                        toolUnknownCount: h.toolUnknownCount,
                         segmentCount: h.segmentCount,
                         gapRate: h.gap?.weightedGapRate ?? 0,
+                        stability: normalizedObserveStability(h),
                         // Legacy reports (pre-confidence) fall back to deriving from segmentCount.
                         confidence: h.confidence ?? confidenceOf(h.segmentCount),
                     };
@@ -750,14 +820,27 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // 仅机器级模式合并;固定 --analyses-dir / --global 时 includeObserveCards=false,只看该目录(逃生舱语义)。
     if (includeObserveCards) {
         for (const card of listLiveObserveCards()) {
-            for (const [skill, h] of Object.entries(card.bySkill)) {
+            let report = null;
+            try {
+                report = parseSkillHealthReport(JSON.parse(readFileSync(card.path, 'utf-8')));
+            }
+            catch {
+                // Scratch cards only discover canonical reports.
+            }
+            if (!report)
+                continue;
+            for (const [skill, h] of Object.entries(report.bySkill)) {
                 const list = (observeBy[skill] ??= []);
                 if (list.some((s) => s.analysisId === card.id))
                     continue;
                 list.push({
-                    analysisId: card.id, generatedAt: card.meta.generatedAt,
-                    healthBand: bandFromObserveHealth(h), failureRate: h.toolFailureRate, segmentCount: h.segmentCount,
-                    gapRate: h.gap?.weightedGapRate ?? 0, confidence: h.confidence ?? confidenceOf(h.segmentCount),
+                    analysisId: card.id, generatedAt: report.meta.generatedAt,
+                    healthBand: bandFromObserveHealth(h), failureRate: h.toolFailureRate,
+                    toolCallCount: h.toolCallCount, toolResolvedCount: h.toolResolvedCount,
+                    toolCancelledCount: h.toolCancelledCount,
+                    toolUnknownCount: h.toolUnknownCount, segmentCount: h.segmentCount,
+                    gapRate: h.gap?.weightedGapRate ?? 0, stability: normalizedObserveStability(h),
+                    confidence: confidenceOf(h.segmentCount),
                 });
             }
         }
@@ -770,8 +853,19 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // 仅机器级模式合并;固定 --doctors-dir / --global 时 includeDoctorCards=false,只看该目录(逃生舱语义)。
     if (includeDoctorCards) {
         for (const card of listLiveDoctorCards()) {
-            const { skillName, snap } = cardToDoctorSnapshot(card);
-            const list = (doctorBy[skillName] ??= []);
+            let report = null;
+            try {
+                report = parseDoctorReport(JSON.parse(readFileSync(card.path, 'utf-8')));
+            }
+            catch {
+                // Scratch cards only discover canonical reports.
+            }
+            if (!report || report.id !== card.reportId)
+                continue;
+            const snap = doctorSnapshot(report, card.skillName);
+            if (!snap)
+                continue;
+            const list = (doctorBy[card.skillName] ??= []);
             if (!list.some((s) => s.reportId === snap.reportId))
                 list.push(snap);
         }
@@ -816,7 +910,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     for (const ent of entries) {
         const evalReport = ent.eval ? reports.find((r) => r.id === ent.eval.reportId && r.kind === 'evaluation') : undefined;
         insightsBySkill.set(ent.skillName, detectInsights(ent, evalReport ?? null, {
-            diagnostics: diagnosisBundle.bySkill[ent.skillName] ?? [],
+            diagnostics: ownRecordValue(diagnosisBundle.bySkill, ent.skillName) ?? [],
         }));
     }
     // 跨层口径统一:三大 snapshot(doctor / eval / observe)都空但 Diagnosis / Insight 投影出

package/dist/server/skill-insights.js

@@ -1,4 +1,5 @@
 import { isActiveDiagnosisLifecycle } from '../diagnosis/types.js';
+import { toolCallStatus } from '../shared/tool-call-status.js';
 /** Resolve which variant in `report` 是这个 entry / insight 关注的。
  *  优先用调用方传的 `preferred`(entry.eval?.variantName);找不到再 fallback 到第一个非 baseline。
  *  这避免 multi-treatment 报告里所有 detector 都默认拿第一个 treatment 的数据,导致
@@ -23,7 +24,11 @@ function summarizeToolCall(tc) {
         else if (typeof inp.query === 'string')
             arg = inp.query.slice(0, 50);
     }
-    const status = tc.success ? '' : ' [失败]';
+    const resultStatus = toolCallStatus(tc);
+    const status = resultStatus === 'failure'
+        ? ' [失败]'
+        : resultStatus === 'cancelled' ? ' [取消]'
+            : resultStatus === 'unknown' ? ' [状态未知]' : '';
     return arg ? `${tool}: ${arg}${status}` : `${tool}${status}`;
 }
 function getFailedSamples(report, variant) {
@@ -91,6 +96,32 @@ function underpoweredCaveat(observe) {
         message: `样本量仅 ${observe.segmentCount} 段(underpowered) — 以下为低置信参考信号,需累积更多真实使用 trace 才能下结论`,
     };
 }
+function capByToolOutcomeConfidence(severity, observe) {
+    const resolved = observe.toolResolvedCount;
+    if (resolved === undefined)
+        return severity;
+    const comparable = Math.max(0, resolved - (observe.toolCancelledCount ?? 0));
+    if (comparable < 5)
+        return 'low';
+    if (comparable < 20 && severity === 'high')
+        return 'medium';
+    return severity;
+}
+function toolOutcomeCaveat(observe) {
+    const resolved = observe.toolResolvedCount;
+    if (resolved === undefined)
+        return null;
+    const cancelled = observe.toolCancelledCount ?? 0;
+    const comparable = Math.max(0, resolved - cancelled);
+    if (comparable >= 20)
+        return null;
+    const unknown = observe.toolUnknownCount ?? Math.max(0, (observe.toolCallCount ?? resolved) - resolved);
+    return {
+        perspective: 'observe',
+        status: 'silent',
+        message: `仅 ${comparable} 次工具结果可比较${cancelled > 0 ? `；另有 ${cancelled} 次取消` : ''}${unknown > 0 ? `；另有 ${unknown} 次状态未知` : ''}。失败率的结果覆盖度不足，需积累更多可比较调用`,
+    };
+}
 function pickIllustrations(samples, n = 2) {
     return samples.slice(0, n).map((s) => ({
         sampleId: s.sampleId,
@@ -396,8 +427,16 @@ function detectProductionInstability(doctor, observe) {
         return null;
     const depRule = doctor?.results.find((r) => r.ruleId === 'dependencies_present'
         && (r.status === 'warn' || r.status === 'fail'));
-    const severity = capByObserveConfidence('high', observe);
-    const caveat = underpoweredCaveat(observe);
+    const severity = capByToolOutcomeConfidence(capByObserveConfidence('high', observe), observe);
+    const caveats = [
+        underpoweredCaveat(observe),
+        toolOutcomeCaveat(observe),
+    ].filter((value) => value !== null);
+    const resolvedOutcomeCount = observe.toolResolvedCount
+        ?? observe.toolCallCount
+        ?? observe.segmentCount;
+    const comparableOutcomeCount = Math.max(0, resolvedOutcomeCount - (observe.toolCancelledCount ?? 0));
+    const failureCount = Math.round(comparableOutcomeCount * observe.failureRate);
     return {
         id: 'production-instability',
         category: 'production-instability',
@@ -405,7 +444,7 @@ function detectProductionInstability(doctor, observe) {
         title: `生产环境跑这个 skill 时,工具失败率 ${(observe.failureRate * 100).toFixed(0)}%`,
         description: '真实用户用这个 skill,LLM 调出去的工具经常报错。可能是凭证/网络/上游 SLA 问题,也可能是 skill 教错了用什么工具/参数。',
         severity,
-        affectedCount: Math.round(observe.segmentCount * observe.failureRate),
+        affectedCount: failureCount,
         stageRefs: {
             observeRefs: ['high-failure-rate'],
             ...(depRule ? { doctorRuleIds: ['dependencies_present'] } : {}),
@@ -427,7 +466,7 @@ function detectProductionInstability(doctor, observe) {
                         ? 'doctor 没警告依赖,失败可能在 CLI/凭证/上游 API 层(skill 自身可能没错)'
                         : '没跑 doctor,无法对照',
                 },
-            ...(caveat ? [caveat] : []),
+            ...caveats,
         ],
         recommendations: [
             {

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

@@ -0,0 +1,3 @@
+import type { ArtifactGraphDocument } from '../types/index.js';
+/** Validate a complete graph, including graph identities and referential integrity. */
+export declare function parseArtifactGraphDocument(value: unknown): ArtifactGraphDocument | null;