oh-my-knowledge 0.34.0 → 0.35.0

package/README.md

@@ -100,6 +100,8 @@ RAG-specific evals: see RAGAS (separate niche, complementary to omk). Full compa
 | **Production observability** | parse Claude Code session JSONL traces; measure per-skill failure rate / latency / cost / knowledge-gap signals |
 | **Knowledge-gap detection** | severity-weighted signals quantify risk exposure instead of claiming completeness |
 | **Construct-validity isolation** | `--strict-baseline` (default ON) cuts three contamination channels so baseline doesn't silently see the skill it's being compared against |
+| **Git & remote sources** | install / eval from a local git ref or a remote git URL (`--git-url`); directory-skills run in a content-addressed **isolated copy** so `references/` assets are real measured input, not just `SKILL.md` |
+| **Evidence-gated management** | `omk install` registers a managed record; `omk eval` auto-writes evidence bound by content fingerprint, moving a skill `installed → measurable`. [spec →](docs/specs/evidence-gated-management.md) |
 | **Sample design science** | sample schema with `capability` / `difficulty` / `construct` / `provenance` metadata (HF Dataset Cards style); studio surfaces coverage breakdown plus `rubric_clarity_low` / `capability_thin` flags. [docs/specs/sample-design-spec.md](docs/specs/sample-design-spec.md) |
 | **Multi-judge ensemble** | `--judge-models claude:opus,openai:gpt-4o` cross-vendor scoring + agreement metrics |
 | **Blind A/B** | `--blind` hides variant names; HTML report has a reveal button |
@@ -122,6 +124,7 @@ The full docs are published at **[oh-my-knowledge.pages.dev](https://oh-my-knowl
 - **[Sample design spec](docs/specs/sample-design-spec.md)** — capability / construct / provenance metadata; industry-gap mapping
 - **[Statistical rigor](docs/explanation/statistical-rigor.md)** — why bootstrap CI / α / length-debias / saturation matter
 - **[Comparison with 7 tools](docs/reference/comparison.md)** — 25+ dimensions across promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai
+- **[Evidence-gated management](docs/specs/evidence-gated-management.md)** — managed records, lifecycle states (installed / measurable / stale), install → eval → measurable
 
 ## Environment variables
 

package/README.zh.md

@@ -100,6 +100,8 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 | **线上 session 观测** | 解析 Claude Code session JSONL，测量各 skill 的失败率、耗时、token 成本、知识缺口信号 |
 | **知识缺口识别** | 严重度加权的信号量化风险敞口，不宣称完备性 |
 | **用例隔离 (construct validity)** | `--strict-baseline`（默认开）三堵 baseline 拿到被测 skill 的污染路径 |
+| **Git / 远端源** | install / eval 支持本地 git ref 或远端 git URL（`--git-url`）；目录-skill 在内容寻址**隔离副本**里执行，`references/` 资产是真实测量输入，不只是 `SKILL.md` |
+| **证据门控管理** | `omk install` 登记受管记录；`omk eval` 按内容指纹自动写入证据，把 skill 从 `installed` 推到 `measurable`。[规范 →](docs/zh/specs/evidence-gated-management.md) |
 | **用例设计科学性** | Sample schema 加 `capability` / `difficulty` / `construct` / `provenance` 元数据字段（HF Dataset Cards 风），studio 输出 coverage 分桶 + `rubric_clarity_low` / `capability_thin` issue。[docs/zh/specs/sample-design-spec.md](docs/zh/specs/sample-design-spec.md) |
 | **多评委 ensemble** | `--judge-models claude:opus,openai:gpt-4o` 跨厂商评分 + agreement 度量 |
 | **盲测 A/B** | `--blind` 隐藏变体名称，HTML 报告有揭晓按钮 |
@@ -122,6 +124,7 @@ RAG 专项评测请看 RAGAS（独立 niche，跟 omk 互补）。完整对比
 - **[用例设计规范](docs/zh/specs/sample-design-spec.md)** —— capability / construct / provenance 元数据；行业 gap 映射
 - **[统计严谨性](docs/zh/explanation/statistical-rigor.md)** —— 为什么 Bootstrap CI / α / 长度去偏 / 饱和曲线重要
 - **[7 工具对比](docs/zh/reference/comparison.md)** —— promptfoo / DeepEval / RAGAS / OpenAI Evals / LangSmith / lm-eval-harness / inspect-ai 等 25+ 维度横评
+- **[证据门控管理](docs/zh/specs/evidence-gated-management.md)** —— 受管记录、生命周期状态（installed / measurable / stale）、install → eval → measurable
 
 ## 环境变量
 

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

@@ -89,6 +89,7 @@ omk eval [flags]
 - `--no-cache` `boolean`:跳过 executor cache
 - `--no-debias-length` `boolean`:关 length-debias（默认开）
 - `--no-diagnostic` `boolean`:关闭 diagnostic 诊断 LLM 调用（默认开，给 failed sample 出「哪错了 + 怎么改」建议）。
+- `--no-evidence` `boolean`:不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。
 - `--no-gate` `boolean`:关 verdict gate
 - `--no-judge` `boolean`:跳过 LLM judge
 - `--no-serve` `boolean`:不启 report server
@@ -303,6 +304,8 @@ omk install <input> [flags]
 - `--dest` `option`:自定义 skill 根目录；skill 安装到 <dir>/<name>（内置 omk-agent-skill 为 <dir>/omk）。
 - `--dry-run` `boolean`:只打印安装目标，不写文件。
 - `--force` `boolean`:覆盖目标位置已存在的 skill。
+- `--git-ref` `option`:远端 git 的 ref（分支 / tag / SHA），默认 HEAD。仅配合 --git-url 使用。
+- `--git-url` `option`:远端 git 仓库 URL（https / ssh / git@host:path）。给了它时，位置参数当作仓库内 skill 路径（spec）。
 - `--kind` `skill|prompt|agent|workflow`:用户 artifact 的 kind（对齐 Artifact.kind）。可省：命中 SKILL.md 自动推导，当前仅支持 skill。
 - `--lang` `option` (默认 `zh`):输出语言 zh|en，优先级 CLI > OMK_LANG env > zh。
 - `--to` `option` (默认 `auto`):安装目标：auto（默认，本机已检测目标） / codex / claude / all。
@@ -339,6 +342,12 @@ omk install ./skills/review
 omk install git:main:skills/review
 ```
 
+> 从远端 git 仓库安装 skill（位置参数是仓库内路径；认证用本机 git 凭证；记录钉实际 SHA）
+
+```bash
+omk install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review
+```
+
 ## omk observe
 
 分析 sessions 目录的 skill 调用健康度（默认行为）。子命令:ingest / inbox / show。

package/dist/authoring/evolver.js

@@ -6,6 +6,7 @@ import { persistReport, DEFAULT_OUTPUT_DIR, generateRunId, hashString } from '..
 import { createFileStore } from '../server/report-store.js';
 import { analyzeResults } from '../analysis/report-diagnostics.js';
 import { loadSamples } from '../inputs/load-samples.js';
+import { hashArtifactSource } from '../inputs/content-hash.js';
 import { buildVariantSummary } from '../eval-core/schema.js';
 import { bootstrapDiffCI, DEFAULT_BOOTSTRAP_ALPHA, DEFAULT_BOOTSTRAP_SAMPLES } from '../eval-core/bootstrap.js';
 import { fixSamples } from './sample-fixer.js';
@@ -88,9 +89,13 @@ function singleVariantReport(report, variantKey) {
 async function findReusableBaselineReport(opts) {
     const store = createFileStore(DEFAULT_OUTPUT_DIR);
     const { samples } = loadSamples(opts.samplesPath);
-    const artifactHash = hashString(opts.skillContent);
+    const artifactHash = opts.artifactHash;
     const reports = await store.findByArtifactHash(artifactHash);
     for (const report of reports) {
+        // schemaVersion < 2 的报告 artifactHashes 是旧文本哈,与当前树哈不同空间:即便值偶合也不该复用
+        // (口径不同会让 lineage 串错身份)。直接跳过,让旧 baseline 重跑出树哈报告。
+        if ((report.meta.schemaVersion ?? 0) < 2)
+            continue;
         if (report.meta.model !== opts.model || report.meta.executor !== opts.executorName)
             continue;
         if ((report.meta.effort ?? undefined) !== (opts.effort ?? undefined))
@@ -669,10 +674,14 @@ export async function evolveSkill({ skillPath, samplesPath, rounds = 5, target =
     let stopReason = 'rounds';
     // 给定一个 report 看任一 variant 的 exec/judge cost 是否未报告
     const reportHasUnreportedCost = (rep) => Object.values(rep.summary).some((v) => v.execCostReported === false || v.judgeCostReported === false);
-    // Round 0: baseline evaluation
+    // Round 0: baseline evaluation。复用查询键走整树哈,与 eval 报告口径一致:round 0 的 currentBest 即
+    // 磁盘上原始 skill,树哈取自磁盘(dir-skill 哈整目录、单文件 .md 哈单文件)。evolve 只改 SKILL.md 正文、
+    // 不动 references/ 资产,故磁盘树哈即该 baseline 的权威指纹。
+    const baselineIsDirSkill = basename(absSkillPath) === 'SKILL.md';
+    const baselineArtifactHash = hashArtifactSource(baselineIsDirSkill ? skillDir : absSkillPath, baselineIsDirSkill);
     let baselineReport = reuseLatestEval
         ? await findReusableBaselineReport({
-            skillContent: currentBest,
+            artifactHash: baselineArtifactHash,
             samplesPath: absSamplesPath,
             model,
             executorName,

package/dist/cli/commands/eval/index.d.ts

@@ -50,6 +50,7 @@ export default class Eval extends BaseCommand {
         'trivial-diff': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'report-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'no-gate': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'no-evidence': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/cli/commands/eval/index.js

@@ -37,12 +37,32 @@ function applyGateExitCode(code, values, lang) {
     process.stderr.write(tCli('cli.run.report_only_gate_skipped', lang));
     return 0;
 }
-async function emitEvaluationVerdict(report, values) {
+async function emitEvaluationVerdict(report, values, lang) {
     const { computeVerdict, formatVerdictText } = await import('../../../eval-core/verdict.js');
     const result = computeVerdict(report, verdictOptions(values));
     console.log(formatVerdictText(result, { verbose: true }));
+    await recordEvidenceSafely(report, result.level, values, lang);
     return verdictPasses(result.level, result.headline) ? 0 : 1;
 }
+/**
+ * 把本次评测写成证据追加进**已纳管**记录(让 install 过的 skill 走到 measurable)。
+ * 永不致命:管理是 eval 的旁路,写入失败 / 无匹配记录都不影响 verdict 与 exit code。
+ * `--no-evidence` 关闭。仅对实际写入的记录打一行提示(无匹配则全静默)。
+ */
+async function recordEvidenceSafely(report, verdict, values, lang) {
+    if (values['no-evidence'] === true)
+        return;
+    try {
+        const { recordEvalEvidence } = await import('../../../managed/index.js');
+        const written = recordEvalEvidence(report, verdict, new Date().toISOString());
+        for (const w of written) {
+            process.stderr.write(tCli(w.bound ? 'cli.run.evidence_recorded' : 'cli.run.evidence_recorded_unbound', lang, { name: w.name }));
+        }
+    }
+    catch {
+        // 证据写入是旁路,任何异常都不该让评测失败
+    }
+}
 function batchItemFallbackReport(batch, item) {
     return {
         reportKind: 'evaluation',
@@ -52,6 +72,9 @@ function batchItemFallbackReport(batch, item) {
             variants: ['baseline', item.name],
             sampleCount: item.sampleCount,
             totalCostUSD: item.totalCostUSD,
+            // item.artifactHash 来自子报告(走 aggregateReport 的整树哈),故 fallback 与之一致标 schemaVersion 3,
+            // 避免「树哈 artifactHashes + 错位 schemaVersion」的错配。
+            schemaVersion: 3,
             artifactHashes: item.artifactHash ? { [item.name]: item.artifactHash } : {},
         },
         summary: item.summary,
@@ -83,6 +106,11 @@ async function emitBatchVerdict(report, reportsDir, values, lang) {
         treatment: child.meta.variants[1] ?? child.id,
         verdict: computeVerdict(child, verdictOptions(values)),
     }));
+    // batch 每个子报告各自是一份独立 skill 的评测 → 各自写证据。
+    for (const child of childReports) {
+        const v = results.find((r) => r.id === child.id)?.verdict.level ?? 'SOLO';
+        await recordEvidenceSafely(child, v, values, lang);
+    }
     const passed = results.filter((r) => verdictPasses(r.verdict.level, r.verdict.headline)).length;
     const failed = results.length - passed;
     const status = lang === 'zh'
@@ -255,7 +283,7 @@ async function runEval(_args, flags, lang) {
         if (filePath) {
             await announceSavedReport({ report, filePath, reportsDir: config.outputDir, values, lang });
         }
-        const exitCode = await emitEvaluationVerdict(report, values);
+        const exitCode = await emitEvaluationVerdict(report, values, lang);
         throw new CliExit(applyGateExitCode(exitCode, values, lang));
     }
     catch (err) {
@@ -466,6 +494,12 @@ export default class Eval extends BaseCommand {
         'no-gate': Flags.boolean({
             description: bilingual({ zh: '关 verdict gate', en: 'Disable verdict gate' }),
         }),
+        'no-evidence': Flags.boolean({
+            description: bilingual({
+                zh: '不把本次评测写成证据追加进受管记录(默认会为已 install 的 skill 自动写)。',
+                en: 'Do not append this run as evidence to managed records (auto-written for installed skills by default).',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Eval);

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

@@ -15,6 +15,8 @@ export default class Install extends BaseCommand {
         dest: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'git-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'git-ref': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     private installBuiltinAgentSkill;

package/dist/cli/commands/install.js

@@ -1,13 +1,13 @@
-import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { copyFileSync, cpSync, existsSync, mkdirSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, relative, resolve, join, sep } from 'node:path';
+import { basename, dirname, resolve, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Args, Flags } from '@oclif/core';
 import { LANG_FLAG, bilingual } from '../oclif/i18n.js';
 import { BaseCommand } from '../oclif/base-command.js';
 import { tCli } from '../lib/i18n.js';
-import { resolveInstallSource, SourceResolveError } from '../../inputs/source-resolver.js';
-import { buildManagedArtifactRecord, hashArtifactSource, isDistributablePath, managedDir, recordManagedArtifact } from '../../managed/index.js';
+import { resolveInstallSource, resolveRemoteGitSource, SourceResolveError } from '../../inputs/source-resolver.js';
+import { buildManagedArtifactRecord, hashArtifactSource, distributableCopyFilter, managedDir, recordManagedArtifact } from '../../managed/index.js';
 const BUILTIN_OMK_AGENT_SKILL_ID = 'omk-agent-skill';
 const INSTALLABLE_KINDS = ['skill', 'prompt', 'agent', 'workflow'];
 const TARGET_ORDER = ['codex', 'claude'];
@@ -163,17 +163,10 @@ function copyArtifactToTarget(params) {
     if (params.isDirectorySkill) {
         cpSync(params.source, params.targetPath, {
             recursive: true,
-            // 与 hashArtifactSource 共用过滤,保证"分发出去的 == 算进 hash 的":
-            // 源根永远拷;软链跳过(与 hash walk 一致,避免软链目标改了却不触发 drift);
-            // evolve 只在源根第一层排除(嵌套 references/evolve 正常分发),.omk/.git 任意层级排除。
-            filter: (src) => {
-                const rel = relative(params.source, src);
-                if (rel === '')
-                    return true;
-                if (lstatSync(src).isSymbolicLink())
-                    return false;
-                return isDistributablePath(rel.split(sep));
-            },
+            // 与 hashArtifactSource / eval 隔离副本共用同一处过滤(distributableCopyFilter),保证
+            // "分发出去的 == 算进 hash 的 == 测量的副本":源根永远拷;软链跳过;evolve 仅源根第一层排除、
+            // .omk/.git/node_modules 任意层级排除。
+            filter: distributableCopyFilter(params.source),
         });
     }
     else {
@@ -253,6 +246,13 @@ export default class Install extends BaseCommand {
             }),
             command: '<%= config.bin %> install git:main:skills/review',
         },
+        {
+            description: bilingual({
+                zh: '从远端 git 仓库安装 skill（位置参数是仓库内路径；认证用本机 git 凭证；记录钉实际 SHA）',
+                en: 'Install a skill from a remote git repo (positional arg is the in-repo path; auth via local git credentials; record pins the actual SHA)',
+            }),
+            command: '<%= config.bin %> install --git-url https://github.com/org/repo.git --git-ref v1.0.0 skills/review',
+        },
     ];
     static args = {
         input: Args.string({
@@ -299,11 +299,35 @@ export default class Install extends BaseCommand {
             }),
             default: false,
         }),
+        'git-url': Flags.string({
+            description: bilingual({
+                zh: '远端 git 仓库 URL（https / ssh / git@host:path）。给了它时，位置参数当作仓库内 skill 路径（spec）。',
+                en: 'Remote git repository URL (https / ssh / git@host:path). When set, the positional arg is the in-repo skill path (spec).',
+            }),
+        }),
+        'git-ref': Flags.string({
+            description: bilingual({
+                zh: '远端 git 的 ref（分支 / tag / SHA），默认 HEAD。仅配合 --git-url 使用。',
+                en: 'Remote git ref (branch / tag / SHA), default HEAD. Only with --git-url.',
+            }),
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Install);
         const lang = this.lang;
         await this.runWithCliExit(async () => {
+            // --git-ref 必须配 --git-url(否则静默丢弃、误把 spec 当本地路径解析,报错令人困惑)。
+            if (flags['git-ref'] && !flags['git-url']) {
+                throw new Error(tCli('cli.install.git_ref_needs_url', lang));
+            }
+            // 远端 git:--git-url 在场时,位置参数是仓库内 spec(repo 相对路径),先于其它分支判定。
+            if (flags['git-url']) {
+                this.installManagedSkill(args.input, flags.kind, flags, lang, {
+                    url: flags['git-url'],
+                    ref: flags['git-ref'] || 'HEAD',
+                });
+                return;
+            }
             if (args.input === BUILTIN_OMK_AGENT_SKILL_ID) {
                 this.installBuiltinAgentSkill(flags, lang);
                 return;
@@ -330,17 +354,18 @@ export default class Install extends BaseCommand {
         if (!flags['dry-run'])
             console.log(tCli('cli.install.next_hint', lang));
     }
-    installManagedSkill(input, kindFlag, flags, lang) {
+    installManagedSkill(input, kindFlag, flags, lang, remote) {
         // kind 推导:--kind 显式优先;否则缺省 skill(Phase 1 仅 skill)。
         const kind = kindFlag ?? 'skill';
         if (kind !== 'skill') {
             throw new Error(tCli('cli.install.kind_unsupported', lang, { kind }));
         }
-        // 源解析委托给 source-resolver(file / git ...),install 主干源无关。
+        // 源解析委托给 source-resolver(file / 本地 git / 远端 git),install 主干源无关。
+        // 远端走结构化 resolveRemoteGitSource(url/ref/spec 分字段,URL 不经任何字符串切分);
         // resolver 不依赖 CLI,错误以 SourceResolveError(messageKey) 抛出,这里映射成本地化文案。
         let src;
         try {
-            src = resolveInstallSource(input);
+            src = remote ? resolveRemoteGitSource(remote.url, remote.ref, input) : resolveInstallSource(input);
         }
         catch (err) {
             if (err instanceof SourceResolveError) {
@@ -349,7 +374,7 @@ export default class Install extends BaseCommand {
             throw err;
         }
         try {
-            const { localRoot, name, isDirectorySkill, sourceKind, locator, ref } = src;
+            const { localRoot, name, isDirectorySkill, sourceKind, locator, ref, url } = src;
             // 目录-skill 哈整棵可分发树(排除 .omk/.git/evolve);git 源哈的是物化后的临时树。
             const contentHash = hashArtifactSource(localRoot, isDirectorySkill);
             const targets = resolveInstallTargets({ to: flags.to, dest: flags.dest, lang });
@@ -371,7 +396,7 @@ export default class Install extends BaseCommand {
                 const record = buildManagedArtifactRecord({
                     name,
                     kind,
-                    source: { sourceKind, locator, ...(ref ? { ref } : {}), isDirectorySkill },
+                    source: { sourceKind, locator, ...(ref ? { ref } : {}), ...(url ? { url } : {}), isDirectorySkill },
                     contentHash,
                     installedAt: now,
                     distribution,

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

@@ -6,7 +6,7 @@ export declare function collectSampleDesignFailureIds(report: Pick<Report, 'resu
 export declare function assertFixReportMatchesCurrentInputs(params: {
     report: Pick<Report, 'meta'>;
     treatmentName: string;
-    skillContent: string;
+    currentContentHash: string;
     samples: SampleType[];
     sampleIds: Set<string>;
     lang?: CliLang;

package/dist/cli/commands/sample.js

@@ -9,7 +9,8 @@ import { CliExit } from '../lib/cli-exit.js';
 import { tCli } from '../lib/i18n.js';
 import { DEFAULT_REPORTS_DIR } from '../lib/parse-run-config.js';
 import { loadSamples, parseYaml } from '../../inputs/load-samples.js';
-import { hashSample, hashString } from '../../eval-core/evaluation-reporting.js';
+import { hashSample } from '../../eval-core/evaluation-reporting.js';
+import { hashArtifactSource } from '../../inputs/content-hash.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -48,20 +49,29 @@ export function collectSampleDesignFailureIds(report, treatmentName) {
     return ids;
 }
 export function assertFixReportMatchesCurrentInputs(params) {
-    const { report, treatmentName, skillContent, samples, sampleIds } = params;
+    const { report, treatmentName, currentContentHash, samples, sampleIds } = params;
     const lang = params.lang ?? 'zh';
     const issues = [];
-    const expectedSkillHash = report.meta.artifactHashes?.[treatmentName];
-    const currentSkillHash = hashString(skillContent);
-    if (!expectedSkillHash) {
+    // schemaVersion < 2 的报告:artifactHashes 是旧「仅 SKILL.md 正文文本」哈,与当前「整棵可分发树」哈
+    // 不同空间,直接比对会必然误报不一致。识别后给可见提示(归入 issues → 触发「请先重跑 eval」),
+    // 不拿旧文本哈与当前树哈错配比对。sample 指纹口径未变,下面照常校。
+    if ((report.meta.schemaVersion ?? 0) < 2) {
         issues.push(lang === 'zh'
-            ? `报告缺少 ${treatmentName} 的 skill 指纹，无法确认诊断对应当前 SKILL.md。`
-            : `Report is missing the skill hash for ${treatmentName}; cannot verify it matches the current SKILL.md.`);
+            ? `报告早于树哈纪元（skill 指纹口径已从「仅 SKILL.md 文本」改为「整棵可分发树」），无法与当前指纹比对。`
+            : `Report predates the tree-hash era (skill fingerprint changed from SKILL.md-body-text to whole-tree); cannot compare against the current fingerprint.`);
     }
-    else if (expectedSkillHash !== currentSkillHash) {
-        issues.push(lang === 'zh'
-            ? `skill 指纹不一致：报告 ${expectedSkillHash}，当前 ${currentSkillHash}。`
-            : `Skill hash mismatch: report ${expectedSkillHash}, current ${currentSkillHash}.`);
+    else {
+        const expectedSkillHash = report.meta.artifactHashes?.[treatmentName];
+        if (!expectedSkillHash) {
+            issues.push(lang === 'zh'
+                ? `报告缺少 ${treatmentName} 的 skill 指纹，无法确认诊断对应当前 SKILL.md。`
+                : `Report is missing the skill hash for ${treatmentName}; cannot verify it matches the current SKILL.md.`);
+        }
+        else if (expectedSkillHash !== currentContentHash) {
+            issues.push(lang === 'zh'
+                ? `skill 指纹不一致：报告 ${expectedSkillHash}，当前 ${currentContentHash}。`
+                : `Skill hash mismatch: report ${expectedSkillHash}, current ${currentContentHash}.`);
+        }
     }
     const reportSampleHashes = report.meta.sampleHashes;
     if (!reportSampleHashes) {
@@ -196,11 +206,14 @@ async function runSampleFix(args, flags, lang) {
         process.stderr.write(lang === 'zh' ? '✅ 没有 sample_design 类型的失败，无需修复\n' : '✅ No sample_design failures found, nothing to fix\n');
         return;
     }
+    // 当前内容指纹走整树哈,与 eval 报告口径一致:dir-skill(用户传 .../SKILL.md)哈整棵 skill 目录、
+    // 单文件 .md 哈单文件字节。
+    const currentContentHash = hashArtifactSource(isDir ? skillDir : resolvedSkillPath, isDir);
     try {
         assertFixReportMatchesCurrentInputs({
             report,
             treatmentName,
-            skillContent,
+            currentContentHash,
             samples,
             sampleIds: sampleDesignIds,
             lang,

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

@@ -108,6 +108,7 @@ export interface EvalFlags {
     'trivial-diff'?: string;
     'report-only'?: boolean;
     'no-gate'?: boolean;
+    'no-evidence'?: boolean;
 }
 export interface EvolveArgs {
     skillPath: string;

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

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type InstallMessageKey = 'cli.install.asset_missing' | 'cli.install.unknown_input' | 'cli.install.unknown_target' | 'cli.install.invalid_target_combo' | 'cli.install.no_detected_targets' | 'cli.install.target_exists' | 'cli.install.plan' | 'cli.install.plan_skill' | 'cli.install.installed' | 'cli.install.kind_unsupported' | 'cli.install.copied' | 'cli.install.adopted' | 'cli.install.registered' | 'cli.install.target_overlaps_source' | 'cli.install.path_not_found' | 'cli.install.skillmd_missing' | 'cli.install.skillmd_is_symlink' | 'cli.install.not_a_skill' | 'cli.install.not_a_git_repo' | 'cli.install.git_skill_not_found' | 'cli.install.git_unsafe_path' | 'cli.install.next_hint';
+export type InstallMessageKey = 'cli.install.asset_missing' | 'cli.install.unknown_input' | 'cli.install.unknown_target' | 'cli.install.invalid_target_combo' | 'cli.install.no_detected_targets' | 'cli.install.target_exists' | 'cli.install.plan' | 'cli.install.plan_skill' | 'cli.install.installed' | 'cli.install.kind_unsupported' | 'cli.install.copied' | 'cli.install.adopted' | 'cli.install.registered' | 'cli.install.target_overlaps_source' | 'cli.install.path_not_found' | 'cli.install.skillmd_missing' | 'cli.install.skillmd_is_symlink' | 'cli.install.not_a_skill' | 'cli.install.not_a_git_repo' | 'cli.install.git_skill_not_found' | 'cli.install.git_unsafe_path' | 'cli.install.invalid_remote_url' | 'cli.install.remote_fetch_failed' | 'cli.install.remote_ref_not_found' | 'cli.install.remote_skill_not_found' | 'cli.install.git_ref_needs_url' | 'cli.install.next_hint';
 export declare const installDict: Record<InstallMessageKey, CliMessage>;

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

@@ -83,6 +83,26 @@ export const installDict = {
         zh: 'git tree 含越界路径 {path}（.. / 绝对路径 / 空段），拒绝物化以防写出临时目录。该 skill 的 git tree 可能被手工构造，请核查来源。',
         en: 'git tree contains an out-of-bounds path {path} (.. / absolute / empty segment); refusing to materialize to avoid escaping the temp dir. The skill git tree may be hand-crafted; verify the source.',
     },
+    'cli.install.invalid_remote_url': {
+        zh: '不是合法的 git 远端 URL：{url}。支持 https:// / ssh:// / git:// / file:// 或 scp 形式 git@host:path。',
+        en: 'Not a valid git remote URL: {url}. Supported: https:// / ssh:// / git:// / file:// or scp-form git@host:path.',
+    },
+    'cli.install.remote_fetch_failed': {
+        zh: '从远端 {url} 拉取 ref {ref} 失败。请检查 URL、ref 是否存在、以及本机 git 凭证（SSH key / credential helper）。',
+        en: 'Failed to fetch ref {ref} from remote {url}. Check the URL, whether the ref exists, and your local git credentials (SSH key / credential helper).',
+    },
+    'cli.install.remote_ref_not_found': {
+        zh: '远端 {url} 上解析不到 ref {ref}。',
+        en: 'Could not resolve ref {ref} on remote {url}.',
+    },
+    'cli.install.remote_skill_not_found': {
+        zh: '在远端 {url} 的 ref {ref} 下找不到 skill {name}（既无 {name}/SKILL.md 也无 {name}.md）。',
+        en: 'Skill {name} not found at ref {ref} of remote {url} (neither {name}/SKILL.md nor {name}.md).',
+    },
+    'cli.install.git_ref_needs_url': {
+        zh: '--git-ref 需要配 --git-url 一起用（远端 git 源 = URL + ref + 仓库内路径）。',
+        en: '--git-ref requires --git-url (a remote git source = URL + ref + in-repo path).',
+    },
     'cli.install.next_hint': {
         zh: '现在可以在 coding agent 中说「用 omk 评测这个 skill」。',
         en: 'You can now ask your coding agent: "use omk to evaluate this skill".',

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

@@ -1,3 +1,3 @@
 import type { CliMessage } from './types.js';
-export type RunMessageKey = 'cli.progress.preflight_starting' | 'cli.progress.sample_retry' | 'cli.progress.sample_error' | 'cli.progress.sample_executing' | 'cli.progress.sample_exec_done' | 'cli.progress.output_preview' | 'cli.progress.judging' | 'cli.progress.judged' | 'cli.progress.skipped' | 'cli.progress.sample_done' | 'cli.progress.sample_failed_done' | 'cli.run.invalid_repeat' | 'cli.run.invalid_judge_repeat' | 'cli.run.no_debias_length_active' | 'cli.run.invalid_bootstrap_samples' | 'cli.run.bootstrap_samples_too_large' | 'cli.run.dry_run_no_scores' | 'cli.run.skill_section' | 'cli.run.run_section' | 'cli.run.batch_complete' | 'cli.run.batch_verdict_header' | 'cli.run.batch_child_report_missing' | 'cli.run.eval_complete' | 'cli.run.tally' | 'cli.run.report_saved' | 'cli.run.report_only_gate_skipped' | 'cli.run.report_server_running' | 'cli.run.report_server_view' | 'cli.run.report_server_stop' | 'cli.run.no_serve_in_non_tty' | 'cli.run.no_serve_view_hint' | 'cli.run.gold_load_failed' | 'cli.run.gold_load_issue' | 'cli.run.contamination_warning' | 'cli.run.skip_connectivity_warning';
+export type RunMessageKey = 'cli.progress.preflight_starting' | 'cli.progress.sample_retry' | 'cli.progress.sample_error' | 'cli.progress.sample_executing' | 'cli.progress.sample_exec_done' | 'cli.progress.output_preview' | 'cli.progress.judging' | 'cli.progress.judged' | 'cli.progress.skipped' | 'cli.progress.sample_done' | 'cli.progress.sample_failed_done' | 'cli.run.invalid_repeat' | 'cli.run.invalid_judge_repeat' | 'cli.run.no_debias_length_active' | 'cli.run.invalid_bootstrap_samples' | 'cli.run.bootstrap_samples_too_large' | 'cli.run.dry_run_no_scores' | 'cli.run.skill_section' | 'cli.run.run_section' | 'cli.run.batch_complete' | 'cli.run.batch_verdict_header' | 'cli.run.batch_child_report_missing' | 'cli.run.eval_complete' | 'cli.run.tally' | 'cli.run.report_saved' | 'cli.run.evidence_recorded' | 'cli.run.evidence_recorded_unbound' | 'cli.run.report_only_gate_skipped' | 'cli.run.report_server_running' | 'cli.run.report_server_view' | 'cli.run.report_server_stop' | 'cli.run.no_serve_in_non_tty' | 'cli.run.no_serve_view_hint' | 'cli.run.gold_load_failed' | 'cli.run.gold_load_issue' | 'cli.run.contamination_warning' | 'cli.run.skip_connectivity_warning';
 export declare const runDict: Record<RunMessageKey, CliMessage>;

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

@@ -99,6 +99,14 @@ export const runDict = {
         zh: '📄 报告已保存到: {path}\n',
         en: '📄 Report saved to: {path}\n',
     },
+    'cli.run.evidence_recorded': {
+        zh: '🔖 已为受管 skill「{name}」记录评测证据 → measurable\n',
+        en: '🔖 Recorded eval evidence for managed skill "{name}" → measurable\n',
+    },
+    'cli.run.evidence_recorded_unbound': {
+        zh: '🔖 受管 skill「{name}」：评测内容与当前安装版本指纹不一致，证据已留存但不绑当前版本\n',
+        en: '🔖 Managed skill "{name}": eval content differs from the installed version; evidence kept but not bound to current\n',
+    },
     'cli.run.report_only_gate_skipped': {
         zh: 'ℹ 已启用 report-only 模式：保留 verdict 输出，但本次不使用 verdict 改写 exit code。\n',
         en: 'ℹ Report-only mode enabled: verdict is still printed, but it will not affect the exit code.\n',

package/dist/cli/lib/parse-run-config/variant-resolution.js

@@ -24,6 +24,13 @@ import { configVariantsToSpecs } from '../../../inputs/eval-config.js';
  *  引导用户改用 --control-cwd / --treatment-cwd 或 eval.yaml 的 variant.cwd。git 修订语法 `@{...}`
  *  由 parseVariantCwd 保护、不误判。cwd 由调用方在边界注入(见 eval-runner)。 */
 function cliVariantSpec(rawExpr, role, cwd) {
+    // 远端 git 不走 CLI 字符串(URL 的 `:`/`@` 会被 parseGitInput / parseVariantCwd 误切)——
+    // 先于 @cwd guard 拦协议 URL 与 scp 形式 `git@host:path`,给明确的「走 eval.yaml」指引,
+    // 而非让 scp 形式落到下面 @cwd 的迁移报错(误导)。绝对本地路径 `/abs/skill.md` 不在此列。
+    if (/^(https?|ssh|git):\/\//i.test(rawExpr) || /^[\w.-]+@[\w.-]+:/.test(rawExpr)) {
+        throw new Error(`远端 git 源不支持经 --${role} 字符串传入: "${rawExpr}"。请在 eval.yaml 的 variant 上用结构化 `
+            + `git: { url, ref, spec } 字段(避开 URL 里的 : / @ 被误切),CLI 仅支持本地路径与 git:<ref>:<spec>。`);
+    }
     // 探测旧 name@cwd 形态报错。注:含合法 `@`(非 `@{`)的路径(如 /x/@dir/skill.md)会被一并
     // 误判 —— 属 pre-existing 限制(这类路径本就不被 @cwd 支持),报错文案仍指向迁移指引。
     if (parseVariantCwd(rawExpr).cwd !== undefined) {

package/dist/doctor/index.js

@@ -26,10 +26,10 @@ export function resolveDoctorTargets(target, cwd) {
         const skillsDir = join(cwd, 'skills');
         if (existsSync(skillsDir) && statSync(skillsDir).isDirectory()) {
             const variants = discoverVariants(skillsDir).filter((v) => v !== 'baseline');
-            return variants.length > 0 ? resolveArtifacts(skillsDir, variants, { strictBaseline: false }) : [];
+            return variants.length > 0 ? resolveArtifacts(skillsDir, variants, { strictBaseline: false, materialize: false }) : [];
         }
         const variants = discoverVariants(cwd).filter((v) => v !== 'baseline');
-        return variants.length > 0 ? resolveArtifacts(cwd, variants, { strictBaseline: false }) : [];
+        return variants.length > 0 ? resolveArtifacts(cwd, variants, { strictBaseline: false, materialize: false }) : [];
     }
     const absTarget = resolve(target);
     if (!existsSync(absTarget)) {
@@ -38,7 +38,7 @@ export function resolveDoctorTargets(target, cwd) {
     const stat = statSync(absTarget);
     if (stat.isFile() && absTarget.endsWith('.md')) {
         // 单文件:用 file-path 模式(走 resolveArtifacts 的 "包含 /" 分支)
-        return resolveArtifacts(dirname(absTarget), [absTarget], { strictBaseline: false });
+        return resolveArtifacts(dirname(absTarget), [absTarget], { strictBaseline: false, materialize: false });
     }
     if (stat.isDirectory()) {
         // 目录自身就是 directory-skill (含 SKILL.md): 按单个 skill 解析,
@@ -48,10 +48,10 @@ export function resolveDoctorTargets(target, cwd) {
         // skillRoot 丢失,assets/foo.md 这类相对依赖会锚到 doctor 的 cwd 而不是
         // skill 目录, 误报缺文件。
         if (existsSync(join(absTarget, 'SKILL.md'))) {
-            return resolveArtifacts(dirname(absTarget), [basename(absTarget)], { strictBaseline: false });
+            return resolveArtifacts(dirname(absTarget), [basename(absTarget)], { strictBaseline: false, materialize: false });
         }
         const variants = discoverVariants(absTarget).filter((v) => v !== 'baseline');
-        return variants.length > 0 ? resolveArtifacts(absTarget, variants, { strictBaseline: false }) : [];
+        return variants.length > 0 ? resolveArtifacts(absTarget, variants, { strictBaseline: false, materialize: false }) : [];
     }
     throw new Error(`doctor target must be a .md file or directory: ${target}`);
 }

package/dist/eval-core/cache.d.ts

@@ -2,8 +2,8 @@
  * Executor result cache.
  *
  * Caches successful executor results to disk to avoid redundant API calls.
- * Cache key v5 = sha256(model + system + prompt + cwd + allowedSkills + executor +
- *                       runtime + mocks + mocksStrict + effort).
+ * Cache key v6 = sha256(model + system + prompt + cwd + allowedSkills + executor +
+ *                       runtime + mocks + mocksStrict + effort + artifactContentHash).
  * Loaded into memory on init, flushed to disk on save().
  *
  * Prefix bumps intentionally invalidate old entries when construct-validity
@@ -15,6 +15,11 @@
  *       报告 meta 标的 effort 跟实际跑的 effort 不一致 — 测量可比性污染);
  *       同时 cache.set 不再砍 turns / toolCalls — 工具类断言 + diagnostic 要看 trace,
  *       砍掉的话 cached rerun 会让工具断言为空、diagnostic 没真实证据,跟 cold run 不一致
+ * - v6: artifact 内容指纹(contentHash)。`system` 只含 SKILL.md 正文,但本地 dir-skill 的
+ *       references/ 资产是真实运行时输入(cwd=skillRoot,agent 可读),改资产只动 contentHash、
+ *       不动 system → 旧 key 会命中旧输出、贴到新 artifactHashes 上,形成静默测量污染。把
+ *       contentHash 纳入 key,资产变即重跑。git skill 的 contentHash 只随 SKILL.md 变(其资产不
+ *       暴露给 executor、本就不该触发重跑),口径自洽
  */
 import type { ExecutorCache } from '../types/index.js';
 export declare function createCache(cacheDir: string): ExecutorCache;
@@ -27,4 +32,7 @@ mocksStrict?: boolean,
 /** Executor effort 也进 key:effort 'low'/'medium'/'high' 改变 LLM 思考预算,
  *  输出/工具调用/分数都可能不同,跨 effort 共享 cache 会让报告 meta 标的 effort
  *  跟实际生成的 effort 不一致,违反"两份报告比分数前先比 cliVersion / effort"语义。 */
-effort?: string): string;
+effort?: string, 
+/** artifact 内容指纹(整树 / 单文件哈)。本地 dir-skill 改 references/ 资产只动此值、不动 system,
+ *  不进 key 会让改资产后命中旧输出 → 静默污染。空(baseline / 无 skill)等价无指纹。 */
+artifactContentHash?: string): string;

package/dist/eval-core/cache.js

@@ -2,8 +2,8 @@
  * Executor result cache.
  *
  * Caches successful executor results to disk to avoid redundant API calls.
- * Cache key v5 = sha256(model + system + prompt + cwd + allowedSkills + executor +
- *                       runtime + mocks + mocksStrict + effort).
+ * Cache key v6 = sha256(model + system + prompt + cwd + allowedSkills + executor +
+ *                       runtime + mocks + mocksStrict + effort + artifactContentHash).
  * Loaded into memory on init, flushed to disk on save().
  *
  * Prefix bumps intentionally invalidate old entries when construct-validity
@@ -15,6 +15,11 @@
  *       报告 meta 标的 effort 跟实际跑的 effort 不一致 — 测量可比性污染);
  *       同时 cache.set 不再砍 turns / toolCalls — 工具类断言 + diagnostic 要看 trace,
  *       砍掉的话 cached rerun 会让工具断言为空、diagnostic 没真实证据,跟 cold run 不一致
+ * - v6: artifact 内容指纹(contentHash)。`system` 只含 SKILL.md 正文,但本地 dir-skill 的
+ *       references/ 资产是真实运行时输入(cwd=skillRoot,agent 可读),改资产只动 contentHash、
+ *       不动 system → 旧 key 会命中旧输出、贴到新 artifactHashes 上,形成静默测量污染。把
+ *       contentHash 纳入 key,资产变即重跑。git skill 的 contentHash 只随 SKILL.md 变(其资产不
+ *       暴露给 executor、本就不该触发重跑),口径自洽
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
@@ -114,7 +119,10 @@ mocksStrict,
 /** Executor effort 也进 key:effort 'low'/'medium'/'high' 改变 LLM 思考预算,
  *  输出/工具调用/分数都可能不同,跨 effort 共享 cache 会让报告 meta 标的 effort
  *  跟实际生成的 effort 不一致,违反"两份报告比分数前先比 cliVersion / effort"语义。 */
-effort) {
+effort, 
+/** artifact 内容指纹(整树 / 单文件哈)。本地 dir-skill 改 references/ 资产只动此值、不动 system,
+ *  不进 key 会让改资产后命中旧输出 → 静默污染。空(baseline / 无 skill)等价无指纹。 */
+artifactContentHash) {
     // allowedSkills 序列化:undefined → "" / [] → "[]" / [...] → 排序后 JSON。
     // 排序保证 ["a","b"] 和 ["b","a"] 命中同一缓存(语义等价)。
     const isoStr = allowedSkills === undefined
@@ -130,8 +138,8 @@ effort) {
     // executor + runtime + effort 进 cache key:同 model 名走不同 executor 或同 executor
     // 换 binary/SDK 版本时输出可能不同,旧 cache 不可复用。
     const hash = createHash('sha256')
-        .update(`${model || ''}\n${system || ''}\n${prompt || ''}\n${cwd || ''}\n${isoStr}\n${executor || ''}\n${runtimeFingerprint || ''}\n${mockStr}\n${strictStr}\n${effortStr}`)
+        .update(`${model || ''}\n${system || ''}\n${prompt || ''}\n${cwd || ''}\n${isoStr}\n${executor || ''}\n${runtimeFingerprint || ''}\n${mockStr}\n${strictStr}\n${effortStr}\n${artifactContentHash || ''}`)
         .digest('hex')
         .slice(0, 16);
-    return `v5:${hash}`;
+    return `v6:${hash}`;
 }