oh-my-knowledge 0.34.0 → 0.35.0

package/dist/eval-core/dependency-checker.js

@@ -159,10 +159,12 @@ function buildPreflightEnv(artifacts) {
         return process.env;
     const extraPaths = [];
     for (const a of artifacts) {
-        // git artifact 的 locator 是 git spec、非在盘目录,对它取 dirname 会得到伪路径;跳过(与 extractSkillDir 一致)。
-        if (!a.locator || a.source === 'git')
+        // 与 extractSkillDir 一致:dir-skill 优先隔离副本 execRoot(副本无 node_modules、.bin 检查恒不命中);
+        // 否则本地文件-skill 取 .md 所在目录。git 文件-skill 的 locator 是 git spec、非在盘目录,无 execRoot
+        // 时跳过(取 dirname 会得伪路径)。
+        const dir = a.execRoot ?? (a.locator && a.source !== 'git' ? dirname(a.locator) : null);
+        if (!dir)
             continue;
-        const dir = dirname(a.locator);
         const nodeBin = join(dir, 'node_modules', '.bin');
         if (existsSync(nodeBin))
             extraPaths.push(nodeBin);

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

@@ -85,7 +85,10 @@ export async function executeTasks({ tasks, executor, executorName, model, noJud
         // don't share cache entries, and include runtime fingerprint so a binary/SDK bump
         // cannot replay old-runtime outputs under new-runtime report metadata.
         // 同时把 mocks + mocksStrict 进 key:改 mock 配置必须重跑,不能命中老 cache。
-        const key = cacheKey(model, executionPlan.cacheSystem, executionPlan.input.prompt, executionPlan.input.cwd, task.artifact.allowedSkills, effectiveExecutorName, executorRuntime.fingerprint, executionPlan.input.mocks, executionPlan.input.mocksStrict, effort);
+        const key = cacheKey(model, executionPlan.cacheSystem, executionPlan.input.prompt, executionPlan.input.cwd, task.artifact.allowedSkills, effectiveExecutorName, executorRuntime.fingerprint, executionPlan.input.mocks, executionPlan.input.mocksStrict, effort, 
+        // artifact 内容指纹进 key:本地 dir-skill 改 references/ 资产只动 contentHash,system 不变,
+        // 不进 key 会命中旧输出贴到新 artifactHashes(静默污染)。
+        task.artifact.contentHash);
         const cached = cache?.get(key);
         const execStart = Date.now();
         if (cached) {

package/dist/eval-core/evaluation-reporting.js

@@ -92,13 +92,14 @@ function buildExecutorRuntimesByVariant({ variants, model, executorName, tasks,
         if (runtimes[variant])
             continue;
         const artifact = artifacts.find((a) => a.name === variant);
-        // git artifact 无在盘 skillDir(content 经 SDK 注入),与 baseline 一样取 null —— 与主路径
-        // extractSkillDir 的判定一致,避免 git variant 的 runtime fingerprint 被 cwd 的 node_modules 污染。
-        const fallbackSkillDir = artifact?.kind === 'baseline' || artifact?.source === 'git'
-            ? null
-            : artifact?.locator
-                ? dirname(artifact.locator)
-                : request?.skillDir;
+        // 与主路径 extractSkillDir 一致:dir-skill 优先隔离副本 execRoot(副本无 node_modules、PATH 不污染);
+        // 否则 baseline / git 文件-skill 取 null,本地文件-skill 取 .md 所在目录。
+        const fallbackSkillDir = artifact?.execRoot
+            ?? (artifact?.kind === 'baseline' || artifact?.source === 'git'
+                ? null
+                : artifact?.locator
+                    ? dirname(artifact.locator)
+                    : request?.skillDir);
         runtimes[variant] = getExecutorRuntimeFingerprint(executorName, model, {
             skillDir: fallbackSkillDir,
         });
@@ -151,7 +152,11 @@ export function aggregateReport({ runId, variants, model, judgeModel, noJudge, e
             }
         }
     }
-    const artifactHashes = Object.fromEntries(artifacts.map((artifact) => [artifact.name, artifact.content ? hashString(artifact.content) : 'no-skill']));
+    // 整树内容指纹:解析期已由 resolveArtifacts 用 hashArtifactSource 算好挂在 artifact.contentHash 上
+    // (目录-skill 覆盖整棵可分发树含 references/ 资产、文件-skill 为单文件字节),与 install 受管记录的
+    // contentHash 落在同一空间——证据可绑定的前提,也修掉「只哈 SKILL.md 正文、改资产指纹不变」的资产瞎。
+    // baseline / 无 skill 记 'no-skill'。
+    const artifactHashes = Object.fromEntries(artifacts.map((artifact) => [artifact.name, artifact.contentHash ?? 'no-skill']));
     const sampleHashes = Object.fromEntries(samples.map((s) => [s.sample_id, hashSample(s)]));
     const judgeRepeat = request?.judgeRepeat && request.judgeRepeat > 1 ? request.judgeRepeat : undefined;
     const runtimeOptions = { skillDir: request?.skillDir };
@@ -191,6 +196,10 @@ export function aggregateReport({ runId, variants, model, judgeModel, noJudge, e
             timestamp: new Date().toISOString(),
             cliVersion: getCliVersion(),
             nodeVersion: process.version,
+            // schemaVersion 3 起,所有 dir-skill(本地 + git)都经隔离副本物化、整棵可分发树哈,与 install
+            // 受管记录 contentHash 同空间(evidence 全绑)。2 是过渡纪元(本地 dir-skill 树哈、git dir-skill
+            // 仅 SKILL.md 字节、不绑);git dir-skill 的 v2 与 v3 不可比。作判别位:消费方对缺位/旧报告不错配比对。
+            schemaVersion: 3,
             artifactHashes,
             sampleHashes,
             ...(noJudge ? {} : { judgePromptHash: getJudgePromptHash(lengthDebiasOn) }),

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

@@ -72,10 +72,12 @@ export function buildVariantConfig(artifact) {
     };
 }
 function extractSkillDir(artifact) {
-    // git artifact 的 content 经 SDK 注入、根本不落盘,其 locator 是 git spec(`review` / `skills/review`)
-    // 而非磁盘目录。若对它取 dirname,会得到相对进程 cwd 的伪 skillDir(`.` / `skills`),进而让 buildExecEnv
-    // 把 `<cwd>/node_modules/.bin` 误并进 PATH、污染 runtime fingerprint —— 与 baseline(skillDir=null)
-    // 不对称,造成 Δ 污染。git 与 baseline 一样无在盘 skillDir,返回 null。
+    // dir-skill(任意源)优先用隔离副本执行根 execRoot:agent cwd 锚副本、skillDir 也指副本。副本经
+    // distributable filter 物化、不含 node_modules → buildExecEnv 的 .bin 检查恒不命中 → PATH 不被污染。
+    if (artifact.execRoot)
+        return artifact.execRoot;
+    // git 文件-skill 无 execRoot 且 locator 是 git spec(`review` / `skills/review`)非磁盘目录,取 dirname
+    // 会得伪 skillDir 污染 PATH/runtime fingerprint → 与 baseline 一样返回 null。本地文件-skill 取 .md 所在目录。
     if (!artifact.locator || artifact.source === 'git')
         return null;
     return dirname(artifact.locator);

package/dist/eval-core/task-planner.js

@@ -62,7 +62,8 @@ export function buildTasksFromArtifacts(samples, artifacts) {
                 assertions: sample.assertions || null,
                 dimensions: sample.dimensions || null,
                 artifactContent: artifact.content,
-                cwd: artifact.cwd || artifact.skillRoot || sample.cwd || null,
+                // 用户显式 cwd > execRoot(隔离副本,dir-skill 执行根) > skillRoot(真源,兜底) > sample.cwd
+                cwd: artifact.cwd || artifact.execRoot || artifact.skillRoot || sample.cwd || null,
                 _sample: sample,
             });
         }

package/dist/eval-workflows/evaluation-preparation.js

@@ -10,7 +10,9 @@ export async function prepareEvaluationRun({ samplesPath, skillDir, variantSpecs
     // 结构化传入 {expr, cwd}(与 variantSpecs 顺序一一对应),cwd 不再编码进 expr 字符串。
     // resolveArtifacts 只保留 strictBaseline 默认(baseline → []);per-variant 隔离声明走
     // spec.allowedSkills,在下面按 spec 身份绑定。
-    const variantInputs = variantSpecs.map((spec) => ({ expr: spec.expr, cwd: spec.cwd }));
+    const variantInputs = variantSpecs.map((spec) => spec.git
+        ? { git: spec.git, cwd: spec.cwd, name: spec.name }
+        : { expr: spec.expr, cwd: spec.cwd });
     const resolvedArtifacts = resolveArtifacts(resolve(skillDir), variantInputs, { strictBaseline });
     // experimentRole / allowedSkills 按 spec 身份绑定。variantSpecs 与 resolvedArtifacts 顺序
     // 一一对应(resolveArtifacts 每个 input 产出一个 artifact),按 index 绑定,并把 spec.name

package/dist/inputs/content-hash.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 给定相对源根的路径分段(空数组 = 源根本身),判断是否进可分发树。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;
+/**
+ * cpSync 的 filter,口径与 hashArtifactSource 的 walk 完全一致(「分发出去的 == 算进 hash 的」):
+ * 源根永远拷;软链跳过(避免软链目标改了却不触发 drift、回避软链环);其余按 isDistributablePath
+ * 逐段判定。install 分发(copyArtifactToTarget)与 eval 隔离副本物化(materializeIsolatedCopy)
+ * 共用此一处 —— copy / hash / 副本三者绝不发散。
+ */
+export declare function distributableCopyFilter(sourceRoot: string): (src: string) => boolean;
+/**
+ * artifact 内容 hash —— drift baseline 与 evidence 绑定的依据。
+ *   - 文件-skill:单个 .md 的字节;
+ *   - 目录-skill:覆盖**整棵可分发目录树**(SKILL.md + references/ 等资产,但排除 .omk / .git /
+ *     evolve 等评测迭代产物),按相对路径排序后把每个文件的`路径 + 字节长度 + 内容`喂进同一个
+ *     sha256 —— 改任意资产都会令 hash 变化、drift 不漏;只补样本则 hash 不动。
+ * 用 createHash 直接喂 Buffer(字节级,二进制资产也稳;分隔符是运行时字节,源码里不引入任何不可见字符)。
+ * 读时(list / drift 检查 / eval 报告)用同一函数重算比对。
+ */
+/** sha256 前 12 位的字节摘要 —— 单文件 / 单 blob 内容指纹的共用底座(整树哈、git 单文件哈都走它)。 */
+export declare function hashBytes(buf: Buffer): string;
+export declare function hashArtifactSource(source: string, isDirectorySkill: boolean): string;

package/dist/inputs/content-hash.js

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, lstatSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+/**
+ * artifact「可分发树」与内容指纹 —— inputs 层的纯内容哈希工具。install(受管记录)与 eval
+ * (report 的 artifactHashes)共用同一处,保证「同一个 skill,装出来与测出来的指纹落在同一空间」,
+ * 是证据随 artifact 走(evidence.contentHash === record.contentHash)的承重基础。
+ *
+ * 放在 inputs 层而非 managed:这两个函数语义上属内容哈希、无 managed 专属依赖;skill-loader、
+ * source-resolver、managed/store 都在它之上消费,inputs 是更低层,不成环。
+ */
+/**
+ * 不进 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;
+}
+/**
+ * cpSync 的 filter,口径与 hashArtifactSource 的 walk 完全一致(「分发出去的 == 算进 hash 的」):
+ * 源根永远拷;软链跳过(避免软链目标改了却不触发 drift、回避软链环);其余按 isDistributablePath
+ * 逐段判定。install 分发(copyArtifactToTarget)与 eval 隔离副本物化(materializeIsolatedCopy)
+ * 共用此一处 —— copy / hash / 副本三者绝不发散。
+ */
+export function distributableCopyFilter(sourceRoot) {
+    return (src) => {
+        const rel = relative(sourceRoot, src);
+        if (rel === '')
+            return true;
+        if (lstatSync(src).isSymbolicLink())
+            return false;
+        return isDistributablePath(rel.split(sep));
+    };
+}
+/**
+ * artifact 内容 hash —— drift baseline 与 evidence 绑定的依据。
+ *   - 文件-skill:单个 .md 的字节;
+ *   - 目录-skill:覆盖**整棵可分发目录树**(SKILL.md + references/ 等资产,但排除 .omk / .git /
+ *     evolve 等评测迭代产物),按相对路径排序后把每个文件的`路径 + 字节长度 + 内容`喂进同一个
+ *     sha256 —— 改任意资产都会令 hash 变化、drift 不漏;只补样本则 hash 不动。
+ * 用 createHash 直接喂 Buffer(字节级,二进制资产也稳;分隔符是运行时字节,源码里不引入任何不可见字符)。
+ * 读时(list / drift 检查 / eval 报告)用同一函数重算比对。
+ */
+/** sha256 前 12 位的字节摘要 —— 单文件 / 单 blob 内容指纹的共用底座(整树哈、git 单文件哈都走它)。 */
+export function hashBytes(buf) {
+    return createHash('sha256').update(buf).digest('hex').slice(0, 12);
+}
+export function hashArtifactSource(source, isDirectorySkill) {
+    if (!isDirectorySkill) {
+        return hashBytes(readFileSync(source));
+    }
+    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);
+}

package/dist/inputs/eval-config.js

@@ -23,13 +23,19 @@ export function loadEvalConfig(configPath) {
  * so the downstream variant resolver can treat CLI and config uniformly.
  */
 export function configVariantsToSpecs(variants) {
-    return variants.map((v) => ({
-        name: v.name,
-        role: v.role,
-        expr: v.artifact, // 纯 artifact 身份;cwd 结构化携带,不再编码进 expr
-        ...(v.cwd !== undefined && { cwd: v.cwd }),
-        ...(v.allowedSkills !== undefined && { allowedSkills: v.allowedSkills }),
-    }));
+    return variants.map((v) => {
+        // 远端 git:expr 落规范身份串 `git+<url>@<ref>:<spec>`(仅供 variantIdentity 去重、绝不 re-split),
+        // 真正解析走结构化 spec.git;本地 artifact 直接用其字符串身份。
+        const expr = v.git ? `git+${v.git.url}@${v.git.ref ?? 'HEAD'}:${v.git.spec}` : v.artifact;
+        return {
+            name: v.name,
+            role: v.role,
+            expr,
+            ...(v.git !== undefined && { git: v.git }),
+            ...(v.cwd !== undefined && { cwd: v.cwd }),
+            ...(v.allowedSkills !== undefined && { allowedSkills: v.allowedSkills }),
+        };
+    });
 }
 function validateEvalConfig(parsed, configPath) {
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
@@ -56,8 +62,31 @@ function validateEvalConfig(parsed, configPath) {
         if (typeof v.role !== 'string' || !VALID_ROLES.includes(v.role)) {
             throw new Error(`${configPath}: variants[${i}].role must be 'control' or 'treatment' (got: ${JSON.stringify(v.role)})`);
         }
-        if (typeof v.artifact !== 'string' || !v.artifact) {
-            throw new Error(`${configPath}: variants[${i}].artifact is required and must be a string`);
+        // artifact(本地字符串身份)与 git(远端结构化)二选一、不可兼有。
+        const hasArtifact = v.artifact !== undefined;
+        const hasGit = v.git !== undefined;
+        if (hasArtifact === hasGit) {
+            throw new Error(`${configPath}: variants[${i}] must have exactly one of 'artifact' or 'git'`);
+        }
+        if (hasArtifact && (typeof v.artifact !== 'string' || !v.artifact)) {
+            throw new Error(`${configPath}: variants[${i}].artifact must be a non-empty string`);
+        }
+        let git;
+        if (hasGit) {
+            if (typeof v.git !== 'object' || v.git === null || Array.isArray(v.git)) {
+                throw new Error(`${configPath}: variants[${i}].git must be an object { url, ref?, spec }`);
+            }
+            const g = v.git;
+            if (typeof g.url !== 'string' || !g.url) {
+                throw new Error(`${configPath}: variants[${i}].git.url is required and must be a string`);
+            }
+            if (typeof g.spec !== 'string' || !g.spec) {
+                throw new Error(`${configPath}: variants[${i}].git.spec is required and must be a string (in-repo skill path)`);
+            }
+            if (g.ref !== undefined && (typeof g.ref !== 'string' || !g.ref)) {
+                throw new Error(`${configPath}: variants[${i}].git.ref must be a non-empty string when present`);
+            }
+            git = { url: g.url, spec: g.spec, ...(g.ref !== undefined && { ref: g.ref }) };
         }
         if (v.cwd !== undefined && typeof v.cwd !== 'string') {
             throw new Error(`${configPath}: variants[${i}].cwd must be a string`);
@@ -88,7 +117,8 @@ function validateEvalConfig(parsed, configPath) {
         variants.push({
             name: v.name,
             role: v.role,
-            artifact: v.artifact,
+            ...(hasArtifact && { artifact: v.artifact }),
+            ...(git !== undefined && { git }),
             cwd: v.cwd,
             ...(allowedSkills !== undefined && { allowedSkills }),
         });
@@ -245,7 +275,10 @@ function resolveConfigPaths(config, configDir) {
         goldDir: config.goldDir ? resolveRel(config.goldDir) : undefined,
         variants: config.variants.map((v) => ({
             ...v,
-            artifact: isNonPathExpr(v.artifact) ? v.artifact : (looksLikePath(v.artifact) ? resolveRel(v.artifact) : v.artifact),
+            // git 变体无 artifact(git.url 是 URL、git.spec 是仓库相对路径,都不按本地路径解析,原样经 ...v 携带)。
+            ...(v.artifact !== undefined && {
+                artifact: isNonPathExpr(v.artifact) ? v.artifact : (looksLikePath(v.artifact) ? resolveRel(v.artifact) : v.artifact),
+            }),
             cwd: v.cwd ? resolveRel(v.cwd) : undefined,
         })),
     };

package/dist/inputs/materialize-copy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 内容寻址隔离副本 —— eval 把任意源(本地目录-skill / 本地单文件-skill / 本地 git ref / 远端 git)
+ * 在测量前落地成的那一份。executor 的 cwd 锚到 copyRoot,被测 agent 在隔离副本里跑、不碰用户真实
+ * 目录,references/ 资产成为真实运行时输入。路径按 contentHash 命名 → 同内容同路径 → task.cwd
+ * 稳定 → cache key / runtime fingerprint 稳定。
+ */
+export interface IsolatedCopy {
+    /** 副本根:目录-skill 为目录 `<treesDir>/<hash>`、单文件-skill 为 `<treesDir>/<hash>/<name>.md`。 */
+    copyRoot: string;
+    /** = hashArtifactSource(copyRoot, isDirectorySkill);与 install 受管记录的 contentHash 同空间。 */
+    contentHash: string;
+    isDirectorySkill: boolean;
+}
+/** 隔离副本根目录(与 managed / isolated-cwd / reports 同 home-dir 模式)。
+ *  `OMK_TREES_DIR` 可重定位(测试隔离 / 用户迁移)。 */
+export declare function treesDir(): string;
+/**
+ * 内容寻址副本的 LRU 回收:`<treesDir>/<hash>` 数超过上限时,按 mtime 从旧到新淘汰,直到回到上限内。
+ * **绝不删**被活进程占用的副本(`.locks/<hash>.<pid>` 且 pid 在世)—— 这才是「正在跑的 eval 的 cwd 不被删」
+ * 的真实保证(不靠 mtime 当 liveness)。grace 窗口是第二道兜底。软上限:被占用/grace 内的大批新副本会暂时
+ * 超限,待其释放/老化后回收。`.tmp-` 暂存与 `.locks` 不计、不删。
+ * materializeIsolatedCopy 命中走 utimes 触碰(LRU touch)+ 落锁;未命中落盘后落锁并调本函数;也可独立调用。
+ */
+export declare function pruneTreesDir(opts?: {
+    maxEntries?: number;
+    graceMs?: number;
+}): void;
+/**
+ * 把一棵已在盘的本地源树(目录或单 .md)落地成内容寻址隔离副本。
+ *   - 先从**源**算整树 / 单文件指纹(`hashArtifactSource` 与副本同 filter → 同 hash),不必先 copy
+ *   - `<treesDir>/<hash>` 已存在 → 内容寻址命中,直接复用、**零 copy**(同 hash 内容必然相同)
+ *   - 未命中 → 物化到同卷临时目录 `<treesDir>/.tmp-xxx`(目录-skill 用 install 同一 distributable
+ *     filter;单文件-skill copyFile 到 `<tmp>/<name>.md`,使 `<hash>` 恒为目录、消歧),再原子
+ *     `rename` 到 `<hash>`;rename 撞 EEXIST/ENOTEMPTY(并发已落同 hash)即删临时复用。
+ * 物化只发生一次/variant(resolveArtifacts 解析期),不随 sample 数放大。
+ */
+export declare function materializeIsolatedCopy(localRoot: string, isDirectorySkill: boolean, name: string): IsolatedCopy;

package/dist/inputs/materialize-copy.js

@@ -0,0 +1,193 @@
+import { mkdtempSync, mkdirSync, cpSync, copyFileSync, existsSync, renameSync, rmSync, readdirSync, statSync, utimesSync, writeFileSync, unlinkSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+import { hashArtifactSource, distributableCopyFilter } from './content-hash.js';
+/** 隔离副本根目录(与 managed / isolated-cwd / reports 同 home-dir 模式)。
+ *  `OMK_TREES_DIR` 可重定位(测试隔离 / 用户迁移)。 */
+export function treesDir() {
+    return process.env.OMK_TREES_DIR || join(homedir(), '.oh-my-knowledge', 'trees');
+}
+/** 内容寻址副本默认上限(distinct 内容版本数);超出按 LRU(mtime)淘汰。
+ *  `OMK_TREES_MAX_ENTRIES` 调整:0 / 负数 = 不限。 */
+const DEFAULT_TREES_MAX_ENTRIES = 200;
+/** 淘汰宽限:mtime 在此窗口内的副本不动。这是**第二道**保护(覆盖物化→落锁那几毫秒的窗口);
+ *  真正挡住「删掉正在跑的 eval 的 cwd」靠下面的 pid 占用锁,不靠「没有 eval 跑这么久」的假设。 */
+const TREES_GRACE_MS = 60 * 60 * 1000;
+function treesCap() {
+    const raw = process.env.OMK_TREES_MAX_ENTRIES;
+    if (raw == null || raw === '')
+        return DEFAULT_TREES_MAX_ENTRIES;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return DEFAULT_TREES_MAX_ENTRIES;
+    if (n <= 0)
+        return Infinity;
+    return Math.floor(n);
+}
+/** 占用锁目录:`<treesDir>/.locks/<hash>.<pid>`。dotfile → 不计入 cap、不被当副本删。 */
+function locksDir() {
+    return join(treesDir(), '.locks');
+}
+function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0); // 信号 0:只探活、不真发信号
+        return true;
+    }
+    catch (err) {
+        // EPERM = 进程存在但无权限(仍算活);ESRCH = 不存在
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * 标记本进程正在用某内容寻址副本作 executor cwd —— 落一个 `<treesDir>/.locks/<hash>.<pid>` 占用锁。
+ * pruneTreesDir 见到**活 pid** 的锁就绝不删对应副本(真实跨进程 liveness,不靠 mtime 猜)。进程崩溃也安全:
+ * 锁不显式回收,prune 惰性按 pid 探活清理死锁。同 hash 同 pid 幂等(覆盖写)。
+ */
+function markCopyInUse(contentHash) {
+    try {
+        const dir = locksDir();
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, `${contentHash}.${process.pid}`), '');
+    }
+    catch {
+        // 落锁失败不致命:还有 grace 窗口兜底
+    }
+    reapDeadLocks(); // 每次落锁顺带清死 pid 的锁 —— 不依赖 prune(prune 仅 cache-miss + 超上限才跑,
+    //                  under-cap 的常见情形下永不触发,死锁会无界堆积)。readdir 小目录,开销可忽略。
+}
+/** 扫 `.locks/`:删掉死 pid 的锁、返回被**活进程**占用的 hash 集合。每次物化(markCopyInUse)无条件调用,
+ *  保证死锁惰性回收的路径始终可达;pruneTreesDir 也用其返回的 live 集合保护 active cwd。 */
+function reapDeadLocks() {
+    const dir = locksDir();
+    const live = new Set();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return live; // 无锁目录
+    }
+    for (const name of names) {
+        const dot = name.lastIndexOf('.');
+        if (dot <= 0)
+            continue;
+        const hash = name.slice(0, dot);
+        const pid = Number(name.slice(dot + 1));
+        if (isPidAlive(pid)) {
+            live.add(hash);
+        }
+        else {
+            try {
+                unlinkSync(join(dir, name)); // 死 pid 的锁惰性回收
+            }
+            catch {
+                // 清理失败不致命
+            }
+        }
+    }
+    return live;
+}
+/**
+ * 内容寻址副本的 LRU 回收:`<treesDir>/<hash>` 数超过上限时,按 mtime 从旧到新淘汰,直到回到上限内。
+ * **绝不删**被活进程占用的副本(`.locks/<hash>.<pid>` 且 pid 在世)—— 这才是「正在跑的 eval 的 cwd 不被删」
+ * 的真实保证(不靠 mtime 当 liveness)。grace 窗口是第二道兜底。软上限:被占用/grace 内的大批新副本会暂时
+ * 超限,待其释放/老化后回收。`.tmp-` 暂存与 `.locks` 不计、不删。
+ * materializeIsolatedCopy 命中走 utimes 触碰(LRU touch)+ 落锁;未命中落盘后落锁并调本函数;也可独立调用。
+ */
+export function pruneTreesDir(opts = {}) {
+    const cap = opts.maxEntries ?? treesCap();
+    if (!Number.isFinite(cap))
+        return;
+    const graceMs = opts.graceMs ?? TREES_GRACE_MS;
+    const root = treesDir();
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return; // 目录不存在 = 无可回收
+    }
+    const dirs = names
+        .filter((n) => !n.startsWith('.')) // 排除 .tmp- 暂存与 .locks
+        .map((n) => {
+        try {
+            return { path: join(root, n), mtimeMs: statSync(join(root, n)).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => x !== null);
+    if (dirs.length <= cap)
+        return;
+    const locked = reapDeadLocks();
+    dirs.sort((a, b) => a.mtimeMs - b.mtimeMs); // 最旧在前
+    const cutoff = Date.now() - graceMs;
+    let removable = dirs.length - cap;
+    for (const d of dirs) {
+        if (removable <= 0)
+            break;
+        if (locked.has(basename(d.path)))
+            continue; // 活进程占用(可能是 active cwd),绝不删
+        if (d.mtimeMs > cutoff)
+            continue; // grace 内:第二道兜底
+        try {
+            rmSync(d.path, { recursive: true, force: true });
+            removable--;
+        }
+        catch {
+            // 删除失败(权限 / 并发)不致命,跳过
+        }
+    }
+}
+/**
+ * 把一棵已在盘的本地源树(目录或单 .md)落地成内容寻址隔离副本。
+ *   - 先从**源**算整树 / 单文件指纹(`hashArtifactSource` 与副本同 filter → 同 hash),不必先 copy
+ *   - `<treesDir>/<hash>` 已存在 → 内容寻址命中,直接复用、**零 copy**(同 hash 内容必然相同)
+ *   - 未命中 → 物化到同卷临时目录 `<treesDir>/.tmp-xxx`(目录-skill 用 install 同一 distributable
+ *     filter;单文件-skill copyFile 到 `<tmp>/<name>.md`,使 `<hash>` 恒为目录、消歧),再原子
+ *     `rename` 到 `<hash>`;rename 撞 EEXIST/ENOTEMPTY(并发已落同 hash)即删临时复用。
+ * 物化只发生一次/variant(resolveArtifacts 解析期),不随 sample 数放大。
+ */
+export function materializeIsolatedCopy(localRoot, isDirectorySkill, name) {
+    const root = treesDir();
+    const contentHash = hashArtifactSource(localRoot, isDirectorySkill);
+    const target = join(root, contentHash);
+    const copyRoot = isDirectorySkill ? target : join(target, `${name}.md`);
+    if (existsSync(target)) {
+        // 命中:零 copy。utimes 触碰 mtime 作 LRU 标记 + 落 pid 占用锁(本进程将拿它当 cwd,prune 不许删)。
+        try {
+            const now = new Date();
+            utimesSync(target, now, now);
+        }
+        catch {
+            // 触碰失败不致命
+        }
+        markCopyInUse(contentHash);
+        return { copyRoot, contentHash, isDirectorySkill };
+    }
+    mkdirSync(root, { recursive: true });
+    const tmp = mkdtempSync(join(root, '.tmp-'));
+    try {
+        if (isDirectorySkill) {
+            cpSync(localRoot, tmp, { recursive: true, filter: distributableCopyFilter(localRoot) });
+        }
+        else {
+            copyFileSync(localRoot, join(tmp, `${name}.md`));
+        }
+        renameSync(tmp, target);
+        markCopyInUse(contentHash); // 先落占用锁,再 prune —— 保证本进程刚落的副本绝不被自己的 prune 删
+        pruneTreesDir(); // 回收超限的旧副本(跳过活进程占用 + grace)
+        return { copyRoot, contentHash, isDirectorySkill };
+    }
+    catch (err) {
+        rmSync(tmp, { recursive: true, force: true });
+        // 并发竞态:另一进程已先 rename 到 target(非空)→ EEXIST/ENOTEMPTY;内容相同,复用。
+        const code = err.code;
+        if (code === 'EEXIST' || code === 'ENOTEMPTY')
+            return { copyRoot, contentHash, isDirectorySkill };
+        throw err;
+    }
+}