oh-my-knowledge 0.35.0 → 0.37.0

package/dist/server/report-server.js

@@ -5,8 +5,9 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { renderReportDocumentDetail, renderTrendsPage, renderRunList } from '../renderer/html-renderer.js';
 import { renderSkillList } from '../renderer/skill-list-renderer.js';
-import { renderSkillDetail } from '../renderer/skill-detail-renderer.js';
 import { renderSkillHealthReport } from '../renderer/skill-health-renderer.js';
+import { renderDoctorDetail } from '../renderer/doctor-detail-renderer.js';
+import { assessHealth } from '../renderer/skill-detail-renderer.js';
 import { renderObservationInboxPage } from '../renderer/observation-inbox-renderer.js';
 import { DEFAULT_LANG, t, layout } from '../renderer/layout.js';
 import { buildSkillIndex } from './skill-index.js';
@@ -80,6 +81,28 @@ function loadAnalysis(dir, id) {
         return null;
     }
 }
+/** 扫 doctorsDir 找 id 匹配的 doctor 报告（文件名不一定等于 report id）。
+ *  批量 doctor 会按 skill 拆成多份共享同一 id 的 per-skill 文件，传 skillName 时
+ *  优先返回含该 skill 的那份；都不含时回退首个 id 命中（单 skill / 无参行为不变）。 */
+function loadDoctorReport(dir, id, skillName) {
+    if (!existsSync(dir))
+        return null;
+    let fallback = null;
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+            if (data?.kind !== 'doctor' || data.id !== id)
+                continue;
+            if (!skillName || data.skills?.some((s) => s.skillName === skillName))
+                return data;
+            fallback ??= data;
+        }
+        catch { /* skip */ }
+    }
+    return fallback;
+}
 /**
  * 扫 analyses/ 所有 JSON,按 skillName 过滤,按时间排序成 trend points。
  */
@@ -204,6 +227,85 @@ function readJsonBody(req, maxBytes = 1024 * 1024) {
         req.on('error', reject);
     });
 }
+function fmtHistDate(ts, lang) {
+    if (!ts)
+        return '-';
+    try {
+        const d = new Date(ts);
+        return d.toLocaleString(lang === 'zh' ? 'zh-CN' : 'en-US', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' });
+    }
+    catch {
+        return ts;
+    }
+}
+// 报告详情页顶部「skill 上下文」:doctor/eval/observe 维度切换器 + 「全部历史」弹框(该 skill 历次 run)。
+// observe 详情是 fleet 级日报,无 per-skill 页,observe chip 只当状态点不可点。
+function buildSkillContext(entry, currentDim, currentReportId, insights, lang) {
+    const zh = lang === 'zh';
+    const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
+    const amp = lang === DEFAULT_LANG ? '' : `&lang=${lang}`;
+    // 综合健康分(= 跨维度聚合,与首页列表同一口径)— 报告页只显单维度分数,这里把「总分」也带上。
+    const health = assessHealth(entry, insights, lang);
+    const d = entry.doctor;
+    const dTotal = d ? d.passCount + d.warnCount + d.failCount : 0;
+    const dScore = d && dTotal > 0 ? Math.round(((d.passCount + d.warnCount * 0.5) / dTotal) * 100) : null;
+    const dBand = d ? (d.failCount > 0 ? 'red' : d.warnCount > 0 ? 'yellow' : 'green') : 'gray';
+    const ev = entry.eval;
+    const evScore = ev && ev.compositeScore != null ? Math.round((ev.compositeScore / 5) * 100) : null;
+    const evBand = ev && ev.compositeScore != null
+        ? (ev.compositeScore >= 4 ? 'green' : ev.compositeScore >= 3 ? 'yellow' : 'red') : 'gray';
+    const ob = entry.observe;
+    const obScore = ob ? Math.round((1 - ob.gapRate) * 100) : null;
+    const obBand = ob ? ob.healthBand : 'gray';
+    // 历史:eval + doctor 历次 run,各自新→旧。点行跳到那次报告。
+    // evalHistory 是「每轮一条」,但一份 evolve 报告(多轮)是同一个 reportId —— 按 reportId 去重,
+    // 一份报告只算一条(取末轮 treatment 分数,与报告头部一致),否则同一报告的多轮会都标「当前」。
+    const evalRoundCount = new Map();
+    const evalByReport = new Map();
+    for (const h of entry.evalHistory) {
+        evalRoundCount.set(h.reportId, (evalRoundCount.get(h.reportId) ?? 0) + 1);
+        evalByReport.set(h.reportId, h); // 末轮(最高 round)胜出 —— history 已按 timestamp#round 升序
+    }
+    const evalHist = [...evalByReport.values()].reverse().map((h) => {
+        const rounds = evalRoundCount.get(h.reportId) ?? 1;
+        return {
+            dim: 'eval',
+            dateText: fmtHistDate(h.timestamp, lang),
+            scoreText: h.compositeScore != null ? `${h.compositeScore.toFixed(2)} / 5` : '—',
+            band: (h.compositeScore == null ? 'gray' : h.compositeScore >= 4 ? 'green' : h.compositeScore >= 3 ? 'yellow' : 'red'),
+            metaText: `${h.passCount}/${h.totalSamples} ${zh ? '通过' : 'pass'}${h.failCount > 0 ? ` · ${h.failCount} ${zh ? '失败' : 'fail'}` : ''}${rounds > 1 ? ` · ${rounds} ${zh ? '轮' : 'rounds'}` : ''}`,
+            href: `/reports/${encodeURIComponent(h.reportId)}${langQ}`,
+            current: h.reportId === currentReportId,
+        };
+    });
+    const doctorHist = [...entry.doctorHistory].reverse().map((h) => {
+        const tot = h.passCount + h.warnCount + h.failCount;
+        return {
+            dim: 'doctor',
+            dateText: fmtHistDate(h.timestamp, lang),
+            scoreText: tot > 0 ? `${Math.round(((h.passCount + h.warnCount * 0.5) / tot) * 100)}` : '—',
+            band: (h.failCount > 0 ? 'red' : h.warnCount > 0 ? 'yellow' : 'green'),
+            metaText: `${h.passCount}✓ ${h.warnCount}⚠ ${h.failCount}✗`,
+            href: `/doctors/${encodeURIComponent(h.reportId)}?skill=${encodeURIComponent(entry.skillName)}${amp}`,
+            current: h.reportId === currentReportId,
+        };
+    });
+    return {
+        skillName: entry.skillName,
+        overall: { score: health.score, band: health.color },
+        // 当前维度 chip 不显分数(hero ring 已显示「本报告」分数,避免与「最新」分数冲突);非当前维度显「最新」分数 + 链接。
+        chips: [
+            { dim: 'doctor', label: zh ? '体检' : 'Doctor', score: currentDim === 'doctor' ? null : dScore, band: dBand,
+                href: currentDim === 'doctor' || !d ? null : `/doctors/${encodeURIComponent(d.reportId)}?skill=${encodeURIComponent(entry.skillName)}${amp}`,
+                active: currentDim === 'doctor' },
+            { dim: 'eval', label: zh ? '评测' : 'Eval', score: currentDim === 'eval' ? null : evScore, band: evBand,
+                href: currentDim === 'eval' || !ev ? null : `/reports/${encodeURIComponent(ev.reportId)}${langQ}`,
+                active: currentDim === 'eval' },
+            { dim: 'observe', label: zh ? '观察' : 'Observe', score: obScore, band: obBand, href: null, active: false },
+        ],
+        history: [...evalHist, ...doctorHist],
+    };
+}
 function renderSkillDiffPage(diff, lang = DEFAULT_LANG) {
     const { fromId, toId, fromAt, toAt, rows } = diff;
     const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
@@ -561,6 +663,29 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
                 res.end(JSON.stringify({ error: 'method not allowed' }));
                 return;
             }
+            const doctorDetailMatch = path.match(/^\/doctors\/(.+)$/);
+            if (doctorDetailMatch) {
+                const id = decodeURIComponent(doctorDetailMatch[1]);
+                const skillName = parsed.searchParams.get('skill') ?? '';
+                const report = loadDoctorReport(doctorsDir, id, skillName || undefined);
+                if (!report) {
+                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                    res.end(lang === 'en' ? 'doctor report not found' : '体检报告不存在');
+                    return;
+                }
+                let ctx;
+                if (skillName) {
+                    const runs = await reportStore.list();
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
+                    const entry = idx.entries.find((en) => en.skillName === skillName);
+                    if (entry)
+                        ctx = buildSkillContext(entry, 'doctor', id, idx.insightsBySkill.get(entry.skillName) ?? [], lang);
+                }
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                const langQ = lang === DEFAULT_LANG ? '' : `?lang=${lang}`;
+                res.end(renderDoctorDetail(report, skillName, langQ, lang, ctx));
+                return;
+            }
             const analysisDetailMatch = path.match(/^\/analyses\/(.+)$/);
             if (analysisDetailMatch) {
                 const id = decodeURIComponent(analysisDetailMatch[1]);
@@ -708,9 +833,19 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
             }
             const reportPageMatch = path.match(/^\/reports\/(.+)$/);
             if (reportPageMatch) {
-                const report = await queryRun(reportStore, decodeURIComponent(reportPageMatch[1]));
+                const reportId = decodeURIComponent(reportPageMatch[1]);
+                const report = await queryRun(reportStore, reportId);
+                let ctx;
+                if (report && report.kind === 'evaluation') {
+                    const runs = await reportStore.list();
+                    const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
+                    // 按 evalHistory 匹配(非仅最新),历史 eval 报告也能定位到所属 skill。
+                    const entry = idx.entries.find((en) => en.evalHistory.some((h) => h.reportId === reportId));
+                    if (entry)
+                        ctx = buildSkillContext(entry, 'eval', reportId, idx.insightsBySkill.get(entry.skillName) ?? [], lang);
+                }
                 res.writeHead(report ? 200 : 404, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(renderReportDocumentDetail(report, lang));
+                res.end(renderReportDocumentDetail(report, lang, ctx));
                 return;
             }
             // 老 run 列表 — 兼容老书签。/skills/ 切换为默认后,run 列表挪这里。
@@ -745,31 +880,10 @@ export function createReportServer({ port, host: hostOption, reportsDir = DEFAUL
                 }));
                 return;
             }
-            // /skills/<name> 详情页 — 4 张卡片(doctor / eval-评分 / eval-功能 / observe)
-            // + 跨报告 cross-link + 行动建议。
-            const skillDetailMatch = path.match(/^\/skills\/(.+)$/);
-            if (skillDetailMatch) {
-                const skillName = decodeURIComponent(skillDetailMatch[1]);
-                const runs = await reportStore.list();
-                const idx = buildSkillIndex(runs, analysesDir, doctorsDir, observationsDir);
-                const entry = idx.entries.find((e) => e.skillName === skillName);
-                if (!entry) {
-                    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-                    res.end(`Skill not found: ${skillName}`);
-                    return;
-                }
-                // 加载完整 eval 报告(为详情页提供 layered scores / coverage / per-sample diagnostic)
-                let evalReport = null;
-                if (entry.eval) {
-                    const r = await reportStore.get(entry.eval.reportId);
-                    if (r && r.reportKind === 'evaluation')
-                        evalReport = r;
-                }
-                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                const insights = idx.insightsBySkill.get(skillName) ?? [];
-                res.end(renderSkillDetail(entry, evalReport, lang, insights));
-                return;
-            }
+            // 注:/skills/<name> 详情页(hub)已下线 — 首页点行直接进 eval/doctor 报告,跨维度靠
+            // 报告页 chip 条 +「全部历史」弹框,不再有中间汇总页。该路由不做兼容重定向:Studio
+            // 是本地临时服务器、端口每次启动都变,跨会话书签 localhost:<port> 本就失效,且 PR 内
+            // 已无任何链接指向它。未匹配的 /skills/<name> 直接落到下方通用 404。
             const skillDiagnosticsApiMatch = path.match(/^\/api\/skills\/(.+)\/diagnostics$/);
             if (skillDiagnosticsApiMatch) {
                 const skillName = decodeURIComponent(skillDiagnosticsApiMatch[1]);

package/dist/server/report-store.d.ts

@@ -20,7 +20,7 @@ export declare function queryJobList(jobStore: JobStore, query?: JobQuery): Prom
 export declare function queryJob(jobStore: JobStore, id: string): Promise<EvaluationJob | null>;
 export interface RunListItem {
     id: string;
-    reportKind: ReportDocument['reportKind'];
+    kind: ReportDocument['kind'];
     meta: ReportDocument['meta'];
     summary?: EvaluationReport['summary'];
     items?: BatchEvaluationReport['items'];

package/dist/server/report-store.js

@@ -39,32 +39,33 @@ export function createFileStore(dir) {
         if (!data || typeof data !== 'object')
             return null;
         const record = data;
-        if (record.reportKind === 'evaluation') {
+        const kind = record.kind === 'evaluation' || record.kind === 'batch-evaluation'
+            ? record.kind
+            : undefined;
+        if (kind === 'evaluation') {
             if (!record.meta || !record.summary || !Array.isArray(record.results))
                 return null;
-            return { ...record, id: typeof record.id === 'string' && record.id ? record.id : fallbackId };
+            return {
+                ...record,
+                kind,
+                id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
+            };
         }
-        if (record.reportKind === 'batch-evaluation') {
+        if (kind === 'batch-evaluation') {
             if (!record.meta || !Array.isArray(record.items))
                 return null;
-            return { ...record, id: typeof record.id === 'string' && record.id ? record.id : fallbackId };
-        }
-        if (record.kind === undefined
-            && record.overview === undefined
-            && record.artifacts === undefined
-            && record.meta
-            && record.summary
-            && Array.isArray(record.results)) {
             return {
                 ...record,
-                reportKind: 'evaluation',
+                kind,
                 id: typeof record.id === 'string' && record.id ? record.id : fallbackId,
             };
         }
+        // 只认 canonical 顶层 `kind`(evaluation / batch-evaluation)。不再为旧格式(顶层无该判别字段的
+        // 历史文件)做读兼容 —— 顶层 kind cutover 是硬切换,旧文件直接判脏丢弃。
         return null;
     }
     function isEvaluationReport(report) {
-        return report.reportKind === 'evaluation';
+        return report.kind === 'evaluation';
     }
     // Studio 每个 / 和 /skills/<name> 请求都调 list(),里面对每个 .json 同步 readFile +
     // JSON.parse。报告数上来后这是主性能瓶颈。缓存策略:fingerprint = dir mtime + 文件名
@@ -217,9 +218,9 @@ export async function queryJob(jobStore, id) {
 export async function queryRunList(reportStore) {
     return (await reportStore.list()).map((report) => ({
         id: report.id,
-        reportKind: report.reportKind,
+        kind: report.kind,
         meta: report.meta,
-        ...(report.reportKind === 'evaluation' ? { summary: report.summary } : { items: report.items }),
+        ...(report.kind === 'evaluation' ? { summary: report.summary } : { items: report.items }),
     }));
 }
 export async function queryRun(reportStore, id) {

package/dist/server/skill-index.js

@@ -69,7 +69,7 @@ function buildIndexFingerprint(reports, analysesDir, doctorsDir, observationsDir
     // 每一段的 right-hand-side 从旧的 "{dir-mtime}-{file-count}" 双标量升级成
     // safeDirJsonContentFingerprint 返回的 "{dir-mtime}|{file1}:{m}:{s},..."
     // content-aware 字符串。
-    const reportIds = reports.map((r) => `${r.id}:${r.meta?.timestamp ?? ''}:${r.reportKind === 'evaluation' ? r.meta.evolve?.skillName ?? '' : ''}`).join(',');
+    const reportIds = reports.map((r) => `${r.id}:${r.meta?.timestamp ?? ''}:${r.kind === 'evaluation' ? r.meta.evolve?.skillName ?? '' : ''}`).join(',');
     const doctorsFp = safeDirJsonContentFingerprint(doctorsDir);
     const analysesFp = safeDirJsonContentFingerprint(analysesDir);
     const observationsFp = safeDirJsonContentFingerprint(observationsDir);
@@ -223,7 +223,8 @@ function scanDoctorReports(dir) {
             continue;
         try {
             const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
-            if (data?.reportKind !== 'doctor' || !Array.isArray(data.skills))
+            const kind = data?.kind === 'doctor' ? data.kind : null;
+            if (!kind || !Array.isArray(data.skills))
                 continue;
             const ts = data.timestamp;
             for (const sr of data.skills) {
@@ -260,7 +261,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // ── eval 聚合(历史 list)─────────────────────────────────
     const evalBy = {};
     for (const r of reports) {
-        if (r.reportKind !== 'evaluation')
+        if (r.kind !== 'evaluation')
             continue;
         const variants = r.meta.variants || [];
         for (const v of variants) {
@@ -347,7 +348,7 @@ export function buildSkillIndex(reports, analysesDir, doctorsDir, observationsDi
     // list 页对每个 entry 跑 detectInsights 的 CPU 开销迁移到这里,只 miss 时算一次。
     const insightsBySkill = new Map();
     for (const ent of entries) {
-        const evalReport = ent.eval ? reports.find((r) => r.id === ent.eval.reportId && r.reportKind === 'evaluation') : undefined;
+        const evalReport = ent.eval ? reports.find((r) => r.id === ent.eval.reportId && r.kind === 'evaluation') : undefined;
         insightsBySkill.set(ent.skillName, detectInsights(ent, evalReport ?? null, {
             diagnostics: diagnosisBundle.bySkill[ent.skillName] ?? [],
         }));

package/dist/types/doctor.d.ts

@@ -10,7 +10,7 @@ export type DoctorSkillStatus = 'pass' | 'warn' | 'fail';
 export type DoctorOutcome = 'passed' | 'warnings_only' | 'failed';
 /** Bumped whenever DoctorReport schema changes in a way CI consumers should
  *  be able to detect. CI can pin/check this when parsing the JSON. */
-export declare const DOCTOR_REPORT_SCHEMA_VERSION = "2.0.0";
+export declare const DOCTOR_REPORT_SCHEMA_VERSION = "3.0.0";
 export interface DoctorRuleResult {
     ruleId: string;
     severity: DoctorSeverity;
@@ -85,6 +85,10 @@ export interface DoctorRule {
     severity: DoctorSeverity;
     /** i18n key,terminal 渲染时用作 rule 标题。 */
     labelKey: string;
+    /** true = 需要外部 I/O(网络 / LLM)的"在线"检查,跟 skill_health composer 同档:
+     *  默认 `omk doctor` 会跑,`--static-only` 离线模式跳过。endpoint 自定义维度置 true。
+     *  缺省(undefined/false)= 纯静态低成本检查(内置 4 条),静态模式才跑。 */
+    external?: boolean;
     check(ctx: DoctorContext): Promise<DoctorRuleCheckOutcome>;
 }
 export interface DoctorSkillReport {
@@ -94,7 +98,7 @@ export interface DoctorSkillReport {
     status: DoctorSkillStatus;
 }
 export interface DoctorReport {
-    reportKind: 'doctor';
+    kind: 'doctor';
     /** Schema version the JSON consumer can pin/check. Bumped on any
      *  user-visible change to this report's shape. See DOCTOR_REPORT_SCHEMA_VERSION. */
     schemaVersion: string;
@@ -126,6 +130,21 @@ export interface DoctorReport {
         total: number;
     };
 }
+/** 批量体检的 per-skill 进度事件。runDoctor 在遍历 artifacts 时,每个 skill
+ *  开始(skill_start)和结束(skill_done)各发一次,对齐 eval 的 per-sample 进度。 */
+export interface DoctorProgressInfo {
+    phase: 'skill_start' | 'skill_done';
+    /** 第几个 skill(1-based)。 */
+    index: number;
+    /** skill 总数。 */
+    total: number;
+    skillName: string;
+    /** 仅 skill_done:该 skill 的最终状态。 */
+    status?: DoctorSkillStatus;
+    /** 仅 skill_done:该 skill 全部 rule 的执行耗时(ms)。 */
+    durationMs?: number;
+}
+export type DoctorProgressCallback = (info: DoctorProgressInfo) => void;
 export interface DoctorRunOptions {
     /** 单 skill 文件 / 目录 / null(=cwd 当前目录批量)。当 artifacts 显式提供时, target 被忽略。 */
     target?: string | null;
@@ -153,4 +172,7 @@ export interface DoctorRunOptions {
      *  programmatic API 默认 false。 */
     runHealthCheck?: boolean;
     effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** 批量体检进度回调(per-skill)。CLI 非 gate 模式注入、写 stderr;eval 内嵌
+     *  调用不传(eval 有自己的进度体系,不应冒出 doctor 进度)。 */
+    onProgress?: DoctorProgressCallback;
 }

package/dist/types/doctor.js

@@ -1,6 +1,6 @@
 /** Bumped whenever DoctorReport schema changes in a way CI consumers should
  *  be able to detect. CI can pin/check this when parsing the JSON. */
-export const DOCTOR_REPORT_SCHEMA_VERSION = '2.0.0';
+export const DOCTOR_REPORT_SCHEMA_VERSION = '3.0.0';
 export function isComposerRule(r) {
     return r.ruleKind === 'composer';
 }

package/dist/types/managed.d.ts

@@ -52,12 +52,25 @@ export interface ManagedEvidenceRef {
     };
 }
 export type ManagedDecisionKind = 'promote' | 'reject' | 'rollback';
-/** 一次人工管理决定。install 时为空,promote/reject/rollback 追加。 */
+/** 一次人工管理决定。install 时为空,promote/reject/rollback 追加(append-only 事件流)。 */
 export interface ManagedDecision {
     decisionKind: ManagedDecisionKind;
     actor: string;
     decidedAt: string;
     reason?: string;
+    /** 被该决定接受 / 回滚到的内容 hash —— 锚定「决定的是哪份内容」。promote 取决定时的 record.contentHash;
+     *  读时只把与当前 contentHash 匹配的 promote 决定算作「当前版本已 promoted」(旧内容的决定不冒充当前)。 */
+    contentHash?: string;
+    /** 该决定锚定的证据 report(promote 取 latestCurrentEvidence 那条的 reportId)——可回溯「凭什么 ship」。 */
+    reportId?: string;
+    /** 越门记录:门禁本应拦下,经 --force 显式越过时记下供审计(spec §7「Overrides must be explicit and
+     *  recorded」)。无此字段 = 正常通过门禁。`verdict` 是越门时证据的 verdict(上下文);`overriddenBlocks`
+     *  是真正被越过的判据(drifted / incomparable / verdict_blocked),让审计能回答「越过了什么」—— 只看
+     *  verdict 会误导(仅因 drift 越门时 verdict 可能仍是 PROGRESS)。 */
+    override?: {
+        verdict: string;
+        overriddenBlocks?: string[];
+    };
 }
 export interface ManagedArtifactSource {
     /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库某 ref 或远端(带 url)。 */
@@ -92,8 +105,9 @@ export interface ManagedArtifactRecord {
     evidence: ManagedEvidenceRef[];
     decisions: ManagedDecision[];
 }
-/** 读时推导的生命周期标签——不持久(见文件头说明)。 */
-export type ManagedLifecycleLabel = 'discovered' | 'installed' | 'measurable' | 'stale';
+/** 读时推导的生命周期标签——不持久(见文件头说明)。`promoted` 由当前内容(contentHash 匹配)有一条
+ *  promote 决定推出:它是 measurable 之上的「已人工接受当前版本」,故优先级高于 measurable。 */
+export type ManagedLifecycleLabel = 'discovered' | 'installed' | 'measurable' | 'stale' | 'promoted';
 export interface DerivedManagedState {
     label: ManagedLifecycleLabel;
     /** 当前源 hash 与记录的 contentHash 不一致(或源已不在)。 */

package/dist/types/observability.d.ts

@@ -43,8 +43,8 @@ export interface ObservationReviewStateEntry {
     snippet?: string;
 }
 export interface ObservationReviewState {
-    reportKind: 'observe-review-state';
-    schemaVersion: 1;
+    kind: 'observe-review-state';
+    schemaVersion: 2;
     updatedAt: string;
     entries: Record<string, ObservationReviewStateEntry>;
 }
@@ -184,8 +184,8 @@ export interface ObservationSessionTimeRange {
     durationMs?: number;
 }
 export interface ObservationInboxReport {
-    reportKind: 'observe-inbox';
-    schemaVersion: 1;
+    kind: 'observe-inbox';
+    schemaVersion: 2;
     meta: {
         tracePath: string;
         generatedAt: string;
@@ -735,8 +735,8 @@ export interface ExperienceSkillSummary {
     relatedObservationIds: string[];
 }
 export interface ObservationExperienceReport {
-    reportKind: 'observe-experience';
-    schemaVersion: 1;
+    kind: 'observe-experience';
+    schemaVersion: 2;
     scope: 'evidence-only';
     generatedAt: string;
     meta: {

package/dist/types/report.d.ts

@@ -253,8 +253,10 @@ export interface ReportMeta {
      *  for eval-side reports). Value 1 was specified for v0.21+ but never emitted in practice.
      *  Value 2 marked the artifactHashes tree-hash era for local dir-skills (git dir-skills still
      *  SKILL.md-only). Value 3 extends whole-tree hashing to git dir-skills via isolated copies
-     *  (all dir-skills bind). Drift / lineage consumers gate on `>= 2` (tree-hash era); git-dir-skill
-     *  binding additionally requires `>= 3`. */
+     *  (all dir-skills bind). Value 4 keeps the v3 hash/binding semantics but marks the canonical
+     *  top-level discriminant era, so external consumers can version-gate the JSON shape. Drift /
+     *  lineage consumers gate on `>= 2` (tree-hash era); git-dir-skill binding additionally
+     *  requires `>= 3`. */
     schemaVersion?: number;
     /** SHA256-12 of every sample's content (sample_id → hash). Same hash = same sample. */
     sampleHashes?: Record<string, string>;
@@ -355,7 +357,7 @@ export interface SampleSnapshot {
     tripwire?: boolean;
 }
 export interface EvaluationReport {
-    reportKind: 'evaluation';
+    kind: 'evaluation';
     id: string;
     meta: ReportMeta;
     summary: Record<string, VariantSummary>;
@@ -369,6 +371,9 @@ export interface EvaluationReport {
 export type Report = EvaluationReport;
 export interface BatchEvaluationMeta {
     mode: 'skill';
+    /** Batch report JSON schema version. Kept in lockstep with child EvaluationReport top-level
+     *  shape so external consumers can identify the canonical discriminant era. */
+    schemaVersion: number;
     model: string;
     executor: string;
     skillDir: string;
@@ -408,7 +413,7 @@ export interface BatchEvaluationItem {
     variance?: VarianceData;
 }
 export interface BatchEvaluationReport {
-    reportKind: 'batch-evaluation';
+    kind: 'batch-evaluation';
     id: string;
     mode: 'skill';
     meta: BatchEvaluationMeta;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "packageManager": "yarn@4.16.0",
   "description": "Evaluation framework for LLM knowledge inputs — prompts, RAG corpora, skills, agent workflows. Fix the model, vary the artifact. Built-in statistical rigor: bootstrap CI, Krippendorff α, length-debias, saturation curves.",
   "type": "module",