@spzhongwin/skill-logger-plugin 1.0.11 → 1.0.13

package/src/updater.ts

@@ -1,433 +1,549 @@
-/**
- * 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 fsSync from "node:fs";
-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 type { PluginConfig } from "./types.ts";
-import { parseSkillVersion, readSkillVersion } 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: string, version: string): string {
-  return createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
-}
-
-/** 一个落后的安装副本（detectOutdated 的产物）。 */
-export type OutdatedCopy = {
-  skillName: string;
-  rootDir: string;
-  localVersion: string;
-  latestVersion: string;
-};
-
-type DownloadFetch = (
-  url: string,
-  init?: RequestInit
-) => Promise<{ ok: boolean; status: number; json: () => Promise<any>; arrayBuffer: () => Promise<ArrayBuffer> }>;
-
-/** 解压函数：把 zipPath 解到 destDir。可注入便于测试。 */
-export type UnzipFn = (zipPath: string, destDir: string) => Promise<void>;
-
-export type UpdaterOptions = {
-  getConfig: () => PluginConfig;
-  fetchImpl?: DownloadFetch;
-  unzip?: UnzipFn;
-  /** 临时工作根目录，便于测试注入；默认 os.tmpdir()。 */
-  tmpDir?: string;
-  /** 冷却期状态持久化文件路径。 */
-  cooldownStatePath?: string;
-};
-
-/** 默认解压：系统 unzip -o -q（覆盖、静默）。 */
-async function systemUnzip(zipPath: string, destDir: string): Promise<void> {
-  await fs.mkdir(destDir, { recursive: true });
-  await execFileAsync("unzip", ["-o", "-q", zipPath, "-d", destDir]);
-}
-
-export class SkillUpdater {
-  private readonly getConfig: () => PluginConfig;
-  private readonly fetchImpl: DownloadFetch;
-  private readonly unzip: UnzipFn;
-  private readonly tmpDir: string;
-  /** 冷却期状态持久化文件路径。 */
-  private readonly cooldownStatePath?: string;
-  /** skill@version → 上次尝试时间戳，用于冷却，避免重复下载覆盖。 */
-  private readonly lastAttempt = new Map<string, number>();
-
-  constructor(opts: UpdaterOptions) {
-    this.getConfig = opts.getConfig;
-    this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as DownloadFetch);
-    this.unzip = opts.unzip ?? systemUnzip;
-    this.tmpDir = opts.tmpDir ?? os.tmpdir();
-    this.cooldownStatePath = opts.cooldownStatePath;
-    this.loadCooldown(); // 同步读取，启动早期就需要用到冷却期
-  }
-
-  private get isDebug(): boolean {
-    return this.getConfig().debugLogging !== false;
-  }
-
-  private debug(...args: any[]): void {
-    if (this.isDebug) console.log("[skill-logger-plugin/updater]", ...args);
-  }
-
-  /** 从文件同步加载冷却期状态到内存Map。文件不存在或解析失败时静默跳过。 */
-  private loadCooldown(): void {
-    if (!this.cooldownStatePath) return;
-    try {
-      const raw = fsSync.readFileSync(this.cooldownStatePath, "utf-8");
-      const obj = JSON.parse(raw) as Record<string, number>;
-      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，插件继续正常工作
-    }
-  }
-
-  /** 将内存中的冷却期状态写入文件。写入失败时静默跳过，不影响主流程。 */
-  private async persistCooldown(): Promise<void> {
-    if (!this.cooldownStatePath) return;
-    try {
-      const obj: Record<string, number> = {};
-      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: OutdatedCopy[]): Promise<void> {
-    const cfg = this.getConfig();
-    if (cfg.autoUpdateSkills === false) return; // 默认开启，仅显式 false 关闭
-    if (!cfg.platformBaseUrl) return; // 无平台地址无法下载
-    if (outdated.length === 0) return;
-
-    const groups = new Map<string, { skillName: string; version: string; targets: string[] }>();
-    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);
-      }
-    }
-  }
-
-  private async updateOne(skillName: string, version: string, targets: string[]): Promise<void> {
-    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;
-      }
-
-      // 守卫：下载包必须能解析出版本号，否则不做覆盖（服务端要求：无版本号不更新）。
-      let packageVersion: string | undefined;
-      try {
-        packageVersion = await readSkillVersion(srcRoot);
-      } catch (err) {
-        console.warn(`[skill-logger-plugin] ${skillName}@${version} 读取下载包版本号失败，放弃覆盖`, err);
-        return;
-      }
-      if (!packageVersion) {
-        console.warn(`[skill-logger-plugin] ${skillName}@${version} 下载包无版本号，放弃覆盖`);
-        return;
-      }
-      if (dl.sha256) {
-        const actualHash = skillIdentityHash(skillName, packageVersion);
-        if (actualHash !== dl.sha256) {
-          console.warn(`[skill-logger-plugin] ${skillName}@${version} 身份哈希不一致，放弃覆盖`);
-          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: packageVersion,
-          publishedAt: Date.now()
-        }, null, 2));
-      }
-
-      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 表示拿不到（调用方放弃本次更新）。 */
-  private async fetchDownloadUrl(
-    skillName: string,
-    version: string
-  ): Promise<{ url: string; version?: string; sha256?: string } | undefined> {
-    const cfg = this.getConfig();
-    const endpoint = cfg.platformBaseUrl!.replace(/\/$/, "") + "/skill_package/pull";
-    const headers: Record<string, string> = { "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()) as { url?: unknown; downloadUrl?: unknown; version?: unknown; sha256?: unknown };
-    const url = typeof data?.url === "string" ? data.url : typeof data?.downloadUrl === "string" ? data.downloadUrl : undefined;
-    const resolvedVersion = typeof data?.version === "string" ? data.version : undefined;
-    const sha256 = typeof data?.sha256 === "string" ? data.sha256 : undefined;
-    if (!url) return undefined;
-    return { url, version: resolvedVersion, sha256 };
-  }
-
-  /** 在解压目录里定位含 SKILL.md 的目录（兼容包内是否带顶层目录）。深度上限 2。 */
-  private async locateSkillRoot(dir: string, depth: number): Promise<string | undefined> {
-    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。
-   */
-  private async replaceDir(src: string, target: string): Promise<void> {
-    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(() => {}); // 成功后清理，不留备份
-  }
-
-  private async exists(p: string): Promise<boolean> {
-    try {
-      await fs.access(p);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * 手动下发安装/更新指令 (供沙盒 HTTP Proxy 与星型架构中控使用)
-   */
-  /**
-   * 从 URL 下载 ZIP 并直接解压替换到目标目录（不检查 SKILL.md）
-   */
-  async installZipFromUrl(url: string, targetDir: string): Promise<{success: boolean; message: string}> {
-    const work = path.join(this.tmpDir, `slp-zip-${randomUUID()}`);
-    await fs.mkdir(work, { recursive: true });
-    try {
-      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);
-
-      const staging = path.join(work, "staging");
-      await this.unzip(zipPath, staging);
-
-      await this.replaceDir(staging, targetDir);
-      return { success: true, message: `安装成功` };
-    } catch (err: any) {
-      return { success: false, message: `执行出错: ${err.message}` };
-    } finally {
-      await fs.rm(work, { recursive: true, force: true }).catch(() => {});
-    }
-  }
-
-  async manualInstall(options: {
-    code: string;
-    url?: string;
-    version?: string;
-    force: boolean;
-    targetDir: string;
-  }): Promise<{ success: boolean; message: string }> {
-    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 {
-            parsedVersion = (await readSkillVersion(srcRoot)) || "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: any) {
-      return { success: false, message: `执行出错: ${err.message}` };
-    } finally {
-      // 清理临时工作区
-      await fs.rm(work, { recursive: true, force: true }).catch(()=>{});
-    }
-  }
-}
+/**
+ * skill 版本自动更新器。
+ *
+ * 触发：reconcile 检测到本地某 skill 版本落后于平台最新版本（config.version）后调用。
+ * 流程（每个 skill@version 仅下载一次，覆盖其全部 workspace 副本）：
+ *   1. POST {platformBaseUrl}/skill_package/pull {skillName, version} → { url }
+ *   2. GET url → zip 字节 → 写入临时文件
+ *   3. 解压到临时 staging 目录（macOS 使用 ditto，其他系统使用 unzip）
+ *   4. 在 staging 内定位含 SKILL.md 的目录作为源根（兼容包内带或不带顶层目录）
+ *   5. 逐个目标目录「直接覆盖、不备份」：先复制到同级临时目录，再删旧、原子 rename 换入，
+ *      避免中途失败留下损坏的半成品；不保留 .bak。
+ *
+ * 安全约束：
+ *   - 仅在 autoUpdateSkills===true 且配置了 platformBaseUrl 时执行，默认关闭。
+ *   - 任一步失败只 warn 并跳过该 skill，绝不抛、绝不阻塞 reconcile。
+ *   - 下载包内必须含 SKILL.md 才会覆盖，否则放弃（防止把目标目录清空成坏内容）。
+ */
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFile } from "node:child_process";
+import { randomUUID, createHash } from "node:crypto";
+import type { PluginConfig } from "./types.ts";
+import { parseSkillVersion, readSkillVersion } from "./skill-version.ts";
+
+const EXTRACT_TIMEOUT_MS = 30_000;
+
+/**
+ * 同一 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: string, version: string): string {
+  return createHash("sha256").update(`${code} ${code} ${version}`).digest("hex");
+}
+
+/** 一个落后的安装副本（detectOutdated 的产物）。 */
+export type OutdatedCopy = {
+  skillName: string;
+  rootDir: string;
+  localVersion: string;
+  latestVersion: string;
+};
+
+type DownloadFetch = (
+  url: string,
+  init?: RequestInit
+) => Promise<{
+  ok: boolean;
+  status: number;
+  headers?: { get: (name: string) => string | null };
+  json: () => Promise<any>;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+}>;
+
+export type InstallTrace = (stage: string, data?: Record<string, unknown>) => void;
+
+/** 解压函数：把 zipPath 解到 destDir。可注入便于测试。 */
+export type UnzipFn = (zipPath: string, destDir: string) => Promise<void>;
+
+export type UpdaterOptions = {
+  getConfig: () => PluginConfig;
+  fetchImpl?: DownloadFetch;
+  unzip?: UnzipFn;
+  /** 临时工作根目录，便于测试注入；默认 os.tmpdir()。 */
+  tmpDir?: string;
+  /** 冷却期状态持久化文件路径。 */
+  cooldownStatePath?: string;
+};
+
+export function extractorCommandForPlatform(
+  platform: NodeJS.Platform,
+  zipPath: string,
+  destDir: string,
+): { command: string; args: string[] } {
+  return platform === "darwin"
+    ? { command: "ditto", args: ["-x", "-k", zipPath, destDir] }
+    : { command: "unzip", args: ["-o", "-q", zipPath, "-d", destDir] };
+}
+
+function runExtractor(command: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, {
+      encoding: "utf8",
+      timeout: EXTRACT_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      maxBuffer: 1024 * 1024,
+    }, (error, _stdout, stderr) => {
+      if (!error) {
+        resolve();
+        return;
+      }
+      const detail = String(stderr || "").trim();
+      const timeout = error.killed ? `，超过 ${EXTRACT_TIMEOUT_MS}ms 已终止` : "";
+      reject(new Error(`${command} 解压失败${timeout}: ${detail || error.message}`));
+    });
+    // 防止 unzip 遇到异常包时弹出 Continue? 并永久等待输入。
+    child.stdin?.end();
+  });
+}
+
+/** 默认解压：macOS 的 ditto 正确支持 ZIP 中文文件名；其余平台保持原 unzip 行为。 */
+async function systemUnzip(zipPath: string, destDir: string): Promise<void> {
+  await fs.mkdir(destDir, { recursive: true });
+  const { command, args } = extractorCommandForPlatform(process.platform, zipPath, destDir);
+  await runExtractor(command, args);
+}
+
+export class SkillUpdater {
+  private readonly getConfig: () => PluginConfig;
+  private readonly fetchImpl: DownloadFetch;
+  private readonly unzip: UnzipFn;
+  private readonly tmpDir: string;
+  /** 冷却期状态持久化文件路径。 */
+  private readonly cooldownStatePath?: string;
+  /** skill@version → 上次尝试时间戳，用于冷却，避免重复下载覆盖。 */
+  private readonly lastAttempt = new Map<string, number>();
+
+  constructor(opts: UpdaterOptions) {
+    this.getConfig = opts.getConfig;
+    this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as DownloadFetch);
+    this.unzip = opts.unzip ?? systemUnzip;
+    this.tmpDir = opts.tmpDir ?? os.tmpdir();
+    this.cooldownStatePath = opts.cooldownStatePath;
+    this.loadCooldown(); // 同步读取，启动早期就需要用到冷却期
+  }
+
+  private get isDebug(): boolean {
+    return this.getConfig().debugLogging !== false;
+  }
+
+  private debug(...args: any[]): void {
+    if (this.isDebug) console.log("[skill-logger-plugin/updater]", ...args);
+  }
+
+  /** 从文件同步加载冷却期状态到内存Map。文件不存在或解析失败时静默跳过。 */
+  private loadCooldown(): void {
+    if (!this.cooldownStatePath) return;
+    try {
+      const raw = fsSync.readFileSync(this.cooldownStatePath, "utf-8");
+      const obj = JSON.parse(raw) as Record<string, number>;
+      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，插件继续正常工作
+    }
+  }
+
+  /** 将内存中的冷却期状态写入文件。写入失败时静默跳过，不影响主流程。 */
+  private async persistCooldown(): Promise<void> {
+    if (!this.cooldownStatePath) return;
+    try {
+      const obj: Record<string, number> = {};
+      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: OutdatedCopy[]): Promise<void> {
+    const cfg = this.getConfig();
+    if (cfg.autoUpdateSkills === false) return; // 默认开启，仅显式 false 关闭
+    if (!cfg.platformBaseUrl) return; // 无平台地址无法下载
+    if (outdated.length === 0) return;
+
+    const groups = new Map<string, { skillName: string; version: string; targets: string[] }>();
+    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);
+      }
+    }
+  }
+
+  private async updateOne(skillName: string, version: string, targets: string[]): Promise<void> {
+    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;
+      }
+
+      // 守卫：下载包必须能解析出版本号，否则不做覆盖（服务端要求：无版本号不更新）。
+      let packageVersion: string | undefined;
+      try {
+        packageVersion = await readSkillVersion(srcRoot);
+      } catch (err) {
+        console.warn(`[skill-logger-plugin] ${skillName}@${version} 读取下载包版本号失败，放弃覆盖`, err);
+        return;
+      }
+      if (!packageVersion) {
+        console.warn(`[skill-logger-plugin] ${skillName}@${version} 下载包无版本号，放弃覆盖`);
+        return;
+      }
+      if (dl.sha256) {
+        const actualHash = skillIdentityHash(skillName, packageVersion);
+        if (actualHash !== dl.sha256) {
+          console.warn(`[skill-logger-plugin] ${skillName}@${version} 身份哈希不一致，放弃覆盖`);
+          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: packageVersion,
+          publishedAt: Date.now()
+        }, null, 2));
+      }
+
+      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 表示拿不到（调用方放弃本次更新）。 */
+  private async fetchDownloadUrl(
+    skillName: string,
+    version: string
+  ): Promise<{ url: string; version?: string; sha256?: string } | undefined> {
+    const cfg = this.getConfig();
+    const endpoint = cfg.platformBaseUrl!.replace(/\/$/, "") + "/skill_package/pull";
+    const headers: Record<string, string> = { "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()) as { url?: unknown; downloadUrl?: unknown; version?: unknown; sha256?: unknown };
+    const url = typeof data?.url === "string" ? data.url : typeof data?.downloadUrl === "string" ? data.downloadUrl : undefined;
+    const resolvedVersion = typeof data?.version === "string" ? data.version : undefined;
+    const sha256 = typeof data?.sha256 === "string" ? data.sha256 : undefined;
+    if (!url) return undefined;
+    return { url, version: resolvedVersion, sha256 };
+  }
+
+  /** 在解压目录里定位含 SKILL.md 的目录（兼容包内是否带顶层目录）。深度上限 2。 */
+  private async locateSkillRoot(dir: string, depth: number): Promise<string | undefined> {
+    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。
+   */
+  private async replaceDir(src: string, target: string): Promise<void> {
+    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(() => {}); // 成功后清理，不留备份
+  }
+
+  private async exists(p: string): Promise<boolean> {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 手动下发安装/更新指令 (供沙盒 HTTP Proxy 与星型架构中控使用)
+   */
+  /**
+   * 从 URL 下载 ZIP 并直接解压替换到目标目录（不检查 SKILL.md）
+   */
+  async installZipFromUrl(url: string, targetDir: string): Promise<{success: boolean; message: string}> {
+    const work = path.join(this.tmpDir, `slp-zip-${randomUUID()}`);
+    await fs.mkdir(work, { recursive: true });
+    try {
+      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);
+
+      const staging = path.join(work, "staging");
+      await this.unzip(zipPath, staging);
+
+      await this.replaceDir(staging, targetDir);
+      return { success: true, message: `安装成功` };
+    } catch (err: any) {
+      return { success: false, message: `执行出错: ${err.message}` };
+    } finally {
+      await fs.rm(work, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+
+  async manualInstall(options: {
+    code: string;
+    url?: string;
+    version?: string;
+    force: boolean;
+    targetDir: string;
+    additionalTargetDirs?: string[];
+    trace?: InstallTrace;
+  }): Promise<{ success: boolean; message: string }> {
+    const { code, force, targetDir, additionalTargetDirs = [], trace } = options;
+    let { url, version } = options;
+    const startedAt = Date.now();
+    let currentStage = "install.start";
+    let work: string | undefined;
+    const emit = (stage: string, data?: Record<string, unknown>) => {
+      currentStage = stage;
+      try {
+        trace?.(stage, data);
+      } catch {
+        // 诊断日志本身绝不能影响安装流程
+      }
+    };
+
+    emit("install.start", {
+      code,
+      version: version || "latest",
+      force,
+      hasDirectUrl: Boolean(url),
+      targetCount: 1 + additionalTargetDirs.length,
+    });
+
+    try {
+      if (!url) {
+        // 若没有直接传入 ZIP 的 URL，向平台索取该 skill 的 latest 下载地址
+        const lookupStartedAt = Date.now();
+        emit("download_url.lookup.start", { code, version: version || "latest" });
+        const dl = await this.fetchDownloadUrl(code, version || "latest");
+        if (!dl?.url) {
+          const message = `无法获取技能 ${code} 的下载地址`;
+          emit("install.failed", { stage: currentStage, message, elapsedMs: Date.now() - startedAt });
+          return { success: false, message };
+        }
+        url = dl.url;
+        version = dl.version || version;
+        emit("download_url.lookup.completed", {
+          version: version || "latest",
+          url,
+          elapsedMs: Date.now() - lookupStartedAt,
+        });
+      }
+
+      const targetSkillPath = path.join(targetDir, code);
+
+      // 如果非强制覆盖，且目标已经存在，则直接返回
+      if (!force && await this.exists(targetSkillPath)) {
+        const message = `技能 ${code} 已存在于目标目录`;
+        emit("install.failed", { stage: currentStage, message, elapsedMs: Date.now() - startedAt });
+        return { success: false, message };
+      }
+
+      work = path.join(this.tmpDir, `slp-manual-${randomUUID()}`);
+      await fs.mkdir(work, { recursive: true });
+
+      // 1. 下载 ZIP
+      const zipPath = path.join(work, "pkg.zip");
+      const downloadStartedAt = Date.now();
+      emit("download.request.start", { url });
+      const res = await this.fetchImpl(url);
+      emit("download.headers.received", {
+        status: res.status,
+        contentLength: res.headers?.get("content-length") || undefined,
+        contentType: res.headers?.get("content-type") || undefined,
+        elapsedMs: Date.now() - downloadStartedAt,
+      });
+      if (!res.ok) {
+        const message = `下载失败: HTTP ${res.status}`;
+        emit("install.failed", { stage: currentStage, message, elapsedMs: Date.now() - startedAt });
+        return { success: false, message };
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      emit("download.body.completed", {
+        bytes: buf.byteLength,
+        elapsedMs: Date.now() - downloadStartedAt,
+      });
+      await fs.writeFile(zipPath, buf);
+      emit("download.file.written", { bytes: buf.byteLength });
+
+      // 2. 调用系统解压工具 unzip
+      const staging = path.join(work, "staging");
+      const unzipStartedAt = Date.now();
+      emit("unzip.start", { extractor: process.platform === "darwin" ? "ditto" : "unzip" });
+      await this.unzip(zipPath, staging);
+      emit("unzip.completed", { elapsedMs: Date.now() - unzipStartedAt });
+
+      // 3. 递归寻找真正的技能根目录（包含 SKILL.md 的一层）
+      const srcRoot = await this.locateSkillRoot(staging, 0);
+      if (!srcRoot) {
+        const message = `下载包内未找到 SKILL.md，非法的技能包结构`;
+        emit("install.failed", { stage: currentStage, message, elapsedMs: Date.now() - startedAt });
+        return { success: false, message };
+      }
+      emit("skill_root.located");
+
+      // [兼容处理] 缺少 .meta.json 时主动补齐
+      const metaPath = path.join(srcRoot, ".meta.json");
+      if (!(await this.exists(metaPath))) {
+        let parsedVersion = version || "unknown";
+        if (!version) {
+          try {
+            parsedVersion = (await readSkillVersion(srcRoot)) || "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. 同一份已解压内容依次原子替换用户目录及明确指定的附加目录
+      const targets = [targetDir, ...additionalTargetDirs];
+      for (let index = 0; index < targets.length; index += 1) {
+        const rootDir = targets[index];
+        const targetPath = path.join(rootDir, code);
+        const replaceStartedAt = Date.now();
+        emit("target.replace.start", { targetDir: rootDir, targetIndex: index, targetCount: targets.length });
+        await this.replaceDir(srcRoot, targetPath);
+        emit("target.replace.completed", {
+          targetDir: rootDir,
+          targetIndex: index,
+          targetCount: targets.length,
+          elapsedMs: Date.now() - replaceStartedAt,
+        });
+      }
+
+      emit("install.completed", { elapsedMs: Date.now() - startedAt, targetCount: targets.length });
+      return { success: true, message: `技能 ${code} 安装/更新成功` };
+    } catch (err: any) {
+      emit("install.failed", {
+        stage: currentStage,
+        errorName: err?.name,
+        message: err?.message || String(err),
+        stack: err?.stack,
+        elapsedMs: Date.now() - startedAt,
+      });
+      return { success: false, message: `执行出错: ${err.message}` };
+    } finally {
+      // 清理临时工作区
+      if (work) {
+        await fs.rm(work, { recursive: true, force: true }).catch(()=>{});
+        emit("cleanup.completed", { elapsedMs: Date.now() - startedAt });
+      }
+    }
+  }
+}