oh-my-knowledge 0.42.0 → 0.43.0

package/dist/eval-core/artifact-file-names.d.ts

@@ -0,0 +1,15 @@
+export declare const REPORT_FILE_SUFFIX = ".report.json";
+export declare const GRAPH_FILE_SUFFIX = ".graph.json";
+export declare const CARD_FILE_SUFFIX = ".card.md";
+export declare function safeArtifactFileStem(id: string): string;
+export declare function reportFileName(stem: string): string;
+export declare function reportFilePath(dir: string, stem: string): string;
+export declare function reportFileStem(fileName: string): string | null;
+export declare function isReportFileName(fileName: string): boolean;
+export declare function graphFileName(stem: string): string;
+export declare function cardFileName(stem: string): string;
+export declare function runTimestamp(date?: Date): string;
+export declare function randomRunToken(): string;
+export declare function runFileSuffix(counter?: number): string;
+export declare function stripDomainPrefix(id: string, domain: string): string;
+export declare function doctorReportFileStem(skillName: string, reportId: string): string;

package/dist/eval-core/artifact-file-names.js

@@ -0,0 +1,46 @@
+import { join } from 'node:path';
+export const REPORT_FILE_SUFFIX = '.report.json';
+export const GRAPH_FILE_SUFFIX = '.graph.json';
+export const CARD_FILE_SUFFIX = '.card.md';
+export function safeArtifactFileStem(id) {
+    return id.replaceAll(/[/\\:*?"<>|]/g, '_');
+}
+export function reportFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${REPORT_FILE_SUFFIX}`;
+}
+export function reportFilePath(dir, stem) {
+    return join(dir, reportFileName(stem));
+}
+export function reportFileStem(fileName) {
+    return fileName.endsWith(REPORT_FILE_SUFFIX)
+        ? fileName.slice(0, -REPORT_FILE_SUFFIX.length)
+        : null;
+}
+export function isReportFileName(fileName) {
+    return reportFileStem(fileName) !== null;
+}
+export function graphFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${GRAPH_FILE_SUFFIX}`;
+}
+export function cardFileName(stem) {
+    return `${safeArtifactFileStem(stem)}${CARD_FILE_SUFFIX}`;
+}
+export function runTimestamp(date = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+export function randomRunToken() {
+    return Math.random().toString(36).slice(2, 6);
+}
+export function runFileSuffix(counter) {
+    const middle = counter === undefined ? '' : `-${counter}`;
+    return `${runTimestamp()}${middle}-${randomRunToken()}`;
+}
+export function stripDomainPrefix(id, domain) {
+    const safeId = safeArtifactFileStem(id);
+    const prefix = `${domain}-`;
+    return safeId.startsWith(prefix) ? safeId.slice(prefix.length) : safeId;
+}
+export function doctorReportFileStem(skillName, reportId) {
+    return `${safeArtifactFileStem(skillName)}-${stripDomainPrefix(reportId, 'doctor')}`;
+}

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

@@ -5,6 +5,7 @@ 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 { reportFilePath } from './artifact-file-names.js';
 import { buildVariantSummary } from './schema.js';
 import { buildVariantConfig, resolveExecutionStrategy } from './execution-strategy.js';
 import { getJudgePromptHash } from '../grading/judge.js';
@@ -280,7 +281,7 @@ export function persistReport(report, outputDir) {
         return null;
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
-    const filePath = join(outputDir, `${report.id}.json`);
+    const filePath = reportFilePath(outputDir, report.id);
     writeFileSync(filePath, JSON.stringify(report, null, 2));
     // 产物发现索引:报告落项目本地后,best-effort 追加全局轻卡片,让 omk studio 跨项目聚合成机器级总览。
     // 永不抛、永不阻断报告落盘(正文是 source of truth)。

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

@@ -1,14 +1,16 @@
 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';
+import { isReportFileName } from './artifact-file-names.js';
+import { migrateLegacyReportFiles } from './report-file-migration.js';
 /**
  * 测量产物的「项目优先 → 全局兜底」目录解析,镜像 managed 的 `resolveManagedDir`
  * (src/managed/store.ts)。测量产物绑用例集上下文(construct validity,不可全局化),
  * 默认落项目 `.omk/`,全局作显式 opt-in。
  *
- * 「记录优先」—— 目录里有匹配 `.json` 才算数(不是「目录存在」),与 managed 同口径,
- * 避免空项目目录遮蔽全局数据。项目目录按**调用时** `cwd()` 求值(函数,不是 import 时
- * 冻结的常量),studio 长会话 per-request 解析才正确。
+ * 「记录优先」—— 目录里有匹配 report 文件才算数（不是「目录存在」），与 managed 同口径，
+ * 避免空项目目录遮蔽全局数据。项目目录按**调用时** `cwd()` 求值（函数，不是 import 时
+ * 冻结的常量），studio 长会话 per-request 解析才正确。
  */
 /** dir 里是否有至少一个满足 match 的文件(短路,不读文件内容)。 */
 function hasMatchingFile(dir, match) {
@@ -22,7 +24,7 @@ function hasMatchingFile(dir, match) {
     }
 }
 // —— observe-health(skill 健康度报告)——
-// 文件名 `{timestamp}-observe-health.json`,匹配后缀避免别的 .json 误翻转 resolver。
+// 文件名 `{run}.report.json`,目录已表达 observe-health 域。
 /** 项目级 observe-health 目录(相对调用时 cwd)。 */
 export function projectObserveHealthDir(cwd = process.cwd()) {
     return join(cwd, '.omk', 'observe-health');
@@ -34,7 +36,9 @@ export function globalObserveHealthDir() {
 /** 权威 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'));
+    migrateLegacyReportFiles(dir, 'observe-health');
+    migrateLegacyReportFiles(global, 'observe-health');
+    const has = (d) => hasMatchingFile(d, isReportFileName);
     if (has(dir))
         return dir;
     if (dir !== global && has(global))
@@ -42,7 +46,7 @@ export function resolveObserveHealthDir(dir = projectObserveHealthDir(), global
     return dir;
 }
 // —— doctors(体检报告)——
-// 文件名 `{skill}-{id}.json`,谓词用「存在任意 .json」即可(真解析在下游 scanDoctorReports)。
+// 文件名 `{skill}-{run}.report.json`,谓词用 report 后缀即可(真解析在下游 scanDoctorReports)。
 /** 项目级 doctors 目录(相对调用时 cwd)。 */
 export function projectDoctorsDir(cwd = process.cwd()) {
     return join(cwd, '.omk', 'doctors');
@@ -54,7 +58,9 @@ export function globalDoctorsDir() {
 /** 权威 doctors 目录:项目有报告取项目,否则全局有取全局,都空回项目(同 resolveManagedDir)。
  *  `global` 可注入(默认真实全局目录),仅供测试用受控 temp 目录复现 project↔global 兜底。 */
 export function resolveDoctorsDir(dir = projectDoctorsDir(), global = globalDoctorsDir()) {
-    const has = (d) => hasMatchingFile(d, (f) => f.endsWith('.json'));
+    migrateLegacyReportFiles(dir, 'doctor');
+    migrateLegacyReportFiles(global, 'doctor');
+    const has = (d) => hasMatchingFile(d, isReportFileName);
     if (has(dir))
         return dir;
     if (dir !== global && has(global))

package/dist/eval-core/report-file-migration.d.ts

@@ -0,0 +1,10 @@
+export type LegacyReportDomain = 'report' | 'doctor' | 'observe-health' | 'observe-inbox';
+/**
+ * One-shot migration for pre-`.report.json` run artifacts.
+ *
+ * This is deliberately scoped to measurement report directories. It does not make
+ * bare `.json` a normal reader format again; it just renames known legacy report
+ * files into the canonical name so old local data can be discovered, rotated, and
+ * eventually garbage-collected by the new code paths.
+ */
+export declare function migrateLegacyReportFiles(dir: string, domain: LegacyReportDomain): void;

package/dist/eval-core/report-file-migration.js

@@ -0,0 +1,90 @@
+import { existsSync, readdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { doctorReportFileStem, isReportFileName, reportFilePath, stripDomainPrefix } from './artifact-file-names.js';
+function legacyJsonStem(fileName) {
+    if (!fileName.endsWith('.json'))
+        return null;
+    if (isReportFileName(fileName))
+        return null;
+    if (fileName.includes('.json.tmp.'))
+        return null;
+    return fileName.slice(0, -'.json'.length);
+}
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function looksLikeObserveHealthReport(value) {
+    return isObject(value.meta) && isObject(value.bySkill) && isObject(value.overall);
+}
+function targetStemForLegacyReport(domain, fileName, data) {
+    const fileStem = legacyJsonStem(fileName);
+    if (!fileStem || !isObject(data))
+        return null;
+    if (domain === 'report') {
+        const kind = data.kind;
+        return (kind === 'evaluation' || kind === 'batch-evaluation') && typeof data.id === 'string' && data.id
+            ? data.id
+            : null;
+    }
+    if (domain === 'doctor') {
+        if (data.kind !== 'doctor' || typeof data.id !== 'string' || !Array.isArray(data.skills) || data.skills.length !== 1)
+            return null;
+        const skill = data.skills[0];
+        return isObject(skill) && typeof skill.skillName === 'string' && skill.skillName
+            ? doctorReportFileStem(skill.skillName, data.id)
+            : null;
+    }
+    if (domain === 'observe-health') {
+        if (data.kind !== 'observe-health' && !looksLikeObserveHealthReport(data))
+            return null;
+        return stripDomainPrefix(fileStem.replace(/-observe-health$/, ''), 'observe-health');
+    }
+    if (data.kind !== 'observe-inbox')
+        return null;
+    return stripDomainPrefix(fileStem.replace(/-observe-inbox$/, ''), 'observe-inbox');
+}
+/**
+ * One-shot migration for pre-`.report.json` run artifacts.
+ *
+ * This is deliberately scoped to measurement report directories. It does not make
+ * bare `.json` a normal reader format again; it just renames known legacy report
+ * files into the canonical name so old local data can be discovered, rotated, and
+ * eventually garbage-collected by the new code paths.
+ */
+export function migrateLegacyReportFiles(dir, domain) {
+    if (!existsSync(dir))
+        return;
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        if (!legacyJsonStem(file))
+            continue;
+        const sourcePath = join(dir, file);
+        let targetStem = null;
+        try {
+            targetStem = targetStemForLegacyReport(domain, file, JSON.parse(readFileSync(sourcePath, 'utf-8')));
+        }
+        catch {
+            continue;
+        }
+        if (!targetStem)
+            continue;
+        const targetPath = reportFilePath(dir, targetStem);
+        try {
+            if (existsSync(targetPath)) {
+                unlinkSync(sourcePath);
+            }
+            else {
+                renameSync(sourcePath, targetPath);
+            }
+        }
+        catch {
+            // Best-effort migration only. Readers will ignore the legacy file if it remains.
+        }
+    }
+}

package/dist/inputs/sample-locator.d.ts

@@ -0,0 +1,23 @@
+export declare const PROJECT_SAMPLE_FILENAMES: readonly ["eval-samples.json", "eval-samples.yaml", "eval-samples.yml"];
+export declare const SKILL_LOCAL_SAMPLE_FILENAMES: readonly ["samples.json", "samples.yaml", "samples.yml"];
+export interface DeprecatedSkillSamplesHint {
+    oldPath: string;
+    newPath: string;
+}
+export declare function isExistingDirectory(path: string): boolean;
+export declare function hasLoadableSampleFile(dir: string): boolean;
+export declare function findProjectSamplesFile(dir: string): string | null;
+export declare function skillLocalSamplesDir(skillRoot: string): string;
+export declare function defaultSkillLocalSamplesFile(skillRoot: string): string;
+export declare function hasUsableSamplesPath(path: string): boolean;
+export declare function findSkillLocalSamplesDir(skillRoot: string): string | null;
+export declare function findSkillSamplesPath(skillRoot: string): string | null;
+export declare function findDeprecatedSkillSamplesHint(skillRoot: string): DeprecatedSkillSamplesHint | null;
+export declare function findFlatSkillSamplesPath(skillDir: string, skillName: string): string | null;
+export declare function defaultFlatSkillSamplesFile(skillDir: string, skillName: string): string;
+export declare function isDirectorySkillRoot(path: string): boolean;
+export declare function findNamedSkillSamplesPath(skillDir: string, skillName: string): string | null;
+export declare function findSingleTreatmentSamplesPath(treatmentExpr: string, skillDir: string, cwd?: string): string | null;
+export declare function findSingleTreatmentDeprecatedSamplesHint(treatmentExpr: string, skillDir: string, cwd?: string): DeprecatedSkillSamplesHint | null;
+export declare function findDoctorSamplesPath(target: string | null, cwd: string): string | null;
+export declare function findDoctorDeprecatedSamplesHint(target: string | null, cwd: string): DeprecatedSkillSamplesHint | null;

package/dist/inputs/sample-locator.js

@@ -0,0 +1,195 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+export const PROJECT_SAMPLE_FILENAMES = ['eval-samples.json', 'eval-samples.yaml', 'eval-samples.yml'];
+export const SKILL_LOCAL_SAMPLE_FILENAMES = ['samples.json', 'samples.yaml', 'samples.yml'];
+const SAMPLE_FILE_RE = /\.(json|ya?ml)$/i;
+const RESERVED_SAMPLE_FILE_RE = /^(report|health|_)/i;
+function isExistingFile(path) {
+    try {
+        return existsSync(path) && statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function isExistingDirectory(path) {
+    try {
+        return existsSync(path) && statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function hasLoadableSampleFile(dir) {
+    if (!isExistingDirectory(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((file) => SAMPLE_FILE_RE.test(file) && !RESERVED_SAMPLE_FILE_RE.test(file));
+    }
+    catch {
+        return false;
+    }
+}
+export function findProjectSamplesFile(dir) {
+    for (const name of PROJECT_SAMPLE_FILENAMES) {
+        const candidate = join(dir, name);
+        if (isExistingFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function skillLocalSamplesDir(skillRoot) {
+    return join(skillRoot, '.omk');
+}
+export function defaultSkillLocalSamplesFile(skillRoot) {
+    return join(skillLocalSamplesDir(skillRoot), SKILL_LOCAL_SAMPLE_FILENAMES[0]);
+}
+export function hasUsableSamplesPath(path) {
+    if (isExistingFile(path))
+        return true;
+    return hasLoadableSampleFile(path);
+}
+export function findSkillLocalSamplesDir(skillRoot) {
+    const dir = skillLocalSamplesDir(skillRoot);
+    return hasLoadableSampleFile(dir) ? dir : null;
+}
+export function findSkillSamplesPath(skillRoot) {
+    return findSkillLocalSamplesDir(skillRoot);
+}
+export function findDeprecatedSkillSamplesHint(skillRoot) {
+    if (!isDirectorySkillRoot(skillRoot))
+        return null;
+    for (const name of PROJECT_SAMPLE_FILENAMES) {
+        const oldPath = join(skillRoot, name);
+        if (isExistingFile(oldPath)) {
+            return { oldPath, newPath: defaultSkillLocalSamplesFile(skillRoot) };
+        }
+    }
+    return null;
+}
+export function findFlatSkillSamplesPath(skillDir, skillName) {
+    for (const ext of ['json', 'yaml', 'yml']) {
+        const candidate = join(skillDir, `${skillName}.eval-samples.${ext}`);
+        if (isExistingFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function defaultFlatSkillSamplesFile(skillDir, skillName) {
+    return join(skillDir, `${skillName}.eval-samples.json`);
+}
+export function isDirectorySkillRoot(path) {
+    return isExistingDirectory(path) && isExistingFile(join(path, 'SKILL.md'));
+}
+export function findNamedSkillSamplesPath(skillDir, skillName) {
+    const flatSkillPath = join(skillDir, `${skillName}.md`);
+    if (isExistingFile(flatSkillPath)) {
+        return findFlatSkillSamplesPath(skillDir, skillName);
+    }
+    const dirSkillRoot = join(skillDir, skillName);
+    if (isDirectorySkillRoot(dirSkillRoot)) {
+        return findSkillSamplesPath(dirSkillRoot);
+    }
+    return null;
+}
+function findSamplesForExistingSkillPath(path) {
+    if (isExistingDirectory(path)) {
+        return findSkillSamplesPath(path);
+    }
+    const parent = dirname(path);
+    if (basename(path) === 'SKILL.md') {
+        return findSkillSamplesPath(parent);
+    }
+    if (/\.md$/i.test(path)) {
+        const skillName = basename(path).replace(/\.md$/i, '');
+        return findFlatSkillSamplesPath(parent, skillName);
+    }
+    return findProjectSamplesFile(parent);
+}
+function findDeprecatedSamplesForExistingSkillPath(path) {
+    if (isExistingDirectory(path)) {
+        return findDeprecatedSkillSamplesHint(path);
+    }
+    if (basename(path) === 'SKILL.md') {
+        return findDeprecatedSkillSamplesHint(dirname(path));
+    }
+    return null;
+}
+export function findSingleTreatmentSamplesPath(treatmentExpr, skillDir, cwd = process.cwd()) {
+    const resolved = resolve(cwd, treatmentExpr);
+    if (existsSync(resolved)) {
+        const samplesPath = findSamplesForExistingSkillPath(resolved);
+        if (samplesPath)
+            return samplesPath;
+    }
+    return findNamedSkillSamplesPath(skillDir, treatmentExpr);
+}
+export function findSingleTreatmentDeprecatedSamplesHint(treatmentExpr, skillDir, cwd = process.cwd()) {
+    const resolved = resolve(cwd, treatmentExpr);
+    if (existsSync(resolved)) {
+        return findDeprecatedSamplesForExistingSkillPath(resolved);
+    }
+    const flatSkillPath = join(skillDir, `${treatmentExpr}.md`);
+    if (isExistingFile(flatSkillPath))
+        return null;
+    return findDeprecatedSkillSamplesHint(join(skillDir, treatmentExpr));
+}
+function projectSampleSearchDirs(target, cwd) {
+    const dirs = [];
+    const add = (dir) => {
+        const abs = resolve(dir);
+        if (!dirs.includes(abs))
+            dirs.push(abs);
+    };
+    if (target) {
+        const absTarget = resolve(target);
+        if (existsSync(absTarget)) {
+            if (isExistingDirectory(absTarget)) {
+                if (isDirectorySkillRoot(absTarget)) {
+                    add(dirname(dirname(absTarget)));
+                }
+                else {
+                    add(absTarget);
+                    add(dirname(absTarget));
+                    add(dirname(dirname(absTarget)));
+                }
+            }
+            else {
+                const parent = dirname(absTarget);
+                if (basename(absTarget) === 'SKILL.md') {
+                    add(dirname(dirname(parent)));
+                }
+                else {
+                    add(parent);
+                    add(dirname(parent));
+                }
+            }
+        }
+    }
+    add(cwd);
+    return dirs;
+}
+export function findDoctorSamplesPath(target, cwd) {
+    if (target) {
+        const absTarget = resolve(target);
+        if (existsSync(absTarget)) {
+            const targetSamples = findSamplesForExistingSkillPath(absTarget);
+            if (targetSamples)
+                return targetSamples;
+        }
+    }
+    for (const dir of projectSampleSearchDirs(target, cwd)) {
+        const samplesPath = findProjectSamplesFile(dir);
+        if (samplesPath)
+            return samplesPath;
+    }
+    return null;
+}
+export function findDoctorDeprecatedSamplesHint(target, cwd) {
+    if (!target)
+        return null;
+    const absTarget = resolve(cwd, target);
+    if (!existsSync(absTarget))
+        return null;
+    return findDeprecatedSamplesForExistingSkillPath(absTarget);
+}

package/dist/inputs/skill-loader.js

@@ -5,6 +5,7 @@ import { execFileSync } from 'node:child_process';
 import { extractSkillHardRules, extractSkillWorkflows } from '../shared/hard-rules.js';
 import { hashArtifactSource, hashBytes, isDistributablePath } from './content-hash.js';
 import { materializeIsolatedCopy } from './materialize-copy.js';
+import { findFlatSkillSamplesPath, findSkillSamplesPath } from './sample-locator.js';
 function parseFrontmatterPreflight(content) {
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
@@ -388,14 +389,9 @@ export function discoverBatchSkills(skillDir) {
         const mdMatch = entry.endsWith('.md') && !entry.endsWith('.eval-samples.json');
         if (mdMatch) {
             const name = entry.slice(0, -3);
-            const candidates = [
-                join(skillDir, name, '.omk'),
-                join(skillDir, `${name}.eval-samples.json`),
-                join(skillDir, `${name}.eval-samples.yaml`),
-                join(skillDir, `${name}.eval-samples.yml`),
-            ].filter(existsSync);
-            if (candidates.length > 0) {
-                skills.push({ name, skillPath: join(skillDir, entry), samplesPath: candidates[0] });
+            const samplesPath = findFlatSkillSamplesPath(skillDir, name);
+            if (samplesPath) {
+                skills.push({ name, skillPath: join(skillDir, entry), samplesPath });
             }
             else {
                 warned.push(name);
@@ -406,15 +402,9 @@ export function discoverBatchSkills(skillDir) {
             const skillMd = join(entryPath, 'SKILL.md');
             if (!existsSync(skillMd))
                 continue;
-            // .omk/ dir (loadSamples handles dir mode) > .omk/samples.json > eval-samples.{json,yaml,yml}
-            const omkDir = join(entryPath, '.omk');
-            const candidates = [
-                ...(existsSync(omkDir) ? [omkDir] : []),
-                join(entryPath, 'eval-samples.json'),
-                join(entryPath, 'eval-samples.yaml'),
-                join(entryPath, 'eval-samples.yml'),
-            ];
-            const samplesPath = candidates.find(existsSync);
+            if (existsSync(join(skillDir, `${entry}.md`)))
+                continue;
+            const samplesPath = findSkillSamplesPath(entryPath);
             if (samplesPath) {
                 skills.push({ name: entry, skillPath: skillMd, samplesPath });
             }

package/dist/observability/inbox.js

@@ -2,13 +2,15 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { OMK_HOME } from '../eval-core/default-dirs.js';
+import { isReportFileName, reportFilePath } from '../eval-core/artifact-file-names.js';
+import { migrateLegacyReportFiles } from '../eval-core/report-file-migration.js';
 import { extractGapSignalsFromTrace } from '../analysis/gap-analyzer.js';
 import { ccTracesToResultEntries } from './trace-adapter.js';
 import { isSearchToolCall, toolCallQuery } from '../shared/tool-search.js';
 import { durationMsBetween } from '../shared/time.js';
 import { buildObservationExperienceReport, normalizeObservationExperienceReport, } from './experience.js';
 // observe inbox（观测收件箱）产物根目录。导出名沿用 *_OBSERVATIONS_DIR 以少动 importer,
-// 但落盘目录已统一到 observe-inbox 词根(命令 omk observe inbox / 文件 *-observe-inbox.json / kind observe-inbox)。
+// 但落盘目录已统一到 observe-inbox 词根(命令 omk observe inbox / kind observe-inbox)。
 // 项目级 .omk/observe-inbox 优先、全局兜底 —— 这套 project/global 归属是既有正常行为,本次只改名不改归属。
 export const DEFAULT_PROJECT_OBSERVATIONS_DIR = join(process.cwd(), '.omk', 'observe-inbox');
 export const DEFAULT_GLOBAL_OBSERVATIONS_DIR = join(OMK_HOME, 'observe-inbox');
@@ -529,10 +531,11 @@ function compareInboxItems(a, b) {
 }
 export function saveObservationInboxReport(report, outDir = DEFAULT_OBSERVATIONS_DIR) {
     mkdirSync(outDir, { recursive: true });
+    migrateLegacyReportFiles(outDir, 'observe-inbox');
     // 保留毫秒;同秒不同毫秒生成的两份 report 不应静默互相覆盖。
     // 例: '2026-05-07T12:00:00.999Z' → '2026-05-07T12-00-00-999'
     const stamp = report.meta.generatedAt.replace(/[:.]/g, '-').replace(/Z$/, '');
-    const path = join(outDir, `${stamp}-observe-inbox.json`);
+    const path = reportFilePath(outDir, stamp);
     writeFileSync(path, JSON.stringify(report, null, 2));
     return path;
 }
@@ -543,8 +546,9 @@ export function loadObservationInboxReports(dir = DEFAULT_OBSERVATIONS_DIR) {
         }
         return [];
     }
+    migrateLegacyReportFiles(dir, 'observe-inbox');
     return readdirSync(dir)
-        .filter((file) => file.endsWith('-observe-inbox.json'))
+        .filter(isReportFileName)
         .map((file) => {
         try {
             const report = normalizeObservationInboxReport(JSON.parse(readFileSync(join(dir, file), 'utf-8')));

package/dist/server/report-server.js

@@ -14,6 +14,8 @@ import { renderManagedList, renderManagedHistory } from '../renderer/managed-his
 import { DEFAULT_JOBS_DIR } from '../eval-core/default-dirs.js';
 import { resolveObserveHealthDir, projectObserveHealthDir, resolveDoctorsDir, projectDoctorsDir, projectReportsDir, globalReportsDir } from '../eval-core/measurement-dirs.js';
 import { listObserveCards, listDoctorCards, listLiveObserveCards } from '../eval-core/artifact-index.js';
+import { isReportFileName, reportFilePath, reportFileStem } from '../eval-core/artifact-file-names.js';
+import { migrateLegacyReportFiles } from '../eval-core/report-file-migration.js';
 import { buildSkillIndex } from './skill-index.js';
 import { createFileJobStore } from './job-store.js';
 import { createFileStore, queryJob, queryJobList, queryRun, queryRunList, queryTrend } from './report-store.js';
@@ -46,18 +48,20 @@ function loadChartJsBundle() {
 }
 function listAnalyses(dir, includeCards = false) {
     const items = [];
+    migrateLegacyReportFiles(dir, 'observe-health');
     // live 扫描 dir 存在才做;dir 不存在(默认机器级模式下当前项目还没 .omk/observe-health、全局也空)时 live 为空,
     // 但**不能早退** —— 后面仍要按 includeCards 合并别项目卡片,否则 observe 列表会与合卡片的 /api/skills 口径分裂。
     if (existsSync(dir)) {
         for (const file of readdirSync(dir)) {
-            if (!file.endsWith('.json'))
+            const id = reportFileStem(file);
+            if (!id)
                 continue;
             try {
                 const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
                 if (!data.meta || !data.overall)
                     continue;
                 items.push({
-                    id: file.replace(/\.json$/, ''),
+                    id,
                     generatedAt: data.meta.generatedAt,
                     sessionCount: data.meta.sessionCount,
                     segmentCount: data.meta.segmentCount,
@@ -89,7 +93,8 @@ function listAnalyses(dir, includeCards = false) {
     return items;
 }
 function loadAnalysis(dir, id, includeCards = false) {
-    const path = join(dir, `${id}.json`);
+    migrateLegacyReportFiles(dir, 'observe-health');
+    const path = reportFilePath(dir, id);
     if (existsSync(path)) {
         try {
             return JSON.parse(readFileSync(path, 'utf-8'));
@@ -114,9 +119,10 @@ function loadAnalysis(dir, id, includeCards = false) {
  *  优先返回含该 skill 的那份；都不含时回退首个 id 命中（单 skill / 无参行为不变）。 */
 function loadDoctorReport(dir, id, skillName, includeCards = false) {
     let fallback = null;
+    migrateLegacyReportFiles(dir, 'doctor');
     if (existsSync(dir)) {
         for (const file of readdirSync(dir)) {
-            if (!file.endsWith('.json'))
+            if (!isReportFileName(file))
                 continue;
             try {
                 const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));