oh-my-knowledge 0.47.0 → 0.49.0

package/dist/observability/problem-patterns.js

@@ -196,12 +196,14 @@ function evidenceRefFromEvent(event) {
     return {
         id: event.id,
         kind: event.kind,
+        traceId: event.traceId,
         sourceTrace: event.sourceTrace,
         sessionId: event.sessionId,
         messageIndex: event.messageIndex,
         logicalMessageIndex: event.logicalMessageIndex ?? event.messageIndex,
         sourceLineIndex: event.sourceLineIndex ?? event.messageIndex,
         messageUuid: event.messageUuid,
+        callInstanceId: event.callInstanceId,
         toolUseId: event.toolUseId,
         timestamp: event.timestamp,
         role: event.role,

package/dist/observability/review-state.d.ts

@@ -1,17 +1,23 @@
 import type { ObservationMetricKey, ObservationMetricScope, ObservationReviewState, ObservationReviewStateEntry, ObservationReviewStateUpdate, ObservationReviewTargetType, ObservationReviewVerdict } from '../types/index.js';
 export type { ObservationMetricKey, ObservationMetricScope, ObservationReviewState, ObservationReviewStateEntry, ObservationReviewStateUpdate, ObservationReviewTargetType, ObservationReviewVerdict, };
+export declare class ObservationReviewStateValidationError extends Error {
+    readonly name = "ObservationReviewStateValidationError";
+}
 export declare function observationReviewStateKey(targetType: ObservationReviewTargetType, targetId: string): string;
 export declare function observationMetricScopeFor(metricKey: ObservationMetricKey): ObservationMetricScope;
 export declare function observationMetricAnnotationTargetId(ref: {
     id?: string;
+    traceId?: string;
     sourceTrace?: string;
     sessionId?: string;
     messageIndex?: number;
     messageUuid?: string;
+    callInstanceId?: string;
     toolUseId?: string;
     metricScopeId?: string;
 }, metricKey: ObservationMetricKey): string;
 export declare function observationMetricAnnotationVerdict(state: ObservationReviewState | undefined, ref: Parameters<typeof observationMetricAnnotationTargetId>[0], metricKey: ObservationMetricKey): 'confirmed' | 'rejected' | undefined;
+export declare function observationMetricAnnotationEntry(state: ObservationReviewState | undefined, ref: Parameters<typeof observationMetricAnnotationTargetId>[0], metricKey: ObservationMetricKey): ObservationReviewStateEntry | undefined;
 export declare function observationReviewStatePath(observationsDir: string): string;
 export declare function emptyObservationReviewState(now?: string): ObservationReviewState;
 export declare function loadObservationReviewState(observationsDir: string): ObservationReviewState;

package/dist/observability/review-state.js

@@ -1,6 +1,12 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, } from 'node:fs';
 import { join } from 'node:path';
+import { writeJsonFileAtomic } from '../shared/atomic-json.js';
+import { withFileLock } from '../shared/file-lock.js';
+import { normalizeRfc3339Timestamp } from '../shared/timestamp.js';
+export class ObservationReviewStateValidationError extends Error {
+    name = 'ObservationReviewStateValidationError';
+}
 export function observationReviewStateKey(targetType, targetId) {
     return `${targetType}:${targetId}`;
 }
@@ -14,36 +20,69 @@ export function observationMetricScopeFor(metricKey) {
         : 'message';
 }
 export function observationMetricAnnotationTargetId(ref, metricKey) {
-    const hasStableTraceRef = Boolean(ref.sourceTrace || ref.sessionId || ref.messageIndex !== undefined || ref.messageUuid || ref.toolUseId);
+    const hasStableTraceRef = Boolean(ref.traceId
+        || ref.sourceTrace
+        || ref.sessionId
+        || ref.messageIndex !== undefined
+        || ref.messageUuid
+        || ref.callInstanceId
+        || ref.toolUseId);
     const scope = observationMetricScopeFor(metricKey);
     const stable = [
         metricKey,
         ...(scope === 'skill_segment' ? [scope, ref.metricScopeId ?? ''] : []),
+        ref.traceId ?? '',
         ref.sourceTrace ?? '',
         ref.sessionId ?? '',
         ref.messageIndex === undefined ? '' : String(ref.messageIndex),
         ref.messageUuid ?? '',
+        ref.callInstanceId ?? '',
         ref.toolUseId ?? '',
         hasStableTraceRef ? '' : ref.id ?? '',
     ].join('\u0000');
     return `metric:${metricKey}:${createHash('sha256').update(stable).digest('hex').slice(0, 16)}`;
 }
 export function observationMetricAnnotationVerdict(state, ref, metricKey) {
+    const entry = observationMetricAnnotationEntry(state, ref, metricKey);
+    return entry?.verdict === 'confirmed' || entry?.verdict === 'rejected'
+        ? entry.verdict
+        : undefined;
+}
+export function observationMetricAnnotationEntry(state, ref, metricKey) {
     if (!state)
         return undefined;
-    const targetId = observationMetricAnnotationTargetId(ref, metricKey);
-    const entry = state.entries[observationReviewStateKey('evidence_metric', targetId)];
-    return entry?.verdict === 'confirmed' || entry?.verdict === 'rejected' ? entry.verdict : undefined;
+    const candidates = [
+        ref,
+        ...(ref.callInstanceId ? [{ ...ref, callInstanceId: undefined }] : []),
+        ...(ref.traceId ? [{ ...ref, traceId: undefined }] : []),
+        ...(ref.traceId && ref.callInstanceId
+            ? [{ ...ref, traceId: undefined, callInstanceId: undefined }]
+            : []),
+    ];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        const targetId = observationMetricAnnotationTargetId(candidate, metricKey);
+        if (seen.has(targetId))
+            continue;
+        seen.add(targetId);
+        const entry = state.entries[observationReviewStateKey('evidence_metric', targetId)];
+        if (entry)
+            return entry;
+    }
+    return undefined;
 }
 export function observationReviewStatePath(observationsDir) {
     return join(observationsDir, 'review-state.json');
 }
 const OBSERVATION_REVIEW_STATE_SCHEMA_VERSION = 2;
 export function emptyObservationReviewState(now = new Date().toISOString()) {
+    const updatedAt = normalizedTimestamp(now);
+    if (!updatedAt)
+        throw new ObservationReviewStateValidationError('invalid updatedAt');
     return {
         kind: 'observe-review-state',
         schemaVersion: OBSERVATION_REVIEW_STATE_SCHEMA_VERSION,
-        updatedAt: now,
+        updatedAt,
         entries: {},
     };
 }
@@ -51,39 +90,57 @@ export function loadObservationReviewState(observationsDir) {
     const path = observationReviewStatePath(observationsDir);
     if (!existsSync(path))
         return emptyObservationReviewState();
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
-        return normalizeObservationReviewState(parsed) ?? emptyObservationReviewState();
+        parsed = JSON.parse(readFileSync(path, 'utf-8'));
     }
-    catch {
-        return emptyObservationReviewState();
+    catch (cause) {
+        throw new Error(`无法读取观测复核状态：${path}`, { cause });
     }
+    const normalized = normalizeObservationReviewState(parsed);
+    if (!normalized)
+        throw new Error(`观测复核状态格式无效：${path}`);
+    return normalized;
 }
-export function updateObservationReviewState(observationsDir, update, now = new Date().toISOString()) {
+export function updateObservationReviewState(observationsDir, update, now) {
     assertReviewStateUpdate(update);
-    const state = loadObservationReviewState(observationsDir);
-    const key = observationReviewStateKey(update.targetType, update.targetId);
-    state.entries[key] = {
-        targetType: update.targetType,
-        targetId: update.targetId,
-        verdict: update.verdict,
-        reviewedAt: now,
-        ...(update.note ? { note: update.note.slice(0, 500) } : {}),
-        ...(update.reason ? { reason: update.reason.slice(0, 500) } : {}),
-        ...(update.metricKey ? { metricKey: update.metricKey } : {}),
-        ...(update.metricKey ? { metricScope: update.metricScope ?? observationMetricScopeFor(update.metricKey) } : {}),
-        ...(update.metricScopeId ? { metricScopeId: update.metricScopeId.slice(0, 200) } : {}),
-        ...(update.sourceTrace ? { sourceTrace: update.sourceTrace } : {}),
-        ...(update.sessionId ? { sessionId: update.sessionId } : {}),
-        ...(update.messageIndex !== undefined ? { messageIndex: update.messageIndex } : {}),
-        ...(update.messageUuid ? { messageUuid: update.messageUuid } : {}),
-        ...(update.toolUseId ? { toolUseId: update.toolUseId } : {}),
-        ...(update.snippet ? { snippet: update.snippet.slice(0, 500) } : {}),
-    };
-    state.updatedAt = now;
-    mkdirSync(observationsDir, { recursive: true });
-    writeFileSync(observationReviewStatePath(observationsDir), JSON.stringify(state, null, 2));
-    return state;
+    const path = observationReviewStatePath(observationsDir);
+    return withFileLock(`${path}.lock`, () => {
+        const reviewedAt = normalizedTimestamp(now ?? new Date().toISOString());
+        if (!reviewedAt) {
+            throw new ObservationReviewStateValidationError('invalid reviewedAt');
+        }
+        const hadPersistedState = existsSync(path);
+        const state = loadObservationReviewState(observationsDir);
+        if (hadPersistedState && reviewedAt < state.updatedAt) {
+            throw new ObservationReviewStateValidationError('reviewedAt cannot precede state updatedAt');
+        }
+        const key = observationReviewStateKey(update.targetType, update.targetId);
+        state.entries[key] = {
+            targetType: update.targetType,
+            targetId: update.targetId,
+            verdict: update.verdict,
+            reviewedAt,
+            ...(update.note ? { note: update.note.slice(0, 500) } : {}),
+            ...(update.reason ? { reason: update.reason.slice(0, 500) } : {}),
+            ...(update.metricKey ? { metricKey: update.metricKey } : {}),
+            ...(update.metricKey ? {
+                metricScope: update.metricScope ?? observationMetricScopeFor(update.metricKey),
+            } : {}),
+            ...(update.metricScopeId ? { metricScopeId: update.metricScopeId.slice(0, 200) } : {}),
+            ...(update.traceId ? { traceId: update.traceId } : {}),
+            ...(update.sourceTrace ? { sourceTrace: update.sourceTrace } : {}),
+            ...(update.sessionId ? { sessionId: update.sessionId } : {}),
+            ...(update.messageIndex !== undefined ? { messageIndex: update.messageIndex } : {}),
+            ...(update.messageUuid ? { messageUuid: update.messageUuid } : {}),
+            ...(update.callInstanceId ? { callInstanceId: update.callInstanceId } : {}),
+            ...(update.toolUseId ? { toolUseId: update.toolUseId } : {}),
+            ...(update.snippet ? { snippet: update.snippet.slice(0, 500) } : {}),
+        };
+        state.updatedAt = reviewedAt;
+        writeObservationReviewState(observationsDir, state);
+        return state;
+    }, { label: 'observation review state' });
 }
 function normalizeObservationReviewState(value) {
     if (!value || typeof value !== 'object')
@@ -94,50 +151,165 @@ function normalizeObservationReviewState(value) {
         return null;
     if (parsed.schemaVersion !== OBSERVATION_REVIEW_STATE_SCHEMA_VERSION)
         return null;
-    if (!parsed.entries || typeof parsed.entries !== 'object')
+    if (!parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries))
+        return null;
+    const updatedAt = normalizedTimestamp(parsed.updatedAt);
+    if (!updatedAt)
+        return null;
+    const entries = {};
+    for (const [key, rawEntry] of Object.entries(parsed.entries)) {
+        const entry = normalizeReviewStateEntry(rawEntry);
+        if (!entry || key !== observationReviewStateKey(entry.targetType, entry.targetId))
+            return null;
+        entries[key] = entry;
+    }
+    if (Object.values(entries).some((entry) => entry.reviewedAt > updatedAt))
         return null;
     return {
         kind: 'observe-review-state',
         schemaVersion: OBSERVATION_REVIEW_STATE_SCHEMA_VERSION,
-        updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
-        entries: Object.fromEntries(Object.entries(parsed.entries).filter(([, entry]) => isReviewStateEntry(entry))),
+        updatedAt,
+        entries,
     };
 }
-export function deleteObservationReviewState(observationsDir, targetType, targetId, now = new Date().toISOString()) {
+export function deleteObservationReviewState(observationsDir, targetType, targetId, now) {
     if (!isReviewTargetType(targetType))
-        throw new Error('invalid review targetType');
+        throw new ObservationReviewStateValidationError('invalid review targetType');
     if (typeof targetId !== 'string' || targetId.trim() === '')
-        throw new Error('invalid review targetId');
-    const state = loadObservationReviewState(observationsDir);
-    const key = observationReviewStateKey(targetType, targetId);
-    delete state.entries[key];
-    state.updatedAt = now;
-    mkdirSync(observationsDir, { recursive: true });
-    writeFileSync(observationReviewStatePath(observationsDir), JSON.stringify(state, null, 2));
-    return state;
+        throw new ObservationReviewStateValidationError('invalid review targetId');
+    const path = observationReviewStatePath(observationsDir);
+    return withFileLock(`${path}.lock`, () => {
+        const updatedAt = normalizedTimestamp(now ?? new Date().toISOString());
+        if (!updatedAt) {
+            throw new ObservationReviewStateValidationError('invalid updatedAt');
+        }
+        const hadPersistedState = existsSync(path);
+        const state = loadObservationReviewState(observationsDir);
+        if (hadPersistedState && updatedAt < state.updatedAt) {
+            throw new ObservationReviewStateValidationError('updatedAt cannot precede state updatedAt');
+        }
+        const key = observationReviewStateKey(targetType, targetId);
+        delete state.entries[key];
+        state.updatedAt = updatedAt;
+        writeObservationReviewState(observationsDir, state);
+        return state;
+    }, { label: 'observation review state' });
 }
 function assertReviewStateUpdate(value) {
     if (!isReviewTargetType(value.targetType))
-        throw new Error('invalid review targetType');
+        throw new ObservationReviewStateValidationError('invalid review targetType');
     if (typeof value.targetId !== 'string' || value.targetId.trim() === '')
-        throw new Error('invalid review targetId');
+        throw new ObservationReviewStateValidationError('invalid review targetId');
     if (!isReviewVerdict(value.verdict))
-        throw new Error('invalid review verdict');
-    if (value.targetType === 'evidence_metric' && !isObservationMetricKey(value.metricKey))
-        throw new Error('invalid metricKey');
-    if (value.metricScope !== undefined && !isObservationMetricScope(value.metricScope))
-        throw new Error('invalid metricScope');
-    if ((value.verdict === 'confirmed' || value.verdict === 'rejected') && value.targetType !== 'evidence_metric')
-        throw new Error('metric verdict requires evidence_metric targetType');
-}
-function isReviewStateEntry(value) {
+        throw new ObservationReviewStateValidationError('invalid review verdict');
+    const optionalStrings = [
+        value.note,
+        value.reason,
+        value.metricScopeId,
+        value.traceId,
+        value.sourceTrace,
+        value.sessionId,
+        value.messageUuid,
+        value.callInstanceId,
+        value.toolUseId,
+        value.snippet,
+    ];
+    if (!optionalStrings.every(optionalString))
+        throw new ObservationReviewStateValidationError('invalid review metadata');
+    if (value.messageIndex !== undefined
+        && (!Number.isSafeInteger(value.messageIndex) || value.messageIndex < 0))
+        throw new ObservationReviewStateValidationError('invalid messageIndex');
+    if (value.targetType === 'evidence_metric') {
+        if (!isObservationMetricKey(value.metricKey))
+            throw new ObservationReviewStateValidationError('invalid metricKey');
+        if (value.verdict !== 'confirmed' && value.verdict !== 'rejected') {
+            throw new ObservationReviewStateValidationError('evidence_metric requires confirmed or rejected verdict');
+        }
+        const expectedScope = observationMetricScopeFor(value.metricKey);
+        if (value.metricScope !== undefined && value.metricScope !== expectedScope) {
+            throw new ObservationReviewStateValidationError('metricScope does not match metricKey');
+        }
+    }
+    else {
+        if (value.verdict === 'confirmed' || value.verdict === 'rejected') {
+            throw new ObservationReviewStateValidationError('metric verdict requires evidence_metric targetType');
+        }
+        if (value.metricKey !== undefined || value.metricScope !== undefined || value.metricScopeId !== undefined) {
+            throw new ObservationReviewStateValidationError('metric metadata requires evidence_metric targetType');
+        }
+    }
+}
+function normalizeReviewStateEntry(value) {
     if (!value || typeof value !== 'object')
-        return false;
+        return null;
     const entry = value;
-    return isReviewTargetType(entry.targetType)
-        && typeof entry.targetId === 'string'
-        && isReviewVerdict(entry.verdict)
-        && typeof entry.reviewedAt === 'string';
+    const reviewedAt = normalizedTimestamp(entry.reviewedAt);
+    if (!isReviewTargetType(entry.targetType)
+        || typeof entry.targetId !== 'string'
+        || entry.targetId.trim() === ''
+        || !isReviewVerdict(entry.verdict)
+        || !reviewedAt
+        || !optionalString(entry.note)
+        || !optionalString(entry.reason)
+        || !optionalString(entry.metricScopeId)
+        || !optionalString(entry.traceId)
+        || !optionalString(entry.sourceTrace)
+        || !optionalString(entry.sessionId)
+        || !optionalString(entry.messageUuid)
+        || !optionalString(entry.callInstanceId)
+        || !optionalString(entry.toolUseId)
+        || !optionalString(entry.snippet)
+        || (entry.messageIndex !== undefined
+            && (!Number.isSafeInteger(entry.messageIndex) || entry.messageIndex < 0))
+        || (entry.metricKey !== undefined && !isObservationMetricKey(entry.metricKey))
+        || (entry.metricScope !== undefined && !isObservationMetricScope(entry.metricScope)))
+        return null;
+    if (entry.targetType === 'evidence_metric') {
+        if (!isObservationMetricKey(entry.metricKey)
+            || (entry.verdict !== 'confirmed' && entry.verdict !== 'rejected'))
+            return null;
+    }
+    else if (entry.verdict === 'confirmed'
+        || entry.verdict === 'rejected'
+        || entry.metricKey !== undefined
+        || entry.metricScope !== undefined
+        || entry.metricScopeId !== undefined) {
+        return null;
+    }
+    const metricScope = entry.metricKey
+        ? entry.metricScope ?? observationMetricScopeFor(entry.metricKey)
+        : undefined;
+    if (entry.metricKey
+        && metricScope !== observationMetricScopeFor(entry.metricKey))
+        return null;
+    return {
+        targetType: entry.targetType,
+        targetId: entry.targetId,
+        verdict: entry.verdict,
+        reviewedAt,
+        ...(entry.note !== undefined ? { note: entry.note } : {}),
+        ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+        ...(entry.metricKey !== undefined ? { metricKey: entry.metricKey, metricScope } : {}),
+        ...(entry.metricScopeId !== undefined ? { metricScopeId: entry.metricScopeId } : {}),
+        ...(entry.traceId !== undefined ? { traceId: entry.traceId } : {}),
+        ...(entry.sourceTrace !== undefined ? { sourceTrace: entry.sourceTrace } : {}),
+        ...(entry.sessionId !== undefined ? { sessionId: entry.sessionId } : {}),
+        ...(entry.messageIndex !== undefined ? { messageIndex: entry.messageIndex } : {}),
+        ...(entry.messageUuid !== undefined ? { messageUuid: entry.messageUuid } : {}),
+        ...(entry.callInstanceId !== undefined ? { callInstanceId: entry.callInstanceId } : {}),
+        ...(entry.toolUseId !== undefined ? { toolUseId: entry.toolUseId } : {}),
+        ...(entry.snippet !== undefined ? { snippet: entry.snippet } : {}),
+    };
+}
+function normalizedTimestamp(value) {
+    return normalizeRfc3339Timestamp(value) ?? null;
+}
+function optionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function writeObservationReviewState(observationsDir, state) {
+    const path = observationReviewStatePath(observationsDir);
+    writeJsonFileAtomic(path, state);
 }
 function isReviewTargetType(value) {
     return value === 'experience_session'

package/dist/observability/skill-chain-advisories.js

@@ -50,7 +50,7 @@ const ADVISORIES = {
         code: 'skill_md_not_found',
         shortLabel: '本地未找到 SKILL.md',
         message: '本地常见 skill 目录里没有这个 skill 的 SKILL.md，inbox 跑不了静态/运行时审计。如果你想看 LLM 健康度审计（触发边界 / 文档 / 依赖 / 安全等 7 维），可以试试 omk doctor；inbox 本身不依赖它。',
-        commandTemplate: 'omk doctor ~/.claude/skills/${skillName}/SKILL.md',
+        commandTemplate: 'omk doctor /path/to/${skillName}/SKILL.md',
     },
 };
 export function getSkillChainAdvisory(code) {

package/dist/observability/skill-chain.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { extractMarkdownStepWorkflows, validateSkillHardRules, validateSkillWorkflows, } from '../shared/hard-rules.js';
+import { incrementRecordCount } from '../shared/record-count.js';
 const MAX_SKILL_DEFINITION_CHARS = 12000;
 export function buildObservationSkillChains(skillNames, cwd = process.cwd(), experienceReports = []) {
     const uniqueSkillNames = Array.from(new Set(skillNames.filter(Boolean))).sort();
@@ -199,7 +200,7 @@ function runtimeEvidence(invocations) {
     const events = invocations.flatMap((invocation) => invocation.timeline ?? []);
     for (const invocation of invocations) {
         for (const [tool, count] of Object.entries(invocation.toolCounts ?? {})) {
-            toolCounts[tool] = (toolCounts[tool] ?? 0) + count;
+            incrementRecordCount(toolCounts, tool, count);
         }
     }
     return {
@@ -207,8 +208,14 @@ function runtimeEvidence(invocations) {
         toolCallCount: invocations.reduce((sum, invocation) => sum + invocation.indicators.toolCallCount, 0),
         toolFailureCount: invocations.reduce((sum, invocation) => sum + invocation.indicators.toolFailureCount, 0),
         events,
-        assistantToolUseIds: new Set(events
-            .filter((event) => event.kind === 'tool_use' && event.role === 'assistant' && event.toolUseId)
+        assistantCallInstanceIds: new Set(events
+            .filter((event) => event.kind === 'tool_use' && event.role === 'assistant' && event.callInstanceId)
+            .map((event) => event.callInstanceId)),
+        legacyAssistantToolUseIds: new Set(events
+            .filter((event) => event.kind === 'tool_use'
+            && event.role === 'assistant'
+            && !event.callInstanceId
+            && event.toolUseId)
             .map((event) => event.toolUseId)),
     };
 }
@@ -351,6 +358,7 @@ function eventToEvidencePackRef(event) {
         messageIndex: event.messageIndex,
         logicalMessageIndex: event.logicalMessageIndex,
         sourceLineIndex: event.sourceLineIndex,
+        callInstanceId: event.callInstanceId,
         toolUseId: event.toolUseId,
         timestamp: event.timestamp,
         role: event.role,
@@ -384,7 +392,12 @@ function isAssistantAuthoredUploadEvent(event, evidence, text) {
         return false;
     if (event.kind === 'tool_use' && event.role === 'assistant')
         return true;
-    if (event.kind === 'tool_result' && event.role === 'tool' && event.toolUseId && evidence.assistantToolUseIds.has(event.toolUseId))
+    if (event.kind === 'tool_result'
+        && event.role === 'tool'
+        && (event.callInstanceId
+            ? evidence.assistantCallInstanceIds.has(event.callInstanceId)
+            : Boolean(event.toolUseId)
+                && evidence.legacyAssistantToolUseIds.has(event.toolUseId)))
         return true;
     return false;
 }

package/dist/observability/skill-health-analyzer.d.ts

@@ -6,28 +6,33 @@
  * 定位是"真实使用 trace 的 skill 维度观察",不是通用 APM / 生产监控。
  *
  * 分析流水线:
- *   1. ccTracesToResultEntries(path) → segments + ResultEntry[]
+ *   1. tracesToResultEntries(path) → segments + ResultEntry[]
  *   2. 时间窗 / skill 白名单过滤
  *   3. 按 skill name (variant key) 分别 computeCoverage + computeGapReport
  *   4. 聚合 overall 指标 + 健康度色带
  */
 import { type CoverageReport } from '../analysis/coverage-analyzer.js';
-import type { GapReport } from '../types/index.js';
-import { type CcSession, type SkillSegment } from './trace-adapter.js';
+import type { GapReport, TraceIngestionSummary } from '../types/index.js';
+import { type CcSession, type TraceSession, type SkillSegment } from './trace-adapter.js';
 export interface SkillHealth {
     skillName: string;
     segmentCount: number;
     toolCallCount: number;
     toolFailureCount: number;
-    /** 失败率 = toolFailureCount / toolCallCount; toolCallCount=0 时为 0 */
+    toolCancelledCount?: number;
+    toolUnknownCount?: number;
+    toolResolvedCount?: number;
+    toolOutcomeCoverage?: number;
+    /** 失败率 = toolFailureCount / 可比较结果数；取消与未知状态不进入分母。 */
     toolFailureRate: number;
     /**
      * 执行稳定性标签。阈值:
      *  - very-unstable: failureRate >= 0.4 (gap 信号极可能是环境问题,不是真知识缺口)
      *  - unstable:      failureRate >= 0.2 (建议排查环境后再看 gap)
+     *  - unknown:       有工具调用,但没有可比较的成功 / 失败结果
      *  - stable:        否则
      */
-    stability: 'stable' | 'unstable' | 'very-unstable';
+    stability: 'stable' | 'unstable' | 'very-unstable' | 'unknown';
     /**
      * 统计可信度(按 segment 数)。守护「1 段 + 一次失败就判 red」的过度自信:
      *  - underpowered: segmentCount < 5  (样本太少,色带 / gap rate 不可信)
@@ -43,6 +48,8 @@ export interface SkillHealth {
         cacheReadTokens: number;
         cacheCreationTokens: number;
         totalTokens: number;
+        tokenObservedSegmentCount: number;
+        tokenCoverage: number;
         durationMs: number;
         numTurns: number;
         avgTokensPerSegment: number;
@@ -61,13 +68,21 @@ export interface SkillHealthReport {
         sessionCount: number;
         segmentCount: number;
         messageCount: number;
+        timestampedSegmentCount?: number;
+        timestampCoverage?: number;
+        excludedUntimestampedSegmentCount?: number;
         toolCallCount: number;
+        toolCancelledCount?: number;
+        toolUnknownCount?: number;
+        toolResolvedCount?: number;
+        toolOutcomeCoverage?: number;
         toolFailureRate: number;
         timeRange: {
             from: string;
             to: string;
         };
         generatedAt: string;
+        ingestion?: TraceIngestionSummary;
     };
     bySkill: Record<string, SkillHealth>;
     overall: {
@@ -89,15 +104,25 @@ export interface AnalyzeOptions {
  * #235 受管反哺时 observe CLI 用本函数逐 skill 算 band 传入 managed —— 阈值单一来源,managed 不复制。
  */
 export declare function healthBandOf(weightedGapRate: number): 'green' | 'yellow' | 'red';
+/**
+ * 按 per-skill 失败率判定执行稳定性。阈值见 SkillHealth.stability。
+ */
+export declare function toolStabilityOf(toolFailureRate: number, comparableToolCalls: number, totalToolCalls: number): SkillHealth['stability'];
 /** 统计可信度护栏:按 segment 数判 high / low / underpowered,守护「1 段就判 red」。
  *  导出供 renderer / CLI / server 给历史报告(缺 confidence 字段)做 segmentCount 兜底。 */
 export declare function confidenceOf(segmentCount: number): SkillHealth['confidence'];
 /**
- * 主入口:从 cc trace 目录生成 SkillHealthReport。
+ * 推断 KB root: 没传 --kb 时,取第一个 assistant record 的 cwd。
+ * 如果跨多个 cwd,取第一个并 warn。
+ */
+type HealthSession = TraceSession | CcSession;
+/**
+ * 主入口：从受支持的 trace 输入生成 SkillHealthReport。
  */
 export declare function computeSkillHealthReport(tracePath: string, opts?: AnalyzeOptions): SkillHealthReport;
 /**
  * 便利入口:直接从已准备好的 segments(跳过 loadCcSessions)算 report。
  * 用于测试 / 已手工组装过 segments 的场景。
  */
-export declare function computeSkillHealthFromSegments(segments: SkillSegment[], sessions: CcSession[], tracePath: string, opts?: AnalyzeOptions): SkillHealthReport;
+export declare function computeSkillHealthFromSegments(segments: SkillSegment[], sessions: HealthSession[], tracePath: string, opts?: AnalyzeOptions, ingestion?: TraceIngestionSummary): SkillHealthReport;
+export {};