@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/src/updater.test.ts

@@ -1,237 +1,325 @@
-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, type OutdatedCopy } from "./updater.ts";
-import type { PluginConfig } from "./types.ts";
-
-/** 与 updater/服务端一致的身份哈希：code code version（空格分隔）。 */
-const idHash = (code: string, version: string) =>
-  createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
-
-let dir: string;
-
-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: { urlOk?: boolean; downloadOk?: boolean; calls?: string[] } = {}) {
-  const calls = opts.calls ?? [];
-  return async (url: string, init?: RequestInit) => {
-    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: string, withSkillMd = true) {
-  return async (_zipPath: string, destDir: string) => {
-    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: string): Promise<string> {
-  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: string): OutdatedCopy[] => [
-  { 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: string[] = [];
-    const cfg: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = {}; // 无平台地址
-    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: PluginConfig = { 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: string[] = [];
-    const cfg: PluginConfig = { 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: string, destDir: string) => {
-      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: PluginConfig = { 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: string) => async (url: string, init?: RequestInit) => {
-    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: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = { 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: string[] = [];
-    const cfg: PluginConfig = { 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: PluginConfig = { 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: string): Promise<boolean> {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
+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 { extractorCommandForPlatform, SkillUpdater, type OutdatedCopy } from "./updater.ts";
+import type { PluginConfig } from "./types.ts";
+
+/** 与 updater/服务端一致的身份哈希：code code version（空格分隔）。 */
+const idHash = (code: string, version: string) =>
+  createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
+
+let dir: string;
+
+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: { urlOk?: boolean; downloadOk?: boolean; calls?: string[] } = {}) {
+  const calls = opts.calls ?? [];
+  return async (url: string, init?: RequestInit) => {
+    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: string, withSkillMd = true) {
+  return async (_zipPath: string, destDir: string) => {
+    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: string): Promise<string> {
+  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: string): OutdatedCopy[] => [
+  { skillName: "demo", rootDir: target, localVersion: "1.0.0", latestVersion: "2.0.0" },
+];
+
+describe("SkillUpdater", () => {
+  it("macOS 使用 ditto 解压，其他平台保持 unzip", () => {
+    assert.deepEqual(extractorCommandForPlatform("darwin", "/tmp/a.zip", "/tmp/out"), {
+      command: "ditto",
+      args: ["-x", "-k", "/tmp/a.zip", "/tmp/out"],
+    });
+    assert.deepEqual(extractorCommandForPlatform("linux", "/tmp/a.zip", "/tmp/out"), {
+      command: "unzip",
+      args: ["-o", "-q", "/tmp/a.zip", "-d", "/tmp/out"],
+    });
+  });
+
+  it("手动更新可复用同一次下载，同时覆盖用户与内置模板目录并记录关键阶段", async () => {
+    const calls: string[] = [];
+    const traces: Array<{ stage: string; data?: Record<string, unknown> }> = [];
+    const userSkillsDir = path.join(dir, "workspace-assistant-12345", "skills");
+    const templateSkillsDir = path.join(dir, "workspace-xgjk-assistant-template", "skills");
+    const cfg: PluginConfig = { platformBaseUrl: "https://api" };
+    const u = new SkillUpdater({
+      getConfig: () => cfg,
+      fetchImpl: makeFetch({ calls }),
+      unzip: makeUnzip("2.0.0"),
+      tmpDir: dir,
+    });
+
+    const result = await u.manualInstall({
+      code: "demo",
+      url: "https://pkg.example/skill.zip?secret=hidden",
+      version: "2.0.0",
+      force: true,
+      targetDir: userSkillsDir,
+      additionalTargetDirs: [templateSkillsDir],
+      trace: (stage, data) => traces.push({ stage, data }),
+    });
+
+    assert.equal(result.success, true);
+    assert.equal(calls.length, 1, "用户目录与模板目录应复用同一次下载");
+    assert.ok((await fs.readFile(path.join(userSkillsDir, "demo", "SKILL.md"), "utf-8")).includes("NEW"));
+    assert.ok((await fs.readFile(path.join(templateSkillsDir, "demo", "SKILL.md"), "utf-8")).includes("NEW"));
+    assert.deepEqual(
+      traces.map((item) => item.stage),
+      [
+        "install.start",
+        "download.request.start",
+        "download.headers.received",
+        "download.body.completed",
+        "download.file.written",
+        "unzip.start",
+        "unzip.completed",
+        "skill_root.located",
+        "target.replace.start",
+        "target.replace.completed",
+        "target.replace.start",
+        "target.replace.completed",
+        "install.completed",
+        "cleanup.completed",
+      ],
+    );
+    assert.equal(
+      traces[1]?.data?.url,
+      "https://pkg.example/skill.zip?secret=hidden",
+      "诊断日志应记录实际请求的完整下载 URL",
+    );
+  });
+
+  it("普通手动安装未传附加目录时只覆盖用户目录", async () => {
+    const userSkillsDir = path.join(dir, "workspace-assistant-12345", "skills");
+    const templateSkillsDir = path.join(dir, "workspace-xgjk-assistant-template", "skills");
+    const cfg: PluginConfig = { platformBaseUrl: "https://api" };
+    const u = new SkillUpdater({
+      getConfig: () => cfg,
+      fetchImpl: makeFetch(),
+      unzip: makeUnzip("2.0.0"),
+      tmpDir: dir,
+    });
+
+    const result = await u.manualInstall({
+      code: "demo",
+      url: "https://pkg.example/skill.zip",
+      version: "2.0.0",
+      force: true,
+      targetDir: userSkillsDir,
+    });
+
+    assert.equal(result.success, true);
+    assert.equal(await fileExists(path.join(userSkillsDir, "demo", "SKILL.md")), true);
+    assert.equal(await fileExists(templateSkillsDir), false, "普通安装不应创建或修改内置模板目录");
+  });
+
+  it("autoUpdateSkills 显式 false：不发请求、不动文件", async () => {
+    const target = await makeTarget("demo");
+    const calls: string[] = [];
+    const cfg: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = {}; // 无平台地址
+    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: PluginConfig = { 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: string[] = [];
+    const cfg: PluginConfig = { 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: string, destDir: string) => {
+      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: PluginConfig = { 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: string) => async (url: string, init?: RequestInit) => {
+    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: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = { 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: PluginConfig = { 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: string[] = [];
+    const cfg: PluginConfig = { 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: PluginConfig = { 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: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}