oh-my-knowledge 0.38.0 → 0.39.0

package/dist/assets/agent-skills/omk/references/commands.md

@@ -584,6 +584,7 @@ omk sample [skillPath] [flags]
 
 **Flags:**
 
+- `--append` `boolean`:在已有用例文件上追加新生成的用例（撞 sample_id 自动加后缀去重，保留原 json/yaml 格式）。仅单 skill 模式，不支持 --batch / --from-traces / --fix。不传则已有文件时报错保护。常配 --focus 补特定场景。
 - `--batch` `boolean`:批量模式：扫 --skill-dir 下所有缺 samples 的 skill，逐个生成。
 - `--count` `option`:生成用例条数。不传由 LLM 按 skill 类型自动决定。
 - `--executor` `option`:执行器名，默认 claude（同 omk eval / doctor / evolve）。指定 codex 等其它执行器时，记得连带传一个该执行器能识别的 --model。

package/dist/cli/commands/sample.d.ts

@@ -2,6 +2,18 @@ import { BaseCommand } from '../oclif/base-command.js';
 import { type CliLang } from '../lib/i18n.js';
 import { type LoadSamplesResult } from '../../inputs/load-samples.js';
 import type { Report, Sample as SampleType } from '../../types/index.js';
+/** --append 合并:已有用例原样保留,新用例逐条接在后面;sample_id 撞已有(或本批已用)时
+ *  自动加 `-2`/`-3` 后缀去重。模型每次从 s001 重编号,撞 id 不代表内容重复,所以是改名保留
+ *  而非丢弃(不做内容级去重)。`reserved` 为额外要避开的 id 集(目录模式跨同目录其它 sample
+ *  文件去重用,见 collectDirSampleIds)。 */
+export declare function mergeAppendSamples(existing: SampleType[], fresh: SampleType[], reserved?: ReadonlySet<string>): SampleType[];
+/** 目录模式 append 选写回目标:复用 listSampleFilesInDir 的排序/过滤(与 eval 目录合并同口径),
+ *  优先 canonical `samples.json`,否则排序后第一个 —— 确定性、不依赖文件系统枚举顺序,
+ *  用户可预测改哪个文件。无候选返回 null。 */
+export declare function pickAppendTargetFile(dir: string): string | null;
+/** 把新用例追加进已有 sample 文件:读 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与
+ *  `{samples:[...]}` wrapper 写回。返回合并后总条数。 */
+export declare function appendSamplesToFile(existingFile: string, fresh: SampleType[], reserved?: ReadonlySet<string>): number;
 export declare function collectSampleDesignFailureIds(report: Pick<Report, 'results'>, treatmentName: string): Set<string>;
 export declare function assertFixReportMatchesCurrentInputs(params: {
     report: Pick<Report, 'meta'>;
@@ -29,6 +41,7 @@ export default class Sample extends BaseCommand {
         executor: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'skill-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         focus: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        append: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-mock': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         fix: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'reports-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/cli/commands/sample.js

@@ -8,7 +8,7 @@ import { integerStringParser } from '../oclif/parsers.js';
 import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { projectReportsDir, globalReportsDir } from '../../eval-core/measurement-dirs.js';
-import { loadSamples, parseYaml } from '../../inputs/load-samples.js';
+import { loadSamples, parseYaml, listSampleFilesInDir } from '../../inputs/load-samples.js';
 import { hashSample } from '../../eval-core/evaluation-reporting.js';
 import { hashArtifactSource } from '../../inputs/content-hash.js';
 function isRecord(value) {
@@ -33,6 +33,78 @@ function stringifySampleDocument(filePath, document) {
         return yaml.dump(document, { lineWidth: -1, noRefs: true });
     return JSON.stringify(document, null, 2);
 }
+/** --append 合并:已有用例原样保留,新用例逐条接在后面;sample_id 撞已有(或本批已用)时
+ *  自动加 `-2`/`-3` 后缀去重。模型每次从 s001 重编号,撞 id 不代表内容重复,所以是改名保留
+ *  而非丢弃(不做内容级去重)。`reserved` 为额外要避开的 id 集(目录模式跨同目录其它 sample
+ *  文件去重用,见 collectDirSampleIds)。 */
+export function mergeAppendSamples(existing, fresh, reserved) {
+    const used = new Set(existing.map((s) => s.sample_id));
+    if (reserved)
+        for (const id of reserved)
+            used.add(id);
+    const merged = [...existing];
+    for (const sample of fresh) {
+        let id = sample.sample_id;
+        if (used.has(id)) {
+            let n = 2;
+            while (used.has(`${id}-${n}`))
+                n += 1;
+            id = `${id}-${n}`;
+        }
+        used.add(id);
+        merged.push(id === sample.sample_id ? sample : { ...sample, sample_id: id });
+    }
+    return merged;
+}
+/** 目录模式 append:收集目录内所有 sample 文件的 sample_id,跨文件去重用 —— eval 走目录模式
+ *  会把目录下所有文件合并加载,跨文件撞 id 直接报错(load-samples 的 duplicate sample_id)。
+ *  复用 listSampleFilesInDir 的排序/过滤口径;best-effort:解析失败的文件跳过。 */
+function collectDirSampleIds(dir) {
+    const ids = new Set();
+    let files;
+    try {
+        files = listSampleFilesInDir(dir);
+    }
+    catch {
+        return ids;
+    }
+    for (const f of files) {
+        const full = join(dir, f);
+        try {
+            for (const s of getSamplesArray(parseSampleDocument(full), full)) {
+                if (typeof s.sample_id === 'string')
+                    ids.add(s.sample_id);
+            }
+        }
+        catch { /* skip unparseable / 非 sample 文件 */ }
+    }
+    return ids;
+}
+/** 目录模式 append 选写回目标:复用 listSampleFilesInDir 的排序/过滤(与 eval 目录合并同口径),
+ *  优先 canonical `samples.json`,否则排序后第一个 —— 确定性、不依赖文件系统枚举顺序,
+ *  用户可预测改哪个文件。无候选返回 null。 */
+export function pickAppendTargetFile(dir) {
+    let files;
+    try {
+        files = listSampleFilesInDir(dir);
+    }
+    catch {
+        return null;
+    }
+    if (files.length === 0)
+        return null;
+    const chosen = files.includes('samples.json') ? 'samples.json' : files[0];
+    return join(dir, chosen);
+}
+/** 把新用例追加进已有 sample 文件:读 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与
+ *  `{samples:[...]}` wrapper 写回。返回合并后总条数。 */
+export function appendSamplesToFile(existingFile, fresh, reserved) {
+    const doc = parseSampleDocument(existingFile);
+    const merged = mergeAppendSamples(getSamplesArray(doc, existingFile), fresh, reserved);
+    const nextDoc = Array.isArray(doc) ? merged : { ...doc, samples: merged };
+    writeFileSync(existingFile, stringifySampleDocument(existingFile, nextDoc));
+    return merged.length;
+}
 function formatIdList(ids) {
     const shown = ids.slice(0, 5);
     const suffix = ids.length > shown.length ? ` +${ids.length - shown.length}` : '';
@@ -328,6 +400,12 @@ async function runSampleFromTraces(flags, lang) {
     }
 }
 async function runSample(args, flags, lang) {
+    // --append 目前只在单 skill 生成路径实现;batch / from-traces / fix 不处理它,
+    // 静默忽略会误导(用户以为在追加,实际没有)。提前互斥校验,明确报错。
+    if (flags.append && (flags.batch || flags['from-traces'] || flags.fix)) {
+        console.error(tCli('cli.gen.append_single_only', lang));
+        throw new CliExit(2);
+    }
     if (flags['from-traces']) {
         await runSampleFromTraces(flags, lang);
         return;
@@ -425,23 +503,23 @@ async function runSample(args, flags, lang) {
         }
         const skillContent = readFileSync(resolved.skillPath, 'utf-8');
         let outputPath;
+        let existingFile = null;
         if (!extname(resolved.samplesPath)) {
             const dir = resolved.samplesPath;
             if (existsSync(dir) && statSync(dir).isDirectory()) {
-                const existing = readdirSync(dir).find((f) => /\.(json|ya?ml)$/i.test(f) && !/^(report|health|_)/i.test(f));
-                if (existing) {
-                    console.error(tCli('cli.gen.samples_already_exists', lang));
-                    throw new CliExit(1);
-                }
+                existingFile = pickAppendTargetFile(dir);
             }
-            outputPath = join(dir, 'samples.json');
+            outputPath = existingFile ?? join(dir, 'samples.json');
         }
         else {
             outputPath = resolved.samplesPath;
-            if (existsSync(outputPath)) {
-                console.error(tCli('cli.gen.samples_already_exists', lang));
-                throw new CliExit(1);
-            }
+            if (existsSync(outputPath))
+                existingFile = outputPath;
+        }
+        // 已有用例文件:默认报错保护;--append 时追加(下面合并),不报错。
+        if (existingFile && !flags.append) {
+            console.error(tCli('cli.gen.samples_already_exists', lang));
+            throw new CliExit(1);
         }
         if (count !== undefined) {
             process.stderr.write(tCli('cli.gen.single_generating', lang, { count }));
@@ -451,12 +529,24 @@ async function runSample(args, flags, lang) {
         }
         try {
             const { samples, costUSD } = await generateSamples({ skillContent, count, model, focus, noMock: flags['no-mock'], executorName: flags.executor });
-            mkdirSync(dirname(outputPath), { recursive: true });
-            writeFileSync(outputPath, JSON.stringify(samples, null, 2));
             const cost = costUSD > 0 ? ` $${costUSD.toFixed(4)}` : '';
-            process.stderr.write(tCli('cli.gen.single_done', lang, {
-                n: samples.length, path: outputPath, cost,
-            }));
+            if (existingFile && flags.append) {
+                // 追加:读已有 → 合并(撞 id 去重)→ 保留原 json/yaml 格式与 wrapper 写回。
+                // 目录模式额外跨同目录其它 sample 文件去重,避免 eval 合并加载时撞 id 报错;
+                // 显式单文件路径无同目录合并语义,不需要。
+                const reserved = extname(resolved.samplesPath) ? undefined : collectDirSampleIds(dirname(existingFile));
+                const total = appendSamplesToFile(existingFile, samples, reserved);
+                process.stderr.write(tCli('cli.gen.append_done', lang, {
+                    added: samples.length, total, path: existingFile, cost,
+                }));
+            }
+            else {
+                mkdirSync(dirname(outputPath), { recursive: true });
+                writeFileSync(outputPath, JSON.stringify(samples, null, 2));
+                process.stderr.write(tCli('cli.gen.single_done', lang, {
+                    n: samples.length, path: outputPath, cost,
+                }));
+            }
             console.log(tCli('cli.gen.review_hint', lang));
         }
         catch (err) {
@@ -553,6 +643,13 @@ export default class Sample extends BaseCommand {
                 en: 'Generation focus (NL hint). Steers LLM toward certain sample types.',
             }),
         }),
+        append: Flags.boolean({
+            description: bilingual({
+                zh: '在已有用例文件上追加新生成的用例（撞 sample_id 自动加后缀去重，保留原 json/yaml 格式）。仅单 skill 模式，不支持 --batch / --from-traces / --fix。不传则已有文件时报错保护。常配 --focus 补特定场景。',
+                en: 'Append newly generated samples to the existing samples file (colliding sample_id auto-suffixed, original json/yaml shape kept). Single-skill mode only; not supported with --batch / --from-traces / --fix. Without it, an existing file errors out. Often paired with --focus.',
+            }),
+            default: false,
+        }),
         'no-mock': Flags.boolean({
             description: bilingual({
                 zh: '不生成 mocks，eval 时所有工具调用真实执行。',

package/dist/cli/lib/cmd-flags.d.ts

@@ -155,6 +155,7 @@ export interface SampleFlags {
     executor?: string;
     'skill-dir': string;
     focus?: string;
+    append: boolean;
     'no-mock': boolean;
     fix: boolean;
     'reports-dir'?: string;

package/dist/cli/lib/i18n-dict/gen.d.ts

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type GenMessageKey = 'cli.gen.skill_skipped_existing' | 'cli.gen.skill_generating' | 'cli.gen.skill_generating_auto' | 'cli.gen.skill_done' | 'cli.gen.skill_failed' | 'cli.gen.batch_none_needed' | 'cli.gen.batch_summary' | 'cli.gen.specify_skill_path' | 'cli.gen.samples_already_exists' | 'cli.gen.single_generating' | 'cli.gen.single_generating_auto' | 'cli.gen.single_done' | 'cli.gen.review_hint' | 'cli.gen.failed' | 'cli.gen.focus_applied';
+export type GenMessageKey = 'cli.gen.skill_skipped_existing' | 'cli.gen.skill_generating' | 'cli.gen.skill_generating_auto' | 'cli.gen.skill_done' | 'cli.gen.skill_failed' | 'cli.gen.batch_none_needed' | 'cli.gen.batch_summary' | 'cli.gen.specify_skill_path' | 'cli.gen.samples_already_exists' | 'cli.gen.single_generating' | 'cli.gen.single_generating_auto' | 'cli.gen.single_done' | 'cli.gen.append_done' | 'cli.gen.append_single_only' | 'cli.gen.review_hint' | 'cli.gen.failed' | 'cli.gen.focus_applied';
 export declare const genDict: Record<GenMessageKey, CliMessage>;

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

@@ -47,6 +47,14 @@ export const genDict = {
         zh: '✅ 已生成 {n} 条用例 → {path}{cost}\n',
         en: '✅ Generated {n} samples → {path}{cost}\n',
     },
+    'cli.gen.append_done': {
+        zh: '✅ 新增 {added} 条用例（撞 id 已自动改名），合并后共 {total} 条 → {path}{cost}\n',
+        en: '✅ Appended {added} samples (colliding ids auto-renamed), {total} total → {path}{cost}\n',
+    },
+    'cli.gen.append_single_only': {
+        zh: '--append 目前仅支持单 skill 模式，不能与 --batch / --from-traces / --fix 同用。\n',
+        en: '--append currently supports single-skill mode only; it cannot be combined with --batch / --from-traces / --fix.\n',
+    },
     'cli.gen.review_hint': {
         zh: '\n请审查生成的评测用例后运行: omk eval',
         en: '\nReview the generated test cases, then run: omk eval',

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

@@ -66,6 +66,7 @@ export function buildVariantConfig(artifact) {
         cwd: artifact.cwd || null,
         locator: artifact.locator,
         ref: artifact.ref,
+        ...(artifact.resolvedCommit ? { resolvedCommit: artifact.resolvedCommit } : {}),
         // propagate skill-isolation declaration so report.meta.skillIsolation
         // 能在 evaluation-reporting 阶段从 variantConfigs 提取 (avoid re-resolving artifacts).
         ...(artifact.allowedSkills !== undefined && { allowedSkills: artifact.allowedSkills }),

package/dist/inputs/load-samples.d.ts

@@ -32,4 +32,9 @@ export interface LoadSamplesResult {
  * - `requires` from each file unioned together
  */
 export declare function loadSamples(samplesPath: string): LoadSamplesResult;
+/** Pull `.json/.yaml/.yml` siblings out of a directory, skipping omk's own report/health
+ *  artifacts and any underscore-prefixed file (the convention for "not a sample").
+ *  Exported so `omk sample --append` picks its target with the same sorted/filtered order
+ *  that directory-mode loading merges by (deterministic, predictable). */
+export declare function listSampleFilesInDir(dir: string): string[];
 export declare function validateSamples(samples: Sample[]): void;

package/dist/inputs/load-samples.js

@@ -38,8 +38,10 @@ export function loadSamples(samplesPath) {
     };
 }
 /** Pull `.json/.yaml/.yml` siblings out of a directory, skipping omk's own report/health
- *  artifacts and any underscore-prefixed file (the convention for "not a sample"). */
-function listSampleFilesInDir(dir) {
+ *  artifacts and any underscore-prefixed file (the convention for "not a sample").
+ *  Exported so `omk sample --append` picks its target with the same sorted/filtered order
+ *  that directory-mode loading merges by (deterministic, predictable). */
+export function listSampleFilesInDir(dir) {
     const RESERVED = /^(report|health|_)/i;
     return readdirSync(dir)
         .filter((f) => /\.(json|ya?ml)$/i.test(f))

package/dist/inputs/skill-loader.d.ts

@@ -5,6 +5,14 @@ export declare function gitShowFile(ref: string, filePath: string, cwd?: string)
  * 同 gitShowFile 用 `cat-file blob`:对目录会非零退出,不会把树清单字节当文件内容物化。
  */
 export declare function gitShowBytes(ref: string, filePath: string, cwd?: string): Buffer | null;
+/**
+ * 把一个 ref(branch / tag / HEAD / 缩写或完整 SHA)解析到它指向的 commit SHA(#234/#236 还原坐标)。
+ * `^{commit}` 会把 annotated tag 也 peel 到 commit;`--verify --quiet` 解析不出时静默非零退出 → 落 null。
+ * 不存在 / 出错 → null(best-effort,绝不抛、不阻断 eval)。`<ref>` 物化内容时用的就是它,故这是被测字节的定点
+ * (与工作树是否 dirty 无关 —— 内容从 object DB 按 ref 取)。dash-ref(前缀 `-`)直接挡,不得被当 git 选项
+ * (rev-parse 的 rev 不能放 `--` 之后,故显式前置守卫,与 gitShowBytes 的 `--` 同口径 fail-closed)。
+ */
+export declare function gitResolveCommit(ref: string, cwd?: string): string | null;
 export interface GitTreeEntry {
     /** git 文件模式:100644/100755=普通文件,120000=软链,160000=submodule。 */
     mode: string;

package/dist/inputs/skill-loader.js

@@ -73,6 +73,24 @@ export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
         return null;
     }
 }
+/**
+ * 把一个 ref(branch / tag / HEAD / 缩写或完整 SHA)解析到它指向的 commit SHA(#234/#236 还原坐标)。
+ * `^{commit}` 会把 annotated tag 也 peel 到 commit;`--verify --quiet` 解析不出时静默非零退出 → 落 null。
+ * 不存在 / 出错 → null(best-effort,绝不抛、不阻断 eval)。`<ref>` 物化内容时用的就是它,故这是被测字节的定点
+ * (与工作树是否 dirty 无关 —— 内容从 object DB 按 ref 取)。dash-ref(前缀 `-`)直接挡,不得被当 git 选项
+ * (rev-parse 的 rev 不能放 `--` 之后,故显式前置守卫,与 gitShowBytes 的 `--` 同口径 fail-closed)。
+ */
+export function gitResolveCommit(ref, cwd = process.cwd()) {
+    if (!ref || ref.startsWith('-'))
+        return null;
+    try {
+        const out = execFileSync('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 递归列出 `<ref>:<treePath>` 子树下的叶子条目(blob / 软链 / submodule)。tree 不存在返回 []。
  * 用 `-z`(NUL 分隔):git 不会对含换行 / 非 ASCII 的路径做 C-quote,路径原样可回喂 git show。
@@ -632,6 +650,9 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             if (!resolved) {
                 throw new Error(`skill not found in git ${ref}: ${name}.md or ${name}/SKILL.md`);
             }
+            // #234/#236:把 variant 的 ref 解析到实际 commit 当还原坐标。是 ref(可能 branch/tag/HEAD)而非进程
+            // cwd 的 HEAD —— 内容从 object DB 按这个 ref 物化,坐标必须对齐它(否则在别的分支跑会记错版本)。
+            const resolvedCommit = gitResolveCommit(ref, gitCtx.repoRoot) ?? undefined;
             if (resolved.isDir) {
                 // git 目录-skill 忠实执行:物化整树到临时目录 → 落地内容寻址隔离副本 → executor cwd 锚副本,
                 // agent 读得到 references/ 资产、资产成为真实运行时输入。整树指纹与 install 受管记录的
@@ -652,6 +673,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                     contentHash: isolated.contentHash,
                     locator: name,
                     ref,
+                    ...(resolvedCommit ? { resolvedCommit } : {}),
                     cwd: variantCwd,
                     ...(isolated.execRoot ? { execRoot: isolated.execRoot } : {}),
                 });
@@ -672,6 +694,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 contentHash: hashBytes(skillMdBytes),
                 locator: name,
                 ref,
+                ...(resolvedCommit ? { resolvedCommit } : {}),
                 cwd: variantCwd,
             });
             continue;

package/dist/managed/evidence.d.ts

@@ -1,7 +1,8 @@
 import type { EvaluationReport, ManagedEvidenceRef } from '../types/index.js';
 /**
  * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
- * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。git 还原坐标从该 variant 的
+ * `resolvedCommit` 取(见 variantResolvedCommit),无则不记。
  */
 export declare function buildEvidenceRef(report: EvaluationReport, variant: string, verdict: string, recordedAt: string): ManagedEvidenceRef | null;
 export interface RecordedEvidence {

package/dist/managed/evidence.js

@@ -27,7 +27,7 @@
  */
 import { basename, dirname } from 'node:path';
 import { hashString } from '../eval-core/evaluation-reporting.js';
-import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir } from './store.js';
+import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir, isShaLike } from './store.js';
 /** baseline / 无 skill 变体的 artifactHash 哨兵(见 report.ts artifactHashes 注释)——不产证据。 */
 const NO_SKILL = 'no-skill';
 /** 样本集覆盖摘要:report 的 sampleHashes 排序后取一个稳定 digest(同一样本集 ⇒ 同 hash)。
@@ -39,9 +39,20 @@ function sampleCoverage(report) {
     const entries = Object.entries(sh).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     return { count: entries.length, hash: hashString(JSON.stringify(entries)) };
 }
+/**
+ * 该版的 git 还原坐标(#234/#236):被测 variant 物化时 `<ref>` 解析出的实际 commit(resolveArtifacts 在
+ * 物化本地 git variant 时算好,经 `variantConfigs[].resolvedCommit` 透传)。**不是**进程 cwd 的 HEAD ——
+ * variant 内容从 object DB 按它自己的 ref 取,在别的分支 / 用显式旧 SHA 跑时 cwd HEAD 会是错版本。
+ * 远端 / file variant 无 resolvedCommit → 不记(诚实留空)。读到的值再过一道 SHA 形态守卫,脏报告不污染证据。
+ */
+function variantResolvedCommit(report, variant) {
+    const cfg = report.meta?.variantConfigs?.find((c) => c.variant === variant);
+    return isShaLike(cfg?.resolvedCommit) ? cfg.resolvedCommit : undefined;
+}
 /**
  * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
- * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。git 还原坐标从该 variant 的
+ * `resolvedCommit` 取(见 variantResolvedCommit),无则不记。
  */
 export function buildEvidenceRef(report, variant, verdict, recordedAt) {
     const contentHash = report.meta?.artifactHashes?.[variant];
@@ -49,6 +60,7 @@ export function buildEvidenceRef(report, variant, verdict, recordedAt) {
         return null;
     const meta = report.meta;
     const cov = sampleCoverage(report);
+    const gitCommit = variantResolvedCommit(report, variant);
     return {
         reportId: report.id,
         contentHash,
@@ -60,6 +72,7 @@ export function buildEvidenceRef(report, variant, verdict, recordedAt) {
             ...(meta.judgePromptHash ? { judgePromptHash: meta.judgePromptHash } : {}),
             ...(meta.debiasMode ? { debiasMode: meta.debiasMode } : {}),
         },
+        ...(gitCommit ? { gitCommit } : {}),
     };
 }
 /**

package/dist/managed/index.d.ts

@@ -5,6 +5,7 @@
 export * from './store.js';
 export * from './evidence.js';
 export * from './list-view.js';
+export * from './version-scores.js';
 export * from './list-query.js';
 export * from './source-probe.js';
 export * from './promote-gate.js';

package/dist/managed/index.js

@@ -5,6 +5,7 @@
 export * from './store.js';
 export * from './evidence.js';
 export * from './list-view.js';
+export * from './version-scores.js';
 export * from './list-query.js';
 export * from './source-probe.js';
 export * from './promote-gate.js';

package/dist/managed/list-view.d.ts

@@ -36,6 +36,12 @@ export interface ManagedListRow {
         judgePromptHash?: string;
         debiasMode?: Array<'length' | 'position'>;
     };
+    /** 当前 promoted 版本是否经 `--force` override 采用(只读审计标);非越门 / 已 rollback / 未采用 → undefined。
+     *  override 的写仍只在 CLI(`promote --force`),Studio 只读展示 —— 见 spec §9(#238)。 */
+    override?: {
+        verdict: string;
+        overriddenBlocks?: string[];
+    };
     /** 最新当前证据的记录时间。 */
     recordedAt?: string;
     /** 当前有效证据数 / 全部证据数(含旧内容的历史证据)。 */

package/dist/managed/list-view.js

@@ -1,4 +1,4 @@
-import { deriveManagedState, isCurrentlyPromoted } from './store.js';
+import { deriveManagedState, isCurrentlyPromoted, currentPromoteOverride } from './store.js';
 /** 当前有效证据(contentHash == record.contentHash)里 recordedAt 最新那条;无则 undefined。
  *  list(展示最新 verdict)与 promote(门禁取证)共用同一口径——旧内容的证据不冒充当前。 */
 export function latestCurrentEvidence(record) {
@@ -35,6 +35,7 @@ export function buildManagedListRow(record, probe) {
         drifted = false;
     }
     const latest = latestCurrentEvidence(record);
+    const override = currentPromoteOverride(record);
     return {
         id: record.id,
         name: record.name,
@@ -47,6 +48,7 @@ export function buildManagedListRow(record, probe) {
         ...(latest?.verdict ? { latestVerdict: latest.verdict } : {}),
         ...(latest?.comparability ? { comparability: latest.comparability } : {}),
         ...(latest?.recordedAt ? { recordedAt: latest.recordedAt } : {}),
+        ...(override ? { override } : {}),
         currentEvidenceCount,
         totalEvidenceCount: record.evidence.length,
         distributionCount: record.distribution.length,

package/dist/managed/store.d.ts

@@ -15,6 +15,9 @@ export declare function recordPath(dir: string, id: string): string;
 /** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
 export declare function managedRecordId(kind: ArtifactKind, name: string): string;
 export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
+/** git commit SHA 形态:7–64 位 hex。写入(evidence.ts)与读取校验共用同一判定,避免写读不对称
+ *  (写时不校验、读时却要求 SHA → 自己写进去的值重载时被自己判脏)。 */
+export declare function isShaLike(v: unknown): v is string;
 export declare function loadManagedRecord(dir: string, id: string): ManagedArtifactRecord | null;
 /** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
 export declare function loadAllManagedRecords(dir?: string): ManagedArtifactRecord[];
@@ -65,6 +68,13 @@ export declare function rebaselineManagedContentHash(dir: string, recordId: stri
  * (数组追加序 = 事件序)。
  */
 export declare function isCurrentlyPromoted(record: ManagedArtifactRecord): boolean;
+/**
+ * 当前 promoted 版本是否经 override(--force)采用 —— 返回该 override(verdict + 被绕过的门),否则 undefined。
+ * 仅当前内容最近一条决定是 promote 且带 override 才有值;rollback 之后(已撤销接受)返回 undefined。供 list /
+ * Studio **读时审计**:从总览一眼看出哪些当前采用是越门来的。override 的**写**仍只在 CLI(`promote --force`),
+ * Studio 不执行——见 evidence-gated-management.md §9(#238)。
+ */
+export declare function currentPromoteOverride(record: ManagedArtifactRecord): ManagedDecision['override'];
 /**
  * 追加一条人工管理决定(append-only,promote/reject/rollback 走此路)。与 evidence 同样**不能走 upsert**
  * (`mergeManagedRecord` 刻意保留旧 decisions、丢弃 next.decisions),必须独立 load→push→原子重写。

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) => {
@@ -273,6 +288,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 +311,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**

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/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

@@ -47,6 +47,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) {
@@ -62,7 +63,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'),
@@ -90,6 +111,15 @@ function eventRow(ev, lang) {
         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>`);
+    }
     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>
@@ -103,10 +133,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 +200,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 +215,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,6 +242,16 @@ 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>`;
+}
 function listRow(row, lang) {
     const t = L(lang);
     const st = stateMeta(row.state, lang);
@@ -164,7 +261,7 @@ function listRow(row, 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-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 +284,7 @@ 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>
   </div>`;
     const body = `<main class="mh-main">
     <header class="mh-hero">
@@ -210,6 +308,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)}
@@ -232,6 +336,7 @@ const MANAGED_CSS = `
 .mh-override{font-size:11px;font-weight:600;color:var(--yellow);background:var(--yellow-bg);padding:1px 8px;border-radius:9px}
 .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}

package/dist/server/report-server.js

@@ -9,7 +9,7 @@ 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 { loadAllManagedRecords, resolveManagedDir, managedDir as projectManagedDir, listManagedRows } from '../managed/index.js';
+import { loadAllManagedRecords, resolveManagedDir, managedDir as projectManagedDir, listManagedRows, buildVersionScores } from '../managed/index.js';
 import { renderManagedList, renderManagedHistory } from '../renderer/managed-history-renderer.js';
 import { DEFAULT_JOBS_DIR } from '../eval-core/default-dirs.js';
 import { resolveObserveHealthDir, projectObserveHealthDir, resolveDoctorsDir, projectDoctorsDir, projectReportsDir, globalReportsDir } from '../eval-core/measurement-dirs.js';
@@ -706,8 +706,17 @@ export function createReportServer({ port, host: hostOption, reportsDir, analyse
                     res.end(lang === 'en' ? 'managed record not found' : '受管记录不存在');
                     return;
                 }
+                // 版本回归曲线要每版的 composite/CI —— 按 evidence.reportId 把报告读出来(去重),读不到的点
+                // buildVersionScores 自会跳过。曲线数据在路由侧算好,renderManagedHistory 保持纯函数、可 snapshot。
+                const reportsById = new Map();
+                for (const ev of record.evidence) {
+                    // 按「打分视角」结构化看报告:受管证据指向的是单次 eval 报告(带 artifactHashes / summary);
+                    // 万一是 batch 报告,meta 无 artifactHashes → buildVersionScores 自会跳过,不会误画。
+                    if (!reportsById.has(ev.reportId))
+                        reportsById.set(ev.reportId, (await reportStore.get(ev.reportId)));
+                }
                 res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(renderManagedHistory(record, lang));
+                res.end(renderManagedHistory(record, lang, buildVersionScores(record, reportsById)));
                 return;
             }
             if (path === '/observe-inbox') {

package/dist/types/eval.d.ts

@@ -139,6 +139,7 @@ export interface Artifact {
     contentHash?: string;
     locator?: string;
     ref?: string;
+    resolvedCommit?: string;
     cwd?: string;
     skillRoot?: string;
     execRoot?: string;
@@ -160,6 +161,7 @@ export interface VariantConfig {
     cwd: string | null;
     locator?: string;
     ref?: string;
+    resolvedCommit?: string;
     allowedSkills?: string[];
 }
 /** 远端 git 源的结构化引用 —— url/ref/spec 分字段,永不拼成单串再 split(避开 parseGitInput 的 `:`

package/dist/types/managed.d.ts

@@ -50,6 +50,13 @@ export interface ManagedEvidenceRef {
         judgePromptHash?: string;
         debiasMode?: Array<'length' | 'position'>;
     };
+    /** §7 #234/#236:这一版被测内容所在的 git commit(full SHA)= 评测时该 variant 的 git ref 解析出的 commit
+     *  (resolveArtifacts 物化时 `git rev-parse <ref>^{commit}`),作每版「还原坐标」指针 —— list / Studio 据此给
+     *  `git checkout <sha> -- <path>` 把源带回这一版(字节级还原由 git 做,omk 不存版本字节)。是 variant 自己的
+     *  ref(可能 branch/tag/HEAD/旧 SHA)而非进程 cwd 的 HEAD —— 内容从 object DB 按 ref 取,故与工作树 dirty
+     *  与否无关。只对本地 git variant 记(远端源还原是重装 fetch-pin SHA;file 源无 git 坐标)。缺失 = 无坐标可
+     *  还原,诚实留空,不臆造。 */
+    gitCommit?: string;
 }
 export type ManagedDecisionKind = 'promote' | 'reject' | 'rollback';
 /** 一次人工管理决定。install 时为空,promote/reject/rollback 追加(append-only 事件流)。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-knowledge",
-  "version": "0.38.0",
+  "version": "0.39.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",
@@ -92,11 +92,11 @@
   "license": "MIT",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
-    "@anthropic-ai/sdk": "^0.102.0",
+    "@anthropic-ai/sdk": "^0.104.1",
     "@inquirer/prompts": "^8.4.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@oclif/core": "^4",
-    "@openai/codex-sdk": "0.137.0",
+    "@openai/codex-sdk": "0.139.0",
     "ajv": "^8.18.0",
     "chart.js": "^4.5.1",
     "js-yaml": "^4.1.1",