oh-my-knowledge 0.34.0 → 0.35.0

package/dist/inputs/source-resolver.js

@@ -1,40 +1,56 @@
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve, sep } from 'node:path';
-import { isDistributablePath } from '../managed/index.js';
-import { classifyGitSkillRef, parseGitInput, resolveGitRepoContext, gitJoin, gitLsTreeBlobs, gitShowBytes, skillNameFromPath } from './skill-loader.js';
-export class SourceResolveError extends Error {
-    messageKey;
-    params;
-    constructor(messageKey, params = {}) {
-        super(messageKey);
-        this.name = 'SourceResolveError';
-        this.messageKey = messageKey;
-        this.params = params;
-    }
-}
-const noop = () => { };
+import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { classifyGitSkillRef, parseGitInput, resolveGitRepoContext, materializeGitSkillTree, skillNameFromPath, SourceResolveError, fetchRemoteGitRef } from './skill-loader.js';
 /**
- * 校验 git tree 条目路径在物化目标内,越界即 fail closed(抛 SourceResolveError)。
- * 双保险:既显式拒 `..` / 空段(git tree 可被手工构造出名为 `..` 的子树),也用 resolve 兜底
- * 确认落点仍在 temp 之下(绝对路径 / 符号化逃逸)。绝不静默跳过——跳过会让物化树与真实树发散。
+ * 安装源解析器 —— 把"各种源"物化成统一的本地形态,让 install / managed 主干**源无关**。
+ * 新增一种源 = 加一个分支,install.ts 不动。本模块不依赖 CLI(不打印、不 tCli):错误以
+ * `SourceResolveError(messageKey)` 抛出,由调用方(install)映射成本地化文案。
+ *
+ * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)、远端 git(URL + ref,fetch 到临时 bare)。
+ * 三者沿同一 `ResolvedSource` 契约,install / managed 主干源无关。
  */
-function assertContainedRelPath(temp, relPath) {
-    const segments = relPath.split('/');
-    if (segments.some((s) => s === '' || s === '.' || s === '..')) {
-        throw new SourceResolveError('cli.install.git_unsafe_path', { path: relPath });
-    }
-    const root = resolve(temp);
-    const dest = resolve(temp, relPath);
-    if (dest !== root && !dest.startsWith(root + sep)) {
-        throw new SourceResolveError('cli.install.git_unsafe_path', { path: relPath });
-    }
-}
+// SourceResolveError 住在 skill-loader(让共享 materializeGitSkillTree 能抛它而不成环);此处 re-export
+// 保持 install 既有 import 不破。
+export { SourceResolveError } from './skill-loader.js';
+const noop = () => { };
 export function resolveInstallSource(input) {
     if (input.startsWith('git:'))
         return resolveGitSource(input);
     return resolveFileSource(input);
 }
+/**
+ * 远端 git 源:`<url>` + `<ref>` + repo 相对 `<spec>`(三者结构化传入,URL 不经任何字符串切分,
+ * 避开 `parseGitInput` 的 `:` 与 `parseVariantCwd` 的 `@`)。fetch 到临时 bare → 复用既有
+ * classifyGitSkillRef / materializeGitSkillTree(repoRoot 换成 bare)。locator 落 `git+<url>@<sha>:<spec>`
+ * 仅作记录身份;url 另以结构化字段携带,供 drift 重取。失败 fail-closed 并清临时资源。
+ */
+export function resolveRemoteGitSource(url, ref, spec) {
+    const checkout = fetchRemoteGitRef(url, ref);
+    try {
+        // 远端 URL 指向仓库根,spec 是仓库相对路径 → gitRelDir 为空。
+        const resolved = classifyGitSkillRef(checkout.ref, '', spec, checkout.repoRoot);
+        if (!resolved)
+            throw new SourceResolveError('cli.install.remote_skill_not_found', { url, ref: checkout.ref, name: spec });
+        const mat = materializeGitSkillTree(checkout.ref, resolved, checkout.repoRoot);
+        return {
+            sourceKind: 'git',
+            localRoot: mat.localRoot,
+            name: mat.name,
+            isDirectorySkill: mat.isDirectorySkill,
+            locator: `git+${url}@${checkout.ref}:${spec}`,
+            ref: checkout.ref,
+            url,
+            cleanup: () => {
+                mat.cleanup();
+                checkout.cleanup();
+            },
+        };
+    }
+    catch (err) {
+        checkout.cleanup();
+        throw err;
+    }
+}
 function resolveFileSource(input) {
     const abs = resolve(input);
     if (!existsSync(abs))
@@ -74,52 +90,16 @@ function resolveGitSource(input) {
     if (!resolved) {
         throw new SourceResolveError('cli.install.git_skill_not_found', { ref, name: spec });
     }
-    const temp = mkdtempSync(join(tmpdir(), 'omk-install-git-'));
-    const cleanup = () => {
-        try {
-            rmSync(temp, { recursive: true, force: true });
-        }
-        catch {
-            // 临时目录清理失败不致命
-        }
+    // 物化复用共享 materializeGitSkillTree(install 与 eval 同一条物化路径);install 只需在其上补
+    // locator / sourceKind 包成 ResolvedSource。
+    const mat = materializeGitSkillTree(ref, resolved, ctx.repoRoot);
+    return {
+        sourceKind: 'git',
+        localRoot: mat.localRoot,
+        name: mat.name,
+        isDirectorySkill: mat.isDirectorySkill,
+        locator: `git:${ref}:${spec}`,
+        ref,
+        cleanup: mat.cleanup,
     };
-    try {
-        const locator = `git:${ref}:${spec}`;
-        if (resolved.isDir) {
-            for (const entry of gitLsTreeBlobs(ref, resolved.treePath, ctx.repoRoot)) {
-                // 安全边界 fail closed:git tree 可被 git mktree 手工构造出名为 `..` 的子树,`ls-tree -r` 会
-                // 吐 `../evil.txt`,`join(temp, ...)` 会逃出临时目录写盘、cleanup 也删不掉。任一越界路径(.. /
-                // 绝对路径 / 空段 / 解析后不在 temp 内)直接抛错,而非静默跳过——静默跳过会让物化树与真实
-                // git tree / hash / 分发树发散。正常 checkout 永不触发。
-                assertContainedRelPath(temp, entry.path);
-                if (entry.mode === '120000' || entry.mode === '160000')
-                    continue; // 跳过软链 / submodule(与本地分发一致)
-                if (!isDistributablePath(entry.path.split('/')))
-                    continue; // 排除 .omk/.git/evolve 等
-                const bytes = gitShowBytes(ref, gitJoin(resolved.treePath, entry.path), ctx.repoRoot);
-                if (!bytes)
-                    continue;
-                const dest = join(temp, entry.path);
-                mkdirSync(dirname(dest), { recursive: true });
-                // 保留可执行位(与本地 cpSync 一致);其余 0644。
-                writeFileSync(dest, bytes, { mode: entry.mode === '100755' ? 0o755 : 0o644 });
-            }
-            // 纵深防御:classify 与物化用的是两条 git 路径(gitShowFile vs ls-tree),万一发散(如 treePath 退化)
-            // 导致空树,这里失败而非静默分发一个空 skill。
-            if (!existsSync(join(temp, 'SKILL.md'))) {
-                throw new SourceResolveError('cli.install.git_skill_not_found', { ref, name: spec });
-            }
-            return { sourceKind: 'git', localRoot: temp, name: resolved.name, isDirectorySkill: true, locator, ref, cleanup };
-        }
-        const bytes = gitShowBytes(ref, resolved.fileSkillPath, ctx.repoRoot);
-        if (!bytes)
-            throw new SourceResolveError('cli.install.git_skill_not_found', { ref, name: spec });
-        const dest = join(temp, `${resolved.name}.md`);
-        writeFileSync(dest, bytes);
-        return { sourceKind: 'git', localRoot: dest, name: resolved.name, isDirectorySkill: false, locator, ref, cleanup };
-    }
-    catch (err) {
-        cleanup();
-        throw err;
-    }
 }

package/dist/managed/evidence.d.ts

@@ -0,0 +1,22 @@
+import type { EvaluationReport, ManagedEvidenceRef } from '../types/index.js';
+/**
+ * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ */
+export declare function buildEvidenceRef(report: EvaluationReport, variant: string, verdict: string, recordedAt: string): ManagedEvidenceRef | null;
+export interface RecordedEvidence {
+    recordId: string;
+    name: string;
+    contentHash: string;
+    /** true ⇒ evidence.contentHash 等于记录当前 contentHash → deriveManagedState 计为当前证据 →
+     *  measurable。false ⇒ 测的是旧内容(已 drift),证据留存但不绑当前版本。 */
+    bound: boolean;
+}
+/**
+ * 驱动:对每个能在报告里(按 contentHash 主键 / 同名回退)匹配到被测 variant 的**已纳管**记录,
+ * 追加一条 evidence。返回实际写入的清单(供 CLI 提示,`name` 取受管记录名而非 variant 键)。
+ * 无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export declare function recordEvalEvidence(report: EvaluationReport, verdict: string, recordedAt: string, opts?: {
+    dir?: string;
+}): RecordedEvidence[];

package/dist/managed/evidence.js

@@ -0,0 +1,143 @@
+/**
+ * eval → managed evidence 写入(承接 #203 管理支柱 / #214 验收第 3 条)。
+ *
+ * 一次 `omk eval` 跑完,把结果落成一条 `ManagedEvidenceRef` 追加进**已纳管**记录的 evidence[],
+ * 让 skill 从 `installed` 走到 `measurable`(由 `deriveManagedState` 读时推导)。承重前提是 #214/#218
+ * 已把 install 与 eval 的内容指纹统一到同一空间(整树哈),所以 `report.artifactHashes[variant]` 与
+ * `record.contentHash` 可直接相等比对、evidence 绑得上。
+ *
+ * 三条设计取舍(对应 issue #221 的"待定决策"):
+ *   - **触发**:eval 完成**自动**写,但只写**已存在**的受管记录 —— install 是显式 opt-in,未纳管的
+ *     skill 永不被凭空建记录(零副作用惊吓)。CLI 另给 `--no-evidence` 关闭。
+ *   - **多对一**:append-only + 按 (reportId, contentHash) 去重;保留全部历史条目,当前有效性仍由
+ *     `deriveManagedState` 按 contentHash 匹配裁定(重装新内容后旧证据留存供回滚,却不让新内容显得已测)。
+ *   - **跨源**:用三级身份消歧把被测 variant 对到受管记录(install 与 eval 命名不一致:记录名是
+ *     skill 短名 `review`,而 eval 报告 variant key 可能是整串表达式 `git:HEAD:skills/review`、
+ *     eval.yaml 别名 `candidate`、blind 模式的 `A`/`B`)。`applyBlindMode` 盲化 `variants` 但**不**动
+ *     `artifactHashes` / `variantConfigs` 的键面,故三级都按真实键工作:
+ *       (a) 显式**同名** variant —— 最强身份(本地 `--treatment <name>` 与 drift);
+ *       (b) **结构化源匹配** —— `variantConfigs[].locator(+ref)` 与 `record.source` 对齐(git / 远端 /
+ *           别名),即便内容撞哈也能精确消歧;
+ *       (c) **纯 contentHash 回退** —— 仅当该内容哈在受管记录中**唯一**才用。否则两条不同记录恰好当前
+ *           内容相同(同模板复制 / 刚装)时,只测了一条的 report 会把同哈的另一条也推成 measurable ——
+ *           唯一性闸门挡掉这种越权写入(撞哈又非同名 / 无结构化身份 → 跳过,不乱绑)。
+ *
+ * bundle 按 evidence-gated-management.md §5 denormalize 进记录(reportId / contentHash /
+ * verdict / sampleCoverage / comparability),不依赖 report 文件仍在盘。
+ */
+import { basename, dirname } from 'node:path';
+import { hashString } from '../eval-core/evaluation-reporting.js';
+import { loadAllManagedRecords, appendManagedEvidence, managedDir, resolveManagedDir } from './store.js';
+/** baseline / 无 skill 变体的 artifactHash 哨兵(见 report.ts artifactHashes 注释)——不产证据。 */
+const NO_SKILL = 'no-skill';
+/** 样本集覆盖摘要:report 的 sampleHashes 排序后取一个稳定 digest(同一样本集 ⇒ 同 hash)。
+ *  缺 sampleHashes(旧报告 / --dry-run)→ undefined,bundle 仍含其余三项 mandatory。 */
+function sampleCoverage(report) {
+    const sh = report.meta?.sampleHashes;
+    if (!sh)
+        return undefined;
+    const entries = Object.entries(sh).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return { count: entries.length, hash: hashString(JSON.stringify(entries)) };
+}
+/**
+ * 为某个变体组装一条 evidence ref;变体无真实内容(baseline / no-skill / 缺 hash)→ null。
+ * `verdict` 由调用方传入(CLI 已 computeVerdict,避免在此重算)。
+ */
+export function buildEvidenceRef(report, variant, verdict, recordedAt) {
+    const contentHash = report.meta?.artifactHashes?.[variant];
+    if (!contentHash || contentHash === NO_SKILL)
+        return null;
+    const meta = report.meta;
+    const cov = sampleCoverage(report);
+    return {
+        reportId: report.id,
+        contentHash,
+        recordedAt,
+        verdict,
+        ...(cov ? { sampleCoverage: cov } : {}),
+        comparability: {
+            cliVersion: meta.cliVersion,
+            ...(meta.judgePromptHash ? { judgePromptHash: meta.judgePromptHash } : {}),
+            ...(meta.debiasMode ? { debiasMode: meta.debiasMode } : {}),
+        },
+    };
+}
+/**
+ * variantConfig 的源身份是否与受管记录 source 对得上 —— install 与 eval 两侧 locator **口径不同**,
+ * 必须先归一化再比,不能裸字符串相等(否则同 hash 多记录场景下正确的本地 git / 目录-skill 也会因
+ * locator 不等而漏写):
+ *   - 直接相等:远端 git(两侧都 `git+<url>@<sha>:<spec>`)、本地 file-skill(两侧都是 .md 路径);
+ *   - 本地 git:install 记完整身份串 `git:<ref>:<spec>`,eval 把 spec 落 `cfg.locator`、ref 另存 `cfg.ref`
+ *     → 归一化成 `git:<cfg.ref>:<cfg.locator>` 再比;
+ *   - 本地目录-skill:install 记目录根,eval 记 `<dir>/SKILL.md` → 比 `dirname(cfg.locator)`。
+ */
+function sourceMatches(cfg, source) {
+    if (!cfg.locator)
+        return false;
+    if (cfg.locator === source.locator)
+        return true;
+    if (source.sourceKind === 'git' && cfg.ref && `git:${cfg.ref}:${cfg.locator}` === source.locator)
+        return true;
+    if (source.isDirectorySkill && basename(cfg.locator) === 'SKILL.md' && dirname(cfg.locator) === source.locator)
+        return true;
+    return false;
+}
+/**
+ * 给某条受管记录在报告里找该绑定的 variant key,三级身份消歧(见文件头「跨源」)。
+ * `hashIsUnique` 由调用方按全体受管记录的 contentHash 计数提供 —— 纯 hash 回退的越权闸门。
+ */
+function matchVariantKey(report, record, hashIsUnique) {
+    const hashes = report.meta?.artifactHashes ?? {};
+    // (a) 显式同名 variant(本地 --treatment <name> / drift)。
+    if (hashes[record.name] && hashes[record.name] !== NO_SKILL)
+        return record.name;
+    // (b) 结构化源匹配:variantConfig.locator(+ref) 对齐记录 source(git / 远端 / 别名)。
+    for (const cfg of report.meta?.variantConfigs ?? []) {
+        const h = hashes[cfg.variant];
+        if (!h || h === NO_SKILL)
+            continue;
+        if (sourceMatches(cfg, record.source))
+            return cfg.variant;
+    }
+    // (c) 纯 contentHash 回退 —— 仅当该哈在受管记录中唯一(否则撞哈会越权写到没测的记录)。
+    if (hashIsUnique(record.contentHash)) {
+        for (const [key, hash] of Object.entries(hashes)) {
+            if (hash !== NO_SKILL && hash === record.contentHash)
+                return key;
+        }
+    }
+    return undefined;
+}
+/**
+ * 驱动:对每个能在报告里(按 contentHash 主键 / 同名回退)匹配到被测 variant 的**已纳管**记录,
+ * 追加一条 evidence。返回实际写入的清单(供 CLI 提示,`name` 取受管记录名而非 variant 键)。
+ * 无任何记录匹配 → 返回空(常见的非管理用户场景,静默无副作用)。
+ */
+export function recordEvalEvidence(report, verdict, recordedAt, opts = {}) {
+    const out = [];
+    if (Object.keys(report.meta?.artifactHashes ?? {}).length === 0)
+        return out;
+    // 写回读方实际取记录的同一目录(project→global 同口径)。
+    const dir = resolveManagedDir(opts.dir ?? managedDir());
+    const records = loadAllManagedRecords(dir);
+    if (records.length === 0)
+        return out;
+    // 全体记录的 contentHash 计数 —— 纯 hash 回退只在唯一时放行(挡同内容多记录的越权写)。
+    const hashCount = new Map();
+    for (const r of records)
+        hashCount.set(r.contentHash, (hashCount.get(r.contentHash) ?? 0) + 1);
+    const hashIsUnique = (hash) => (hashCount.get(hash) ?? 0) === 1;
+    for (const rec of records) {
+        const variantKey = matchVariantKey(report, rec, hashIsUnique);
+        if (!variantKey)
+            continue;
+        const ref = buildEvidenceRef(report, variantKey, verdict, recordedAt);
+        if (!ref)
+            continue;
+        const merged = appendManagedEvidence(dir, rec.id, ref);
+        if (!merged)
+            continue;
+        out.push({ recordId: rec.id, name: rec.name, contentHash: ref.contentHash, bound: ref.contentHash === merged.contentHash });
+    }
+    return out;
+}

package/dist/managed/index.d.ts

@@ -3,3 +3,4 @@
  * 不直接依赖内部文件布局。
  */
 export * from './store.js';
+export * from './evidence.js';

package/dist/managed/index.js

@@ -3,3 +3,4 @@
  * 不直接依赖内部文件布局。
  */
 export * from './store.js';
+export * from './evidence.js';

package/dist/managed/store.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDistributionTarget } from '../types/index.js';
+import type { ArtifactKind, DeriveManagedStateInput, DerivedManagedState, ManagedArtifactRecord, ManagedArtifactSource, ManagedDistributionTarget, ManagedEvidenceRef } from '../types/index.js';
 /**
  * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
  * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
@@ -14,28 +14,16 @@ export declare function globalManagedDir(): string;
 export declare function recordPath(dir: string, id: string): string;
 /** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
 export declare function managedRecordId(kind: ArtifactKind, name: string): string;
-/**
- * 给定相对源根的路径分段(空数组 = 源根本身),判断是否进可分发树。hash 的 walk、copy 的 filter、
- * git 物化共用此一处,保证三者完全一致。
- *
- * 关键:检查**每一段**而非只看叶子。本地 walk / cpSync 是逐层下降、命中目录即剪枝,只看叶子也够;
- * 但 git ls-tree 给的是**扁平路径**(如 `.omk/samples.json`),只看叶子 `samples.json` 会让 `.omk`
- * 内容漏过。故:任一段命中全局排除即排除;首段命中 root-only(evolve)即排除(嵌套同名是合法资产)。
- */
-export declare function isDistributablePath(segments: string[]): boolean;
-/**
- * artifact 内容 hash —— drift baseline 与 evidence 绑定的依据。
- *   - 文件-skill:单个 .md 的字节;
- *   - 目录-skill:覆盖**整棵可分发目录树**(SKILL.md + references/ 等资产,但排除 .omk / .git /
- *     evolve 等评测迭代产物),按相对路径排序后把每个文件的`路径 + 字节长度 + 内容`喂进同一个
- *     sha256 —— 改任意资产都会令 hash 变化、drift 不漏;只补样本则 hash 不动。
- * 用 createHash 直接喂 Buffer(字节级,二进制资产也稳;分隔符是运行时字节,源码里不引入任何不可见字符)。
- * 读时(未来 list / drift 检查)用同一函数重算比对。
- */
-export declare function hashArtifactSource(source: string, isDirectorySkill: boolean): string;
+export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
 export declare function loadManagedRecord(dir: string, id: string): ManagedArtifactRecord | null;
 /** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
 export declare function loadAllManagedRecords(dir?: string): ManagedArtifactRecord[];
+/**
+ * 哪个 managed 目录是权威(有记录的那个):项目目录非空取项目,否则全局非空取全局,都空回项目。
+ * 与 `loadAllManagedRecords` 的 project→global 回退**同口径** —— 写方(append evidence)据此写回
+ * 读方实际取记录的同一目录,避免"读全局、写项目"把证据落到空目录。
+ */
+export declare function resolveManagedDir(dir?: string): string;
 /**
  * 纯合并逻辑(无 IO):install 写的是事实,绝不动 evidence/decisions(那是 eval/promote 的地盘)。
  *   - distribution 按 path 去重(同路径以新值替换);
@@ -48,6 +36,14 @@ export declare function loadAllManagedRecords(dir?: string): ManagedArtifactReco
 export declare function mergeManagedRecord(prev: ManagedArtifactRecord | null, next: ManagedArtifactRecord): ManagedArtifactRecord;
 /** 读旧记录 → 合并 → 原子 tmp+rename 只写该 id 的文件。返回合并后记录。 */
 export declare function upsertManagedRecord(dir: string, record: ManagedArtifactRecord): ManagedArtifactRecord;
+/**
+ * 追加一条评测证据(append-only)。与 install 的 upsert 路径相反——`mergeManagedRecord` 刻意**保留旧
+ * evidence、丢弃 next.evidence**(install 只写事实),所以证据写入不能走 upsert,必须独立 load→push→
+ * 原子重写。按 `(reportId, contentHash)` 去重:重跑同一份 eval 不堆重复条目(reportId 含运行身份,
+ * 同内容重测会是新 reportId → 新条目,正是要的版本史)。记录不存在(未 install / 名字不匹配)返回
+ * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
+ */
+export declare function appendManagedEvidence(dir: string, recordId: string, evidence: ManagedEvidenceRef): ManagedArtifactRecord | null;
 /**
  * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
  * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。

package/dist/managed/store.js

@@ -1,4 +1,3 @@
-import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, normalize } from 'node:path';
@@ -26,81 +25,9 @@ export function recordPath(dir, id) {
 export function managedRecordId(kind, name) {
     return hashString(`${kind}|${name}`);
 }
-/**
- * 不进 artifact「可分发树」的条目 —— omk 的评测 / 迭代 / VCS / 系统产物,既不该被拷进 agent
- * skill 目录,也不该计入 artifact contentHash。区分两类语义,避免误伤合法嵌套资产:
- *   - **任意层级排除**:隐藏元数据 / VCS / 系统 / 依赖目录,任何深度出现都是噪声
- *     (`.omk` = samples / managed / observations;`.git`;`node_modules`;OS 垃圾);
- *   - **仅源根第一层排除**:omk 保留的工作目录,只在 skill 根有保留语义,嵌套同名是用户合法资产
- *     (`evolve` 是 `<skillDir>/evolve/` 候选快照;但 `references/evolve/guide.md` 应正常分发并计入 hash)。
- * spec 里 artifact content hash 与 sample-set hash 是分开的证据轴,故只补样本(.omk)不该改 hash。
- */
-const GLOBAL_EXCLUDED_NAMES = new Set(['.omk', '.git', 'node_modules', '.DS_Store', 'Thumbs.db']);
-const ROOT_ONLY_EXCLUDED_NAMES = new Set(['evolve']);
-/**
- * 给定相对源根的路径分段(空数组 = 源根本身),判断是否进可分发树。hash 的 walk、copy 的 filter、
- * git 物化共用此一处,保证三者完全一致。
- *
- * 关键:检查**每一段**而非只看叶子。本地 walk / cpSync 是逐层下降、命中目录即剪枝,只看叶子也够;
- * 但 git ls-tree 给的是**扁平路径**(如 `.omk/samples.json`),只看叶子 `samples.json` 会让 `.omk`
- * 内容漏过。故:任一段命中全局排除即排除;首段命中 root-only(evolve)即排除(嵌套同名是合法资产)。
- */
-export function isDistributablePath(segments) {
-    if (segments.length === 0)
-        return true; // 源根永远算
-    for (const seg of segments) {
-        if (GLOBAL_EXCLUDED_NAMES.has(seg))
-            return false;
-    }
-    if (ROOT_ONLY_EXCLUDED_NAMES.has(segments[0]))
-        return false;
-    return true;
-}
-/**
- * artifact 内容 hash —— drift baseline 与 evidence 绑定的依据。
- *   - 文件-skill:单个 .md 的字节;
- *   - 目录-skill:覆盖**整棵可分发目录树**(SKILL.md + references/ 等资产,但排除 .omk / .git /
- *     evolve 等评测迭代产物),按相对路径排序后把每个文件的`路径 + 字节长度 + 内容`喂进同一个
- *     sha256 —— 改任意资产都会令 hash 变化、drift 不漏;只补样本则 hash 不动。
- * 用 createHash 直接喂 Buffer(字节级,二进制资产也稳;分隔符是运行时字节,源码里不引入任何不可见字符)。
- * 读时(未来 list / drift 检查)用同一函数重算比对。
- */
-export function hashArtifactSource(source, isDirectorySkill) {
-    if (!isDirectorySkill) {
-        return createHash('sha256').update(readFileSync(source)).digest('hex').slice(0, 12);
-    }
-    const rels = [];
-    const walk = (dir, segments) => {
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            const segs = [...segments, entry.name];
-            if (!isDistributablePath(segs))
-                continue;
-            // 软链既非 isFile 也非 isDirectory,天然跳过 —— 与 copyArtifactToTarget 的 filter 一致
-            // (hash 覆盖的 == 分发出去的),避免软链目标改变却不触发 drift,也回避软链环。
-            if (entry.isDirectory())
-                walk(join(dir, entry.name), segs);
-            else if (entry.isFile())
-                rels.push(segs.join('/'));
-        }
-    };
-    walk(source, []);
-    rels.sort();
-    const h = createHash('sha256');
-    const sep = Buffer.from([0]);
-    for (const rel of rels) {
-        const content = readFileSync(join(source, rel));
-        // 路径与内容都做长度前缀,彻底排除"不同树拼出同一串"的歧义(文件名虽不含 NUL,核心层仍按可注入防)。
-        h.update(String(Buffer.byteLength(rel)));
-        h.update(sep);
-        h.update(rel);
-        h.update(sep);
-        h.update(String(content.length));
-        h.update(sep);
-        h.update(content);
-        h.update(sep);
-    }
-    return h.digest('hex').slice(0, 12);
-}
+// 内容指纹工具已下沉到 inputs 层(install 与 eval 共用同一处,保证指纹同空间);此处 re-export
+// 保持 managed 公共入口不破(install 仍从 managed 取 hashArtifactSource / isDistributablePath)。
+export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from '../inputs/content-hash.js';
 function isStringField(v) {
     return typeof v === 'string';
 }
@@ -175,6 +102,19 @@ export function loadAllManagedRecords(dir = managedDir()) {
     }
     return local;
 }
+/**
+ * 哪个 managed 目录是权威(有记录的那个):项目目录非空取项目,否则全局非空取全局,都空回项目。
+ * 与 `loadAllManagedRecords` 的 project→global 回退**同口径** —— 写方(append evidence)据此写回
+ * 读方实际取记录的同一目录,避免"读全局、写项目"把证据落到空目录。
+ */
+export function resolveManagedDir(dir = managedDir()) {
+    if (readRecordsFromDir(dir).length > 0)
+        return dir;
+    const global = globalManagedDir();
+    if (dir !== global && readRecordsFromDir(global).length > 0)
+        return global;
+    return dir;
+}
 /**
  * 纯合并逻辑(无 IO):install 写的是事实,绝不动 evidence/decisions(那是 eval/promote 的地盘)。
  *   - distribution 按 path 去重(同路径以新值替换);
@@ -217,6 +157,30 @@ export function upsertManagedRecord(dir, record) {
     renameSync(tmp, path);
     return merged;
 }
+/**
+ * 追加一条评测证据(append-only)。与 install 的 upsert 路径相反——`mergeManagedRecord` 刻意**保留旧
+ * evidence、丢弃 next.evidence**(install 只写事实),所以证据写入不能走 upsert,必须独立 load→push→
+ * 原子重写。按 `(reportId, contentHash)` 去重:重跑同一份 eval 不堆重复条目(reportId 含运行身份,
+ * 同内容重测会是新 reportId → 新条目,正是要的版本史)。记录不存在(未 install / 名字不匹配)返回
+ * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
+ */
+export function appendManagedEvidence(dir, recordId, evidence) {
+    const prev = loadManagedRecord(dir, recordId);
+    if (!prev)
+        return null;
+    const dup = prev.evidence.some((e) => e.reportId === evidence.reportId && e.contentHash === evidence.contentHash);
+    const merged = dup
+        ? prev
+        : { ...prev, evidence: [...prev.evidence, evidence] };
+    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;
+}
 /**
  * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
  * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。

package/dist/renderer/layout.js

@@ -159,7 +159,7 @@ export const I18N = {
         diffColCoverage: '覆盖',
         viewTrendLink: '查看趋势 →',
         artifactHashLabel: '版本指纹',
-        artifactHashTooltip: 'skill 文件内容的 SHA-256 前 12 位(不含路径/时间/git),用于辨别报告对应哪一版 skill;同文件多次跑指纹不变,改一字节就变——防止"改动效果"和"随机波动"混淆',
+        artifactHashTooltip: 'skill 内容指纹的 SHA-256 前 12 位(不含路径/时间/git):目录-skill(本地或 git)覆盖整棵可分发树(SKILL.md + references/ 资产,排除 .omk/.git/node_modules/evolve;改任意资产都变,git 源经隔离副本物化、整树暴露给 executor),单文件-skill 取该 .md 字节;用于辨别报告对应哪一版 skill,同输入指纹不变——防止"改动效果"和"随机波动"混淆',
         switchLang: '英文',
     },
     en: {
@@ -272,7 +272,7 @@ export const I18N = {
         diffColCoverage: 'Coverage',
         viewTrendLink: 'trend →',
         artifactHashLabel: 'Version fingerprint',
-        artifactHashTooltip: 'First 12 hex chars of SHA-256 over the skill file content (content-only: no path/time/git); identifies which version of the skill this report ran — same file = same fingerprint, any byte change = different fingerprint. Keeps "intentional change" separate from "random variance"',
+        artifactHashTooltip: 'First 12 hex chars of SHA-256 over the skill content (content-only: no path/time/git): a directory-skill (local or git) covers the whole distributable tree (SKILL.md + references/ assets, excluding .omk/.git/node_modules/evolve; any asset change flips it; git sources are materialized into an isolated copy whose whole tree is exposed to the executor), a file-skill covers the single .md bytes. Identifies which version of the skill this report ran — same input = same fingerprint. Keeps "intentional change" separate from "random variance"',
         switchLang: 'Chinese',
     },
 };

package/dist/types/eval.d.ts

@@ -136,10 +136,12 @@ export interface Artifact {
     kind: ArtifactKind;
     source: 'baseline' | 'variant-name' | 'file-path' | 'git' | 'inline' | 'custom';
     content: string | null;
+    contentHash?: string;
     locator?: string;
     ref?: string;
     cwd?: string;
     skillRoot?: string;
+    execRoot?: string;
     experimentRole?: ExperimentRole;
     allowedSkills?: string[];
     metadata?: Record<string, unknown>;
@@ -160,17 +162,26 @@ export interface VariantConfig {
     ref?: string;
     allowedSkills?: string[];
 }
+/** 远端 git 源的结构化引用 —— url/ref/spec 分字段,永不拼成单串再 split(避开 parseGitInput 的 `:`
+ *  与 parseVariantCwd 的 `@`)。eval 经 eval.yaml 结构化携带,install 经 --git-url/--git-ref。 */
+export interface RemoteGitRef {
+    url: string;
+    ref?: string;
+    spec: string;
+}
 export interface VariantSpec {
     name: string;
     role: ExperimentRole;
     expr: string;
+    git?: RemoteGitRef;
     cwd?: string;
     allowedSkills?: string[];
 }
 export interface EvalConfigVariant {
     name: string;
     role: ExperimentRole;
-    artifact: string;
+    artifact?: string;
+    git?: RemoteGitRef;
     cwd?: string;
     allowedSkills?: string[];
 }

package/dist/types/managed.d.ts

@@ -21,13 +21,35 @@ export interface ManagedDistributionTarget {
     contentHash: string;
     copiedAt: string;
 }
-/** 指向一份 Report 的引用——不是 verdict 本体。install 时为空,eval/promote 追加。 */
+/** 指向一份 Report 的引用 + 该 report 的最小可比性快照——不是 verdict 本体。install 时为空,
+ *  eval 完成后追加(见 `src/managed/evidence.ts`)。
+ *
+ *  `reportId` / `contentHash` 是承重的两根(读时门控只认这俩,validator 也只硬查这俩);其余三项是
+ *  `evidence-gated-management.md` §5 的 mandatory bundle —— **denormalize** 进记录(而非读时回 report
+ *  解析),让受管记录自解释、可 grep、不依赖 report 文件仍在盘。旧记录(eval 写入前)无这三项,按
+ *  optional 读;deriveManagedState 不依赖它们,故缺失不影响生命周期推导。 */
 export interface ManagedEvidenceRef {
     reportId: string;
     /** 该 report 测的是哪份内容(artifact contentHash)。读时只把与记录当前 contentHash 匹配的
      *  evidence 算作当前有效证据——重装到新内容后旧证据保留供回滚,但不让新内容显得已测。 */
     contentHash: string;
     recordedAt: string;
+    /** §5 mandatory:report 时计算的 verdict 等级(PROGRESS / CAUTIOUS / REGRESS / NOISE /
+     *  UNDERPOWERED / SOLO)。存字符串而非 import VerdictLevel —— 保 types 层为叶子、不依赖 eval-core。
+     *  measurable 不看 verdict(任何评测都算"已测");verdict 是 promote 门控的事。 */
+    verdict?: string;
+    /** §5 mandatory:样本集覆盖。`count`=被测样本数,`hash`=report 的 sampleHashes 排序后摘要
+     *  (同一样本集 ⇒ 同 hash),供 promote / list 不加载重 report 即可判覆盖与"同一用例集"。 */
+    sampleCoverage?: {
+        count: number;
+        hash: string;
+    };
+    /** §5 mandatory:可比性 marker。跨 report 比 verdict / Δ 前必须三者一致,否则不可比。 */
+    comparability?: {
+        cliVersion: string;
+        judgePromptHash?: string;
+        debiasMode?: Array<'length' | 'position'>;
+    };
 }
 export type ManagedDecisionKind = 'promote' | 'reject' | 'rollback';
 /** 一次人工管理决定。install 时为空,promote/reject/rollback 追加。 */
@@ -38,14 +60,17 @@ export interface ManagedDecision {
     reason?: string;
 }
 export interface ManagedArtifactSource {
-    /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库的某个 ref。 */
+    /** 源类型(限定判别字,非裸 kind)。`file`=本地路径;`git`=当前仓库某 ref 或远端(带 url)。 */
     sourceKind: 'file' | 'git';
     /** 源身份,按 sourceKind 分义:
      *   - file:本地重哈根(目录-skill 为根目录、文件-skill 为 .md),`hashArtifactSource(locator, isDirectorySkill)` 直接 round-trip;
-     *   - git:`git:<ref>:<name>`(非临时物化路径),drift 由 resolver 重物化重哈 —— mutable ref 给真实漂移、SHA 给不可变。 */
+     *   - 本地 git:`git:<ref>:<name>`;远端 git:`git+<url>@<sha>:<name>`(均非临时物化路径,远端串仅作身份、不回喂 parseGitInput)。
+     *     drift 由 resolver 重物化重哈 —— mutable ref 给真实漂移、SHA 给不可变。 */
     locator: string;
-    /** git 来源的 ref(file 源无)。 */
+    /** git 来源的 ref(file 源无);远端为 fetch 后 pin 的实际 SHA。 */
     ref?: string;
+    /** 远端 git 的 URL(本地源 / 本地 git 无)。结构化存,供 drift 重取,不必从 locator 反 parse。 */
+    url?: string;
     /** 目录-skill(SKILL.md + assets)还是裸 .md 文件-skill。 */
     isDirectorySkill: boolean;
 }