oh-my-knowledge 0.33.0 → 0.35.0

package/dist/inputs/skill-loader.js

@@ -1,7 +1,10 @@
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, relative, dirname, basename } from 'node:path';
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { resolve, join, relative, dirname, basename, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { extractSkillHardRules, extractSkillWorkflows } from '../shared/hard-rules.js';
+import { hashArtifactSource, hashBytes, isDistributablePath } from './content-hash.js';
+import { materializeIsolatedCopy } from './materialize-copy.js';
 function parseFrontmatterPreflight(content) {
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
@@ -37,17 +40,299 @@ function buildMetadata(content) {
         metadata.workflows = workflows;
     return Object.keys(metadata).length > 0 ? metadata : undefined;
 }
-function gitShowFile(ref, filePath) {
+// 这些是**探测**(尝试某路径是否存在),miss 是正常流程,不是错误 → 吞掉 git 的 `fatal:` stderr,
+// 否则一次成功的 install/eval 也会在用户终端打印吓人的 `fatal: path ... does not exist`。
+const GIT_PROBE_STDIO = ['ignore', 'pipe', 'ignore'];
+// 用 `cat-file blob` 而非 `git show`:`git show <ref>:<目录>` 对**目录**会退出码 0 并打印树清单
+// (`tree <ref>:path\n\nSKILL.md`),被这里当成"文件存在 + 内容"误收 —— 名字以 .md 结尾的目录会被
+// classify 误判为 file-skill、物化出树清单当 skill 正文,也会让 eval 把清单文本量成 skill 内容。
+// `cat-file blob` 对非 blob(tree/submodule)直接非零退出,从根上只认 blob。对真 blob 字节与 show 一致。
+// 所有 git helper 收 `cwd`(默认进程 cwd):git 解析必须在**目标仓库**里跑,否则 eval 从别处调用、
+// skillDir 指向另一个 repo 时,会拿进程 cwd 的 repo 与 HEAD 去解析,轻则 not_found、重则评测错内容。
+// 由 resolveGitRepoContext 解出 repoRoot 后逐处显式传入。
+export function gitShowFile(ref, filePath, cwd = process.cwd()) {
     try {
-        return execFileSync('git', ['show', `${ref}:${filePath}`], { encoding: 'utf-8' }).trim();
+        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
     }
     catch {
         return null;
     }
 }
-function getGitRelativePath(absolutePath) {
-    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' }).trim();
-    return relative(gitRoot, absolutePath);
+/**
+ * 取 `<ref>:<filePath>` 的原始字节(二进制资产用,不做 utf-8 解码);不存在/非 blob/出错返回 null。
+ * 同 gitShowFile 用 `cat-file blob`:对目录会非零退出,不会把树清单字节当文件内容物化。
+ */
+export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
+    try {
+        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, stdio: GIT_PROBE_STDIO }); // 无 encoding → Buffer
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 递归列出 `<ref>:<treePath>` 子树下的叶子条目(blob / 软链 / submodule)。tree 不存在返回 []。
+ * 用 `-z`(NUL 分隔):git 不会对含换行 / 非 ASCII 的路径做 C-quote,路径原样可回喂 git show。
+ * 用 `--full-tree`:treePath 是仓库根相对路径,不受当前 cwd 前缀限制 —— 否则在仓库子目录执行时
+ * `ls-tree HEAD:skills/review` 会返回空(而 gitShowFile 探测不受限,导致"探测命中→物化为空"的发散)。
+ * `treePath` 为空时列整棵根 tree(`<ref>:`)。
+ */
+export function gitLsTreeBlobs(ref, treePath, cwd = process.cwd()) {
+    let out;
+    try {
+        out = execFileSync('git', ['ls-tree', '-r', '-z', '--full-tree', `${ref}:${treePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO });
+    }
+    catch {
+        return [];
+    }
+    const NUL = String.fromCharCode(0);
+    const entries = [];
+    for (const rec of out.split(NUL)) {
+        // 记录格式:`<mode> <type> <object>\t<path>`(path 可含换行,故用 [\s\S])。
+        const m = rec.match(/^(\d+) \S+ \S+\t([\s\S]*)$/);
+        if (m)
+            entries.push({ mode: m[1], path: m[2] });
+    }
+    return entries;
+}
+/** 从 p 起向上找最近的存在目录(skillDir 可能尚不在磁盘,但仍要定位它所属的 repo)。 */
+function nearestExistingDir(p) {
+    let cur = resolve(p);
+    while (!existsSync(cur)) {
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return cur;
+}
+/**
+ * 解出 `fromPath` 所属 git 仓库的上下文。**关键**:`git rev-parse` 在 `fromPath` 处执行(-C),
+ * 而非进程 cwd —— 否则 eval 从别处调用、skillDir 指向另一个 repo 时,会拿进程 cwd 的 repo root 和
+ * HEAD 去解析,轻则 not_found、重则评测错 repo 的同名内容。repoRoot / relDir 都 realpath 归一,
+ * 消除 /var ↔ /private/var 这类等价路径导致 relative 算错。不在 git 仓库时 rev-parse 抛错,由上层转
+ * not_a_git_repo。stderr 吞掉,不双重打印 `fatal:`。
+ */
+export function resolveGitRepoContext(fromPath) {
+    const absInput = resolve(fromPath);
+    const existing = nearestExistingDir(absInput);
+    const anchor = realpathSync(existing);
+    const repoRoot = realpathSync(execFileSync('git', ['-C', anchor, 'rev-parse', '--show-toplevel'], { encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim());
+    // 对称归一:repoRoot 经 realpath,fromPath 也必须经同源 realpath,否则 fromPath 尚不在磁盘时
+    // (纯 git eval:skill 只在 HEAD、工作树已删)absFrom 保留未归一字面,在 macOS /var ↔ /private/var
+    // 这类等价路径上 relative 会算出越界的 `../../..` relDir → classify 探到仓库外 → 误报 not_found。
+    // 做法:realpath 最近存在祖先,再拼回尚不存在的尾段(尾段为空即 fromPath 本身存在)。
+    const tail = relative(existing, absInput);
+    const absFrom = tail ? join(anchor, tail) : anchor;
+    return { repoRoot, relDir: relative(repoRoot, absFrom) };
+}
+/** 拼 git 仓库相对路径:始终用 `/`,空 base 直接返回 b(避免 join 产生 `.` 这类退化 tree-ish)。 */
+export function gitJoin(base, sub) {
+    return base ? `${base}/${sub}` : sub;
+}
+/**
+ * 解析 `git:<ref>:<spec>` —— **install 与 eval 共用此一处**,保证两侧对 ref/spec 的切分与合法性
+ * 判定一致。`git:<spec>` 缺省 ref=HEAD;spec 可含 `/`(如 skills/review)。空 ref / 空 spec 都非法
+ * 并返回 null:空 ref(`git::x`)会被 git 当 index/stage-0 解析,量到不可复取、依赖本地暂存区的内容,
+ * 破坏 git variant 的可复现语义;空 spec(`git:HEAD:`)会退化去探 `.md`/`SKILL.md` 误命中。
+ */
+export function parseGitInput(input) {
+    const parts = input.slice('git:'.length).split(':');
+    const { ref, spec } = parts.length === 1
+        ? { ref: 'HEAD', spec: parts[0] }
+        : { ref: parts[0], spec: parts.slice(1).join(':') };
+    if (!ref || !spec)
+        return null;
+    return { ref, spec };
+}
+/**
+ * 把 git spec 解析成 dir / file skill —— **install 与 eval 共用此一处**,保证两条路径对同一
+ * `git:<ref>:<spec>` 的 file-vs-dir 归类绝不发散(发散会让 eval 量文件、install 注册目录,
+ * 两边对不上)。接受三种写法,与本地路径安装对称:
+ *   - 显式 SKILL.md:`skills/dir/SKILL.md` → 目录-skill,name 取父目录名;
+ *   - 显式 .md:`skills/foo.md` → 文件-skill;
+ *   - 裸 spec:`skills/review` → **文件优先**(先试 `<spec>.md`,再试 `<spec>/SKILL.md`)。
+ * 裸 spec 的文件优先必须与 eval 历史顺序一致 —— 否则同名同时存在 .md 与 dir/SKILL.md 时,
+ * eval 量文件、install 注册目录,evidence 读时按 hash 门控被静默剥离、记录永久 stale。
+ * `gitRelDir` 是各调用方的解析基准(install=cwd 相对仓库根、eval=skillDir 相对仓库根),作为显式
+ * 参数传入,基准差异留给调用方、归类逻辑单一来源。任一探测命中即返回;都不中返回 null。
+ */
+export function classifyGitSkillRef(ref, gitRelDir, spec, cwd = process.cwd()) {
+    if (basename(spec) === 'SKILL.md') {
+        if (gitShowFile(ref, gitJoin(gitRelDir, spec), cwd) === null)
+            return null;
+        const dirSpec = dirname(spec);
+        const treePath = dirSpec === '.' ? gitRelDir : gitJoin(gitRelDir, dirSpec);
+        let name = basename(dirSpec);
+        if (name === '.' || name === '')
+            name = basename(treePath) || basename(gitRelDir) || 'skill';
+        return { isDir: true, treePath, fileSkillPath: '', name };
+    }
+    if (/\.md$/i.test(spec)) {
+        const fileSkillPath = gitJoin(gitRelDir, spec);
+        if (gitShowFile(ref, fileSkillPath, cwd) === null)
+            return null;
+        return { isDir: false, treePath: '', fileSkillPath, name: basename(spec).replace(/\.md$/i, '') };
+    }
+    if (gitShowFile(ref, gitJoin(gitRelDir, `${spec}.md`), cwd) !== null) {
+        return { isDir: false, treePath: '', fileSkillPath: gitJoin(gitRelDir, `${spec}.md`), name: basename(spec) };
+    }
+    if (gitShowFile(ref, gitJoin(gitJoin(gitRelDir, spec), 'SKILL.md'), cwd) !== null) {
+        return { isDir: true, treePath: gitJoin(gitRelDir, spec), fileSkillPath: '', name: basename(spec) };
+    }
+    return null;
+}
+/**
+ * 源解析的结构化错误 —— 不依赖 CLI:以 `messageKey` 抛出,由调用方(install 走 tCli、eval 走自身
+ * 中文错误)映射成本地化文案。住在 skill-loader(而非 source-resolver)是为了让共享的
+ * `materializeGitSkillTree` 能抛它而不致 skill-loader → source-resolver 反向成环;source-resolver
+ * re-export 以保持 install 既有 import 不破。
+ */
+export class SourceResolveError extends Error {
+    messageKey;
+    params;
+    constructor(messageKey, params = {}) {
+        super(messageKey);
+        this.name = 'SourceResolveError';
+        this.messageKey = messageKey;
+        this.params = params;
+    }
+}
+/**
+ * 校验 git tree 条目路径在物化目标内,越界即 fail closed(抛 SourceResolveError)。
+ * 双保险:既显式拒 `..` / 空段(git tree 可被手工构造出名为 `..` 的子树),也用 resolve 兜底
+ * 确认落点仍在 temp 之下(绝对路径 / 符号化逃逸)。绝不静默跳过——跳过会让物化树与真实树发散。
+ */
+export 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 });
+    }
+}
+/**
+ * 把 git 某个 ref 上的 skill(已由 `classifyGitSkillRef` 归类)逐文件物化到临时目录 ——
+ * **install 与 eval 共用此一处物化**,保证两侧拿到完全一致的本地树(此前 install/eval 各写一套
+ * git 解析正是四轮 bug 的根源,已靠共享 helper 收敛)。eval 仅为算整树指纹(hashArtifactSource)而
+ * 物化,算完即 cleanup;install 物化后分发并登记。失败(越界路径 / 空树 / 取不到 blob)抛
+ * SourceResolveError,绝不静默落空壳。
+ */
+export function materializeGitSkillTree(ref, resolved, repoRoot) {
+    const temp = mkdtempSync(join(tmpdir(), 'omk-git-skill-'));
+    const cleanup = () => {
+        try {
+            rmSync(temp, { recursive: true, force: true });
+        }
+        catch {
+            // 临时目录清理失败不致命
+        }
+    };
+    try {
+        if (resolved.isDir) {
+            for (const entry of gitLsTreeBlobs(ref, resolved.treePath, repoRoot)) {
+                // 安全边界 fail closed:git tree 可被 git mktree 手工构造出名为 `..` 的子树,`ls-tree -r` 会
+                // 吐 `../evil.txt`,`join(temp, ...)` 会逃出临时目录写盘、cleanup 也删不掉。任一越界路径直接抛错,
+                // 而非静默跳过——静默跳过会让物化树与真实 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), 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: resolved.name });
+            }
+            return { localRoot: temp, isDirectorySkill: true, name: resolved.name, cleanup };
+        }
+        const bytes = gitShowBytes(ref, resolved.fileSkillPath, repoRoot);
+        if (!bytes)
+            throw new SourceResolveError('cli.install.git_skill_not_found', { ref, name: resolved.name });
+        const dest = join(temp, `${resolved.name}.md`);
+        writeFileSync(dest, bytes);
+        return { localRoot: dest, isDirectorySkill: false, name: resolved.name, cleanup };
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
+}
+/**
+ * 远端 git URL 形态校验:接受 https(s):// / ssh:// / git:// / file:// 协议 URL、scp 形式
+ * `user@host:path`、绝对本地路径(file 远端 / 测试)。明显非法(空、相对裸串)拒。
+ */
+export function isPlausibleGitUrl(url) {
+    if (!url)
+        return false;
+    if (/^(https?|ssh|git|file):\/\//i.test(url))
+        return true;
+    if (/^[\w.-]+@[\w.-]+:/.test(url))
+        return true;
+    if (/^\//.test(url))
+        return true;
+    return false;
+}
+/**
+ * 远端 git:clone 某 ref 到临时 bare 仓库、pin 实际 SHA —— **install 与 eval 共用此一处**,远端只是
+ * 把下游 git helper(classifyGitSkillRef / materializeGitSkillTree)的 repoRoot 从「当前仓库」换成
+ * 「fetch 下来的临时 bare」,其余一字不改。`git init --bare` + `git fetch --depth 1`(省带宽,只取该
+ * ref 的 tip 树);ref 为 branch/tag/HEAD 通用,裸 SHA 取决于服务端是否允许 reachable-SHA fetch。
+ * 认证依赖本机 git 凭证(SSH agent / credential helper),omk 不自管 token。失败 fail-closed
+ * (SourceResolveError),由调用方本地化;eval 侧捕获后改抛中文 Error。
+ */
+export function fetchRemoteGitRef(url, ref) {
+    if (!isPlausibleGitUrl(url))
+        throw new SourceResolveError('cli.install.invalid_remote_url', { url });
+    const bare = mkdtempSync(join(tmpdir(), 'omk-git-remote-'));
+    const cleanup = () => {
+        try {
+            rmSync(bare, { recursive: true, force: true });
+        }
+        catch {
+            // 临时目录清理失败不致命
+        }
+    };
+    try {
+        execFileSync('git', ['init', '--bare', '--quiet', bare], { stdio: GIT_PROBE_STDIO });
+        try {
+            // `--` 隔断:git fetch 会扫描**全部** argv 找带短横的选项,不止第一个。少了 `--`,一个形如
+            // `--upload-pack=<cmd>` 的 ref 会被当成选项执行任意命令(RCE)。`--` 后一切按位置参数
+            // (repository + refspec)解析,恶意 ref 退化成非法 refspec、fail-closed。url 也一并护在 `--` 后。
+            execFileSync('git', ['--git-dir', bare, 'fetch', '--depth', '1', '--quiet', '--', url, `${ref}:refs/omk/fetched`], { stdio: GIT_PROBE_STDIO });
+        }
+        catch {
+            throw new SourceResolveError('cli.install.remote_fetch_failed', { url, ref });
+        }
+        let sha;
+        try {
+            sha = execFileSync('git', ['--git-dir', bare, 'rev-parse', 'refs/omk/fetched'], {
+                encoding: 'utf-8',
+                stdio: GIT_PROBE_STDIO,
+            }).trim();
+        }
+        catch {
+            throw new SourceResolveError('cli.install.remote_ref_not_found', { url, ref });
+        }
+        if (!sha)
+            throw new SourceResolveError('cli.install.remote_ref_not_found', { url, ref });
+        return { repoRoot: bare, ref: sha, cleanup };
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
 }
 export function discoverVariants(skillDir) {
     if (!existsSync(skillDir))
@@ -124,7 +409,8 @@ export function discoverBatchSkills(skillDir) {
     return skills;
 }
 export function loadSkills(skillDir, variants) {
-    return Object.fromEntries(resolveArtifacts(skillDir, variants).map((artifact) => [artifact.name, artifact.content]));
+    // 只取 content 映射,不执行 → 不落副本(materialize:false)。
+    return Object.fromEntries(resolveArtifacts(skillDir, variants, { materialize: false }).map((artifact) => [artifact.name, artifact.content]));
 }
 /**
  * Parse variant expression, extracting optional cwd suffix.
@@ -171,12 +457,15 @@ function pathPhysicalId(p) {
  *      `skillDir/name/SKILL.md`)取物理身份,这样裸名 `greeter` 与指向同一文件的 `./greeter.md`
  *      能判为重复;没传 skillDir(如纯单测)则退回字面名。
  *    - `git:` / `baseline`：本身就是稳定标识,原样返回。
- *  `@cwd` 也按物理身份纳入 key —— 同一份 skill 绑不同 cwd 是不同 runtime context,不算重复。
- *  不要用派生短名判重:`v1/greeter.md` 与 `v2/greeter.md` 短名都是 greeter 却是两个 variant。 */
-export function variantIdentity(expr, skillDir) {
-    const { name, cwd } = parseVariantCwd(expr);
+ *  结构化的 `cwd`(第三参数)按物理身份纳入 key —— 同一份 skill 绑不同 cwd 是不同 runtime
+ *  context,不算重复。不要用派生短名判重:`v1/greeter.md` 与 `v2/greeter.md` 短名都是 greeter
+ *  却是两个 variant。 */
+export function variantIdentity(expr, skillDir, cwd) {
+    // expr 已是纯 artifact 身份(@cwd 在 CLI/config 边界已剥离);cwd 结构化显式传入。
+    const name = expr;
     let id;
-    if (name.startsWith('git:')) {
+    if (name.startsWith('git:') || name.startsWith('git+')) {
+        // 本地 git:<ref>:<spec> 与远端 git+<url>@<sha>:<spec> 都是稳定身份串,原样作 key,绝不再 split。
         id = name;
     }
     else if (name === 'baseline') {
@@ -204,29 +493,115 @@ export function skillNameFromPath(filePath) {
     const base = basename(filePath);
     return base === 'SKILL.md' ? basename(dirname(filePath)) : base.replace(/\.md$/i, '');
 }
-/** Extract short skill name from a variant expression (which may be a path). */
+/** 从 variant 表达式(纯 artifact 身份,可能是路径)取短名。 */
 export function variantExprToSkillName(expr) {
-    const { name } = parseVariantCwd(expr);
-    if (name.startsWith('git:'))
-        return name;
-    if (!name.includes('/'))
-        return name || expr;
+    if (expr.startsWith('git:'))
+        return expr;
+    if (!expr.includes('/'))
+        return expr;
     // 先折叠 dir↔SKILL.md 再取短名,与 resolveArtifacts 的命名一致(否则 `weird.md/` 这类
     // 以 .md 结尾的目录,两处会派生出不同短名)。
-    return skillNameFromPath(canonicalSkillAnchor(resolve(name))) || name;
+    return skillNameFromPath(canonicalSkillAnchor(resolve(expr))) || expr;
+}
+/**
+ * 解析一个目录-skill 的整树指纹 + SKILL.md 正文;`materialize` 为真时另落地内容寻址隔离副本、返回执行根。
+ * 本地源 localDir 是真源目录;git 源 localDir 是 materializeGitSkillTree 物化出的临时目录。
+ * execRoot(副本)供 executor cwd / skillDir 锚定;skillRoot(真源)由各分支自行保留。
+ * 只有 eval 路径需要副本(执行隔离);doctor / loadSkills 只需指纹与正文,materialize=false 不落副本、
+ * 不写 `~/.oh-my-knowledge/trees`(避免纯读路径的副作用 I/O 与 trees 污染)。
+ */
+function isolateDirSkill(localDir, name, materialize) {
+    const content = readFileSync(join(localDir, 'SKILL.md'), 'utf-8').trim();
+    if (materialize) {
+        const copy = materializeIsolatedCopy(localDir, true, name);
+        return { execRoot: copy.copyRoot, contentHash: copy.contentHash, content };
+    }
+    return { contentHash: hashArtifactSource(localDir, true), content };
+}
+/**
+ * 远端 git variant:fetch 到临时 bare → classify → materialize 临时树 → 隔离副本(dir,materialize 时)
+ * 或单文件字节(file)。url/ref/spec 全程结构化,locator 落 `git+<url>@<sha>:<spec>` 身份串。
+ * SourceResolveError(install 口径的 messageKey)在此转成 eval 的中文 Error。临时树与 bare 用完即清。
+ */
+function resolveRemoteGitVariant(input, materialize, artifacts) {
+    const { url, spec } = input.git;
+    const ref = input.git.ref ?? 'HEAD';
+    let checkout;
+    try {
+        checkout = fetchRemoteGitRef(url, ref);
+    }
+    catch (err) {
+        if (err instanceof SourceResolveError) {
+            const zh = err.messageKey === 'cli.install.invalid_remote_url'
+                ? `不是合法的 git 远端 URL：${url}`
+                : `从远端 ${url} 拉取 ref ${ref} 失败，请检查 URL / ref 是否存在与本机 git 凭证。`;
+            throw new Error(zh);
+        }
+        throw err;
+    }
+    try {
+        const resolved = classifyGitSkillRef(checkout.ref, '', spec, checkout.repoRoot);
+        if (!resolved)
+            throw new Error(`在远端 ${url} 的 ref ${ref} 下找不到 skill ${spec}（既无 ${spec}/SKILL.md 也无 ${spec}.md）。`);
+        const mat = materializeGitSkillTree(checkout.ref, resolved, checkout.repoRoot);
+        try {
+            const locator = `git+${url}@${checkout.ref}:${spec}`;
+            if (resolved.isDir) {
+                const iso = isolateDirSkill(mat.localRoot, resolved.name, materialize);
+                artifacts.push({
+                    name: input.name,
+                    kind: 'skill',
+                    source: 'git',
+                    content: iso.content,
+                    contentHash: iso.contentHash,
+                    locator,
+                    ref: checkout.ref,
+                    cwd: input.cwd,
+                    ...(iso.execRoot ? { execRoot: iso.execRoot } : {}),
+                });
+            }
+            else {
+                const bytes = readFileSync(mat.localRoot);
+                artifacts.push({
+                    name: input.name,
+                    kind: 'skill',
+                    source: 'git',
+                    content: bytes.toString('utf-8').trim(),
+                    contentHash: hashArtifactSource(mat.localRoot, false),
+                    locator,
+                    ref: checkout.ref,
+                    cwd: input.cwd,
+                });
+            }
+        }
+        finally {
+            mat.cleanup();
+        }
+    }
+    finally {
+        checkout.cleanup();
+    }
 }
 export function resolveArtifacts(skillDir, variants, opts = {}) {
     const strictBaseline = opts.strictBaseline ?? true;
-    const variantAllowedSkills = opts.variantAllowedSkills ?? {};
+    const materialize = opts.materialize ?? true;
     const artifacts = [];
-    let gitRelDir = null;
+    let gitCtx = null;
     for (const rawVariant of variants) {
-        const { name: variantName, cwd: variantCwd } = parseVariantCwd(rawVariant);
+        // 远端 git 结构化输入:url/ref/spec 分字段,fetch 到临时 bare 后复用 classify/materialize/隔离副本,
+        // URL 全程不经任何字符串切分(避开 parseGitInput 的 `:` 与 parseVariantCwd 的 `@`)。
+        if (typeof rawVariant === 'object' && 'git' in rawVariant) {
+            resolveRemoteGitVariant(rawVariant, materialize, artifacts);
+            continue;
+        }
+        // 字符串即纯 expr(无 cwd);结构化对象直接取 expr/cwd。不再 split @cwd。
+        const variantName = typeof rawVariant === 'string' ? rawVariant : rawVariant.expr;
+        const variantCwd = typeof rawVariant === 'string' ? undefined : rawVariant.cwd;
         if (!variantName) {
-            throw new Error(`variant 名不能为空: "${rawVariant}"。如需绑定 runtime context,用 label@/path 形式声明。`);
+            throw new Error(`variant 名不能为空。如需绑定 runtime context,用 --control-cwd / --treatment-cwd 或 eval.yaml 的 variant.cwd。`);
         }
         if (variantName === 'baseline' && variantCwd) {
-            throw new Error('baseline cannot be bound to a cwd. To express a project-level runtime context, use a custom label such as project-env@/path/to/project');
+            throw new Error('baseline cannot be bound to a cwd. To express a project-level runtime context, use a custom label + cwd (e.g. --treatment project-env --treatment-cwd /path).');
         }
         if (variantName === 'baseline') {
             artifacts.push({
@@ -239,22 +614,51 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             continue;
         }
         if (variantName.startsWith('git:')) {
-            const parts = variantName.slice(4).split(':');
-            let ref;
-            let name;
-            if (parts.length === 1) {
-                ref = 'HEAD';
-                name = parts[0];
+            // 与 install 共用 parseGitInput:空 ref(`git::x`,会被 git 当 index 量本地暂存区、不可复取)/
+            // 空 spec(`git:HEAD:`)一律拒,守住 git variant 的可复现语义。
+            const parsed = parseGitInput(variantName);
+            if (!parsed) {
+                throw new Error(`无效的 git variant "${variantName}"：ref 与 skill 名都不能为空，应为 git:<ref>:<name>（如 git:HEAD:review）。`);
             }
-            else {
-                ref = parts[0];
-                name = parts.slice(1).join(':');
+            const { ref, spec: name } = parsed;
+            // git 上下文锚定 skillDir 所属仓库(不是进程 cwd):从别处调用、skillDir 在另一个 repo 时也对。
+            if (!gitCtx)
+                gitCtx = resolveGitRepoContext(skillDir);
+            // file-vs-dir 归类与 install 共用 classifyGitSkillRef(裸 spec 文件优先),两条路径绝不发散。
+            const resolved = classifyGitSkillRef(ref, gitCtx.relDir, name, gitCtx.repoRoot);
+            if (!resolved) {
+                throw new Error(`skill not found in git ${ref}: ${name}.md or ${name}/SKILL.md`);
+            }
+            if (resolved.isDir) {
+                // git 目录-skill 忠实执行:物化整树到临时目录 → 落地内容寻址隔离副本 → executor cwd 锚副本,
+                // agent 读得到 references/ 资产、资产成为真实运行时输入。整树指纹与 install 受管记录的
+                // contentHash 落同一空间 → evidence 可绑(见 docs/specs/evidence-gated-management.md §9)。
+                const mat = materializeGitSkillTree(ref, resolved, gitCtx.repoRoot);
+                let isolated;
+                try {
+                    isolated = isolateDirSkill(mat.localRoot, resolved.name, materialize);
+                }
+                finally {
+                    mat.cleanup(); // 临时物化树只为喂副本,落地完即删
+                }
+                artifacts.push({
+                    name: variantName,
+                    kind: 'skill',
+                    source: 'git',
+                    content: isolated.content,
+                    contentHash: isolated.contentHash,
+                    locator: name,
+                    ref,
+                    cwd: variantCwd,
+                    ...(isolated.execRoot ? { execRoot: isolated.execRoot } : {}),
+                });
+                continue;
             }
-            if (!gitRelDir)
-                gitRelDir = getGitRelativePath(skillDir);
-            const content = gitShowFile(ref, join(gitRelDir, `${name}.md`))
-                || gitShowFile(ref, join(gitRelDir, name, 'SKILL.md'));
-            if (!content) {
+            // git 文件-skill:单个 .md 字节(与 install 单文件分支「不 trim」一致),无资产、本就与本地 /
+            // file 源同空间可绑,不走副本。
+            const skillMdBytes = gitShowBytes(ref, resolved.fileSkillPath, gitCtx.repoRoot);
+            const content = skillMdBytes !== null ? skillMdBytes.toString('utf-8').trim() : null;
+            if (!skillMdBytes || !content) {
                 throw new Error(`skill not found in git ${ref}: ${name}.md or ${name}/SKILL.md`);
             }
             artifacts.push({
@@ -262,6 +666,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 kind: 'skill',
                 source: 'git',
                 content,
+                contentHash: hashBytes(skillMdBytes),
                 locator: name,
                 ref,
                 cwd: variantCwd,
@@ -283,14 +688,32 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             const content = readFileSync(filePath, 'utf-8').trim();
             const isSkillMd = basename(filePath) === 'SKILL.md';
             const name = skillNameFromPath(filePath);
+            if (isSkillMd) {
+                // dir-skill:落地隔离副本,执行根锚副本(agent 读 references)、整树指纹;skillRoot 仍记真源(doctor 等用)。
+                const isolated = isolateDirSkill(dirname(filePath), name, materialize);
+                artifacts.push({
+                    name,
+                    kind: 'skill',
+                    source: 'file-path',
+                    content: isolated.content,
+                    contentHash: isolated.contentHash,
+                    locator: filePath,
+                    cwd: variantCwd,
+                    skillRoot: dirname(filePath),
+                    ...(isolated.execRoot ? { execRoot: isolated.execRoot } : {}),
+                    metadata: buildMetadata(isolated.content),
+                });
+                continue;
+            }
+            // 裸 .md 文件-skill:单文件字节,无资产不 copy。
             artifacts.push({
                 name,
                 kind: 'skill',
                 source: 'file-path',
                 content,
+                contentHash: hashArtifactSource(filePath, false),
                 locator: filePath,
                 cwd: variantCwd,
-                ...(isSkillMd && { skillRoot: dirname(filePath) }),
                 metadata: buildMetadata(content),
             });
             continue;
@@ -305,23 +728,27 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 kind: 'skill',
                 source: 'variant-name',
                 content,
+                contentHash: hashArtifactSource(mdPath, false),
                 locator: mdPath,
                 cwd: variantCwd,
                 metadata: buildMetadata(content),
             });
         }
         else if (existsSync(dirSkillPath)) {
-            // directory-skill:SKILL.md 引相对路径 assets,cwd 默认锚到 skill 根目录
-            const content = readFileSync(dirSkillPath, 'utf-8').trim();
+            // directory-skill:SKILL.md 引相对路径 assets;落地隔离副本,executor cwd 锚副本读 references,
+            // skillRoot 仍记真源(doctor / dependency-checker 用)。
+            const isolated = isolateDirSkill(dirname(dirSkillPath), variantName, materialize);
             artifacts.push({
                 name: variantName,
                 kind: 'skill',
                 source: 'variant-name',
-                content,
+                content: isolated.content,
+                contentHash: isolated.contentHash,
                 locator: dirSkillPath,
                 cwd: variantCwd,
                 skillRoot: dirname(dirSkillPath),
-                metadata: buildMetadata(content),
+                ...(isolated.execRoot ? { execRoot: isolated.execRoot } : {}),
+                metadata: buildMetadata(isolated.content),
             });
         }
         else if (variantCwd) {
@@ -337,25 +764,15 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             throw new Error(`skill not found: ${mdPath} or ${dirSkillPath}`);
         }
     }
-    // Skill-isolation wiring（按 artifact 名查 variantAllowedSkills）。
-    //   Priority: variantAllowedSkills (explicit eval.yaml) > strictBaseline default > none。
-    //   strictBaseline=true 时,所有 kind:'baseline' artifact 默认 allowedSkills=[]。
-    //   显式 [] 也是合法(用户主动想"完全发现")的反义靠 strictBaseline=false 表达整批关闭。
-    //
-    //   职责边界:这条按名查的绑定服务 doctor / batch / loadSkills 等直接调 resolveArtifacts 的
-    //   调用方。eval 主路径(prepareEvaluationRun)已改为按 spec 身份绑定、不再传 variantAllowedSkills,
-    //   不走这里。两条路径暂并存。
-    //   TODO: 待 batch 也迁到 spec-based 绑定后,退役 opts.variantAllowedSkills,让隔离绑定收成一处。
+    // Skill-isolation:resolveArtifacts 只负责 strictBaseline 默认——strictBaseline=true 时
+    //   所有 kind:'baseline' artifact 默认 allowedSkills=[];否则保持 undefined → SDK 全量发现。
+    //   per-variant 显式隔离声明(eval.yaml variants[].allowedSkills)统一走 spec.allowedSkills,
+    //   由 prepareEvaluationRun 按 spec 身份绑定;batch 的 eval.yaml allowedSkills 也已在
+    //   buildBatchVariantSpecs 处挂到 spec 上。隔离绑定收成单一来源,这里不再按名查。
     for (const artifact of artifacts) {
-        const explicit = variantAllowedSkills[artifact.name];
-        if (explicit !== undefined) {
-            artifact.allowedSkills = explicit;
-            continue;
-        }
         if (strictBaseline && artifact.kind === 'baseline') {
             artifact.allowedSkills = [];
         }
-        // else leave undefined → SDK default (full discovery)
     }
     ensureUniqueVariantNames(artifacts);
     return artifacts;
@@ -417,4 +834,3 @@ export function ensureUniqueVariantNames(artifacts) {
         });
     }
 }
-//# sourceMappingURL=skill-loader.js.map