oh-my-knowledge 0.34.0 → 0.36.0

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

@@ -1,4 +1,4 @@
-import type { Artifact } from '../types/index.js';
+import type { Artifact, RemoteGitRef } from '../types/index.js';
 export declare function gitShowFile(ref: string, filePath: string, cwd?: string): string | null;
 /**
  * 取 `<ref>:<filePath>` 的原始字节(二进制资产用,不做 utf-8 解码);不存在/非 blob/出错返回 null。
@@ -66,6 +66,61 @@ export interface GitSkillRef {
  * 参数传入,基准差异留给调用方、归类逻辑单一来源。任一探测命中即返回;都不中返回 null。
  */
 export declare function classifyGitSkillRef(ref: string, gitRelDir: string, spec: string, cwd?: string): GitSkillRef | null;
+/**
+ * 源解析的结构化错误 —— 不依赖 CLI:以 `messageKey` 抛出,由调用方(install 走 tCli、eval 走自身
+ * 中文错误)映射成本地化文案。住在 skill-loader(而非 source-resolver)是为了让共享的
+ * `materializeGitSkillTree` 能抛它而不致 skill-loader → source-resolver 反向成环;source-resolver
+ * re-export 以保持 install 既有 import 不破。
+ */
+export declare class SourceResolveError extends Error {
+    readonly messageKey: string;
+    readonly params: Record<string, string | number>;
+    constructor(messageKey: string, params?: Record<string, string | number>);
+}
+/**
+ * 校验 git tree 条目路径在物化目标内,越界即 fail closed(抛 SourceResolveError)。
+ * 双保险:既显式拒 `..` / 空段(git tree 可被手工构造出名为 `..` 的子树),也用 resolve 兜底
+ * 确认落点仍在 temp 之下(绝对路径 / 符号化逃逸)。绝不静默跳过——跳过会让物化树与真实树发散。
+ */
+export declare function assertContainedRelPath(temp: string, relPath: string): void;
+export interface MaterializedGitTree {
+    /** 物化后的本地根:目录-skill 为临时目录、文件-skill 为临时 .md;喂 hashArtifactSource + 分发。 */
+    localRoot: string;
+    isDirectorySkill: boolean;
+    name: string;
+    /** 释放临时目录;调用方务必 try/finally 调用(物化只为算哈/分发,用完即删)。 */
+    cleanup: () => void;
+}
+/**
+ * 把 git 某个 ref 上的 skill(已由 `classifyGitSkillRef` 归类)逐文件物化到临时目录 ——
+ * **install 与 eval 共用此一处物化**,保证两侧拿到完全一致的本地树(此前 install/eval 各写一套
+ * git 解析正是四轮 bug 的根源,已靠共享 helper 收敛)。eval 仅为算整树指纹(hashArtifactSource)而
+ * 物化,算完即 cleanup;install 物化后分发并登记。失败(越界路径 / 空树 / 取不到 blob)抛
+ * SourceResolveError,绝不静默落空壳。
+ */
+export declare function materializeGitSkillTree(ref: string, resolved: GitSkillRef, repoRoot: string): MaterializedGitTree;
+export interface RemoteGitCheckout {
+    /** 临时 bare 仓库路径,作为 git helper 的 cwd(repoRoot)。 */
+    repoRoot: string;
+    /** fetch 落地后 rev-parse 出的**实际 SHA**(branch/tag 会漂,记录与重取都钉 SHA)。 */
+    ref: string;
+    /** 删临时 bare 仓库;调用方务必 try/finally 调用。 */
+    cleanup: () => void;
+}
+/**
+ * 远端 git URL 形态校验:接受 https(s):// / ssh:// / git:// / file:// 协议 URL、scp 形式
+ * `user@host:path`、绝对本地路径(file 远端 / 测试)。明显非法(空、相对裸串)拒。
+ */
+export declare function isPlausibleGitUrl(url: string): boolean;
+/**
+ * 远端 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 declare function fetchRemoteGitRef(url: string, ref: string): RemoteGitCheckout;
 export declare function discoverVariants(skillDir: string): string[];
 export declare function discoverBatchSkills(skillDir: string): Array<{
     name: string;
@@ -79,6 +134,9 @@ export interface ResolveArtifactsOptions {
      *  显式 per-variant 隔离声明走 spec.allowedSkills(prepareEvaluationRun 按 spec 身份绑定),
      *  不经此处——resolveArtifacts 只认 strictBaseline 默认,隔离绑定收成单一来源。 */
     strictBaseline?: boolean;
+    /** Default true. dir-skill 是否落地隔离副本(写 `~/.oh-my-knowledge/trees` 并设 execRoot)。
+     *  只有 eval(执行隔离)需要;doctor / loadSkills 等纯读路径传 false,只算指纹与正文、不写副本。 */
+    materialize?: boolean;
 }
 /**
  * Parse variant expression, extracting optional cwd suffix.
@@ -106,10 +164,15 @@ export declare function variantIdentity(expr: string, skillDir?: string, cwd?: s
 export declare function skillNameFromPath(filePath: string): string;
 /** 从 variant 表达式(纯 artifact 身份,可能是路径)取短名。 */
 export declare function variantExprToSkillName(expr: string): string;
-/** variant 输入:纯 artifact 表达式字符串,或结构化的 `{expr, cwd?}`。cwd 不再编码进 expr。 */
+/** variant 输入:纯 artifact 表达式字符串、结构化 `{expr, cwd?}`、或远端 git 结构化 `{git, cwd?, name}`
+ *  (url/ref/spec 分字段,绝不拼成单串再经 parseGitInput/parseVariantCwd 切分)。 */
 export type VariantInput = string | {
     expr: string;
     cwd?: string;
+} | {
+    git: RemoteGitRef;
+    cwd?: string;
+    name: string;
 };
 export declare function resolveArtifacts(skillDir: string, variants: VariantInput[], opts?: ResolveArtifactsOptions): Artifact[];
 /** 消歧:多个 variant resolve 出同名时(如 `v1/greeter.md` vs `v2/greeter.md` 都叫 `greeter`),

package/dist/inputs/skill-loader.js

@@ -1,7 +1,10 @@
-import { readFileSync, existsSync, readdirSync, statSync, realpathSync } 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)
@@ -49,7 +52,10 @@ const GIT_PROBE_STDIO = ['ignore', 'pipe', 'ignore'];
 // 由 resolveGitRepoContext 解出 repoRoot 后逐处显式传入。
 export function gitShowFile(ref, filePath, cwd = process.cwd()) {
     try {
-        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
+        // `--` 隔断 tree-ish:ref 可能来自盘上受管记录的 locator(用户可手改 / 随仓库分发,被 omk list 等只读
+        // 命令喂进来),前缀 `-` 的 ref 不得被当成 git 选项解析(与 #219 fetch 路径同口径,见
+        // feedback_git_subprocess_dashdash)。加 `--` 后 dash-ref 退化为「非法 object name」fail-closed,普通 ref 输出不变。
+        return execFileSync('git', ['cat-file', 'blob', '--', `${ref}:${filePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO }).trim();
     }
     catch {
         return null;
@@ -61,7 +67,7 @@ export function gitShowFile(ref, filePath, cwd = process.cwd()) {
  */
 export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
     try {
-        return execFileSync('git', ['cat-file', 'blob', `${ref}:${filePath}`], { cwd, stdio: GIT_PROBE_STDIO }); // 无 encoding → Buffer
+        return execFileSync('git', ['cat-file', 'blob', '--', `${ref}:${filePath}`], { cwd, stdio: GIT_PROBE_STDIO }); // 无 encoding → Buffer;`--` 隔断同 gitShowFile
     }
     catch {
         return null;
@@ -77,7 +83,7 @@ export function gitShowBytes(ref, filePath, cwd = process.cwd()) {
 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 });
+        out = execFileSync('git', ['ls-tree', '-r', '-z', '--full-tree', '--', `${ref}:${treePath}`], { cwd, encoding: 'utf-8', stdio: GIT_PROBE_STDIO });
     }
     catch {
         return [];
@@ -179,6 +185,158 @@ export function classifyGitSkillRef(ref, gitRelDir, spec, cwd = process.cwd()) {
     }
     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))
         return [];
@@ -254,7 +412,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.
@@ -308,7 +467,8 @@ 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') {
@@ -346,11 +506,97 @@ export function variantExprToSkillName(expr) {
     // 以 .md 结尾的目录,两处会派生出不同短名)。
     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 materialize = opts.materialize ?? true;
     const artifacts = [];
     let gitCtx = null;
     for (const rawVariant of variants) {
+        // 远端 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;
@@ -383,10 +629,39 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 gitCtx = resolveGitRepoContext(skillDir);
             // file-vs-dir 归类与 install 共用 classifyGitSkillRef(裸 spec 文件优先),两条路径绝不发散。
             const resolved = classifyGitSkillRef(ref, gitCtx.relDir, name, gitCtx.repoRoot);
-            const content = resolved
-                ? (resolved.isDir ? gitShowFile(ref, gitJoin(resolved.treePath, 'SKILL.md'), gitCtx.repoRoot) : gitShowFile(ref, resolved.fileSkillPath, gitCtx.repoRoot))
-                : null;
-            if (!content) {
+            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;
+            }
+            // 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({
@@ -394,6 +669,7 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 kind: 'skill',
                 source: 'git',
                 content,
+                contentHash: hashBytes(skillMdBytes),
                 locator: name,
                 ref,
                 cwd: variantCwd,
@@ -415,14 +691,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;
@@ -437,23 +731,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) {

package/dist/inputs/source-resolver.d.ts

@@ -3,9 +3,10 @@
  * 新增一种源 = 加一个分支,install.ts 不动。本模块不依赖 CLI(不打印、不 tCli):错误以
  * `SourceResolveError(messageKey)` 抛出,由调用方(install)映射成本地化文案。
  *
- * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)。远端 git / URL clone 留作后续,
- * 沿同一 `ResolvedSource` 契约扩展即可。
+ * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)、远端 git(URL + ref,fetch 到临时 bare)。
+ * 三者沿同一 `ResolvedSource` 契约,install / managed 主干源无关。
  */
+export { SourceResolveError } from './skill-loader.js';
 export type SourceKind = 'file' | 'git';
 export interface ResolvedSource {
     sourceKind: SourceKind;
@@ -14,15 +15,21 @@ export interface ResolvedSource {
     /** skill 短名(分发落点 / 记录 name)。 */
     name: string;
     isDirectorySkill: boolean;
-    /** 记录身份:file=绝对路径;git=`git:<ref>:<spec>`(非临时物化路径)。 */
+    /** 记录身份:file=绝对路径;本地 git=`git:<ref>:<spec>`;远端 git=`git+<url>@<sha>:<spec>`
+     *  (均非临时物化路径;远端身份串仅作记录/相等比较,绝不回喂 parseGitInput 的 `:` 切分)。 */
     locator: string;
+    /** git 来源的 ref;远端为 fetch 后 pin 的实际 SHA。 */
     ref?: string;
-    /** 释放临时资源(git 删临时目录);file 源为 noop。 */
+    /** 远端 git 的 URL(本地源 / 本地 git 无)。供受管记录结构化存、drift 重取,不挤进 locator 再 split。 */
+    url?: string;
+    /** 释放临时资源(git 删临时目录 / 远端另删 bare);file 源为 noop。 */
     cleanup: () => void;
 }
-export declare class SourceResolveError extends Error {
-    readonly messageKey: string;
-    readonly params: Record<string, string | number>;
-    constructor(messageKey: string, params?: Record<string, string | number>);
-}
 export declare function resolveInstallSource(input: string): ResolvedSource;
+/**
+ * 远端 git 源:`<url>` + `<ref>` + repo 相对 `<spec>`(三者结构化传入,URL 不经任何字符串切分,
+ * 避开 `parseGitInput` 的 `:` 与 `parseVariantCwd` 的 `@`)。fetch 到临时 bare → 复用既有
+ * classifyGitSkillRef / materializeGitSkillTree(repoRoot 换成 bare)。locator 落 `git+<url>@<sha>:<spec>`
+ * 仅作记录身份;url 另以结构化字段携带,供 drift 重取。失败 fail-closed 并清临时资源。
+ */
+export declare function resolveRemoteGitSource(url: string, ref: string, spec: string): ResolvedSource;