oh-my-knowledge 0.38.0 → 0.40.0

package/dist/managed/store.js

@@ -35,6 +35,16 @@ function isStringField(v) {
 function isOptionalString(v) {
     return v === undefined || typeof v === 'string';
 }
+/** git commit SHA 形态:7–64 位 hex。写入(evidence.ts)与读取校验共用同一判定,避免写读不对称
+ *  (写时不校验、读时却要求 SHA → 自己写进去的值重载时被自己判脏)。 */
+export function isShaLike(v) {
+    return typeof v === 'string' && /^[0-9a-f]{7,64}$/i.test(v);
+}
+/** 可选 git SHA 字段守卫(evidence.gitCommit):缺省或合法 SHA 形态。脏值会让 Studio 渲染
+ *  `ev.gitCommit.slice()` 抛 TypeError(整页打不开),故读时按 SHA 形态收窄(脏值只剥字段,见下)。 */
+function isOptionalSha(v) {
+    return v === undefined || isShaLike(v);
+}
 // 受管记录可安装的 kind(managed 记录绝不是 baseline)。
 const MANAGED_KINDS = new Set(['skill', 'prompt', 'agent', 'workflow']);
 // 校验到**运行时实际收窄**的边界,不止「字段是 string」:记录文件是用户可手改、且可能随仓库分发(被
@@ -90,6 +100,11 @@ function isManagedArtifactRecord(value) {
                 && !(Array.isArray(c.debiasMode) && c.debiasMode.every((m) => m === 'length' || m === 'position')))
                 return false;
         }
+        // gitCommit 是纯展示的还原指针:脏值(非 SHA 形态)只剥掉该字段,不像测量关键字段那样判脏丢整条记录
+        // —— 一处装饰字段的 typo 不该让整条记录连同 evidence / decision 历史从 list / Studio 消失。剥后剩余
+        // 字段仍是合法 evidence,Studio 渲染 `ev.gitCommit.slice()` 也不再触雷(字段已不存在)。
+        if (!isOptionalSha(ev.gitCommit))
+            delete ev.gitCommit;
         return true;
     });
     const okDec = r.decisions.every((d) => {
@@ -115,7 +130,28 @@ function isManagedArtifactRecord(value) {
         }
         return true;
     });
-    return okDist && okEv && okDec;
+    // observations(#235)缺省合法(旧记录无);present 必须是数组,每条窄到声明类型 —— healthBand / confidence
+    // 驱动读时 marker(deriveProductionGap),畸形脏值会让 list / Studio 误判,故判脏丢整条记录(同 okEv / okDec)。
+    const okObs = r.observations === undefined || (Array.isArray(r.observations) && r.observations.every((o) => {
+        if (!o || typeof o !== 'object')
+            return false;
+        const obs = o;
+        if (obs.observationKind !== 'production-health')
+            return false;
+        if (!isStringField(obs.reportId) || !isStringField(obs.observedAt))
+            return false;
+        if (typeof obs.gapRate !== 'number' || typeof obs.weightedGapRate !== 'number' || typeof obs.segmentCount !== 'number')
+            return false;
+        if (obs.confidence !== 'high' && obs.confidence !== 'low' && obs.confidence !== 'underpowered')
+            return false;
+        if (obs.healthBand !== 'green' && obs.healthBand !== 'yellow' && obs.healthBand !== 'red')
+            return false;
+        const g = obs.gapByType;
+        if (!g || typeof g !== 'object')
+            return false;
+        return ['failed_search', 'explicit_marker', 'hedging', 'repeated_failure'].every((k) => typeof g[k] === 'number');
+    }));
+    return okDist && okEv && okDec && okObs;
 }
 export function loadManagedRecord(dir, id) {
     const path = recordPath(dir, id);
@@ -192,7 +228,7 @@ export function mergeManagedRecord(prev, next) {
         byPath.set(normKey(t.path), t);
     for (const t of next.distribution)
         byPath.set(normKey(t.path), t);
-    // 维护点:`...next` 取本次安装的事实,下面四个字段从 prev 保留(历史 / 首次时间)。
+    // 维护点:`...next` 取本次安装的事实,下面这些字段从 prev 保留(历史 / 首次时间)。
     // 将来若新增任何"必须从安装基线保留"的字段,务必加进这份覆盖清单,否则会被 next 静默覆盖成 undefined。
     // 注意语义边界:distribution 是**多源容忍**的(按归一化 path 累积去重),而 source / contentHash 是
     // **末次写入(单源)**。同一 (kind,name) 先 file 后 git 重装会得到一条 source=git 的记录,但 distribution
@@ -203,6 +239,7 @@ export function mergeManagedRecord(prev, next) {
         distribution: [...byPath.values()],
         evidence: prev.evidence,
         decisions: prev.decisions,
+        ...(prev.observations ? { observations: prev.observations } : {}),
     };
 }
 /** 读旧记录 → 合并 → 原子 tmp+rename 只写该 id 的文件。返回合并后记录。 */
@@ -239,6 +276,29 @@ export function appendManagedEvidence(dir, recordId, evidence) {
     }
     return merged;
 }
+/**
+ * 追加一条 observe 生产健康观测(append-only,#235)。同 evidence 不走 upsert:`mergeManagedRecord` 保留旧
+ * observations、丢弃 next 的(install 只写事实)。按 `reportId` 去重——observe 无 contentHash,一份 observe 报告
+ * 对一条观测;同报告重跑不堆重复,不同报告(新窗口)是新 reportId → 新条目。记录不存在(未 install / 名字不
+ * 匹配)返回 null —— 与 evidence 同口径:observe 绝不为未纳管 skill 凭空建记录(管理是 install 显式 opt-in)。
+ */
+export function appendManagedObservation(dir, recordId, observation) {
+    const prev = loadManagedRecord(dir, recordId);
+    if (!prev)
+        return null;
+    const dup = (prev.observations ?? []).some((o) => o.reportId === observation.reportId);
+    const merged = dup
+        ? prev
+        : { ...prev, observations: [...(prev.observations ?? []), observation] };
+    if (!dup) {
+        mkdirSync(dir, { recursive: true });
+        const path = recordPath(dir, recordId);
+        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(merged, null, 2));
+        renameSync(tmp, path);
+    }
+    return merged;
+}
 /**
  * 把受管记录的 drift 基线(contentHash)重锚到新源内容哈,保留 evidence / decisions / source /
  * distribution 全不动。用于 `omk evolve` 把胜出版本写回 source 后,让记录跟上实际内容——否则记录的
@@ -273,6 +333,12 @@ export function rebaselineManagedContentHash(dir, recordId, newHash) {
  * (数组追加序 = 事件序)。
  */
 export function isCurrentlyPromoted(record) {
+    return latestPromoteRollbackForCurrent(record)?.decisionKind === 'promote';
+}
+/** 当前内容(contentHash === record.contentHash)最近一条 promote/rollback 决定;无则 undefined。latest-wins
+ *  口径见上(decidedAt 真实时刻、不可解析退字典序、并列取后出现的)。isCurrentlyPromoted 与
+ *  currentPromoteOverride 共用,避免两处各写一遍 latest-wins 走样。 */
+function latestPromoteRollbackForCurrent(record) {
     const ms = (s) => { const n = Date.parse(s); return Number.isNaN(n) ? null : n; };
     let latest;
     for (const d of record.decisions) {
@@ -290,7 +356,17 @@ export function isCurrentlyPromoted(record) {
         if (newer)
             latest = d;
     }
-    return latest?.decisionKind === 'promote';
+    return latest;
+}
+/**
+ * 当前 promoted 版本是否经 override(--force)采用 —— 返回该 override(verdict + 被绕过的门),否则 undefined。
+ * 仅当前内容最近一条决定是 promote 且带 override 才有值;rollback 之后(已撤销接受)返回 undefined。供 list /
+ * Studio **读时审计**:从总览一眼看出哪些当前采用是越门来的。override 的**写**仍只在 CLI(`promote --force`),
+ * Studio 不执行——见 evidence-gated-management.md §9(#238)。
+ */
+export function currentPromoteOverride(record) {
+    const d = latestPromoteRollbackForCurrent(record);
+    return d?.decisionKind === 'promote' ? d.override : undefined;
 }
 /**
  * 追加一条人工管理决定(append-only,promote/reject/rollback 走此路)。与 evidence 同样**不能走 upsert**
@@ -371,3 +447,40 @@ export function deriveManagedState(input) {
         return { label: 'measurable', drifted: false, hasEvidence };
     return { label: 'installed', drifted: false, hasEvidence };
 }
+/** 一条观测是否构成「确诊生产盲区」:healthBand 红 **且** 统计够力。underpowered(数据不足)是 §6.1 的
+ *  unknown —— 既不放行也不拦截,不当确诊盲区;yellow / green 也不算(留信息展示,避免低样本噪声里过度报警)。 */
+export function isProductionGapObservation(obs) {
+    return obs.healthBand === 'red' && obs.confidence !== 'underpowered';
+}
+const obsMs = (s) => { const n = Date.parse(s); return Number.isNaN(n) ? null : n; };
+/** 谁更新(按 observedAt = 流量窗口结束时刻):真实时刻可解析则比时刻,否则退字典序;并列取后出现的。 */
+function obsNewerWins(cur, latest) {
+    const tc = obsMs(cur);
+    const tl = obsMs(latest);
+    return tc !== null && tl !== null ? tc >= tl : cur >= latest;
+}
+/**
+ * observe 生产健康观测的**读时 marker**(#235)。取**最新一条**观测(latest-wins,按 observedAt = 被观测
+ * 流量窗口结束时刻)分类:red + 够力 → `gap`;underpowered → `underpowered`(数据不足);其余 → `none`。
+ *
+ * **版本无关的生产信号**:observe 量的是线上**部署版**的行为,而记录里没有可靠的「源码版 ↔ 部署版」时间锚
+ * (`evolve` 改写源、`rebaselineManagedContentHash` 只换 `contentHash`,不碰 distribution/installedAt;部署副本
+ * 仍是旧的)——所以这里**不按源码版归因、也不臆造版本闸门**(那只会给假精度、还会在源码 bump 后压掉仍然有效的
+ * 真盲区)。marker 反映的是部署版的近况,可能滞后于当前源码版,UI / spec 据此老实标注。
+ *
+ * **绝不翻 stale / 不动生命周期枚举**(§6.1:只有内容漂移翻 stale,observe 是信号源不是受控 eval)。
+ */
+export function deriveProductionGap(record) {
+    const obs = record.observations ?? [];
+    if (obs.length === 0)
+        return { marker: 'none' };
+    let latest = obs[0];
+    for (const o of obs)
+        if (obsNewerWins(o.observedAt, latest.observedAt))
+            latest = o;
+    if (isProductionGapObservation(latest))
+        return { marker: 'gap', latest };
+    if (latest.confidence === 'underpowered')
+        return { marker: 'underpowered', latest };
+    return { marker: 'none', latest };
+}

package/dist/managed/version-scores.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 版本回归曲线的数据点构造(#236 Studio 决策史)。纯函数:report 由调用方按 evidence.reportId 读好传进来
+ * (Map,值可为 null = 报告已清 / 读不到),把受管记录的逐版证据拼成按时间从旧到新的 composite + 95%CI 序列。
+ *
+ * 测量味:每版的可比性签名(评委 prompt hash + debias + 样本集 hash)与「当前内容那版」一致才算 comparable;
+ * 换过评委 / 改过样本集的版本标 false —— 渲染据此把跨不可比的段画虚、点画空心,不糊一条误导的「在变好」线
+ * (spec evidence-gated-management.md §3「可比性必须可见」)。
+ */
+import type { ManagedArtifactRecord } from '../types/index.js';
+/** buildVersionScores 只需要报告里的这几样 —— 用结构化最小入参而非整个 ReportDocument,叶子可测、与 report schema 解耦。 */
+export interface ReportScoreView {
+    meta?: {
+        artifactHashes?: Record<string, string>;
+    };
+    summary?: Record<string, {
+        avgCompositeScore?: number;
+        bootstrapCI?: {
+            low: number;
+            high: number;
+        };
+    } | undefined>;
+}
+export interface VersionScorePoint {
+    contentHash: string;
+    recordedAt: string;
+    composite: number;
+    ciLow: number;
+    ciHigh: number;
+    verdict?: string;
+    /** 与基线(当前内容那版)测量条件一致 → 可比;换过评委 / 改过样本集 → false。 */
+    comparable: boolean;
+}
+export declare function buildVersionScores(record: ManagedArtifactRecord, reportsById: Map<string, ReportScoreView | null>): VersionScorePoint[];

package/dist/managed/version-scores.js

@@ -0,0 +1,70 @@
+const ms = (s) => { const n = Date.parse(s); return Number.isNaN(n) ? null : n; };
+/** 旧→新排序;omk 自写恒 UTC `Z`、字典序即时间序,但记录可手改,两端可解析才用真实时刻、否则退字典序。 */
+function olderFirst(a, b) {
+    const pa = ms(a);
+    const pb = ms(b);
+    if (pa !== null && pb !== null)
+        return pa - pb;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * 一条证据的可比性签名:评委模板 + debias + 样本集,三者全一致才认为两次测量同口径、可直接比分。
+ * 缺评委指纹或样本集指纹 → 无从核对是否同口径,返回 null(= unknown);spec §6.1 明确 unknown 既不隐式
+ * 放行也不隐式拦截,故调用处把 null 一律按不可比渲染(空心点 + 虚线),不把「不知道能不能比」糊成实线趋势。
+ * debias 缺失退空串参与字符串比对(空 debias 是合法状态,非 unknown),只跟同样缺的版本算一致。
+ */
+function comparabilitySig(ev) {
+    const judge = ev.comparability?.judgePromptHash;
+    const samples = ev.sampleCoverage?.hash;
+    if (!judge || !samples)
+        return null;
+    const debias = (ev.comparability?.debiasMode ?? []).slice().sort().join(',');
+    return `${judge}|${debias}|${samples}`;
+}
+export function buildVersionScores(record, reportsById) {
+    // 一版(contentHash)可能多条证据(重测)→ 按 contentHash 收敛,留 recordedAt 最新且能画出点的那条。
+    const byHash = new Map();
+    for (const ev of record.evidence) {
+        const report = reportsById.get(ev.reportId);
+        if (!report)
+            continue; // 报告已清 / 读不到 → 该点跳过,不臆造
+        const hashes = report.meta?.artifactHashes;
+        if (!hashes)
+            continue;
+        const variant = Object.keys(hashes).find((v) => hashes[v] === ev.contentHash);
+        if (!variant)
+            continue; // 匹配不到变体(旧 schema 不绑 / blind 未带哈)→ 跳过
+        const s = report.summary?.[variant];
+        const composite = s?.avgCompositeScore;
+        if (typeof composite !== 'number' || Number.isNaN(composite))
+            continue; // 无 composite → 无从画点
+        const ci = s?.bootstrapCI;
+        const ciLow = typeof ci?.low === 'number' ? ci.low : composite;
+        const ciHigh = typeof ci?.high === 'number' ? ci.high : composite;
+        const prev = byHash.get(ev.contentHash);
+        if (!prev || olderFirst(prev.ev.recordedAt, ev.recordedAt) < 0) {
+            byHash.set(ev.contentHash, { ev, composite, ciLow, ciHigh });
+        }
+    }
+    const entries = [...byHash.values()].sort((a, b) => olderFirst(a.ev.recordedAt, b.ev.recordedAt));
+    if (entries.length === 0)
+        return [];
+    // 基线 = 当前内容那版(没有就用最新一条),其余版本与之比对可比性。
+    const baselineEntry = byHash.get(record.contentHash) ?? entries[entries.length - 1];
+    const baselineSig = comparabilitySig(baselineEntry.ev);
+    return entries.map((en) => {
+        const sig = comparabilitySig(en.ev);
+        // 自身与基线都能核对(签名非 null)且签名一致才算可比;任一缺评委 / 样本指纹(null = unknown)→ 不可比。
+        // 基线本身 unknown → baselineSig 为 null → 全版本(含基线自身)不可比,宁可全空心也不把 unknown 糊成可比。
+        const comparable = sig !== null && baselineSig !== null && sig === baselineSig;
+        return {
+            contentHash: en.ev.contentHash,
+            recordedAt: en.ev.recordedAt,
+            composite: en.composite,
+            ciLow: en.ciLow,
+            ciHigh: en.ciHigh,
+            ...(en.ev.verdict ? { verdict: en.ev.verdict } : {}),
+            comparable,
+        };
+    });
+}

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

@@ -84,6 +84,11 @@ export interface AnalyzeOptions {
     to?: string;
     skills?: string[];
 }
+/**
+ * 健康度色带。阈值对齐 bench ci --max-gap-rate 经验值(spec §五)。observe 报告只在 overall 给 band;
+ * #235 受管反哺时 observe CLI 用本函数逐 skill 算 band 传入 managed —— 阈值单一来源,managed 不复制。
+ */
+export declare function healthBandOf(weightedGapRate: number): 'green' | 'yellow' | 'red';
 /** 统计可信度护栏:按 segment 数判 high / low / underpowered,守护「1 段就判 red」。
  *  导出供 renderer / CLI / server 给历史报告(缺 confidence 字段)做 segmentCount 兜底。 */
 export declare function confidenceOf(segmentCount: number): SkillHealth['confidence'];

package/dist/observability/skill-health-analyzer.js

@@ -31,9 +31,10 @@ function withinTimeWindow(seg, from, to) {
     return true;
 }
 /**
- * overall 健康度色带。阈值对齐 bench ci --max-gap-rate 经验值(spec §五)。
+ * 健康度色带。阈值对齐 bench ci --max-gap-rate 经验值(spec §五)。observe 报告只在 overall 给 band;
+ * #235 受管反哺时 observe CLI 用本函数逐 skill 算 band 传入 managed —— 阈值单一来源,managed 不复制。
  */
-function healthBandOf(weightedGapRate) {
+export function healthBandOf(weightedGapRate) {
     if (weightedGapRate >= 0.3)
         return 'red';
     if (weightedGapRate >= 0.1)

package/dist/renderer/managed-history-renderer.d.ts

@@ -1,5 +1,5 @@
 import type { Lang } from '../types/index.js';
 import type { ManagedArtifactRecord } from '../types/index.js';
-import type { ManagedListRow } from '../managed/index.js';
-export declare function renderManagedHistory(record: ManagedArtifactRecord, lang: Lang): string;
+import type { ManagedListRow, VersionScorePoint } from '../managed/index.js';
+export declare function renderManagedHistory(record: ManagedArtifactRecord, lang: Lang, versionScores?: VersionScorePoint[]): string;
 export declare function renderManagedList(rows: ManagedListRow[], lang: Lang): string;

package/dist/renderer/managed-history-renderer.js

@@ -18,6 +18,26 @@ const VERDICT_LEVELS = {
 const isVerdictLevel = (v) => Object.prototype.hasOwnProperty.call(VERDICT_LEVELS, v);
 const shortHash = (h) => h.slice(0, 12);
 const L = (lang) => (zh, en) => (lang === 'zh' ? zh : en);
+// 盲区信号类型 → 人话标签。与 CLI observe 的 GAP_AREA_LABELS 同义但本地另存一份 —— renderer 绝不 import
+// cli/commands(支柱分层),且两边走各自的 i18n 机制。键集随 ManagedObservation.gapByType 固定四类同步。
+const GAP_AREA_LABELS = {
+    failed_search: { zh: '检索失败', en: 'failed search' },
+    explicit_marker: { zh: '显式缺口', en: 'explicit gap' },
+    hedging: { zh: '含糊回避', en: 'hedging' },
+    repeated_failure: { zh: '反复失败', en: 'repeated failure' },
+};
+/** 盲区计数最高的前几类组成人话区域串(只展示信号所在,不生成用例)。全 0 → 空串(调用方据此略过)。
+ *  只迭代**四个已知盲区类型**(GAP_AREA_LABELS 的键),记录里若被手改塞进额外键则一律忽略 —— 消费侧收口,
+ *  比让 validator 因一个额外键丢整条记录更稳;额外键即便混入也进不了展示(再叠 e() 转义,无注入面)。 */
+function topGapAreas(gapByType, lang) {
+    return Object.keys(GAP_AREA_LABELS)
+        .map((k) => [k, gapByType[k] ?? 0])
+        .filter(([, n]) => n > 0)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([k]) => GAP_AREA_LABELS[k][lang])
+        .join(lang === 'zh' ? '、' : ', ');
+}
 /** 页内跳转统一带上 lang，否则点一下就掉回默认中文。zh 是默认 → 空串(不脏 URL)。 */
 const langQuery = (lang) => (lang === 'en' ? '?lang=en' : '');
 /** ISO 时刻解析（两端可解析按真实时刻、否则退字典序），与 latestCurrentEvidence 同口径。 */
@@ -47,6 +67,7 @@ function buildTimeline(record) {
         events.push({
             at: ev.recordedAt, type: 'eval', contentHash: ev.contentHash, verdict: ev.verdict,
             reportId: ev.reportId, sampleCount: ev.sampleCoverage?.count, cliVersion: ev.comparability?.cliVersion,
+            ...(ev.gitCommit ? { gitCommit: ev.gitCommit } : {}),
         });
     }
     for (const d of record.decisions) {
@@ -55,6 +76,14 @@ function buildTimeline(record) {
             reportId: d.reportId, actor: d.actor, reason: d.reason, override: d.override,
         });
     }
+    // observe 生产健康观测(#235):每条一个事件。**不带 contentHash** —— observe 是版本无关的生产信号
+    // (量线上部署版),像 install 事件那样只作时间点,绝不重置版本分段(见 renderManagedHistory 分段循环)。
+    for (const obs of record.observations ?? []) {
+        events.push({
+            at: obs.observedAt, type: 'observe',
+            healthBand: obs.healthBand, confidence: obs.confidence, gapByType: obs.gapByType,
+        });
+    }
     return events.sort((a, b) => cmpDesc(a.at, b.at));
 }
 function reportLink(reportId, lang) {
@@ -62,7 +91,27 @@ function reportLink(reportId, lang) {
         return '';
     return `<a class="mh-link" href="/reports/${encodeURIComponent(reportId)}${langQuery(lang)}">${L(lang)('查看报告', 'report')} →</a>`;
 }
-function eventRow(ev, lang) {
+/** 本地 git 源的仓内路径(`git:<ref>:<spec>` → spec),给 `git checkout <sha> -- <path>` 提示带上 `-- <path>`。
+ *  远端 / file 源 → undefined(本地 git 才有 cwd checkout 语义)。
+ *  file-skill 的实际仓内文件是 `<spec>.md`(install 裸名 spec 经 classifyGitSkillRef 解到 `<spec>.md`),
+ *  故 file-skill 且 spec 未带 `.md` 时补上 —— 否则 `git checkout … -- review` 匹配不到 `review.md`。
+ *  已知局限:locator 的 spec 是**安装时 cwd 相对**的(不含 gitRelDir 前缀),在仓库子目录里 install 的 skill,
+ *  还原路径会缺该子目录前缀。彻底修需在记录上另存仓库根相对路径(与 drift 重解析的 cwd 相对语义解耦),留 follow-up。 */
+function gitRestorePath(source) {
+    if (source.sourceKind !== 'git' || source.url)
+        return undefined;
+    const m = /^git:[^:]*:(.+)$/.exec(source.locator);
+    if (!m)
+        return undefined;
+    const spec = m[1];
+    return (!source.isDirectorySkill && !/\.md$/i.test(spec)) ? `${spec}.md` : spec;
+}
+/** POSIX 单引号包裹,内部 `'` 按 `'\''` 标准转义。还原提示是给用户复制粘贴的 shell 命令,git 路径可含
+ *  空格 / 分号 / 反引号 / `$()` 等元字符 —— e()(HTML escaping)挡不住 shell,不 quote 会被改写命令语义。 */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function eventRow(ev, lang, restorePath) {
     const t = L(lang);
     const typeLabel = {
         install: t('安装纳管', 'Installed'),
@@ -70,10 +119,28 @@ function eventRow(ev, lang) {
         promote: t('采用', 'Promote'),
         reject: t('否决', 'Reject'),
         rollback: t('回滚', 'Rollback'),
+        observe: t('观测', 'Observe'),
     };
     const head = [`<span class="mh-type">${e(typeLabel[ev.type])}</span>`];
     if (ev.type === 'eval')
         head.push(verdictBadge(ev.verdict, lang));
+    // observe 观测徽标,四分支(green / yellow 必须分开 —— yellow 不是健康):红 + 够力 → 「生产盲区」(确诊);
+    // underpowered → 「数据不足」(unknown,任意 band 都先归此,与 deriveProductionGap 同口径);yellow + 够力 →
+    // 「需关注」(盲区已进注意区间、未达 red 告警,不能说成健康);green + 够力 → 「健康」。
+    if (ev.type === 'observe') {
+        if (ev.healthBand === 'red' && ev.confidence !== 'underpowered') {
+            head.push(`<span class="mh-gap">🔬 ${t('生产盲区', 'production gap')}</span>`);
+        }
+        else if (ev.confidence === 'underpowered') {
+            head.push(`<span class="mh-badge-raw">${t('数据不足', 'underpowered')}</span>`);
+        }
+        else if (ev.healthBand === 'yellow') {
+            head.push(`<span class="mh-watch">${t('需关注', 'elevated')}</span>`);
+        }
+        else {
+            head.push(`<span class="mh-badge-raw">${t('健康', 'healthy')}</span>`);
+        }
+    }
     if (ev.override) {
         const blocks = ev.override.overriddenBlocks?.length ? `：${e(ev.override.overriddenBlocks.join(' / '))}` : '';
         head.push(`<span class="mh-override">${t('越门 override', 'override')}${blocks}</span>`);
@@ -84,15 +151,40 @@ function eventRow(ev, lang) {
     if (ev.type === 'eval' && typeof ev.sampleCount === 'number') {
         detail.push(`<span class="mh-detail-item">${ev.sampleCount} ${t('用例', 'samples')}</span>`);
     }
+    // observe 事件:列盲区集中的信号区域 + 建议补样本(只提示、不生成用例,不改样本集)。全 0 不显区域行。
+    if (ev.type === 'observe' && ev.gapByType) {
+        const areas = topGapAreas(ev.gapByType, lang);
+        if (areas)
+            detail.push(`<span class="mh-detail-item">${t('盲区集中在：', 'gaps in: ')}${e(areas)}</span>`);
+        if (ev.healthBand === 'red' && ev.confidence !== 'underpowered') {
+            detail.push(`<span class="mh-detail-item mh-gap-hint">${t('建议补对应用例后重跑 omk eval', 'add matching samples, then re-run omk eval')}</span>`);
+        }
+    }
     if (ev.cliVersion)
         detail.push(`<span class="mh-detail-item">omk ${e(ev.cliVersion)}</span>`);
     if (ev.reportId)
         detail.push(reportLink(ev.reportId, lang));
     if (ev.reason)
         detail.push(`<span class="mh-reason">「${e(ev.reason)}」</span>`);
+    // #234/#236 还原指针:这一版有 git 坐标 + 能解析出仓内路径 → 给现成的 `git checkout <sha> -- <path>` 把
+    // 该路径还原进工作树(字节级还原交给 git)。必须带 `-- <path>`:不带 pathspec 的 `git checkout <sha>` 是切
+    // detached HEAD、整棵工作树被换,语义完全不同且危险 —— 故解析不出路径时干脆不显,不退化成那条命令。显
+    // full SHA(精确坐标、无歧义);路径 shell-quote 防注入(见 shellQuote)。
+    // 注:对目录-skill,checkout 还原该版的跟踪文件,但不会删除其后新增的文件 —— git pathspec 的固有语义。
+    if (ev.gitCommit && restorePath) {
+        const cmd = `git checkout ${ev.gitCommit} -- ${shellQuote(restorePath)}`;
+        detail.push(`<span class="mh-detail-item mh-restore">${t('还原', 'restore')} <code>${e(cmd)}</code></span>`);
+    }
+    // 圆点配色:多数事件按 type 取色;observe 事件按**健康 band** 取色(盲区红 / 数据不足灰 / 注意黄 / 健康绿)
+    // —— observe 是 type 内有强弱的事件,健康或注意观测画错色会撒谎,故按实际健康度上色,与上面徽标四分支同口径。
+    const dotClass = ev.type === 'observe'
+        ? (ev.healthBand === 'red' && ev.confidence !== 'underpowered' ? 'mh-dot--red'
+            : ev.confidence === 'underpowered' ? 'mh-dot--muted'
+                : ev.healthBand === 'yellow' ? 'mh-dot--yellow' : 'mh-dot--green')
+        : `mh-dot--${ev.type}`;
     return `<li class="mh-event mh-event--${ev.type}">
     <span class="mh-time">${e(fmtLocalTime(ev.at))}</span>
-    <span class="mh-marker"><span class="mh-dot mh-dot--${ev.type}"></span></span>
+    <span class="mh-marker"><span class="mh-dot ${dotClass}"></span></span>
     <div class="mh-body">
       <div class="mh-head">${head.join(' ')}</div>
       ${detail.length ? `<div class="mh-detail">${detail.join('')}</div>` : ''}
@@ -103,10 +195,66 @@ function versionHeader(hash, isCurrent, lang) {
     const cur = isCurrent ? `<span class="mh-vcur">${L(lang)('当前', 'current')}</span>` : '';
     return `<li class="mh-vhead"><span class="mh-vhead-label">${L(lang)('版本', 'version')}</span><code class="mh-hash">${e(shortHash(hash))}</code>${cur}</li>`;
 }
-export function renderManagedHistory(record, lang) {
+/** 版本回归曲线(纯 SVG,确定性、可 snapshot):每版 composite 均值 + 95%CI 竖须,按时间从旧到新。
+ *  不可比的版本(换过评委 / 改过样本集,或缺指纹无法核对)点画空心、连线画虚 —— 不糊一条误导的「在变好」线(spec §3)。
+ *  数据由 buildVersionScores 算好;少于 2 个点不画(单点无趋势可言)。composite 量纲不定,y 轴按数据自适应。 */
+function renderVersionCurve(points, lang) {
+    if (points.length < 2)
+        return '';
+    const t = L(lang);
+    const width = 620, height = 250, padL = 46, padR = 16, padT = 16, padB = 46;
+    const plotW = width - padL - padR;
+    const plotH = height - padT - padB;
+    const n = points.length;
+    let yLo = Math.min(...points.map((p) => p.ciLow));
+    let yHi = Math.max(...points.map((p) => p.ciHigh));
+    if (yHi - yLo < 1e-9) {
+        yLo -= 0.5;
+        yHi += 0.5;
+    } // 全相等退化:给个最小跨度,免除零。
+    const pad = (yHi - yLo) * 0.08;
+    yLo -= pad;
+    yHi += pad;
+    const xAt = (i) => padL + (plotW * i) / (n - 1);
+    const yAt = (v) => padT + plotH - (plotH * (v - yLo)) / (yHi - yLo);
+    const parts = [];
+    // 连线逐段;任一端不可比 → 虚线,提示别把跨不可比的差值读作进步 / 回退。
+    for (let i = 1; i < n; i++) {
+        const a = points[i - 1], b = points[i];
+        const dash = (!a.comparable || !b.comparable) ? ' stroke-dasharray="4 3"' : '';
+        parts.push(`<line x1="${xAt(i - 1).toFixed(1)}" y1="${yAt(a.composite).toFixed(1)}" x2="${xAt(i).toFixed(1)}" y2="${yAt(b.composite).toFixed(1)}" stroke="var(--accent)" stroke-width="2"${dash} />`);
+    }
+    // 每点:CI 竖须 + 上下端帽 + 点(可比实心 / 不可比空心)+ 短 hash 轴标。
+    points.forEach((p, i) => {
+        const x = xAt(i), yL = yAt(p.ciLow), yH = yAt(p.ciHigh), yM = yAt(p.composite);
+        parts.push(`<line x1="${x.toFixed(1)}" y1="${yH.toFixed(1)}" x2="${x.toFixed(1)}" y2="${yL.toFixed(1)}" stroke="var(--accent)" stroke-width="1" stroke-opacity="0.5" />`);
+        parts.push(`<line x1="${(x - 3).toFixed(1)}" y1="${yH.toFixed(1)}" x2="${(x + 3).toFixed(1)}" y2="${yH.toFixed(1)}" stroke="var(--accent)" stroke-width="1" stroke-opacity="0.5" />`);
+        parts.push(`<line x1="${(x - 3).toFixed(1)}" y1="${yL.toFixed(1)}" x2="${(x + 3).toFixed(1)}" y2="${yL.toFixed(1)}" stroke="var(--accent)" stroke-width="1" stroke-opacity="0.5" />`);
+        parts.push(p.comparable
+            ? `<circle cx="${x.toFixed(1)}" cy="${yM.toFixed(1)}" r="4" fill="var(--accent)" />`
+            : `<circle cx="${x.toFixed(1)}" cy="${yM.toFixed(1)}" r="4" fill="var(--bg-surface)" stroke="var(--accent)" stroke-width="1.5" />`);
+        parts.push(`<text x="${x.toFixed(1)}" y="${height - padB + 14}" font-size="9" text-anchor="middle" fill="var(--text-muted)">${e(p.contentHash.slice(0, 7))}</text>`);
+    });
+    const yTicks = [0, 0.5, 1].map((f) => {
+        const v = yLo + (yHi - yLo) * f;
+        const y = yAt(v);
+        return `<line x1="${padL}" y1="${y.toFixed(1)}" x2="${width - padR}" y2="${y.toFixed(1)}" stroke="var(--border)" stroke-width="0.5" /><text x="${padL - 6}" y="${(y + 3).toFixed(1)}" font-size="10" text-anchor="end" fill="var(--text-muted)">${v.toFixed(2)}</text>`;
+    }).join('');
+    const anyIncomparable = points.some((p) => !p.comparable);
+    const note = anyIncomparable
+        ? t('空心点 = 测量条件不同或无法核对（换过评委 / 改过样本集 / 缺指纹），与当前版不可比；虚线段别直接读作进步或回退。', 'Hollow dots = measured under a different or unverifiable instrument (judge / sample set changed, or fingerprint missing) than the current version, not comparable; do not read dashed segments as progress or regression.')
+        : t('每个版本的 composite 均值与 95% 置信区间，按时间从旧到新。', 'Composite mean and 95% CI per version, oldest to newest.');
+    return `<section class="mh-curve">
+    <h2 class="mh-curve-title">${t('版本回归曲线', 'Version regression')}</h2>
+    <svg viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg" class="mh-curve-svg">${yTicks}${parts.join('')}</svg>
+    <p class="mh-curve-note">${note}</p>
+  </section>`;
+}
+export function renderManagedHistory(record, lang, versionScores = []) {
     const t = L(lang);
     const events = buildTimeline(record);
     // 倒序遍历：内容版本（contentHash）变化处插版本段头；install 等无 hash 事件不重置分段。
+    const restorePath = gitRestorePath(record.source);
     const rows = [];
     let prevHash;
     for (const ev of events) {
@@ -114,7 +262,7 @@ export function renderManagedHistory(record, lang) {
             rows.push(versionHeader(ev.contentHash, ev.contentHash === record.contentHash, lang));
             prevHash = ev.contentHash;
         }
-        rows.push(eventRow(ev, lang));
+        rows.push(eventRow(ev, lang, restorePath));
     }
     const meta = [
         record.kind,
@@ -129,6 +277,7 @@ export function renderManagedHistory(record, lang) {
       <h1 class="mh-name">${e(record.name)}</h1>
       <div class="mh-meta">${meta}</div>
     </header>
+    ${renderVersionCurve(versionScores, lang)}
     <ol class="mh-timeline">${rows.join('')}</ol>
   </main>
   <style>${MANAGED_CSS}</style>`;
@@ -155,16 +304,37 @@ function stateMeta(state, lang) {
     const [label, tip] = lang === 'zh' ? m.zh : m.en;
     return { label, tip };
 }
+/** 列表只读审计标:当前采用版本是越门(`--force`)来的就标出来,tooltip 列被绕过的门。复用详情时间线的
+ *  `.mh-override` 样式。override 的写仍只在 CLI —— Studio 只读(spec §9 / #238)。 */
+function overrideBadge(row, lang) {
+    if (!row.override)
+        return '';
+    const t = L(lang);
+    const blocks = row.override.overriddenBlocks?.length ? row.override.overriddenBlocks.join(' / ') : '';
+    const tip = blocks ? t(`越门采用，绕过：${blocks}`, `force-promoted, waved: ${blocks}`) : t('越门采用', 'force-promoted');
+    return ` <span class="mh-override" title="${e(tip)}">${t('越门', 'override')}</span>`;
+}
+/** 生产盲区只读标(#235):该 skill 最新观测是确诊生产盲区(红 + 够力)就标出来,tooltip 列盲区区域。
+ *  与 state 正交(observe 量线上部署版、版本无关),只 surface、不参与生命周期 —— 见 deriveProductionGap。 */
+function productionGapBadge(row, lang) {
+    if (!row.productionGap)
+        return '';
+    const t = L(lang);
+    const areas = topGapAreas(row.productionGap.gapByType, lang);
+    const tip = areas ? t(`线上生产盲区，集中在：${areas}`, `production gap in real traffic, in: ${areas}`) : t('线上检测到生产盲区', 'production gap detected in real traffic');
+    // 只放图标(state 列窄、固定 130px,带文字徽标会溢出压到 name 列);全称走 tooltip + legend + 时间线。
+    return ` <span class="mh-gap" title="${e(tip)}">🔬</span>`;
+}
 function listRow(row, lang) {
     const t = L(lang);
     const st = stateMeta(row.state, lang);
     const mark = !row.reachable ? ' <span class="mh-mark mh-mark--q" title="' + e(t('源不可达 / 拒读，漂移未核', 'source unreachable / refused, drift unchecked')) + '">?</span>'
         : row.state === 'stale' ? ' <span class="mh-mark mh-mark--warn" title="' + e(t('已漂移，需重测', 'drifted, re-measure')) + '">⚠️</span>' : '';
     return `<a class="mh-row" href="/managed/${encodeURIComponent(row.id)}${langQuery(lang)}">
-    <span class="mh-row-state" title="${e(st.tip)}"><span class="mh-dot mh-dot--${stateBand(row.state)}"></span>${e(st.label)}${mark}</span>
+    <span class="mh-row-state" title="${e(st.tip)}"><span class="mh-dot mh-dot--${stateBand(row.state)}"></span>${e(st.label)}${mark}${productionGapBadge(row, lang)}</span>
     <span class="mh-row-name">${e(row.name)}</span>
     <span class="mh-row-kind">${e(row.kind)}</span>
-    <span class="mh-row-verdict">${row.latestVerdict ? verdictBadge(row.latestVerdict, lang) : '—'}</span>
+    <span class="mh-row-verdict">${row.latestVerdict ? verdictBadge(row.latestVerdict, lang) : '—'}${overrideBadge(row, lang)}</span>
     <span class="mh-row-ev">${row.currentEvidenceCount}/${row.totalEvidenceCount}</span>
     <span class="mh-row-src" title="${e(row.sourceLabel)}">${e(row.sourceLabel)}</span>
   </a>`;
@@ -187,6 +357,8 @@ export function renderManagedList(rows, lang) {
     <span class="mh-legend-item"><span class="mh-dot mh-dot--red"></span>${t('已漂移 ⚠️：源变了、需重跑 omk eval', 'Drifted ⚠️ = source changed, re-run omk eval')}</span>
     <span class="mh-legend-item">${t('? 源未核（不可达 / 拒读，漂移待定）', '? = source unverified (unreachable / refused)')}</span>
     <span class="mh-legend-item">${t('证据列：当前有效 / 全部历史（旧证据留作回滚）', 'Evidence = current / total (old evidence kept for rollback)')}</span>
+    <span class="mh-legend-item"><span class="mh-override">${t('越门', 'override')}</span>${t(' 当前采用是 --force 越门来的（决定人由命令行记录）', ' = current version force-promoted via --force (actor recorded by CLI)')}</span>
+    <span class="mh-legend-item"><span class="mh-gap">🔬</span>${t(' 生产盲区：observe 在线上检测到的盲区（版本无关信号、与生命周期正交，不翻 stale）', ' = production gap from observe (version-agnostic, orthogonal to lifecycle, never flips stale)')}</span>
   </div>`;
     const body = `<main class="mh-main">
     <header class="mh-hero">
@@ -210,6 +382,12 @@ const MANAGED_CSS = `
 .mh-meta{display:flex;flex-wrap:wrap;gap:6px 14px;margin-top:6px;color:var(--text-muted);font-size:12px}
 .mh-meta span{display:inline-flex;align-items:center;gap:4px;font-variant-numeric:tabular-nums}
 
+/* ── 版本回归曲线 ── */
+.mh-curve{background:var(--bg-surface);border:1px solid var(--border);border-radius:var(--radius-lg);box-shadow:var(--shadow-sm);padding:16px 20px;margin-bottom:18px}
+.mh-curve-title{margin:0 0 4px;font-size:15px;font-weight:700;color:var(--text-primary);letter-spacing:-.2px}
+.mh-curve-svg{width:100%;max-width:620px;height:auto;display:block;margin:6px 0}
+.mh-curve-note{font-size:12px;color:var(--text-muted);margin:6px 0 0}
+
 /* ── 时间线 ── */
 .mh-timeline{list-style:none;padding:0;margin:0;background:var(--bg-surface);border:1px solid var(--border);border-radius:var(--radius-lg);box-shadow:var(--shadow-sm);overflow:hidden}
 .mh-vhead{display:flex;align-items:center;gap:8px;padding:10px 20px;background:var(--bg-elevated);border-top:1px solid var(--border);font-size:12px;color:var(--text-secondary)}
@@ -225,13 +403,17 @@ const MANAGED_CSS = `
 .mh-dot--promote{background:var(--green)}
 .mh-dot--rollback{background:var(--yellow)}
 .mh-dot--reject{background:var(--red)}
-.mh-dot--green{background:var(--green)}.mh-dot--accent{background:var(--accent)}.mh-dot--muted{background:var(--text-muted)}.mh-dot--red{background:var(--red)}
+.mh-dot--green{background:var(--green)}.mh-dot--accent{background:var(--accent)}.mh-dot--muted{background:var(--text-muted)}.mh-dot--red{background:var(--red)}.mh-dot--yellow{background:var(--yellow)}
 .mh-body{flex:1;min-width:0}
 .mh-head{display:flex;flex-wrap:wrap;align-items:center;gap:8px;font-size:14px}
 .mh-type{font-weight:600;color:var(--text-primary)}
 .mh-override{font-size:11px;font-weight:600;color:var(--yellow);background:var(--yellow-bg);padding:1px 8px;border-radius:9px}
+.mh-gap{font-size:11px;font-weight:600;color:var(--red);background:var(--red-bg);padding:1px 8px;border-radius:9px;white-space:nowrap}
+.mh-watch{font-size:11px;font-weight:600;color:var(--yellow);background:var(--yellow-bg);padding:1px 8px;border-radius:9px;white-space:nowrap}
+.mh-gap-hint{color:var(--red)}
 .mh-badge-raw{font-size:11.5px;color:var(--text-secondary);background:var(--bg-soft);padding:1px 8px;border-radius:9px}
 .mh-detail{display:flex;flex-wrap:wrap;gap:4px 14px;margin-top:4px;font-size:12px;color:var(--text-muted)}
+.mh-restore code{font-family:"SF Mono",Menlo,monospace;font-size:11.5px;color:var(--text-secondary);background:var(--bg-soft);padding:1px 6px;border-radius:5px;user-select:all}
 .mh-reason{color:var(--text-secondary);font-style:italic}
 .mh-link{color:var(--accent);text-decoration:none}
 .mh-link:hover{text-decoration:underline}