@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/dist/updater.js

@@ -0,0 +1,352 @@
+/**
+ * skill 版本自动更新器。
+ *
+ * 触发：reconcile 检测到本地某 skill 版本落后于平台最新版本（config.version）后调用。
+ * 流程（每个 skill@version 仅下载一次，覆盖其全部 workspace 副本）：
+ *   1. POST {platformBaseUrl}/skill_package/pull {skillName, version} → { url }
+ *   2. GET url → zip 字节 → 写入临时文件
+ *   3. 解压到临时 staging 目录（默认调用系统 unzip）
+ *   4. 在 staging 内定位含 SKILL.md 的目录作为源根（兼容包内带或不带顶层目录）
+ *   5. 逐个目标目录「直接覆盖、不备份」：先复制到同级临时目录，再删旧、原子 rename 换入，
+ *      避免中途失败留下损坏的半成品；不保留 .bak。
+ *
+ * 安全约束：
+ *   - 仅在 autoUpdateSkills===true 且配置了 platformBaseUrl 时执行，默认关闭。
+ *   - 任一步失败只 warn 并跳过该 skill，绝不抛、绝不阻塞 reconcile。
+ *   - 下载包内必须含 SKILL.md 才会覆盖，否则放弃（防止把目标目录清空成坏内容）。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID, createHash } from "node:crypto";
+import { parseSkillVersion } from "./skill-version.ts";
+const execFileAsync = promisify(execFile);
+/**
+ * 同一 skill@version 的更新尝试冷却期。
+ * 防止「下载包版本号与平台 latestVersion 不一致 / 非 semver 版本永不相等」等情况下，
+ * 每 3 分钟一轮 reconcile 反复下载覆盖。成功更新会改变本地版本从而不再判过期，故冷却只影响失败/不一致场景。
+ */
+const ATTEMPT_COOLDOWN_MS = 30 * 60 * 1000;
+/**
+ * 轻量「身份哈希」：name + code + version。约定 name==code（SKILL.md 的 name 即 skillCode），
+ * 故按 `code code version`（空格分隔）计算 sha256。与服务端 skillIdentityHash 必须保持一致。
+ * 仅做身份/版本一致性校验，不做整包字节哈希。
+ */
+function skillIdentityHash(code, version) {
+    return createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
+}
+/** 默认解压：系统 unzip -o -q（覆盖、静默）。 */
+async function systemUnzip(zipPath, destDir) {
+    await fs.mkdir(destDir, { recursive: true });
+    await execFileAsync("unzip", ["-o", "-q", zipPath, "-d", destDir]);
+}
+export class SkillUpdater {
+    getConfig;
+    fetchImpl;
+    unzip;
+    tmpDir;
+    /** 冷却期状态持久化文件路径。 */
+    cooldownStatePath;
+    /** skill@version → 上次尝试时间戳，用于冷却，避免重复下载覆盖。 */
+    lastAttempt = new Map();
+    constructor(opts) {
+        this.getConfig = opts.getConfig;
+        this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+        this.unzip = opts.unzip ?? systemUnzip;
+        this.tmpDir = opts.tmpDir ?? os.tmpdir();
+        this.cooldownStatePath = opts.cooldownStatePath;
+        this.loadCooldown(); // 同步读取，启动早期就需要用到冷却期
+    }
+    get isDebug() {
+        return this.getConfig().debugLogging !== false;
+    }
+    debug(...args) {
+        if (this.isDebug)
+            console.log("[skill-logger-plugin/updater]", ...args);
+    }
+    /** 从文件同步加载冷却期状态到内存Map。文件不存在或解析失败时静默跳过。 */
+    loadCooldown() {
+        if (!this.cooldownStatePath)
+            return;
+        try {
+            const raw = fs.readFileSync(this.cooldownStatePath, "utf-8");
+            const obj = JSON.parse(raw);
+            for (const [k, v] of Object.entries(obj)) {
+                if (typeof v === "number" && Number.isFinite(v)) {
+                    this.lastAttempt.set(k, v);
+                }
+            }
+            this.debug(`冷却期状态已从文件恢复，共 ${this.lastAttempt.size} 条`);
+        }
+        catch {
+            // 文件不存在或解析失败 → 用空Map，插件继续正常工作
+        }
+    }
+    /** 将内存中的冷却期状态写入文件。写入失败时静默跳过，不影响主流程。 */
+    async persistCooldown() {
+        if (!this.cooldownStatePath)
+            return;
+        try {
+            const obj = {};
+            for (const [k, v] of this.lastAttempt) {
+                obj[k] = v;
+            }
+            await fs.writeFile(this.cooldownStatePath, JSON.stringify(obj), "utf-8");
+        }
+        catch {
+            // 写入失败不影响主流程，下次会继续尝试
+        }
+    }
+    /** 对一批落后副本执行更新。按 skill@version 去重下载，覆盖各自的全部目标目录。 */
+    async applyUpdates(outdated) {
+        const cfg = this.getConfig();
+        if (cfg.autoUpdateSkills === false)
+            return; // 默认开启，仅显式 false 关闭
+        if (!cfg.platformBaseUrl)
+            return; // 无平台地址无法下载
+        if (outdated.length === 0)
+            return;
+        const groups = new Map();
+        for (const o of outdated) {
+            const key = `${o.skillName}@${o.latestVersion}`;
+            let g = groups.get(key);
+            if (!g) {
+                g = { skillName: o.skillName, version: o.latestVersion, targets: [] };
+                groups.set(key, g);
+            }
+            if (!g.targets.includes(o.rootDir))
+                g.targets.push(o.rootDir);
+        }
+        for (const g of groups.values()) {
+            const key = `${g.skillName}@${g.version}`;
+            const last = this.lastAttempt.get(key);
+            if (last !== undefined && Date.now() - last < ATTEMPT_COOLDOWN_MS) {
+                this.debug(`跳过 ${key}：距上次尝试不足冷却期（防重复下载覆盖）`);
+                continue;
+            }
+            this.lastAttempt.set(key, Date.now()); // 不论成败都记，失败也按冷却退避，避免每 3 分钟重试
+            await this.persistCooldown(); // 持久化到文件，重启后冷却期不丢失
+            try {
+                await this.updateOne(g.skillName, g.version, g.targets);
+            }
+            catch (err) {
+                console.warn(`[skill-logger-plugin] 自动更新 ${key} 异常`, err);
+            }
+        }
+    }
+    async updateOne(skillName, version, targets) {
+        const dl = await this.fetchDownloadUrl(skillName, version);
+        if (!dl?.url)
+            return;
+        const work = path.join(this.tmpDir, `slp-update-${randomUUID()}`);
+        await fs.mkdir(work, { recursive: true });
+        try {
+            const zipPath = path.join(work, "pkg.zip");
+            const res = await this.fetchImpl(dl.url);
+            if (!res.ok) {
+                console.warn(`[skill-logger-plugin] 下载 ${skillName}@${version} 失败 HTTP`, res.status);
+                return;
+            }
+            const buf = Buffer.from(await res.arrayBuffer());
+            await fs.writeFile(zipPath, buf);
+            const staging = path.join(work, "staging");
+            await this.unzip(zipPath, staging);
+            const srcRoot = await this.locateSkillRoot(staging, 0);
+            if (!srcRoot) {
+                console.warn(`[skill-logger-plugin] ${skillName}@${version} 下载包内未找到 SKILL.md，放弃覆盖`);
+                return;
+            }
+            // [兼容处理] 缺少 .meta.json 时主动补齐
+            const metaPath = path.join(srcRoot, ".meta.json");
+            if (!(await this.exists(metaPath))) {
+                this.debug(`[skill-logger-plugin] 为 ${skillName}@${version} 自动生成 .meta.json`);
+                await fs.writeFile(metaPath, JSON.stringify({
+                    ownerId: 'CMS_COMPAT',
+                    slug: skillName,
+                    version: version,
+                    publishedAt: Date.now()
+                }, null, 2));
+            }
+            // 守卫：下载包的 SKILL.md 必须能解析出版本号，否则不做覆盖（服务端要求：无版本号不更新）。
+            let packageVersion;
+            try {
+                const newSkillMd = await fs.readFile(path.join(srcRoot, "SKILL.md"), "utf-8");
+                packageVersion = parseSkillVersion(newSkillMd);
+            }
+            catch {
+                console.warn(`[skill-logger-plugin] ${skillName}@${version} 读取下载包 SKILL.md 失败，放弃覆盖`);
+                return;
+            }
+            if (!packageVersion) {
+                console.warn(`[skill-logger-plugin] ${skillName}@${version} 下载包 SKILL.md 无版本号，放弃覆盖`);
+                return;
+            }
+            for (const target of targets) {
+                try {
+                    await this.replaceDir(srcRoot, target);
+                    this.debug(`已更新 ${skillName} → ${version} @ ${target}`);
+                }
+                catch (err) {
+                    console.warn(`[skill-logger-plugin] 覆盖 ${skillName} 到 ${target} 失败`, err);
+                }
+            }
+        }
+        finally {
+            await fs.rm(work, { recursive: true, force: true });
+        }
+    }
+    /** POST 下载接口取包 URL。返回 undefined 表示拿不到（调用方放弃本次更新）。 */
+    async fetchDownloadUrl(skillName, version) {
+        const cfg = this.getConfig();
+        const endpoint = cfg.platformBaseUrl.replace(/\/$/, "") + "/skill_package/pull";
+        const headers = { "Content-Type": "application/json" };
+        if (cfg.authToken)
+            headers.Authorization = cfg.authToken;
+        const res = await this.fetchImpl(endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ skillName, version }),
+        });
+        if (!res.ok) {
+            console.warn(`[skill-logger-plugin] 取下载地址 ${skillName}@${version} 失败 HTTP`, res.status);
+            return undefined;
+        }
+        const data = (await res.json());
+        const url = typeof data?.url === "string" ? data.url : typeof data?.downloadUrl === "string" ? data.downloadUrl : undefined;
+        const resolvedVersion = typeof data?.version === "string" ? data.version : undefined;
+        if (!url)
+            return undefined;
+        return { url, version: resolvedVersion };
+    }
+    /** 在解压目录里定位含 SKILL.md 的目录（兼容包内是否带顶层目录）。深度上限 2。 */
+    async locateSkillRoot(dir, depth) {
+        if (depth > 2)
+            return undefined;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return undefined;
+        }
+        if (entries.some((e) => e.isFile() && e.name === "SKILL.md"))
+            return dir;
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                const found = await this.locateSkillRoot(path.join(dir, e.name), depth + 1);
+                if (found)
+                    return found;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 直接覆盖、不备份，但保证「不丢数据」：
+     *   先把新内容暂存到同级临时目录 → 旧目录改名挪开 → 新内容 rename 换入 → 删掉挪开的旧目录。
+     * 换入失败时把旧目录还原，避免目标被清空。过程中的临时/旧目录都是隐藏且即时清理，不保留 .bak。
+     */
+    async replaceDir(src, target) {
+        const parent = path.dirname(target);
+        await fs.mkdir(parent, { recursive: true });
+        const tag = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+        const stage = path.join(parent, `.${path.basename(target)}.new-${tag}`);
+        const old = path.join(parent, `.${path.basename(target)}.old-${tag}`);
+        await fs.rm(stage, { recursive: true, force: true });
+        await fs.cp(src, stage, { recursive: true });
+        const hadTarget = await this.exists(target);
+        if (hadTarget)
+            await fs.rename(target, old); // 旧目录先挪开（仍完整保留，便于回滚）
+        try {
+            await fs.rename(stage, target); // 新内容换入
+        }
+        catch (err) {
+            // 换入失败：还原旧目录，清理暂存，确保目标不丢
+            if (hadTarget)
+                await fs.rename(old, target).catch(() => { });
+            await fs.rm(stage, { recursive: true, force: true }).catch(() => { });
+            throw err;
+        }
+        await fs.rm(old, { recursive: true, force: true }).catch(() => { }); // 成功后清理，不留备份
+    }
+    async exists(p) {
+        try {
+            await fs.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 手动下发安装/更新指令 (供沙盒 HTTP Proxy 与星型架构中控使用)
+     */
+    async manualInstall(options) {
+        const { code, force, targetDir } = options;
+        let { url, version } = options;
+        if (!url) {
+            // 若没有直接传入 ZIP 的 URL，向平台索取该 skill 的 latest 下载地址
+            const dl = await this.fetchDownloadUrl(code, version || "latest");
+            if (!dl?.url) {
+                return { success: false, message: `无法获取技能 ${code} 的下载地址` };
+            }
+            url = dl.url;
+            version = dl.version || version;
+        }
+        const targetSkillPath = path.join(targetDir, code);
+        // 如果非强制覆盖，且目标已经存在，则直接返回
+        if (!force && await this.exists(targetSkillPath)) {
+            return { success: false, message: `技能 ${code} 已存在于目标目录` };
+        }
+        const work = path.join(this.tmpDir, `slp-manual-${randomUUID()}`);
+        await fs.mkdir(work, { recursive: true });
+        try {
+            // 1. 下载 ZIP
+            const zipPath = path.join(work, "pkg.zip");
+            const res = await this.fetchImpl(url);
+            if (!res.ok) {
+                return { success: false, message: `下载失败: HTTP ${res.status}` };
+            }
+            const buf = Buffer.from(await res.arrayBuffer());
+            await fs.writeFile(zipPath, buf);
+            // 2. 调用系统解压工具 unzip
+            const staging = path.join(work, "staging");
+            await this.unzip(zipPath, staging);
+            // 3. 递归寻找真正的技能根目录（包含 SKILL.md 的一层）
+            const srcRoot = await this.locateSkillRoot(staging, 0);
+            if (!srcRoot) {
+                return { success: false, message: `下载包内未找到 SKILL.md，非法的技能包结构` };
+            }
+            // [兼容处理] 缺少 .meta.json 时主动补齐
+            const metaPath = path.join(srcRoot, ".meta.json");
+            if (!(await this.exists(metaPath))) {
+                let parsedVersion = version || "unknown";
+                if (!version) {
+                    try {
+                        const newSkillMd = await fs.readFile(path.join(srcRoot, "SKILL.md"), "utf-8");
+                        parsedVersion = parseSkillVersion(newSkillMd) || "unknown";
+                    }
+                    catch { }
+                }
+                this.debug(`[skill-logger-plugin] 为手动安装的 ${code}@${parsedVersion} 自动生成 .meta.json`);
+                await fs.writeFile(metaPath, JSON.stringify({
+                    ownerId: 'CMS_COMPAT',
+                    slug: code,
+                    version: parsedVersion,
+                    publishedAt: Date.now()
+                }, null, 2));
+            }
+            // 4. 原子级无缝替换目录 (先暂存，再 rename)
+            await this.replaceDir(srcRoot, targetSkillPath);
+            return { success: true, message: `技能 ${code} 安装/更新成功` };
+        }
+        catch (err) {
+            return { success: false, message: `执行出错: ${err.message}` };
+        }
+        finally {
+            // 清理临时工作区
+            await fs.rm(work, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/dist/updater.test.js

@@ -0,0 +1,212 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { createHash } from "node:crypto";
+import { SkillUpdater } from "./updater.ts";
+/** 与 updater/服务端一致的身份哈希：code code version（空格分隔）。 */
+const idHash = (code, version) => createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
+let dir;
+beforeEach(async () => {
+    dir = path.join(os.tmpdir(), `slp-updater-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await fs.mkdir(dir, { recursive: true });
+});
+afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+});
+/** 注入的假 fetch：POST 取下载地址返回 {url}，GET 下载返回固定 zip 字节。 */
+function makeFetch(opts = {}) {
+    const calls = opts.calls ?? [];
+    return async (url, init) => {
+        calls.push(url);
+        if (init?.method === "POST") {
+            return {
+                ok: opts.urlOk !== false,
+                status: opts.urlOk !== false ? 200 : 500,
+                json: async () => ({ url: "https://pkg.example/skill.zip" }),
+                arrayBuffer: async () => new ArrayBuffer(0),
+            };
+        }
+        // GET 下载
+        return {
+            ok: opts.downloadOk !== false,
+            status: opts.downloadOk !== false ? 200 : 500,
+            json: async () => ({}),
+            arrayBuffer: async () => new Uint8Array([1, 2, 3]).buffer,
+        };
+    };
+}
+/** 注入的假 unzip：把「新版本」内容写进 staging（含 SKILL.md），模拟解压结果。 */
+function makeUnzip(newVersion, withSkillMd = true) {
+    return async (_zipPath, destDir) => {
+        const root = path.join(destDir, "skill-root");
+        await fs.mkdir(root, { recursive: true });
+        if (withSkillMd) {
+            await fs.writeFile(path.join(root, "SKILL.md"), `---\nname: demo\nversion: ${newVersion}\n---\nNEW\n`);
+            await fs.writeFile(path.join(root, "new-file.txt"), "added by update");
+        }
+        else {
+            await fs.writeFile(path.join(root, "note.txt"), "no skill md here");
+        }
+    };
+}
+async function makeTarget(name) {
+    const target = path.join(dir, "workspace", "skills", name);
+    await fs.mkdir(target, { recursive: true });
+    await fs.writeFile(path.join(target, "SKILL.md"), "---\nname: demo\nversion: 1.0.0\n---\nOLD\n");
+    await fs.writeFile(path.join(target, "old-file.txt"), "should be gone after update");
+    return target;
+}
+const outdatedFor = (target) => [
+    { skillName: "demo", rootDir: target, localVersion: "1.0.0", latestVersion: "2.0.0" },
+];
+describe("SkillUpdater", () => {
+    it("autoUpdateSkills 显式 false：不发请求、不动文件", async () => {
+        const target = await makeTarget("demo");
+        const calls = [];
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: false };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch({ calls }), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.equal(calls.length, 0);
+        assert.equal((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"), true);
+    });
+    it("autoUpdateSkills 未设置（默认开启）：执行更新", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api" }; // 不设 autoUpdateSkills → 默认开
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch(), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("NEW"), "默认应执行更新");
+    });
+    it("未配置 platformBaseUrl：不更新", async () => {
+        const target = await makeTarget("demo");
+        const cfg = {}; // 无平台地址
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch(), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"));
+    });
+    it("开启后：下载→解压→覆盖目标目录（直接覆盖，旧文件消失，无 .bak）", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch(), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        const skillMd = await fs.readFile(path.join(target, "SKILL.md"), "utf-8");
+        assert.ok(skillMd.includes("NEW"), "SKILL.md 应被更新为新内容");
+        assert.ok(skillMd.includes("version: 2.0.0"), "版本应升级");
+        assert.ok(await fileExists(path.join(target, "new-file.txt")), "新增文件应出现");
+        assert.equal(await fileExists(path.join(target, "old-file.txt")), false, "旧文件应被覆盖移除");
+        // 不留备份
+        const siblings = await fs.readdir(path.join(dir, "workspace", "skills"));
+        assert.ok(!siblings.some((f) => f.includes(".bak")), "不应留下 .bak 备份");
+    });
+    it("一个 skill 装在多个 workspace：仅下载一次，覆盖全部副本", async () => {
+        const t1 = await makeTarget("demo");
+        const t2Dir = path.join(dir, "workspace-coder", "skills", "demo");
+        await fs.mkdir(t2Dir, { recursive: true });
+        await fs.writeFile(path.join(t2Dir, "SKILL.md"), "---\nname: demo\nversion: 1.0.0\n---\nOLD2\n");
+        const calls = [];
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch({ calls }), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates([
+            { skillName: "demo", rootDir: t1, localVersion: "1.0.0", latestVersion: "2.0.0" },
+            { skillName: "demo", rootDir: t2Dir, localVersion: "1.0.0", latestVersion: "2.0.0" },
+        ]);
+        const postCalls = calls.filter((c) => c.endsWith("/skill_package/pull"));
+        assert.equal(postCalls.length, 1, "同 skill@version 只取一次下载地址");
+        assert.ok((await fs.readFile(path.join(t1, "SKILL.md"), "utf-8")).includes("NEW"));
+        assert.ok((await fs.readFile(path.join(t2Dir, "SKILL.md"), "utf-8")).includes("NEW"));
+    });
+    it("下载包 SKILL.md 无版本号：放弃覆盖（服务端要求无版本不更新）", async () => {
+        const target = await makeTarget("demo");
+        // 解压出的 SKILL.md 不含版本号
+        const unzipNoVersion = async (_z, destDir) => {
+            const root = path.join(destDir, "skill-root");
+            await fs.mkdir(root, { recursive: true });
+            await fs.writeFile(path.join(root, "SKILL.md"), "---\nname: demo\n---\nNEW but no version\n");
+        };
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch(), unzip: unzipNoVersion, tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"), "无版本号时应保持原样");
+    });
+    /** 构造一个 POST 返回指定 sha256 的 fetch。 */
+    const makeFetchWithHash = (sha256) => async (url, init) => {
+        if (init?.method === "POST") {
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({ url: "https://pkg.example/skill.zip", sha256 }),
+                arrayBuffer: async () => new ArrayBuffer(0),
+            };
+        }
+        return { ok: true, status: 200, json: async () => ({}), arrayBuffer: async () => new Uint8Array([1]).buffer };
+    };
+    it("身份哈希一致：正常覆盖", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        // 服务端按 demo + 包内版本 2.0.0 计算哈希；包内 SKILL.md 也是 2.0.0 → 一致
+        const u = new SkillUpdater({
+            getConfig: () => cfg,
+            fetchImpl: makeFetchWithHash(idHash("demo", "2.0.0")),
+            unzip: makeUnzip("2.0.0"),
+            tmpDir: dir,
+        });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("NEW"), "哈希一致应覆盖");
+    });
+    it("身份哈希不一致：放弃覆盖", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetchWithHash("deadbeef"), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"), "校验失败应保持原样");
+    });
+    it("包内版本与服务端声称不符（哈希对不上）：放弃覆盖", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        // 服务端按声称的最新版本 2.0.0 算哈希，但下载包实际是 9.9.9 → 包内版本算出的哈希对不上
+        const u = new SkillUpdater({
+            getConfig: () => cfg,
+            fetchImpl: makeFetchWithHash(idHash("demo", "2.0.0")),
+            unzip: makeUnzip("9.9.9"),
+            tmpDir: dir,
+        });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"), "版本错配应放弃覆盖");
+    });
+    it("下载包内无 SKILL.md：放弃覆盖，目标目录保持原样", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch(), unzip: makeUnzip("2.0.0", false), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"), "目标应保持旧内容");
+        assert.ok(await fileExists(path.join(target, "old-file.txt")), "目标旧文件应仍在");
+    });
+    it("冷却：同 skill@version 失败后短期内不重复尝试", async () => {
+        const target = await makeTarget("demo");
+        const calls = [];
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        // 取下载地址一直失败 → 每次尝试都不会成功
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch({ urlOk: false, calls }), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        await u.applyUpdates(outdatedFor(target)); // 第二轮应被冷却拦下
+        const postCalls = calls.filter((c) => c.endsWith("/skill_package/pull"));
+        assert.equal(postCalls.length, 1, "冷却期内不应重复发起下载");
+    });
+    it("取下载地址失败：不动目标目录", async () => {
+        const target = await makeTarget("demo");
+        const cfg = { platformBaseUrl: "https://api", autoUpdateSkills: true };
+        const u = new SkillUpdater({ getConfig: () => cfg, fetchImpl: makeFetch({ urlOk: false }), unzip: makeUnzip("2.0.0"), tmpDir: dir });
+        await u.applyUpdates(outdatedFor(target));
+        assert.ok((await fs.readFile(path.join(target, "SKILL.md"), "utf-8")).includes("OLD"));
+    });
+});
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}