oh-my-knowledge 0.33.0 → 0.35.0

package/dist/inputs/materialize-copy.js

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

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

@@ -47,4 +47,3 @@ export declare function resolveMcpUrls(samples: Sample[], mcpServers: McpServers
  * Should be called when the evaluation run finishes.
  */
 export declare function stopAllServers(): Promise<void>;
-//# sourceMappingURL=mcp-resolver.d.ts.map

package/dist/inputs/mcp-resolver.js

@@ -304,4 +304,3 @@ async function fetchFromServer(serverName, serverDef, urls, resultMap) {
     });
     await Promise.allSettled(promises);
 }
-//# sourceMappingURL=mcp-resolver.js.map

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

@@ -1,4 +1,126 @@
-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。
+ * 同 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;
+/**
+ * 源解析的结构化错误 —— 不依赖 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;
@@ -8,12 +130,13 @@ 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[]>;
+    /** Default true. dir-skill 是否落地隔离副本(写 `~/.oh-my-knowledge/trees` 并设 execRoot)。
+     *  只有 eval(执行隔离)需要;doctor / loadSkills 等纯读路径传 false,只算指纹与正文、不写副本。 */
+    materialize?: boolean;
 }
 /**
  * Parse variant expression, extracting optional cwd suffix.
@@ -31,19 +154,29 @@ 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?}`、或远端 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`),
  *  用父目录逐段限定恢复唯一性。否则 `results[sample][variant]` / `summary[variant]` 按 name 键时
  *  后写覆盖前写,把对照 / 实验组的结果搅在一起、verdict 拿同名跟自己比 —— 静默破坏对比可信度。
  *  没有可用路径(baseline / git)时退化加 `#n` 序号兜底,保证返回的 name 一定两两不同。 */
 export declare function ensureUniqueVariantNames(artifacts: Artifact[]): void;
-//# sourceMappingURL=skill-loader.d.ts.map