oh-my-knowledge 0.32.0 → 0.34.0

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))
@@ -82,9 +212,14 @@ export function discoverBatchSkills(skillDir) {
         const mdMatch = entry.endsWith('.md') && !entry.endsWith('.eval-samples.json');
         if (mdMatch) {
             const name = entry.slice(0, -3);
-            const samplesPath = join(skillDir, `${name}.eval-samples.json`);
-            if (existsSync(samplesPath)) {
-                skills.push({ name, skillPath: join(skillDir, entry), samplesPath });
+            const candidates = [
+                join(skillDir, name, '.omk'),
+                join(skillDir, `${name}.eval-samples.json`),
+                join(skillDir, `${name}.eval-samples.yaml`),
+                join(skillDir, `${name}.eval-samples.yml`),
+            ].filter(existsSync);
+            if (candidates.length > 0) {
+                skills.push({ name, skillPath: join(skillDir, entry), samplesPath: candidates[0] });
             }
             else {
                 warned.push(name);
@@ -93,11 +228,21 @@ export function discoverBatchSkills(skillDir) {
         }
         if (statSync(entryPath).isDirectory()) {
             const skillMd = join(entryPath, 'SKILL.md');
-            const samplesPath = join(entryPath, 'eval-samples.json');
-            if (existsSync(skillMd) && existsSync(samplesPath)) {
+            if (!existsSync(skillMd))
+                continue;
+            // .omk/ dir (loadSamples handles dir mode) > .omk/samples.json > eval-samples.{json,yaml,yml}
+            const omkDir = join(entryPath, '.omk');
+            const candidates = [
+                ...(existsSync(omkDir) ? [omkDir] : []),
+                join(entryPath, 'eval-samples.json'),
+                join(entryPath, 'eval-samples.yaml'),
+                join(entryPath, 'eval-samples.yml'),
+            ];
+            const samplesPath = candidates.find(existsSync);
+            if (samplesPath) {
                 skills.push({ name: entry, skillPath: skillMd, samplesPath });
             }
-            else if (existsSync(skillMd)) {
+            else {
                 warned.push(entry);
             }
         }
@@ -116,20 +261,104 @@ export function loadSkills(skillDir, variants) {
  * Format: "name@/path/to/cwd" or just "name"
  */
 export function parseVariantCwd(variant) {
-    const atIdx = variant.indexOf('@');
+    // 找 name@cwd 的切分点:跳过 git 修订语法里的 `@{...}`(reflog `HEAD@{2}`、upstream
+    // `main@{u}`),取第一个不是紧跟 `{` 的 `@`。这样 `git:v1@/proj`(git artifact + cwd,
+    // eval.yaml 经 configVariantsToSpecs 生成的形态)仍能切出 cwd,而 `git:HEAD@{2}:x`
+    // (无 cwd)不会被误拆成 name=`git:HEAD`、cwd=`{2}:x` → 下游静默评测错版本。
+    let atIdx = -1;
+    for (let i = variant.indexOf('@'); i !== -1; i = variant.indexOf('@', i + 1)) {
+        if (variant[i + 1] !== '{') {
+            atIdx = i;
+            break;
+        }
+    }
     if (atIdx === -1)
         return { name: variant };
     return { name: variant.slice(0, atIdx), cwd: variant.slice(atIdx + 1) };
 }
+/** 把一个路径折叠到稳定的 skill 锚点:目录型 skill 与其 `SKILL.md` 归一到同一个
+ *  `dir/SKILL.md`,单文件 .md 用其路径本身。返回路径(不解物理身份),供取短名与身份判重共用。 */
+function canonicalSkillAnchor(absPath) {
+    return existsSync(absPath) && statSync(absPath).isDirectory() ? join(absPath, 'SKILL.md') : absPath;
+}
+/** 路径的稳定物理身份:存在则取 `dev:ino`(解符号链接、折叠大小写不敏感卷的等价写法、认硬链),
+ *  不存在则退回原路径串。判重必须用物理身份——纯字符串 resolve 会把同一文件的软链/大小写/
+ *  绝对 vs CWD 相对写法判成两个 variant,放过真重复 → 同一份 skill 自比、悄悄废掉对比保护。 */
+function pathPhysicalId(p) {
+    try {
+        const st = statSync(p);
+        return `ino:${st.dev}:${st.ino}`;
+    }
+    catch {
+        return p;
+    }
+}
+/** 把一个 variant 表达式规范化成稳定的物理身份,用于「同一 variant 不能既是 control 又是
+ *  treatment」的判重。同一份 skill 的不同写法必须折叠成同一个 key:
+ *    - `./x.md` 与 `x.md`、符号链接、大小写不敏感卷上的等价写法:resolve 后取 `dev:ino` 物理身份。
+ *    - 目录 `dir` 与 `dir/SKILL.md`：先折叠到同一锚点再取物理身份。
+ *    - 裸短名(传了 `skillDir` 时):按 resolveArtifacts 的解析基准(`skillDir/name.md` 或
+ *      `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, cwd) {
+    // expr 已是纯 artifact 身份(@cwd 在 CLI/config 边界已剥离);cwd 结构化显式传入。
+    const name = expr;
+    let id;
+    if (name.startsWith('git:')) {
+        id = name;
+    }
+    else if (name === 'baseline') {
+        id = 'baseline';
+    }
+    else if (name.includes('/') || /\.md$/i.test(name)) {
+        id = pathPhysicalId(canonicalSkillAnchor(resolve(name)));
+    }
+    else if (skillDir) {
+        // 裸短名按 resolveArtifacts 的同一基准(skillDir/name.md 或 skillDir/name/SKILL.md)解析,
+        // 命不中就退回字面名(resolveArtifacts 随后会报 not found)。
+        const md = join(skillDir, `${name}.md`);
+        const dirMd = join(skillDir, name, 'SKILL.md');
+        id = existsSync(md) ? pathPhysicalId(md) : existsSync(dirMd) ? pathPhysicalId(dirMd) : name;
+    }
+    else {
+        id = name; // 无 skillDir 上下文:不同短名即不同 variant
+    }
+    return cwd ? `${id}@${pathPhysicalId(resolve(cwd))}` : id;
+}
+/** 从已解析的 skill 路径取短名:`SKILL.md` 取其父目录名,否则取去掉 `.md` 后缀的 basename。
+ *  `variantExprToSkillName`(expr → 短名)与 `resolveArtifacts` 的 file-path 命名共用这一处,
+ *  避免两份各写一遍后悄悄发散——report 键就来自 resolveArtifacts 这一支。 */
+export function skillNameFromPath(filePath) {
+    const base = basename(filePath);
+    return base === 'SKILL.md' ? basename(dirname(filePath)) : base.replace(/\.md$/i, '');
+}
+/** 从 variant 表达式(纯 artifact 身份,可能是路径)取短名。 */
+export function variantExprToSkillName(expr) {
+    if (expr.startsWith('git:'))
+        return expr;
+    if (!expr.includes('/'))
+        return expr;
+    // 先折叠 dir↔SKILL.md 再取短名,与 resolveArtifacts 的命名一致(否则 `weird.md/` 这类
+    // 以 .md 结尾的目录,两处会派生出不同短名)。
+    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 名不能为空。如需绑定 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({
@@ -142,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];
-            }
-            else {
-                ref = parts[0];
-                name = parts.slice(1).join(':');
+            // 与 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）。`);
             }
-            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`);
             }
@@ -176,7 +405,6 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             if (!existsSync(filePath)) {
                 throw new Error(`skill file not found: ${filePath}`);
             }
-            // If path is a directory, look for SKILL.md inside it
             if (statSync(filePath).isDirectory()) {
                 const skillMd = join(filePath, 'SKILL.md');
                 if (!existsSync(skillMd)) {
@@ -185,10 +413,10 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
                 filePath = skillMd;
             }
             const content = readFileSync(filePath, 'utf-8').trim();
-            // 用户直接指 SKILL.md 等同 directory-skill 约定:cwd 默认锚到该目录
             const isSkillMd = basename(filePath) === 'SKILL.md';
+            const name = skillNameFromPath(filePath);
             artifacts.push({
-                name: variantName,
+                name,
                 kind: 'skill',
                 source: 'file-path',
                 content,
@@ -241,21 +469,73 @@ export function resolveArtifacts(skillDir, variants, opts = {}) {
             throw new Error(`skill not found: ${mdPath} or ${dirSkillPath}`);
         }
     }
-    // Skill-isolation wiring.
-    //   Priority: variantAllowedSkills (explicit eval.yaml) > strictBaseline default > none.
-    //   strictBaseline=true 时,所有 kind:'baseline' artifact 默认 allowedSkills=[]。
-    //   显式 [] 也是合法(用户主动想"完全发现")的反义靠 strictBaseline=false 表达整批关闭。
+    // 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;
 }
-//# sourceMappingURL=skill-loader.js.map
+/** variant 短名的消歧路径:取「短名所源自的那一段」所在的完整路径,用来逐段往前限定。
+ *  - dir/SKILL.md 或 dir-variant:skillRoot(= 那个 skill 目录,basename 即短名)
+ *  - 单文件 .md:locator 去掉 .md(basename 即短名)
+ *  - baseline / git variant:无可用路径(git 名本就唯一,baseline 不参与对比键),返回 null。 */
+function identityPathOf(a) {
+    if (a.kind !== 'skill' || a.source === 'git' || !a.locator)
+        return null;
+    return a.skillRoot ?? a.locator.replace(/\.md$/i, '');
+}
+/** 消歧:多个 variant resolve 出同名时(如 `v1/greeter.md` vs `v2/greeter.md` 都叫 `greeter`),
+ *  用父目录逐段限定恢复唯一性。否则 `results[sample][variant]` / `summary[variant]` 按 name 键时
+ *  后写覆盖前写,把对照 / 实验组的结果搅在一起、verdict 拿同名跟自己比 —— 静默破坏对比可信度。
+ *  没有可用路径(baseline / git)时退化加 `#n` 序号兜底,保证返回的 name 一定两两不同。 */
+export function ensureUniqueVariantNames(artifacts) {
+    const groups = new Map();
+    for (const a of artifacts) {
+        const g = groups.get(a.name);
+        if (g)
+            g.push(a);
+        else
+            groups.set(a.name, [a]);
+    }
+    if (![...groups.values()].some((g) => g.length > 1))
+        return; // 无冲突,常见路径直接返回
+    const used = new Set();
+    for (const [name, g] of groups)
+        if (g.length === 1)
+            used.add(name);
+    for (const [name, g] of groups) {
+        if (g.length === 1)
+            continue;
+        // 找能让组内全部区分、又不撞已用名的最小段深,组内统一用同一深度 → 对称标签(v1/greeter 对 v2/greeter)
+        const segLists = g.map((a) => {
+            const p = identityPathOf(a);
+            return p ? p.split(/[\\/]+/).filter(Boolean) : null;
+        });
+        const maxDepth = Math.max(0, ...segLists.map((s) => s?.length ?? 0));
+        let chosen = null;
+        for (let take = 2; take <= maxDepth; take++) {
+            const cands = segLists.map((s) => (s && s.length >= take ? s.slice(-take).join('/') : null));
+            if (cands.includes(null))
+                continue;
+            if (new Set(cands).size === cands.length && cands.every((c) => !used.has(c))) {
+                chosen = cands;
+                break;
+            }
+        }
+        g.forEach((a, i) => {
+            const candidate = chosen ? chosen[i] : name; // 无可用路径(baseline 等)退化到原名 + #n 序号
+            let unique = candidate;
+            for (let n = 2; used.has(unique); n++)
+                unique = `${candidate}#${n}`;
+            a.name = unique;
+            used.add(unique);
+        });
+    }
+}

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';