oh-my-knowledge 0.37.0 → 0.38.0

package/dist/eval-core/artifact-index.js

@@ -0,0 +1,277 @@
+/**
+ * 产物发现索引(report / doctor / observe-health 三域)。
+ *
+ * 每类测量产物的正文(含逐样本 / 逐规则 / 逐信号重体)永远单份留它的项目本地 `.omk/<域>/`;产物落盘后,
+ * 在全局 `state/artifact-index/<域>/<id>.json` 留一张轻卡片(元数据 + 必要标量,剥掉重体,`path` 指向真身),
+ * 让 `omk studio` 跨项目聚合成「机器级总览」—— 当前项目 + 全局靠 live-scan 永远新鲜,别的项目靠卡片发现。
+ *
+ * 索引是可重生 scratch:写失败永不阻断正文落盘(正文是 source of truth);丢了由 live-scan / 重跑重建。
+ * 三域共用 `artifactIndexDir(domain)` + tmp-rename 原子写 + 指纹缓存读 的同一套机制,各域只差「投影成卡片」
+ * 与「卡片还原成 snapshot」两段域特定逻辑。
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { DEFAULT_ARTIFACT_INDEX_DIR } from './default-dirs.js';
+import { globalReportsDir, globalDoctorsDir, globalObserveHealthDir } from './measurement-dirs.js';
+// ── 通用机制(域无关)──────────────────────────────────────────────────────────
+/** 索引根:`OMK_ARTIFACT_INDEX_DIR` 覆盖(测试隔离,仿 OMK_TREES_DIR),默认 state/artifact-index。 */
+function artifactIndexRoot() {
+    return process.env.OMK_ARTIFACT_INDEX_DIR || DEFAULT_ARTIFACT_INDEX_DIR;
+}
+/** 某域的索引目录 `<root>/<domain>/`。 */
+export function artifactIndexDir(domain) {
+    return join(artifactIndexRoot(), domain);
+}
+/** 只索引「非全局目录」的写:全局是单一物理目录、任何 studio 都 live-scan 它 → 全局写卡片冗余;
+ *  卡片唯一价值是别项目的项目级 `.omk/<域>`。 */
+function shouldIndexDir(outputDir, globalDir) {
+    return resolve(outputDir) !== resolve(globalDir);
+}
+/** report 域口径(保持向后兼容的既有导出)。 */
+export function shouldIndexReport(outputDir) {
+    return shouldIndexDir(outputDir, globalReportsDir());
+}
+function safeFileName(id) {
+    return id.replaceAll(/[/\\:*?"<>|]/g, '_');
+}
+// 卡片读侧小 guard:索引是可重生 scratch,坏卡片(脏文件 / 别域误落 / 字段缺失)读侧从严跳过,
+// 不让 undefined / 非法枚举 / NaN 当可信输入污染 studio。
+const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isDoctorStatus = (v) => v === 'pass' || v === 'warn' || v === 'fail';
+const isHealthBand = (v) => v === 'green' || v === 'yellow' || v === 'red';
+const isConfidence = (v) => v === undefined || v === 'high' || v === 'low' || v === 'underpowered';
+/** 原子写一张卡片(tmp+rename,防半截 JSON 被 reader 读到)。 */
+function writeCard(domain, id, card) {
+    const indexDir = artifactIndexDir(domain);
+    mkdirSync(indexDir, { recursive: true });
+    const target = join(indexDir, `${safeFileName(id)}.json`);
+    const tmp = `${target}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(card, null, 2));
+    renameSync(tmp, target);
+}
+/** 读某域全部卡片,逐条用 `valid` 谓词过滤坏文件 / 缺字段(索引是 scratch,读侧从严)。 */
+function readArtifactCards(domain, valid) {
+    const dir = artifactIndexDir(domain);
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json') || f.includes('.json.tmp.'))
+            continue;
+        try {
+            const c = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+            if (valid(c))
+                out.push(c);
+        }
+        catch { /* skip corrupt card */ }
+    }
+    return out;
+}
+/** 删某域某 id 的卡片。幂等、best-effort。返回卡片是否曾存在。 */
+function removeArtifactCard(domain, id) {
+    try {
+        const p = join(artifactIndexDir(domain), `${safeFileName(id)}.json`);
+        if (!existsSync(p))
+            return false;
+        unlinkSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 过滤悬空卡片:真身文件(`card.path`)已不在(项目被整目录删 / 移走等带外途径)→ 卡片视为「指向不存在的产物」。
+ * 机器级 list / merge 展示路径用 listLive*Cards,不展示这类卡片(把卡片当活指针,而非持久记录)。
+ * 注:by-id 的 get / loadXReport 兜底仍走 raw list*Cards —— 直链书签按 card.path 读到则给真身、读不到各自降级,
+ * 是 best-effort,不在这层过滤。doctor 历史 prune 已连带删卡片,故悬空主要发生在「带外删整个项目目录」。
+ */
+function liveCards(cards) {
+    return cards.filter((c) => existsSync(c.path));
+}
+/**
+ * 某域所有卡片「真身(card.path)」的存在性 + mtime/size 指纹。
+ * 消费方(indexed-report-store / buildSkillIndex)的缓存指纹必须纳入它:卡片 JSON 本身没变、只靠卡片目录
+ * mtime 的指纹检测不到「真身被带外删」,长会话会继续命中旧缓存展示悬空卡片。真身删/改 → 此 sentinel 变 →
+ * 缓存失效 → live 过滤生效。读卡片只为拿 path,字段宽松。
+ */
+export function cardTargetSentinel(domain) {
+    const dir = artifactIndexDir(domain);
+    if (!existsSync(dir))
+        return '';
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return '';
+    }
+    const parts = [];
+    for (const f of files) {
+        if (!f.endsWith('.json') || f.includes('.json.tmp.'))
+            continue;
+        try {
+            const c = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+            if (typeof c.path !== 'string')
+                continue;
+            try {
+                const s = statSync(c.path);
+                parts.push(`${f}=${s.mtimeMs}:${s.size}`);
+            }
+            catch {
+                parts.push(`${f}=gone`);
+            }
+        }
+        catch { /* skip corrupt */ }
+    }
+    return parts.sort().join(',');
+}
+// ── report 域 ───────────────────────────────────────────────────────────────
+/** 报告投影成卡片(剥掉 results 重体)。 */
+function reportCard(report, sourcePath) {
+    return report.kind === 'evaluation'
+        ? { domain: 'report', id: report.id, path: sourcePath, kind: 'evaluation', meta: report.meta, summary: report.summary }
+        : { domain: 'report', id: report.id, path: sourcePath, kind: 'batch-evaluation', meta: report.meta, items: report.items };
+}
+/**
+ * persistReport 的索引钩子:报告落盘后 best-effort 追加卡片。永不抛、永不阻断报告落盘。
+ * 入参故意收 `{id}` 宽松(同 persistReport 的 PersistableReport):非完整报告(无 canonical kind)防御式跳过。
+ */
+export function indexReportWrite(report, sourcePath, outputDir) {
+    try {
+        if (!shouldIndexReport(outputDir))
+            return;
+        const doc = report;
+        if (doc.kind !== 'evaluation' && doc.kind !== 'batch-evaluation')
+            return;
+        writeCard('report', report.id, reportCard(doc, sourcePath));
+    }
+    catch {
+        // 索引可重建,失败静默(可选 stderr warn);正文已落盘不受影响。
+    }
+}
+/** 读 report 域全部卡片(跳过坏文件 / 缺字段 / 坏 kind)。 */
+export function listReportCards() {
+    return readArtifactCards('report', (c) => {
+        const card = c;
+        // kind 白名单:cardToReportDocument 对任何非 evaluation 一律按 batch 投影,坏 kind(拼错 / 'doctor')
+        // 会污染机器级 list 成空 batch 报告。索引是可重生 scratch,读侧从严跳过坏卡片。
+        const kindOk = card?.kind === 'evaluation' || card?.kind === 'batch-evaluation';
+        return !!card && card.domain === 'report' && kindOk && typeof card.id === 'string' && typeof card.path === 'string' && !!card.meta;
+    });
+}
+/** report 卡片(过滤悬空真身):供 studio 机器级 list / findBy 展示。 */
+export function listLiveReportCards() {
+    return liveCards(listReportCards());
+}
+/** 卡片 → ReportDocument(results:[]):供 studio list / buildSkillIndex / trend 消费(它们不读 results)。 */
+export function cardToReportDocument(card) {
+    return card.kind === 'evaluation'
+        ? { kind: 'evaluation', id: card.id, meta: card.meta, summary: card.summary ?? {}, results: [] }
+        : { kind: 'batch-evaluation', id: card.id, mode: 'skill', meta: card.meta, items: card.items ?? [] };
+}
+/** 删 report 域某 id 的卡片(DELETE 报告时连卡片一起删,使其从机器级 list 消失)。幂等、best-effort。 */
+export function removeReportCard(id) {
+    return removeArtifactCard('report', id);
+}
+/** persistDoctorReport per-skill 循环里的索引钩子。best-effort,永不抛、永不阻断正文落盘。 */
+export function indexDoctorWrite(card, outputDir) {
+    try {
+        if (!shouldIndexDir(outputDir, globalDoctorsDir()))
+            return;
+        writeCard('doctor', card.id, { domain: 'doctor', ...card });
+    }
+    catch { /* 索引可重建,失败静默 */ }
+}
+/** 读 doctor 域全部卡片。 */
+export function listDoctorCards() {
+    return readArtifactCards('doctor', (c) => {
+        const card = c;
+        return !!card && card.domain === 'doctor' && typeof card.id === 'string' && typeof card.path === 'string'
+            && typeof card.skillName === 'string' && typeof card.reportId === 'string' && typeof card.timestamp === 'string'
+            && isDoctorStatus(card.status)
+            && isFiniteNumber(card.passCount) && isFiniteNumber(card.warnCount) && isFiniteNumber(card.failCount);
+    });
+}
+/** doctor 卡片(过滤悬空真身):供 buildSkillIndex 机器级合并。 */
+export function listLiveDoctorCards() {
+    return liveCards(listDoctorCards());
+}
+/** doctor 卡片 → (skillName, SkillDoctorSnapshot)。results:[](逐规则详情需回源项目看)。 */
+export function cardToDoctorSnapshot(card) {
+    return {
+        skillName: card.skillName,
+        snap: {
+            reportId: card.reportId, timestamp: card.timestamp, status: card.status,
+            passCount: card.passCount, warnCount: card.warnCount, failCount: card.failCount, results: [],
+        },
+    };
+}
+/** 删 doctor 域某 id(文件 stem)的卡片。doctor 历史按 50/skill prune,删正文时必须连卡片一起删,
+ *  否则被 prune 掉的报告会经卡片合并在本项目 studio「复活」。 */
+export function removeDoctorCard(id) {
+    return removeArtifactCard('doctor', id);
+}
+/** persistObserveHealthReport 的索引钩子。best-effort,永不抛、永不阻断正文落盘。 */
+export function indexObserveWrite(report, sourcePath, outputDir, id) {
+    try {
+        if (!shouldIndexDir(outputDir, globalObserveHealthDir()))
+            return;
+        const bySkill = {};
+        for (const [name, h] of Object.entries(report.bySkill || {})) {
+            bySkill[name] = {
+                toolFailureRate: h.toolFailureRate, segmentCount: h.segmentCount,
+                gap: { weightedGapRate: h.gap?.weightedGapRate ?? 0 }, confidence: h.confidence,
+            };
+        }
+        const card = {
+            domain: 'observe-health', id, path: sourcePath,
+            meta: { generatedAt: report.meta.generatedAt, sessionCount: report.meta.sessionCount, segmentCount: report.meta.segmentCount },
+            overall: { healthBand: report.overall.healthBand, confidence: report.overall.confidence },
+            bySkill,
+        };
+        writeCard('observe-health', id, card);
+    }
+    catch { /* 索引可重建,失败静默 */ }
+}
+/** 读 observe-health 域全部卡片。 */
+export function listObserveCards() {
+    return readArtifactCards('observe-health', (c) => {
+        const card = c;
+        if (!card || card.domain !== 'observe-health' || typeof card.id !== 'string' || typeof card.path !== 'string')
+            return false;
+        const meta = card.meta;
+        const overall = card.overall;
+        const bySkill = card.bySkill;
+        if (!meta || !isFiniteNumber(meta.sessionCount) || !isFiniteNumber(meta.segmentCount) || typeof meta.generatedAt !== 'string')
+            return false;
+        if (!overall || !isHealthBand(overall.healthBand) || !isConfidence(overall.confidence))
+            return false;
+        if (!bySkill || typeof bySkill !== 'object')
+            return false;
+        // 每个 skill 的标量也校验:坏 toolFailureRate / segmentCount / gap.weightedGapRate 会让 bandFromObserveHealth /
+        // 趋势 / 健康快照出 NaN(buildSkillIndex 直接取 h.gap?.weightedGapRate ?? 0 进 gapRate、参与阈值判断)。
+        for (const h of Object.values(bySkill)) {
+            if (!h || !isFiniteNumber(h.toolFailureRate) || !isFiniteNumber(h.segmentCount) || !isConfidence(h.confidence))
+                return false;
+            if (h.gap !== undefined && h.gap.weightedGapRate !== undefined && !isFiniteNumber(h.gap.weightedGapRate))
+                return false;
+        }
+        return true;
+    });
+}
+/** observe 卡片(过滤悬空真身):供 listAnalyses / buildSkillIndex 机器级合并。 */
+export function listLiveObserveCards() {
+    return liveCards(listObserveCards());
+}
+/** 删 observe 域某 id 的卡片。 */
+export function removeObserveCard(id) {
+    return removeArtifactCard('observe-health', id);
+}

package/dist/eval-core/default-dirs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * omk 所有默认产物的用户级根目录 —— 全部 `~/.oh-my-knowledge/*` 默认目录的单一基准,
+ * 各目录都从这里派生,不在散落各处重复拼 `join(homedir(), '.oh-my-knowledge', ...)`。
+ *
+ * `OMK_HOME` 环境变量可整体重定向这棵树:一处覆盖即把 reports / doctors / observe-health / state
+ * (cache / trees / jobs / artifact-index)全部移走。测试用它一次性隔离,免得每加一个会从深层调用点写
+ * 全局默认目录的写路径,都得单独补一个 per-dir env 兜底(否则注入不进的写路径会静默污染真实 home)。
+ * 生产不设此变量时回落到 `~/.oh-my-knowledge`,行为不变。用户迁移整个数据目录也可用它。
+ */
+export declare const OMK_HOME: string;
+/**
+ * 耐久测量数据(要留、被 reportId 等引用,绝不自动删)的默认根目录。这几个是 cli 写、server(Studio)读
+ * 的同一处,必须一致 —— 否则 cli 把产物写到一处、studio 从另一处读,页面就空。放在中立的 eval-core 层,
+ * 让 cli/ 与 server/ 两个交付层都能合法 import 同一个常量,而不必让 server 反向 import cli
+ * (那是 #242 清掉的分层倒挂)。
+ */
+export declare const DEFAULT_REPORTS_DIR: string;
+export declare const DEFAULT_OBSERVE_HEALTH_DIR: string;
+export declare const DEFAULT_DOCTORS_DIR: string;
+/**
+ * 可重生的执行 scratch(删了能重建)统一收在 `state/` 子树下,跟上面的耐久数据物理分开 ——
+ * 想清磁盘时「这一坨能整删」一眼可见。各 scratch 目录都派生自这个 state 根,避免散落硬编码。
+ */
+export declare const DEFAULT_STATE_DIR: string;
+export declare const DEFAULT_CACHE_DIR: string;
+export declare const DEFAULT_ISOLATED_CWD_DIR: string;
+export declare const DEFAULT_TREES_DIR: string;
+export declare const DEFAULT_JOBS_DIR: string;
+/**
+ * 产物发现索引根:每类测量产物(report / doctor / observe-health)项目本地落盘后,在全局这里留一张
+ * 轻量目录卡片(指向项目里的真身),让 `omk studio` 跨项目聚合成「机器级总览」。索引是可重生的 scratch
+ * (丢了重跑即重建,且当前项目+全局靠 live-scan 永远覆盖),故收在 state/ 子树。
+ */
+export declare const DEFAULT_ARTIFACT_INDEX_DIR: string;

package/dist/eval-core/default-dirs.js

@@ -0,0 +1,36 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * omk 所有默认产物的用户级根目录 —— 全部 `~/.oh-my-knowledge/*` 默认目录的单一基准,
+ * 各目录都从这里派生,不在散落各处重复拼 `join(homedir(), '.oh-my-knowledge', ...)`。
+ *
+ * `OMK_HOME` 环境变量可整体重定向这棵树:一处覆盖即把 reports / doctors / observe-health / state
+ * (cache / trees / jobs / artifact-index)全部移走。测试用它一次性隔离,免得每加一个会从深层调用点写
+ * 全局默认目录的写路径,都得单独补一个 per-dir env 兜底(否则注入不进的写路径会静默污染真实 home)。
+ * 生产不设此变量时回落到 `~/.oh-my-knowledge`,行为不变。用户迁移整个数据目录也可用它。
+ */
+export const OMK_HOME = process.env.OMK_HOME || join(homedir(), '.oh-my-knowledge');
+/**
+ * 耐久测量数据(要留、被 reportId 等引用,绝不自动删)的默认根目录。这几个是 cli 写、server(Studio)读
+ * 的同一处,必须一致 —— 否则 cli 把产物写到一处、studio 从另一处读,页面就空。放在中立的 eval-core 层,
+ * 让 cli/ 与 server/ 两个交付层都能合法 import 同一个常量,而不必让 server 反向 import cli
+ * (那是 #242 清掉的分层倒挂)。
+ */
+export const DEFAULT_REPORTS_DIR = join(OMK_HOME, 'reports');
+export const DEFAULT_OBSERVE_HEALTH_DIR = join(OMK_HOME, 'observe-health');
+export const DEFAULT_DOCTORS_DIR = join(OMK_HOME, 'doctors');
+/**
+ * 可重生的执行 scratch(删了能重建)统一收在 `state/` 子树下,跟上面的耐久数据物理分开 ——
+ * 想清磁盘时「这一坨能整删」一眼可见。各 scratch 目录都派生自这个 state 根,避免散落硬编码。
+ */
+export const DEFAULT_STATE_DIR = join(OMK_HOME, 'state');
+export const DEFAULT_CACHE_DIR = join(DEFAULT_STATE_DIR, 'cache');
+export const DEFAULT_ISOLATED_CWD_DIR = join(DEFAULT_STATE_DIR, 'isolated-cwd');
+export const DEFAULT_TREES_DIR = join(DEFAULT_STATE_DIR, 'trees');
+export const DEFAULT_JOBS_DIR = join(DEFAULT_STATE_DIR, 'jobs');
+/**
+ * 产物发现索引根:每类测量产物(report / doctor / observe-health)项目本地落盘后,在全局这里留一张
+ * 轻量目录卡片(指向项目里的真身),让 `omk studio` 跨项目聚合成「机器级总览」。索引是可重生的 scratch
+ * (丢了重跑即重建,且当前项目+全局靠 live-scan 永远覆盖),故收在 state/ 子树。
+ */
+export const DEFAULT_ARTIFACT_INDEX_DIR = join(DEFAULT_STATE_DIR, 'artifact-index');

package/dist/eval-core/evaluation-execution.js

@@ -4,9 +4,9 @@ import { safeSliceForJson } from '../util/safe-slice.js';
 import { grade } from '../grading/index.js';
 import { checkFacts } from './fact-checker.js';
 import { resolveExecutionStrategy } from './execution-strategy.js';
+import { DEFAULT_CACHE_DIR } from './default-dirs.js';
 import { getExecutorRuntimeFingerprint } from '../executors/runtime-fingerprint.js';
-import { resolve, join, dirname } from 'node:path';
-import { homedir } from 'node:os';
+import { resolve, dirname } from 'node:path';
 async function runWithConcurrency(tasks, concurrency, fn) {
     let index = 0;
     async function worker() {
@@ -50,7 +50,7 @@ export async function executeTasks({ tasks, executor, executorName, model, noJud
             results[sampleId] = { ...variants };
         }
     }
-    const cacheDir = join(homedir(), '.oh-my-knowledge', 'cache');
+    const cacheDir = DEFAULT_CACHE_DIR;
     const cache = noCache ? null : createCache(cacheDir);
     async function executeTask(task) {
         // Skip if already have a successful result (--resume)

package/dist/eval-core/evaluation-reporting.d.ts

@@ -33,5 +33,12 @@ export interface PersistableReport {
     id: string;
 }
 export declare function persistReport(report: PersistableReport, outputDir: string | null): string | null;
+/**
+ * run id 的时间戳后缀 `YYYYMMDD-HHmmss-rand4`。
+ * 含秒 + 4 位随机:id 是 run 标签(非测量数),但被 studio 机器级 dedup 与 managed 证据 (reportId,
+ * contentHash) 去重当唯一键用。分钟级会让跨项目 / 同分钟重跑撞同 id → 索引静默顶掉一份、managed 错并一条。
+ * 秒+随机根治撞名,保证每次 run 全局唯一。供 generateRunId 与 evolve 合并 id 共用,避免靠 split 反解格式。
+ */
+export declare function runIdSuffix(): string;
 export declare function generateRunId(variants: string[]): string;
 export {};

package/dist/eval-core/evaluation-reporting.js

@@ -1,9 +1,10 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { DEFAULT_REPORTS_DIR } from './default-dirs.js';
+import { indexReportWrite } from './artifact-index.js';
 import { buildVariantSummary } from './schema.js';
 import { buildVariantConfig, resolveExecutionStrategy } from './execution-strategy.js';
 import { getJudgePromptHash } from '../grading/judge.js';
@@ -21,7 +22,8 @@ function findPackageJson(startDir) {
     return join(startDir, '..', 'package.json');
 }
 const PKG = JSON.parse(readFileSync(findPackageJson(__dirname), 'utf-8'));
-export const DEFAULT_OUTPUT_DIR = join(homedir(), '.oh-my-knowledge', 'reports');
+// 写报告的默认目录 = reports 单一来源(default-dirs)。保留 DEFAULT_OUTPUT_DIR 名给既有 16 处 import,值统一,杜绝写/读两端漂移。
+export const DEFAULT_OUTPUT_DIR = DEFAULT_REPORTS_DIR;
 export const EVALUATION_REPORT_SCHEMA_VERSION = 4;
 export function hashString(str) {
     return createHash('sha256').update(str).digest('hex').slice(0, 12);
@@ -290,15 +292,28 @@ export function persistReport(report, outputDir) {
         mkdirSync(outputDir, { recursive: true });
     const filePath = join(outputDir, `${report.id}.json`);
     writeFileSync(filePath, JSON.stringify(report, null, 2));
+    // 产物发现索引:报告落项目本地后,best-effort 追加全局轻卡片,让 omk studio 跨项目聚合成机器级总览。
+    // 永不抛、永不阻断报告落盘(正文是 source of truth)。
+    indexReportWrite(report, filePath, outputDir);
     return filePath;
 }
-export function generateRunId(variants) {
+/**
+ * run id 的时间戳后缀 `YYYYMMDD-HHmmss-rand4`。
+ * 含秒 + 4 位随机:id 是 run 标签(非测量数),但被 studio 机器级 dedup 与 managed 证据 (reportId,
+ * contentHash) 去重当唯一键用。分钟级会让跨项目 / 同分钟重跑撞同 id → 索引静默顶掉一份、managed 错并一条。
+ * 秒+随机根治撞名,保证每次 run 全局唯一。供 generateRunId 与 evolve 合并 id 共用,避免靠 split 反解格式。
+ */
+export function runIdSuffix() {
     const d = new Date();
     const pad = (n) => String(n).padStart(2, '0');
     const date = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
-    const time = `${pad(d.getHours())}${pad(d.getMinutes())}`;
+    const time = `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `${date}-${time}-${rand}`;
+}
+export function generateRunId(variants) {
     const variantPart = variants
         .map((variant) => variant.replaceAll(/[\\/:]/g, '-').replaceAll(/[^a-zA-Z0-9._@-]/g, '_'))
         .join('-vs-');
-    return `${variantPart}-${date}-${time}`;
+    return `${variantPart}-${runIdSuffix()}`;
 }

package/dist/eval-core/execution-strategy.js

@@ -1,6 +1,6 @@
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { DEFAULT_ISOLATED_CWD_DIR } from './default-dirs.js';
 /**
  * Isolated cwd for strict baseline. Empty dir under ~/.oh-my-knowledge/
  * so baseline's Glob/Read tools can't walk into the user's eval workdir (which
@@ -11,7 +11,7 @@ import { homedir } from 'node:os';
  * Stable path (not per-task tmpdir) so cache keys remain consistent.
  */
 function getIsolatedCwd() {
-    const dir = join(homedir(), '.oh-my-knowledge', 'isolated-cwd');
+    const dir = DEFAULT_ISOLATED_CWD_DIR;
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }

package/dist/eval-core/measurement-dirs.d.ts

@@ -0,0 +1,18 @@
+/** 项目级 observe-health 目录(相对调用时 cwd)。 */
+export declare function projectObserveHealthDir(cwd?: string): string;
+/** 全局 observe-health 目录。 */
+export declare function globalObserveHealthDir(): string;
+/** 权威 observe-health 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
+ *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
+export declare function resolveObserveHealthDir(dir?: string, global?: string): string;
+/** 项目级 doctors 目录(相对调用时 cwd)。 */
+export declare function projectDoctorsDir(cwd?: string): string;
+/** 全局 doctors 目录。 */
+export declare function globalDoctorsDir(): string;
+/** 权威 doctors 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
+ *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
+export declare function resolveDoctorsDir(dir?: string, global?: string): string;
+/** 项目级 reports 目录(相对调用时 cwd)。 */
+export declare function projectReportsDir(cwd?: string): string;
+/** 全局 reports 目录。 */
+export declare function globalReportsDir(): string;

package/dist/eval-core/measurement-dirs.js

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_OBSERVE_HEALTH_DIR, DEFAULT_DOCTORS_DIR, DEFAULT_REPORTS_DIR } from './default-dirs.js';
+/**
+ * 测量产物的「项目优先 → 全局兜底」目录解析,镜像 managed 的 `resolveManagedDir`
+ * (src/managed/store.ts)。测量产物绑用例集上下文(construct validity,不可全局化),
+ * 默认落项目 `.omk/`,全局作显式 opt-in。
+ *
+ * 「记录优先」—— 目录里有匹配 `.json` 才算数(不是「目录存在」),与 managed 同口径,
+ * 避免空项目目录遮蔽全局数据。项目目录按**调用时** `cwd()` 求值(函数,不是 import 时
+ * 冻结的常量),studio 长会话 per-request 解析才正确。
+ */
+/** dir 里是否有至少一个满足 match 的文件(短路,不读文件内容)。 */
+function hasMatchingFile(dir, match) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some(match);
+    }
+    catch {
+        return false;
+    }
+}
+// —— observe-health(skill 健康度报告)——
+// 文件名 `{timestamp}-observe-health.json`,匹配后缀避免别的 .json 误翻转 resolver。
+/** 项目级 observe-health 目录(相对调用时 cwd)。 */
+export function projectObserveHealthDir(cwd = process.cwd()) {
+    return join(cwd, '.omk', 'observe-health');
+}
+/** 全局 observe-health 目录。 */
+export function globalObserveHealthDir() {
+    return DEFAULT_OBSERVE_HEALTH_DIR;
+}
+/** 权威 observe-health 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
+ *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
+export function resolveObserveHealthDir(dir = projectObserveHealthDir(), global = globalObserveHealthDir()) {
+    const has = (d) => hasMatchingFile(d, (f) => f.endsWith('-observe-health.json'));
+    if (has(dir))
+        return dir;
+    if (dir !== global && has(global))
+        return global;
+    return dir;
+}
+// —— doctors(体检报告)——
+// 文件名 `{skill}-{id}.json`,谓词用「存在任意 .json」即可(真解析在下游 scanDoctorReports)。
+/** 项目级 doctors 目录(相对调用时 cwd)。 */
+export function projectDoctorsDir(cwd = process.cwd()) {
+    return join(cwd, '.omk', 'doctors');
+}
+/** 全局 doctors 目录。 */
+export function globalDoctorsDir() {
+    return DEFAULT_DOCTORS_DIR;
+}
+/** 权威 doctors 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
+ *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
+export function resolveDoctorsDir(dir = projectDoctorsDir(), global = globalDoctorsDir()) {
+    const has = (d) => hasMatchingFile(d, (f) => f.endsWith('.json'));
+    if (has(dir))
+        return dir;
+    if (dir !== global && has(global))
+        return global;
+    return dir;
+}
+// —— reports(eval 评测报告)——
+// reports 与 observe-health / doctors 不同:它不是「选一个权威目录」就够的展示列表,而是按 id
+// 寻址的 store(get(id) / findByArtifactHash 被 resume / gold-compare / baseline 复用依赖)。
+// 故记录优先在 store 层做(见 createOverlayReportStore:项目盖全局),此处只给写入侧与 --global
+// 用的项目 / 全局目录 getter,不给 resolveReportsDir(单目录二选一会让目标 id 在另一目录时 get 落空)。
+/** 项目级 reports 目录(相对调用时 cwd)。 */
+export function projectReportsDir(cwd = process.cwd()) {
+    return join(cwd, '.omk', 'reports');
+}
+/** 全局 reports 目录。 */
+export function globalReportsDir() {
+    return DEFAULT_REPORTS_DIR;
+}

package/dist/eval-workflows/batch-evaluation-workflow.js

@@ -2,7 +2,8 @@ import { dirname } from 'node:path';
 import { DEFAULT_OUTPUT_DIR, EVALUATION_REPORT_SCHEMA_VERSION, generateRunId, getCliVersion, getGitInfo, persistReport, } from '../eval-core/evaluation-reporting.js';
 import { buildEvaluationRequest, createEvaluationRun, createSucceededJob, finalizeEvaluationRun } from '../eval-core/evaluation-job.js';
 import { getExecutorRuntimeFingerprint } from '../executors/runtime-fingerprint.js';
-import { createFileJobStore, DEFAULT_JOBS_DIR } from '../server/job-store.js';
+import { createFileJobStore } from '../server/job-store.js';
+import { DEFAULT_JOBS_DIR } from '../eval-core/default-dirs.js';
 /** Batch 每个 entry 的实验结构固定:baseline control vs 当前 skill treatment。
  *  构造 VariantSpec 交给 runEvaluation 的 spec-based 解析按身份绑定 role / 隔离——与单跑
  *  路径同一处绑定逻辑,batch 不再自管 artifact 拼装(此前两处手抄 resolveArtifacts().map()

package/dist/eval-workflows/evaluation-pipeline/run-state.js

@@ -12,7 +12,8 @@
  * 不再单独 export 给测试 —— job 生命周期通过 orchestrator 间接验证,无独立单测。
  */
 import { buildEvaluationRequest, createFailedJob, createEvaluationRun, createQueuedJob, createSucceededJob, finalizeEvaluationRun, markJobRunning, failEvaluationRun, } from '../../eval-core/evaluation-job.js';
-import { createFileJobStore, DEFAULT_JOBS_DIR, } from '../../server/job-store.js';
+import { createFileJobStore } from '../../server/job-store.js';
+import { DEFAULT_JOBS_DIR } from '../../eval-core/default-dirs.js';
 export async function initializeEvaluationRunState({ samplesPath, skillDir, artifacts, model, judgeModel, noJudge, executorName, judgeExecutorName, concurrency, timeoutMs, noCache, blind, project, owner, tags, runId, jobStore, persistJob, repeat, batch, judgeRepeat, judgeModels, bootstrap, bootstrapSamples, lengthDebias, budget, effort, }) {
     const effectiveJudges = judgeModels && judgeModels.length > 0
         ? judgeModels

package/dist/eval-workflows/run-evaluation.js

@@ -94,8 +94,11 @@ export async function runEvaluation({ samplesPath, skillDir, variantSpecs = [],
     // --resume: load existing report results to skip completed tasks
     let existingResults;
     if (resume) {
-        const { createFileStore } = await import('../server/report-store.js');
-        const store = createFileStore(resolve(outputDir || DEFAULT_OUTPUT_DIR));
+        // 读侧走 overlay(本次 outputDir 优先 → 全局兜底):写默认翻项目后,--resume 一个存量 / 全局报告(升级前
+        // 全部落全局)仍能 get 命中,不致整轮重跑。写仍是另起新报告到 outputDir,与读位置解耦,无 read/write 分叉。
+        const { createOverlayReportStore } = await import('../server/report-store.js');
+        const { globalReportsDir } = await import('../eval-core/measurement-dirs.js');
+        const store = createOverlayReportStore(resolve(outputDir || DEFAULT_OUTPUT_DIR), globalReportsDir());
         const existing = await store.get(resume);
         if (existing?.kind === 'evaluation') {
             existingResults = {};

package/dist/executors/codex-cli.js

@@ -10,7 +10,7 @@ import { buildExecEnv, DEFAULT_TIMEOUT_MS, errorMessage, interruptedExecResult,
 //
 //   undefined         → 不传 -C(原行为,看 cwd 里有什么 codex 自己决定)
 //   []                → 必须提供 cwd 非空(否则 throw),caller 应传一个
-//                       isolated 空目录(如 ~/.oh-my-knowledge/isolated-cwd/)
+//                       isolated 空目录(如 ~/.oh-my-knowledge/state/isolated-cwd/)
 //   [...] (length>0)  → throw,codex CLI 没有 partial 白名单 flag
 export function isolateCodexCwd(allowedSkills, cwd, executorName = 'codex-cli') {
     if (allowedSkills === undefined)
@@ -25,7 +25,7 @@ export function isolateCodexCwd(allowedSkills, cwd, executorName = 'codex-cli')
         throw new Error(`${executorName} executor allowedSkills=[] 需要提供 cwd 非空(channel 3 cwd 隔离)。\n`
             + '  codex 没有 SDK skill 自动发现 / subagent Skill 工具这两条 channel,\n'
             + '  cwd 文件系统隔离是它唯一能堵 AGENTS.md / .agents/skills/ 自动加载的途径。\n'
-            + '  caller 应传一个 isolated 空目录(如 ~/.oh-my-knowledge/isolated-cwd/)。');
+            + '  caller 应传一个 isolated 空目录(如 ~/.oh-my-knowledge/state/isolated-cwd/)。');
     }
 }
 // codex 的 verbose 降级提示是 binary 能力快照(无 --system-prompt flag / 不报 cost),