oh-my-knowledge 0.33.0 → 0.34.0

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

@@ -1,4 +1,71 @@
 import type { Artifact } from '../types/index.js';
+export declare function gitShowFile(ref: string, filePath: string, cwd?: string): string | null;
+/**
+ * 取 `<ref>:<filePath>` 的原始字节(二进制资产用,不做 utf-8 解码);不存在/非 blob/出错返回 null。
+ * 同 gitShowFile 用 `cat-file blob`:对目录会非零退出,不会把树清单字节当文件内容物化。
+ */
+export declare function gitShowBytes(ref: string, filePath: string, cwd?: string): Buffer | null;
+export interface GitTreeEntry {
+    /** git 文件模式:100644/100755=普通文件,120000=软链,160000=submodule。 */
+    mode: string;
+    /** 相对所列 tree 的路径。 */
+    path: string;
+}
+/**
+ * 递归列出 `<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 declare function gitLsTreeBlobs(ref: string, treePath: string, cwd?: string): GitTreeEntry[];
+export interface GitRepoContext {
+    /** 仓库根(realpath 归一,避免 macOS /var ↔ /private/var 等价路径算错)。所有 git helper 以此为 cwd。 */
+    repoRoot: string;
+    /** fromPath 相对仓库根的路径(realpath 归一后计算)。 */
+    relDir: string;
+}
+/**
+ * 解出 `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 declare function resolveGitRepoContext(fromPath: string): GitRepoContext;
+/** 拼 git 仓库相对路径:始终用 `/`,空 base 直接返回 b(避免 join 产生 `.` 这类退化 tree-ish)。 */
+export declare function gitJoin(base: string, sub: string): string;
+/**
+ * 解析 `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 declare function parseGitInput(input: string): {
+    ref: string;
+    spec: string;
+} | null;
+export interface GitSkillRef {
+    isDir: boolean;
+    /** dir-skill 的子树根(仓库相对);file-skill 为空。 */
+    treePath: string;
+    /** file-skill 的 .md 路径(仓库相对);dir-skill 为空。 */
+    fileSkillPath: string;
+    name: string;
+}
+/**
+ * 把 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 declare function classifyGitSkillRef(ref: string, gitRelDir: string, spec: string, cwd?: string): GitSkillRef | null;
 export declare function discoverVariants(skillDir: string): string[];
 export declare function discoverBatchSkills(skillDir: string): Array<{
     name: string;
@@ -8,12 +75,10 @@ export declare function discoverBatchSkills(skillDir: string): Array<{
 export declare function loadSkills(skillDir: string, variants: string[]): Record<string, string | null>;
 /** opts for resolveArtifacts skill-isolation wiring. */
 export interface ResolveArtifactsOptions {
-    /** Default true. When true, baseline-kind artifacts get allowedSkills=[] auto-injected
-     *  unless overridden by variantAllowedSkills. */
+    /** Default true. When true, baseline-kind artifacts get allowedSkills=[] auto-injected.
+     *  显式 per-variant 隔离声明走 spec.allowedSkills(prepareEvaluationRun 按 spec 身份绑定),
+     *  不经此处——resolveArtifacts 只认 strictBaseline 默认,隔离绑定收成单一来源。 */
     strictBaseline?: boolean;
-    /** Per-variant explicit allowedSkills (from eval.yaml). Keyed by variant name (post
-     *  parseVariantCwd, matches Artifact.name). Always overrides strictBaseline default. */
-    variantAllowedSkills?: Record<string, string[]>;
 }
 /**
  * Parse variant expression, extracting optional cwd suffix.
@@ -31,19 +96,24 @@ export declare function parseVariantCwd(variant: string): {
  *      `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 declare function variantIdentity(expr: string, skillDir?: string): string;
+ *  结构化的 `cwd`(第三参数)按物理身份纳入 key —— 同一份 skill 绑不同 cwd 是不同 runtime
+ *  context,不算重复。不要用派生短名判重:`v1/greeter.md` 与 `v2/greeter.md` 短名都是 greeter
+ *  却是两个 variant。 */
+export declare function variantIdentity(expr: string, skillDir?: string, cwd?: string): string;
 /** 从已解析的 skill 路径取短名:`SKILL.md` 取其父目录名,否则取去掉 `.md` 后缀的 basename。
  *  `variantExprToSkillName`(expr → 短名)与 `resolveArtifacts` 的 file-path 命名共用这一处,
  *  避免两份各写一遍后悄悄发散——report 键就来自 resolveArtifacts 这一支。 */
 export declare function skillNameFromPath(filePath: string): string;
-/** Extract short skill name from a variant expression (which may be a path). */
+/** 从 variant 表达式(纯 artifact 身份,可能是路径)取短名。 */
 export declare function variantExprToSkillName(expr: string): string;
-export declare function resolveArtifacts(skillDir: string, variants: string[], opts?: ResolveArtifactsOptions): Artifact[];
+/** variant 输入:纯 artifact 表达式字符串,或结构化的 `{expr, cwd?}`。cwd 不再编码进 expr。 */
+export type VariantInput = string | {
+    expr: string;
+    cwd?: string;
+};
+export declare function resolveArtifacts(skillDir: string, variants: VariantInput[], opts?: ResolveArtifactsOptions): Artifact[];
 /** 消歧:多个 variant resolve 出同名时(如 `v1/greeter.md` vs `v2/greeter.md` 都叫 `greeter`),
  *  用父目录逐段限定恢复唯一性。否则 `results[sample][variant]` / `summary[variant]` 按 name 键时
  *  后写覆盖前写,把对照 / 实验组的结果搅在一起、verdict 拿同名跟自己比 —— 静默破坏对比可信度。
  *  没有可用路径(baseline / git)时退化加 `#n` 序号兜底,保证返回的 name 一定两两不同。 */
 export declare function ensureUniqueVariantNames(artifacts: Artifact[]): void;
-//# sourceMappingURL=skill-loader.d.ts.map

package/dist/inputs/skill-loader.js

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, statSync, realpathSync } from 'node:fs';
 import { resolve, join, relative, dirname, basename } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { extractSkillHardRules, extractSkillWorkflows } from '../shared/hard-rules.js';
@@ -37,17 +37,147 @@ 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;
 }
 export function discoverVariants(skillDir) {
     if (!existsSync(skillDir))
@@ -171,10 +301,12 @@ 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:')) {
         id = name;
@@ -204,29 +336,29 @@ 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;
 }
 export function resolveArtifacts(skillDir, variants, opts = {}) {
     const strictBaseline = opts.strictBaseline ?? true;
-    const variantAllowedSkills = opts.variantAllowedSkills ?? {};
     const artifacts = [];
-    let gitRelDir = null;
+    let gitCtx = null;
     for (const rawVariant of variants) {
-        const { name: variantName, cwd: variantCwd } = parseVariantCwd(rawVariant);
+        // 字符串即纯 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,21 +371,21 @@ 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(':');
-            }
-            if (!gitRelDir)
-                gitRelDir = getGitRelativePath(skillDir);
-            const content = gitShowFile(ref, join(gitRelDir, `${name}.md`))
-                || gitShowFile(ref, join(gitRelDir, name, 'SKILL.md'));
+            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);
+            const content = resolved
+                ? (resolved.isDir ? gitShowFile(ref, gitJoin(resolved.treePath, 'SKILL.md'), gitCtx.repoRoot) : gitShowFile(ref, resolved.fileSkillPath, gitCtx.repoRoot))
+                : null;
             if (!content) {
                 throw new Error(`skill not found in git ${ref}: ${name}.md or ${name}/SKILL.md`);
             }
@@ -337,25 +469,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 +539,3 @@ export function ensureUniqueVariantNames(artifacts) {
         });
     }
 }
-//# sourceMappingURL=skill-loader.js.map

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

@@ -0,0 +1,28 @@
+/**
+ * 安装源解析器 —— 把"各种源"物化成统一的本地形态,让 install / managed 主干**源无关**。
+ * 新增一种源 = 加一个分支,install.ts 不动。本模块不依赖 CLI(不打印、不 tCli):错误以
+ * `SourceResolveError(messageKey)` 抛出,由调用方(install)映射成本地化文案。
+ *
+ * 当前支持:`file`(本地路径)、`git`(当前仓库的某个 ref)。远端 git / URL clone 留作后续,
+ * 沿同一 `ResolvedSource` 契约扩展即可。
+ */
+export type SourceKind = 'file' | 'git';
+export interface ResolvedSource {
+    sourceKind: SourceKind;
+    /** 物化后的本地根:目录-skill 为目录、文件-skill 为 .md;喂 hashArtifactSource + 分发。 */
+    localRoot: string;
+    /** skill 短名(分发落点 / 记录 name)。 */
+    name: string;
+    isDirectorySkill: boolean;
+    /** 记录身份:file=绝对路径;git=`git:<ref>:<spec>`(非临时物化路径)。 */
+    locator: string;
+    ref?: string;
+    /** 释放临时资源(git 删临时目录);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;

package/dist/inputs/source-resolver.js

@@ -0,0 +1,125 @@
+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 = () => { };
+/**
+ * 校验 git tree 条目路径在物化目标内,越界即 fail closed(抛 SourceResolveError)。
+ * 双保险:既显式拒 `..` / 空段(git tree 可被手工构造出名为 `..` 的子树),也用 resolve 兜底
+ * 确认落点仍在 temp 之下(绝对路径 / 符号化逃逸)。绝不静默跳过——跳过会让物化树与真实树发散。
+ */
+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 });
+    }
+}
+export function resolveInstallSource(input) {
+    if (input.startsWith('git:'))
+        return resolveGitSource(input);
+    return resolveFileSource(input);
+}
+function resolveFileSource(input) {
+    const abs = resolve(input);
+    if (!existsSync(abs))
+        throw new SourceResolveError('cli.install.path_not_found', { path: abs });
+    const isDir = statSync(abs).isDirectory();
+    if (isDir) {
+        const skillMd = join(abs, 'SKILL.md');
+        if (!existsSync(skillMd)) {
+            throw new SourceResolveError('cli.install.skillmd_missing', { path: abs });
+        }
+        // 软链 SKILL.md 会被分发跳过(与 git 物化、cpSync 的软链策略一致)→ 装出空壳。指向真源,让记录落在真源上。
+        if (lstatSync(skillMd).isSymbolicLink()) {
+            throw new SourceResolveError('cli.install.skillmd_is_symlink', { target: realpathSync(skillMd) });
+        }
+    }
+    if (!isDir && !/\.md$/i.test(abs)) {
+        throw new SourceResolveError('cli.install.not_a_skill', { path: abs });
+    }
+    const name = isDir ? skillNameFromPath(join(abs, 'SKILL.md')) : skillNameFromPath(abs);
+    return { sourceKind: 'file', localRoot: abs, name, isDirectorySkill: isDir, locator: abs, cleanup: noop };
+}
+function resolveGitSource(input) {
+    // 空 spec / 空 ref 由共享 parseGitInput 拒(返回 null):空 ref(`git::x`)会被 git 当 index/stage-0
+    // 解析,破坏"可复现、可重取"的前提;eval 与 install 经同一 helper 判定一致。
+    const parsed = parseGitInput(input);
+    if (!parsed)
+        throw new SourceResolveError('cli.install.git_skill_not_found', { ref: '', name: input });
+    const { ref, spec } = parsed;
+    let ctx;
+    try {
+        ctx = resolveGitRepoContext(resolve('.'));
+    }
+    catch {
+        throw new SourceResolveError('cli.install.not_a_git_repo', {});
+    }
+    const resolved = classifyGitSkillRef(ref, ctx.relDir, spec, ctx.repoRoot);
+    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 {
+            // 临时目录清理失败不致命
+        }
+    };
+    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/inputs/url-fetcher.d.ts

@@ -16,4 +16,3 @@ export declare function isPlaceholderUrl(url: string): boolean;
  * @param skipUrls - URLs already resolved (e.g. by MCP), will be skipped
  */
 export declare function resolveUrls(samples: Sample[], skipUrls?: Set<string>): Promise<void>;
-//# sourceMappingURL=url-fetcher.d.ts.map

package/dist/inputs/url-fetcher.js

@@ -238,4 +238,3 @@ function getSolution(statusCode, result) {
     }
     return '请将文档内容复制到 eval-samples 的 context 字段中';
 }
-//# sourceMappingURL=url-fetcher.js.map

package/dist/managed/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 受管 artifact 域的单一公共入口。CLI、未来的 server / web / SDK 都从这里消费,
+ * 不直接依赖内部文件布局。
+ */
+export * from './store.js';

package/dist/managed/index.js

@@ -0,0 +1,5 @@
+/**
+ * 受管 artifact 域的单一公共入口。CLI、未来的 server / web / SDK 都从这里消费,
+ * 不直接依赖内部文件布局。
+ */
+export * from './store.js';