oh-my-knowledge 0.37.0 → 0.38.0

package/dist/cli/lib/i18n-dict/help.js

@@ -1,13 +1,10 @@
 export const helpDict = {
     'cli.help.observe': {
         zh: `
-omk observe——分析真实 session trace，生成 skill 健康度日报
+omk observe——分析真实 session trace，生成 skill 健康度报告
 
 用法：
   omk observe <sessions-dir> [options]
-  omk observe ingest <sessions-dir> [options]
-  omk observe inbox [options]
-  omk observe show <inbox_id> [options]
 
 选项：
   --kb <path>                         知识库根路径（默认：从 trace cwd 推断）
@@ -15,27 +12,16 @@ omk observe——分析真实 session trace，生成 skill 健康度日报
   --from <iso>                        窗口起点，优先级高于 --last
   --to <iso>                          窗口终点，优先级高于 --last
   --skills <n1,n2,...>                只分析指定 skill
-  --output-dir <path>                 输出目录（默认：~/.oh-my-knowledge/analyses）
-
-Inbox:
-  ingest --output-dir <path>           写入 observe inbox 数据（默认：.omk/observations；读取时兜底到 ~/.oh-my-knowledge/observations）
-  inbox --input-dir <path>             读取 observe inbox 数据
-  inbox --limit <n>                    展示 top N（默认：20）
-  inbox --skill <name>                 只看指定 skill
-  inbox --explore <n>                  从最近 50 条 medium/low 问题里抽样查看长尾
-  inbox --include-noise                --explore 时显式包含 noise 桶
-  inbox --by-skill                     按 skill 输出资产看板
-  inbox --json                         输出 JSON
-  show <inbox_id> --input-dir <path>    查看单条 observation 的前后上下文
+  --output-dir <path>                 输出目录（默认：项目级 .omk/observe-health）
+  --global                            写全局 ~/.oh-my-knowledge/observe-health，而非项目 .omk/
+
+观测收件箱（observe inbox）是另一条线，见 omk observe inbox --help。
 `,
         en: `
 omk observe — analyze production session traces and produce skill health reports
 
 Usage:
   omk observe <sessions-dir> [options]
-  omk observe ingest <sessions-dir> [options]
-  omk observe inbox [options]
-  omk observe show <inbox_id> [options]
 
 Options:
   --kb <path>                         Knowledge base root (default: infer from trace cwd)
@@ -43,18 +29,10 @@ Options:
   --from <iso>                        Window start, overrides --last
   --to <iso>                          Window end, overrides --last
   --skills <n1,n2,...>                Only analyze selected skills
-  --output-dir <path>                 Output directory (default: ~/.oh-my-knowledge/analyses)
-
-Inbox:
-  ingest --output-dir <path>           Write observe inbox data (default: .omk/observations; read fallback: ~/.oh-my-knowledge/observations)
-  inbox --input-dir <path>             Read observe inbox data
-  inbox --limit <n>                    Show top N (default: 20)
-  inbox --skill <name>                 Only show one skill
-  inbox --explore <n>                  Sample long-tail issues from the latest 50 medium/low items
-  inbox --include-noise                Explicitly include the noise bucket with --explore
-  inbox --by-skill                     Print the skill-level asset board
-  inbox --json                         Print JSON
-  show <inbox_id> --input-dir <path>    Show context around one observation
+  --output-dir <path>                 Output directory (default: project-level .omk/observe-health)
+  --global                            Write to global ~/.oh-my-knowledge/observe-health instead of project .omk/
+
+The observe inbox is a separate line; see omk observe inbox --help.
 `,
     },
     'cli.help.observe_ingest': {
@@ -65,7 +43,7 @@ omk observe ingest — 读取真实 session trace，写入 observe inbox 数据
   omk observe ingest <sessions-dir-or-file> [options]
 
 选项：
-  --output-dir <path>                输出目录（默认：.omk/observations；读取时兜底到 ~/.oh-my-knowledge/observations）
+  --output-dir <path>                输出目录（默认：.omk/observe-inbox；读取时兜底到 ~/.oh-my-knowledge/observe-inbox）
 
 支持：
   Claude Code JSONL
@@ -78,7 +56,7 @@ Usage:
   omk observe ingest <sessions-dir-or-file> [options]
 
 Options:
-  --output-dir <path>                Output directory (default: .omk/observations; read fallback: ~/.oh-my-knowledge/observations)
+  --output-dir <path>                Output directory (default: .omk/observe-inbox; read fallback: ~/.oh-my-knowledge/observe-inbox)
 
 Supported:
   Claude Code JSONL
@@ -93,7 +71,7 @@ omk observe inbox — 查看已写入的 observe inbox 问题列表
   omk observe inbox [options]
 
 选项：
-  --input-dir <path>                 读取目录（默认：.omk/observations；兜底到 ~/.oh-my-knowledge/observations）
+  --input-dir <path>                 读取目录（默认：.omk/observe-inbox；兜底到 ~/.oh-my-knowledge/observe-inbox）
   --limit <n>                        展示 top N（默认：20）
   --skill <name>                     只看指定 skill
   --explore <n>                      从最近 50 条 medium/low 问题里抽样查看长尾
@@ -112,7 +90,7 @@ Usage:
   omk observe inbox [options]
 
 Options:
-  --input-dir <path>                 Input directory (default: .omk/observations; fallback: ~/.oh-my-knowledge/observations)
+  --input-dir <path>                 Input directory (default: .omk/observe-inbox; fallback: ~/.oh-my-knowledge/observe-inbox)
   --limit <n>                        Show top N (default: 20)
   --skill <name>                     Only show one skill
   --explore <n>                      Sample long-tail issues from the latest 50 medium/low items
@@ -133,7 +111,7 @@ omk observe show — 查看单条 observation 的原始上下文
   omk observe show <inbox_id> [options]
 
 选项：
-  --input-dir <path>                 读取目录（默认：.omk/observations；兜底到 ~/.oh-my-knowledge/observations）
+  --input-dir <path>                 读取目录（默认：.omk/observe-inbox；兜底到 ~/.oh-my-knowledge/observe-inbox）
 `,
         en: `
 omk observe show — inspect the raw context around one observation
@@ -142,7 +120,7 @@ Usage:
   omk observe show <inbox_id> [options]
 
 Options:
-  --input-dir <path>                 Input directory (default: .omk/observations; fallback: ~/.oh-my-knowledge/observations)
+  --input-dir <path>                 Input directory (default: .omk/observe-inbox; fallback: ~/.oh-my-knowledge/observe-inbox)
 `,
     },
     'cli.help.evolve': {
@@ -243,16 +221,18 @@ omk studio——打开本地知识工作台
 选项：
   --port <n>                          本地服务端口（默认：7799）
   --host <host>                       监听地址（默认：127.0.0.1；局域网访问可用 0.0.0.0）
-  --reports-dir <path>                报告目录（默认：~/.oh-my-knowledge/reports）
-  --analyses-dir <path>               观测分析目录
-  --observations-dir <path>           observe inbox 数据目录（默认：.omk/observations）
+  --reports-dir <path>                只看指定报告目录（默认机器级聚合：当前项目 + 全局 + 别项目索引）
+  --analyses-dir <path>               观测健康报告目录（默认：项目级 .omk/observe-health，空则全局兜底）
+  --doctors-dir <path>                体检报告目录（默认：项目级 .omk/doctors，空则全局兜底）
+  --observations-dir <path>           observe inbox 数据目录（默认：.omk/observe-inbox）
+  --global                            只看全局 reports / observe-health / doctors 目录（~/.oh-my-knowledge/*），而非机器级聚合 / 项目优先；managed / observe-inbox 不受影响
   --no-open                           只启动服务，不自动打开浏览器
   --dev                               开发模式：文件变化时自动重启
 
 示例：
   omk studio
   omk studio --port 7798
-  omk studio --host 0.0.0.0 --observations-dir .omk/observations
+  omk studio --host 0.0.0.0 --observations-dir .omk/observe-inbox
   omk studio --no-open
 `,
         en: `
@@ -264,16 +244,18 @@ Usage:
 Options:
   --port <n>                          Local server port (default: 7799)
   --host <host>                       Listen address (default: 127.0.0.1; use 0.0.0.0 for LAN access)
-  --reports-dir <path>                Reports directory (default: ~/.oh-my-knowledge/reports)
-  --analyses-dir <path>               Observation analyses directory
-  --observations-dir <path>           Observe inbox data directory (default: .omk/observations)
+  --reports-dir <path>                View only this reports dir (default aggregates machine-wide: current project + global + other projects via index)
+  --analyses-dir <path>               Observe-health reports dir (default: project .omk/observe-health, falls back to global)
+  --doctors-dir <path>                Doctor reports dir (default: project .omk/doctors, falls back to global)
+  --observations-dir <path>           Observe inbox data directory (default: .omk/observe-inbox)
+  --global                            View only global reports / observe-health / doctors dirs (~/.oh-my-knowledge/*) instead of machine-wide / project-first; does not affect managed / observe-inbox
   --no-open                           Start the server without opening a browser
   --dev                               Dev mode: restart on file changes
 
 Examples:
   omk studio
   omk studio --port 7798
-  omk studio --host 0.0.0.0 --observations-dir .omk/observations
+  omk studio --host 0.0.0.0 --observations-dir .omk/observe-inbox
   omk studio --no-open
 `,
     },

package/dist/cli/lib/i18n-dict/init.js

@@ -1,7 +1,7 @@
 export const initDict = {
     'cli.init.scaffolded': {
-        zh: '已初始化测评项目: {dir}',
-        en: 'Eval project scaffolded at: {dir}',
+        zh: '已初始化 omk 项目: {dir}',
+        en: 'omk project initialized at: {dir}',
     },
     'cli.init.next_steps_title': {
         zh: '下一步:',

package/dist/cli/lib/parse-run-config.d.ts

@@ -83,7 +83,6 @@ export interface ParseRunConfigResult {
      *  (e.g. repeat / judgeRepeat / bootstrap — handled in `commands/eval-runner.ts` for input validation). */
     evalConfig: EvalConfig | null;
 }
-export declare const DEFAULT_REPORTS_DIR: string;
 /**
  * 接 typed flags(来自 oclif Command.parse() 输出)。oclif strict 模式已经在
  * 上游对未知 flag 拦截 exit 2,这里不再 parseArgs。eval-runner 等业务 caller

package/dist/cli/lib/parse-run-config.js

@@ -17,15 +17,14 @@
  * `cli ?? evalConfig ?? default`,刻意不再细拆,否则只是把一长串 ?? 散到多文件,
  * 反而失去「精度链一目了然」的可读性。
  */
-import { resolve, join } from 'node:path';
-import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
 import { loadEvalConfig } from '../../inputs/eval-config.js';
 import { DEFAULT_MODEL } from '../../executors/shared.js';
 import { parseJudgeModelsArgOrExit } from './parse-run-config/judge-models.js';
 import { discoverSamplesPath } from './parse-run-config/samples-discovery.js';
 import { resolveVariantSpecs } from './parse-run-config/variant-resolution.js';
 export { parseJudgeModelsArg, parseJudgeModelsArgOrExit } from './parse-run-config/judge-models.js';
-export const DEFAULT_REPORTS_DIR = join(homedir(), '.oh-my-knowledge', 'reports');
 /**
  * 接 typed flags(来自 oclif Command.parse() 输出)。oclif strict 模式已经在
  * 上游对未知 flag 拦截 exit 2,这里不再 parseArgs。eval-runner 等业务 caller
@@ -72,7 +71,10 @@ export function parseRunConfig(values) {
     const judgeModels = parsedJudges
         ?? evalConfig?.judgeModels
         ?? [{ executor: executorName, model: 'haiku' }];
-    const outputDir = resolve(values['output-dir'] ?? DEFAULT_REPORTS_DIR);
+    // 报告默认落项目 `.omk/reports`(绑用例集,construct validity);--global 写全局;--output-dir 最高优先。
+    // 同 observe / doctor 写入侧口径。读取侧(studio / resume / gold-compare / 复用)走 overlay 项目→全局兜底。
+    const outputDir = resolve(values['output-dir']
+        ?? (values.global ? globalReportsDir() : projectReportsDir()));
     const concurrencyRaw = values.concurrency !== undefined
         ? Number(values.concurrency)
         : evalConfig?.concurrency ?? 1;

package/dist/cli/lib/record-evolve-outcome.d.ts

@@ -0,0 +1,31 @@
+import type { EvaluationReport } from '../../types/index.js';
+export interface EvolveOutcomeInput {
+    /** 合并 evolve 报告 id（evolveSkill 返回的 reportId）。 */
+    reportId?: string;
+    /** 胜出轮（0 = 无改进，不记）。 */
+    bestRound: number;
+    /** resolveSkillInput 给的 skillPath（文件-skill 为 .md、目录-skill 为内部 SKILL.md）。 */
+    skillPath: string;
+    /** resolveSkillInput 给的 skillDir。 */
+    skillDir: string;
+    /** evolve 目标本身的形态（目录-skill / 文件-skill），由原始入参 statSync 判定。用于按形态精确匹配受管记录。 */
+    isDirectorySkill: boolean;
+    /** 报告加载器覆盖（测试用）；默认走 overlay 报告存储（项目 .omk/reports → 全局兜底）按 id 读。 */
+    loadReport?: (id: string) => Promise<EvaluationReport | null>;
+    /** 受管目录覆盖（测试用）。 */
+    dir?: string;
+}
+export interface EvolveOutcomeResult {
+    name: string;
+    contentHash: string;
+    verdict: string;
+}
+/**
+ * evolve 把胜出版本写回 source 后，为受管 skill 记一条带 verdict 的证据，并把记录 re-baseline 到新版本，
+ * 让 `omk list` 显 measurable（而非永久 stale）。**不写 promote 决定** —— 升 promoted 仍由人 `omk promote`（A 方案：
+ * 统计门 ≠ 人的生产接受）。未纳管 / 无改进 / 源不可达 / 报告缺失 → no-op 返回 null。
+ *
+ * 证据 contentHash 统一锚到 re-baseline 后的源哈（probeSourceState 与 install / list 同口径），规避「文件-skill 哈
+ * vs 目录-skill 整树哈」可能与报告内 artifactHash 不在同空间的边角，保证证据判为「当前」。
+ */
+export declare function recordEvolveOutcome(input: EvolveOutcomeInput): Promise<EvolveOutcomeResult | null>;

package/dist/cli/lib/record-evolve-outcome.js

@@ -0,0 +1,110 @@
+import { resolve } from 'node:path';
+import { createOverlayReportStore } from '../../server/report-store.js';
+import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
+import { computeVerdict } from '../../eval-core/verdict.js';
+import { bootstrapDiffCI, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES } from '../../eval-core/bootstrap.js';
+import { resolveManagedDir, managedDir, loadAllManagedRecords, appendManagedEvidence, rebaselineManagedContentHash, buildEvidenceRef, probeSourceState, } from '../../managed/index.js';
+/**
+ * round-bestRound vs round-0 的忠实 verdict：复刻 eval 管线（evaluation-reporting.ts）对两变体抽
+ * per-sample composite → bootstrapDiffCI → computeVerdict，与 `omk eval --bootstrap` 同口径、同 α / 重采样数。
+ * 不自造门限：评委是否显著、是否 PROGRESS 全交给既有 computeVerdict。
+ */
+function winnerVerdict(report, winnerVariant) {
+    const baseline = 'round-0';
+    const scoresOf = (v) => report.results
+        .map((r) => r.variants[v])
+        .filter((e) => !!e && typeof e.compositeScore === 'number' && e.compositeScore > 0)
+        .map((e) => e.compositeScore);
+    const ctrl = scoresOf(baseline);
+    const treat = scoresOf(winnerVariant);
+    const pairComparisons = ctrl.length >= 2 && treat.length >= 2
+        ? [{
+                control: baseline,
+                treatment: winnerVariant,
+                diffBootstrapCI: bootstrapDiffCI(ctrl, treat, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES),
+            }]
+        : undefined;
+    const slice = {
+        ...report,
+        meta: {
+            ...report.meta,
+            variants: [baseline, winnerVariant],
+            ...(pairComparisons ? { pairComparisons } : {}),
+        },
+        summary: {
+            [baseline]: report.summary[baseline],
+            [winnerVariant]: report.summary[winnerVariant],
+        },
+    };
+    return computeVerdict(slice).level;
+}
+/**
+ * 受管目录里按源路径定位被 evolve 的那条记录。**形态感知**,且对目录-skill 的两种 install 落盘形态都认:
+ *   - 目录-skill(`isDirectorySkill=true`):install 既可能落「目录形态」(`source.isDirectorySkill=true`、
+ *     locator=skill 根目录 = skillDir),也可能因用户 `install <dir>/SKILL.md` 落「文件形态」
+ *     (`isDirectorySkill=false`、locator=该 SKILL.md = skillPath)。两者都对应同一个 skill,故都匹配。
+ *   - 扁平文件-skill(`isDirectorySkill=false`):只认「文件形态 + locator=该 .md 本身(skillPath)」。
+ *
+ * 绝不拿父目录 skillDir 去撞目录-skill 记录:对散文件 skill(`skills/foo.md`)跑 evolve 时,skillDir = `skills/`,
+ * 若并集匹配会误命中一条 locator 恰为 `skills/` 的目录-skill 记录,把证据 / re-baseline 写到根本没被 evolve 的
+ * 记录上。这里每条匹配目标(skillDir / skillPath)都唯一指向被 evolve 的 skill 自身,无此越权。
+ */
+function findRecordBySource(records, skillPath, skillDir, isDirectorySkill) {
+    const fileTarget = resolve(skillPath);
+    const dirTarget = resolve(skillDir);
+    return records.find((r) => {
+        if (r.source.sourceKind !== 'file')
+            return false;
+        const loc = resolve(r.source.locator);
+        if (isDirectorySkill) {
+            return (r.source.isDirectorySkill && loc === dirTarget) // 目录形态记录:locator = skill 根目录
+                || (!r.source.isDirectorySkill && loc === fileTarget); // 文件形态记录(install <dir>/SKILL.md):locator = 该 SKILL.md
+        }
+        return !r.source.isDirectorySkill && loc === fileTarget; // 扁平文件-skill:只认该 .md 本身,绝不撞父目录
+    });
+}
+async function loadEvolveReport(id) {
+    // overlay get：项目 .omk/reports → 全局兜底，evolve 写到全局的合并报告仍命中，eval 新写项目的也能取到。
+    const doc = await createOverlayReportStore(projectReportsDir(), globalReportsDir()).get(id);
+    return doc && doc.kind === 'evaluation' ? doc : null;
+}
+/**
+ * evolve 把胜出版本写回 source 后，为受管 skill 记一条带 verdict 的证据，并把记录 re-baseline 到新版本，
+ * 让 `omk list` 显 measurable（而非永久 stale）。**不写 promote 决定** —— 升 promoted 仍由人 `omk promote`（A 方案：
+ * 统计门 ≠ 人的生产接受）。未纳管 / 无改进 / 源不可达 / 报告缺失 → no-op 返回 null。
+ *
+ * 证据 contentHash 统一锚到 re-baseline 后的源哈（probeSourceState 与 install / list 同口径），规避「文件-skill 哈
+ * vs 目录-skill 整树哈」可能与报告内 artifactHash 不在同空间的边角，保证证据判为「当前」。
+ */
+export async function recordEvolveOutcome(input) {
+    if (input.bestRound <= 0 || !input.reportId)
+        return null;
+    const dir = input.dir ?? resolveManagedDir(managedDir());
+    const record = findRecordBySource(loadAllManagedRecords(dir), input.skillPath, input.skillDir, input.isDirectorySkill);
+    if (!record)
+        return null; // 未纳管 → no-op（管理是 install 显式 opt-in）
+    const probe = probeSourceState(record);
+    if (!probe.reachable || probe.hash === undefined)
+        return null; // 源不可达 → 不动
+    const newHash = probe.hash;
+    const report = input.loadReport ? await input.loadReport(input.reportId) : await loadEvolveReport(input.reportId);
+    if (!report || report.kind !== 'evaluation')
+        return null;
+    const winnerVariant = `round-${input.bestRound}`;
+    // 防御:正常 evolve 产物必含基线 round-0 与胜出轮的 summary(同一次 run 产出 bestRound 与合并报告),此守卫只挡
+    // 报告损坏 / 被截断的边角 —— 缺任一则无可信 verdict 可算,直接 no-op,避免 winnerVerdict→computeVerdict 读 undefined。
+    if (!report.summary?.['round-0'] || !report.summary?.[winnerVariant])
+        return null;
+    const ref = buildEvidenceRef(report, winnerVariant, winnerVerdict(report, winnerVariant), new Date().toISOString());
+    if (!ref)
+        return null;
+    const evidence = { ...ref, contentHash: newHash };
+    // 用 store 写函数的返回值判定:记录在 find 与写之间被删/改(TOCTOU)→ 两次写 no-op 返回 null → 不回报成功,
+    // 避免 CLI 打印「已记证据」而盘上其实没写。name/contentHash 取自 append 后的 merged 记录,不用旧 in-memory。
+    if (!rebaselineManagedContentHash(dir, record.id, newHash))
+        return null;
+    const merged = appendManagedEvidence(dir, record.id, evidence);
+    if (!merged)
+        return null;
+    return { name: merged.name, contentHash: merged.contentHash, verdict: evidence.verdict ?? 'UNKNOWN' };
+}

package/dist/cli/lib/resolve-skill-input.d.ts

@@ -3,5 +3,11 @@ export interface ResolvedSkillInput {
     skillPath: string;
     skillDir: string;
     samplesPath: string;
+    /**
+     * 目标是否为目录-skill。**只看解析后形态、不看入参写法**：传目录 `skills/foo` 或传内部
+     * `skills/foo/SKILL.md` 都判 true(两者 skillPath 都落到 `.../SKILL.md`),扁平 `bar.md` 判 false。
+     * 受管联动按此对齐 install 落的记录形态(`source.isDirectorySkill`),避免「传 SKILL.md 文件路径就匹配不到目录记录」。
+     */
+    isDirectorySkill: boolean;
 }
 export declare function resolveSkillInput(input: string, lang: CliLang): ResolvedSkillInput;

package/dist/cli/lib/resolve-skill-input.js

@@ -1,4 +1,4 @@
-import { resolve, join, dirname } from 'node:path';
+import { resolve, join, dirname, basename } from 'node:path';
 import { existsSync, statSync } from 'node:fs';
 import { tCli } from './i18n.js';
 // 统一 skill 入参解析:既接受 SKILL.md 文件(老式 + flat skill),也接受 directory-skill
@@ -35,5 +35,7 @@ export function resolveSkillInput(input, lang) {
     ];
     // fallback 到 .omk/ 目录：上游会报 "no sample files found in directory" 引导用户创建
     const samplesPath = candidates.find(existsSync) ?? omkDir;
-    return { skillPath, skillDir, samplesPath };
+    // 形态以解析后的 skillPath 命名为准:目录-skill 的 skillPath 总是 `.../SKILL.md`。
+    const isDirectorySkill = basename(skillPath) === 'SKILL.md';
+    return { skillPath, skillDir, samplesPath, isDirectorySkill };
 }

package/dist/diagnosis/types.js

@@ -6,7 +6,7 @@
  *    confirmed:目前 mapper 不产出,如果将来 producer / review-state 写出,会被一并算 inactive
  *               —— 跟 confirmed soft standard 的「已被认知、进入处理流程」语义一致。
  *
- *  抽这个 helper 是为了:Insight 投影(影响 skill 健康 / 待优化数)和 /api/observations/diagnostics
+ *  抽这个 helper 是为了:Insight 投影(影响 skill 健康 / 待优化数)和 /api/observe-inbox/diagnostics
  *  的 active 列表共用同一份口径,避免「Insight 把 confirmed 算 active 但 API 不算」的口径分叉。
  */
 const ACTIVE_DIAGNOSIS_LIFECYCLES = new Set([

package/dist/doctor/index.js

@@ -167,7 +167,10 @@ let reportIdCounter = 0;
 function nextReportId() {
     reportIdCounter += 1;
     const ts = new Date().toISOString().replace(/[-:.]/g, '').slice(0, 15);
-    return `doctor-${ts}-${reportIdCounter}`;
+    // 进程内计数器只防同进程同秒撞;跨进程同秒(两个 omk doctor 并发 / 不同项目)仍会撞同 id,
+    // 经机器级卡片 dedup 当唯一键用时会静默并掉一份。加 4 位随机根治跨进程撞名(id 是标签非测量数)。
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `doctor-${ts}-${reportIdCounter}-${rand}`;
 }
 function readCliVersion() {
     // 不依赖 package.json import(避免 type 解析复杂度);用环境变量或退回 'unknown'

package/dist/eval-core/artifact-index.d.ts

@@ -0,0 +1,106 @@
+import type { ReportDocument, ReportIndexCard } from '../types/index.js';
+import type { SkillDoctorSnapshot } from '../types/skill-index.js';
+import type { DoctorSkillStatus } from '../types/doctor.js';
+export type ArtifactDomain = 'report' | 'doctor' | 'observe-health';
+/** 某域的索引目录 `<root>/<domain>/`。 */
+export declare function artifactIndexDir(domain: ArtifactDomain): string;
+/** report 域口径(保持向后兼容的既有导出)。 */
+export declare function shouldIndexReport(outputDir: string): boolean;
+/**
+ * 某域所有卡片「真身(card.path)」的存在性 + mtime/size 指纹。
+ * 消费方(indexed-report-store / buildSkillIndex)的缓存指纹必须纳入它:卡片 JSON 本身没变、只靠卡片目录
+ * mtime 的指纹检测不到「真身被带外删」,长会话会继续命中旧缓存展示悬空卡片。真身删/改 → 此 sentinel 变 →
+ * 缓存失效 → live 过滤生效。读卡片只为拿 path,字段宽松。
+ */
+export declare function cardTargetSentinel(domain: ArtifactDomain): string;
+/**
+ * persistReport 的索引钩子:报告落盘后 best-effort 追加卡片。永不抛、永不阻断报告落盘。
+ * 入参故意收 `{id}` 宽松(同 persistReport 的 PersistableReport):非完整报告(无 canonical kind)防御式跳过。
+ */
+export declare function indexReportWrite(report: {
+    id: string;
+}, sourcePath: string, outputDir: string): void;
+/** 读 report 域全部卡片(跳过坏文件 / 缺字段 / 坏 kind)。 */
+export declare function listReportCards(): ReportIndexCard[];
+/** report 卡片(过滤悬空真身):供 studio 机器级 list / findBy 展示。 */
+export declare function listLiveReportCards(): ReportIndexCard[];
+/** 卡片 → ReportDocument(results:[]):供 studio list / buildSkillIndex / trend 消费(它们不读 results)。 */
+export declare function cardToReportDocument(card: ReportIndexCard): ReportDocument;
+/** 删 report 域某 id 的卡片(DELETE 报告时连卡片一起删,使其从机器级 list 消失)。幂等、best-effort。 */
+export declare function removeReportCard(id: string): boolean;
+/** doctor 卡片:per-skill 文件(`{skillName}-{reportId}.json`)一张。id = 文件名 stem(唯一),
+ *  reportId = 该次 doctor run 的 id(同 run 多 skill 共享)。剥掉逐规则 results 重体,只留 per-skill 计数。
+ *  无 `kind` 字段 —— domain 已足够判别(doctor 只有一种报告 kind)。 */
+export interface DoctorIndexCard {
+    domain: 'doctor';
+    id: string;
+    path: string;
+    skillName: string;
+    reportId: string;
+    timestamp: string;
+    status: DoctorSkillStatus;
+    passCount: number;
+    warnCount: number;
+    failCount: number;
+}
+/** persistDoctorReport per-skill 循环里的索引钩子。best-effort,永不抛、永不阻断正文落盘。 */
+export declare function indexDoctorWrite(card: Omit<DoctorIndexCard, 'domain'>, outputDir: string): void;
+/** 读 doctor 域全部卡片。 */
+export declare function listDoctorCards(): DoctorIndexCard[];
+/** doctor 卡片(过滤悬空真身):供 buildSkillIndex 机器级合并。 */
+export declare function listLiveDoctorCards(): DoctorIndexCard[];
+/** doctor 卡片 → (skillName, SkillDoctorSnapshot)。results:[](逐规则详情需回源项目看)。 */
+export declare function cardToDoctorSnapshot(card: DoctorIndexCard): {
+    skillName: string;
+    snap: SkillDoctorSnapshot;
+};
+/** 删 doctor 域某 id(文件 stem)的卡片。doctor 历史按 50/skill prune,删正文时必须连卡片一起删,
+ *  否则被 prune 掉的报告会经卡片合并在本项目 studio「复活」。 */
+export declare function removeDoctorCard(id: string): boolean;
+/** observe 报告投影到卡片所需的结构子集(不 import observability/SkillHealthReport,保持 eval-core 解耦)。 */
+interface ObserveCardSkill {
+    toolFailureRate: number;
+    segmentCount: number;
+    gap?: {
+        weightedGapRate?: number;
+    };
+    confidence?: 'high' | 'low' | 'underpowered';
+}
+interface ObserveSource {
+    meta: {
+        generatedAt: string;
+        sessionCount: number;
+        segmentCount: number;
+    };
+    overall: {
+        healthBand: 'green' | 'yellow' | 'red';
+        confidence?: 'high' | 'low' | 'underpowered';
+    };
+    bySkill: Record<string, ObserveCardSkill>;
+}
+/** observe 卡片:每份报告一张。id = 文件名 stem。剥掉每个 skill 的 gap.signals 等重体,只留 list / skill-index
+ *  口径需要的标量(meta 摘要 + overall + per-skill 标量)。详情(含 signals)走 card.path 读真身。无 `kind` 字段。 */
+export interface ObserveIndexCard {
+    domain: 'observe-health';
+    id: string;
+    path: string;
+    meta: {
+        generatedAt: string;
+        sessionCount: number;
+        segmentCount: number;
+    };
+    overall: {
+        healthBand: 'green' | 'yellow' | 'red';
+        confidence?: 'high' | 'low' | 'underpowered';
+    };
+    bySkill: Record<string, ObserveCardSkill>;
+}
+/** persistObserveHealthReport 的索引钩子。best-effort,永不抛、永不阻断正文落盘。 */
+export declare function indexObserveWrite(report: ObserveSource, sourcePath: string, outputDir: string, id: string): void;
+/** 读 observe-health 域全部卡片。 */
+export declare function listObserveCards(): ObserveIndexCard[];
+/** observe 卡片(过滤悬空真身):供 listAnalyses / buildSkillIndex 机器级合并。 */
+export declare function listLiveObserveCards(): ObserveIndexCard[];
+/** 删 observe 域某 id 的卡片。 */
+export declare function removeObserveCard(id: string): boolean;
+export {};