@spzhongwin/skill-logger-plugin 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spzhongwin/skill-logger-plugin",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "type": "module",
   "exports": "./dist/index.js",
   "scripts": {
@@ -31,4 +31,4 @@
     "adm-zip": "^0.6.0",
     "ws": "^8.21.0"
   }
-}
+}

package/src/expert-skill-layout.test.ts

@@ -0,0 +1,196 @@
+import { afterEach, beforeEach, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { repairNestedExpertSkillLayouts } from "./expert-skill-layout.ts";
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), "expert-skill-layout-"));
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+async function writeSkill(dir: string, version: string, marker: string) {
+  await fs.mkdir(path.join(dir, "scripts"), { recursive: true });
+  await fs.writeFile(path.join(dir, "SKILL.md"), `---\nname: demo\nversion: ${version}\n---\n${marker}\n`);
+  await fs.writeFile(path.join(dir, "scripts", `${marker}.txt`), marker);
+}
+
+describe("repairNestedExpertSkillLayouts", () => {
+  it("将同名子目录中的新版提升到专家 Skill 根目录", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(outer, "2.1.1", "old");
+    await writeSkill(path.join(outer, "demo"), "2.1.4", "new");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 2\.1\.4/);
+    assert.equal(await fs.readFile(path.join(outer, "scripts", "new.txt"), "utf8"), "new");
+    await assert.rejects(fs.access(path.join(outer, "demo")), { code: "ENOENT" });
+    await assert.rejects(fs.access(path.join(outer, "scripts", "old.txt")), { code: "ENOENT" });
+  });
+
+  it("外层没有 SKILL.md 时也修复初次安装产生的同名嵌套", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(path.join(outer, "demo"), "1.0.0", "nested");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 1\.0\.0/);
+  });
+
+  it("内层版本低于外层时保留现场，避免错误降级", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(outer, "2.1.4", "new");
+    await writeSkill(path.join(outer, "demo"), "2.1.1", "old");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, []);
+    assert.deepEqual(result.skipped, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 2\.1\.4/);
+    assert.match(await fs.readFile(path.join(outer, "demo", "SKILL.md"), "utf8"), /version: 2\.1\.1/);
+  });
+
+  it("修复后重复运行保持幂等，并忽略不符合用户 workspace 规则的目录", async () => {
+    const validOuter = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    const invalidOuter = path.join(root, "workspace-assistant-test", ".user", "skills", "demo");
+    await writeSkill(validOuter, "1.0.0", "outer");
+    await writeSkill(path.join(validOuter, "demo"), "1.0.0", "nested");
+    await writeSkill(path.join(invalidOuter, "demo"), "1.0.0", "invalid");
+
+    const first = await repairNestedExpertSkillLayouts(root);
+    const second = await repairNestedExpertSkillLayouts(root);
+
+    assert.equal(first.repaired.length, 1);
+    assert.equal(second.repaired.length, 0);
+    assert.equal(second.errors.length, 0);
+    assert.equal(await fs.readFile(path.join(invalidOuter, "demo", "SKILL.md"), "utf8"), "---\nname: demo\nversion: 1.0.0\n---\ninvalid\n");
+  });
+
+  it("多层历史异常一次提升到最高版本，不按扫描周期继续拼接或逐层修复", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(outer, "2.1.1", "v211");
+    await writeSkill(path.join(outer, "demo"), "2.1.4", "v214");
+    await writeSkill(path.join(outer, "demo", "demo"), "2.1.5", "v215");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 2\.1\.5/);
+    await assert.rejects(fs.access(path.join(outer, "demo")), { code: "ENOENT" });
+    assert.equal((await repairNestedExpertSkillLayouts(root)).repaired.length, 0);
+  });
+
+  it("非单调同名链按全链最高版本修复", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(outer, "2.1.1", "v211");
+    await writeSkill(path.join(outer, "demo"), "2.1.5", "v215");
+    await writeSkill(path.join(outer, "demo", "demo"), "2.1.4", "v214");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 2\.1\.5/);
+    await assert.rejects(fs.access(path.join(outer, "demo")), { code: "ENOENT" });
+  });
+
+  it("外层版本无法判断时保留现场", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await fs.mkdir(outer, { recursive: true });
+    await fs.writeFile(path.join(outer, "SKILL.md"), "---\nname: demo\n---\nno version\n");
+    await writeSkill(path.join(outer, "demo"), "2.1.4", "new");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, []);
+    assert.deepEqual(result.skipped, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "demo", "SKILL.md"), "utf8"), /version: 2\.1\.4/);
+  });
+
+  it("非数值版本不按字典序臆测新旧，避免自动降级", async () => {
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    await writeSkill(outer, "2.10.0", "new");
+    await writeSkill(path.join(outer, "demo"), "2.9.x", "old");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, []);
+    assert.deepEqual(result.skipped, [outer]);
+    assert.match(await fs.readFile(path.join(outer, "SKILL.md"), "utf8"), /version: 2\.10\.0/);
+    assert.match(await fs.readFile(path.join(outer, "demo", "SKILL.md"), "utf8"), /version: 2\.9\.x/);
+  });
+
+  it("被提升内容中的同名普通文件会保留，且不会泄漏 repair-new 残留", async () => {
+    const skillsRoot = path.join(root, "workspace-assistant-12345", ".user", "skills");
+    const outer = path.join(skillsRoot, "demo");
+    const nested = path.join(outer, "demo");
+    await writeSkill(outer, "2.1.1", "old");
+    await writeSkill(nested, "2.1.4", "new");
+    await fs.writeFile(path.join(nested, "demo"), "合法的同名数据文件");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, [outer]);
+    assert.equal(await fs.readFile(path.join(outer, "demo"), "utf8"), "合法的同名数据文件");
+    assert.deepEqual((await fs.readdir(skillsRoot)).filter((name) => name.includes("repair-new")), []);
+    assert.equal((await repairNestedExpertSkillLayouts(root)).repaired.length, 0);
+  });
+
+  it("拒绝跟随同名符号链接，且不修改链接目标", async (t) => {
+    if (process.platform === "win32") return t.skip("Windows 创建目录符号链接需要额外权限");
+    const outer = path.join(root, "workspace-assistant-12345", ".user", "skills", "demo");
+    const external = path.join(root, "external-demo");
+    await writeSkill(outer, "2.1.1", "old");
+    await writeSkill(external, "9.9.9", "external");
+    await fs.symlink(external, path.join(outer, "demo"), "dir");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.deepEqual(result.repaired, []);
+    assert.equal(result.errors.length, 1);
+    assert.match(result.errors[0].message, /符号链接/);
+    assert.equal(await fs.readFile(path.join(external, "scripts", "external.txt"), "utf8"), "external");
+    assert.equal((await fs.lstat(path.join(outer, "demo"))).isSymbolicLink(), true);
+  });
+
+  it("规范目录在换入前崩溃时从 repair-old 残留恢复", async () => {
+    const skillsRoot = path.join(root, "workspace-assistant-12345", ".user", "skills");
+    const old = path.join(skillsRoot, ".demo.repair-old-100-old");
+    const stage = path.join(skillsRoot, ".demo.repair-new-100-new");
+    await writeSkill(old, "2.1.1", "old");
+    await writeSkill(stage, "2.1.4", "stage");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+    const target = path.join(skillsRoot, "demo");
+
+    assert.equal(result.errors.length, 0);
+    assert.match(await fs.readFile(path.join(target, "SKILL.md"), "utf8"), /version: 2\.1\.1/);
+    await assert.rejects(fs.access(old), { code: "ENOENT" });
+    await assert.rejects(fs.access(stage), { code: "ENOENT" });
+  });
+
+  it("规范目录已存在时清理 repair-old 和 repair-new 残留", async () => {
+    const skillsRoot = path.join(root, "workspace-assistant-12345", ".user", "skills");
+    const target = path.join(skillsRoot, "demo");
+    const old = path.join(skillsRoot, ".demo.repair-old-100-old");
+    const stage = path.join(skillsRoot, ".demo.repair-new-100-new");
+    await writeSkill(target, "2.1.5", "current");
+    await writeSkill(old, "2.1.1", "old");
+    await writeSkill(stage, "2.1.4", "stage");
+
+    const result = await repairNestedExpertSkillLayouts(root);
+
+    assert.equal(result.errors.length, 0);
+    assert.match(await fs.readFile(path.join(target, "SKILL.md"), "utf8"), /version: 2\.1\.5/);
+    await assert.rejects(fs.access(old), { code: "ENOENT" });
+    await assert.rejects(fs.access(stage), { code: "ENOENT" });
+  });
+});

package/src/expert-skill-layout.ts

@@ -0,0 +1,233 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { Dirent } from "node:fs";
+import { compareVersions, isComparableVersion } from "./semver.ts";
+import { readSkillVersion } from "./skill-version.ts";
+
+const ASSISTANT_WORKSPACE_RE = /^workspace-assistant-\d{5,}$/;
+const REPAIR_RESIDUE_RE = /^\.(.+)\.repair-(old|new)-(.+)$/;
+
+export type ExpertSkillLayoutRepairResult = {
+  scannedWorkspaces: number;
+  repaired: string[];
+  skipped: string[];
+  errors: Array<{ path: string; message: string }>;
+};
+
+async function lstatOrUndefined(filePath: string) {
+  try {
+    return await fs.lstat(filePath);
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+async function isRegularFile(filePath: string): Promise<boolean> {
+  const stat = await lstatOrUndefined(filePath);
+  return Boolean(stat?.isFile() && !stat.isSymbolicLink());
+}
+
+async function removeRealDirectory(dirPath: string): Promise<void> {
+  const stat = await lstatOrUndefined(dirPath);
+  if (!stat) return;
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`拒绝清理非真实目录: ${dirPath}`);
+  }
+  await fs.rm(dirPath, { recursive: true });
+}
+
+async function removeNestedDirectoryIfPresent(dirPath: string): Promise<void> {
+  const stat = await lstatOrUndefined(dirPath);
+  if (!stat) return;
+  if (stat.isSymbolicLink()) throw new Error(`拒绝清理符号链接: ${dirPath}`);
+  if (stat.isDirectory()) await fs.rm(dirPath, { recursive: true });
+}
+
+async function recoverRepairResidues(
+  skillsRoot: string,
+  entries: Dirent<string>[],
+  result: ExpertSkillLayoutRepairResult
+): Promise<void> {
+  const groups = new Map<string, { old: string[]; stage: string[] }>();
+  for (const entry of entries) {
+    const match = REPAIR_RESIDUE_RE.exec(entry.name);
+    if (!match) continue;
+    const group = groups.get(match[1]) ?? { old: [], stage: [] };
+    group[match[2] === "old" ? "old" : "stage"].push(path.join(skillsRoot, entry.name));
+    groups.set(match[1], group);
+  }
+
+  for (const [code, group] of groups) {
+    const targetDir = path.join(skillsRoot, code);
+    try {
+      const targetStat = await lstatOrUndefined(targetDir);
+      if (targetStat?.isSymbolicLink() || (targetStat && !targetStat.isDirectory())) {
+        throw new Error(`规范路径不是可安全操作的真实目录: ${targetDir}`);
+      }
+
+      group.old.sort().reverse();
+      if (!targetStat && group.old.length > 0) {
+        const restore = group.old.shift()!;
+        const restoreStat = await lstatOrUndefined(restore);
+        if (!restoreStat?.isDirectory() || restoreStat.isSymbolicLink()) {
+          throw new Error(`拒绝从非真实目录恢复: ${restore}`);
+        }
+        await fs.rename(restore, targetDir);
+      }
+
+      if (await lstatOrUndefined(targetDir)) {
+        for (const residue of [...group.old, ...group.stage]) {
+          await removeRealDirectory(residue);
+        }
+      }
+    } catch (error: any) {
+      result.errors.push({ path: targetDir, message: error?.message || String(error) });
+    }
+  }
+}
+
+async function promoteNestedSkill(sourceDir: string, targetDir: string): Promise<void> {
+  const parent = path.dirname(targetDir);
+  const tag = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const stage = path.join(parent, `.${path.basename(targetDir)}.repair-new-${tag}`);
+  const old = path.join(parent, `.${path.basename(targetDir)}.repair-old-${tag}`);
+
+  let movedOld = false;
+  try {
+    await fs.cp(sourceDir, stage, { recursive: true });
+    // 同名子项为目录时是历史嵌套，应删除；普通文件属于 Skill 内容，必须保留。
+    await removeNestedDirectoryIfPresent(path.join(stage, path.basename(targetDir)));
+    await fs.rename(targetDir, old);
+    movedOld = true;
+    await fs.rename(stage, targetDir);
+  } catch (error: any) {
+    const rollbackErrors: string[] = [];
+    try {
+      await removeRealDirectory(stage);
+    } catch (cleanupError: any) {
+      rollbackErrors.push(`清理暂存目录失败: ${cleanupError?.message || String(cleanupError)}`);
+    }
+    if (movedOld) {
+      try {
+        await fs.rename(old, targetDir);
+      } catch (restoreError: any) {
+        rollbackErrors.push(`恢复旧目录失败: ${restoreError?.message || String(restoreError)}`);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new Error(`${error?.message || String(error)}; ${rollbackErrors.join("; ")}`);
+    }
+    throw error;
+  }
+  await removeRealDirectory(old);
+}
+
+/**
+ * 修复历史 UPDATE_SKILL 将新版写入 `.user/skills/<code>/<code>` 的异常布局。
+ * 完整扫描同名目录链并提升全局最高版本；符号链接和版本不明的现场一律保守跳过。
+ */
+export async function repairNestedExpertSkillLayouts(
+  openclawRoot: string
+): Promise<ExpertSkillLayoutRepairResult> {
+  const result: ExpertSkillLayoutRepairResult = {
+    scannedWorkspaces: 0,
+    repaired: [],
+    skipped: [],
+    errors: [],
+  };
+
+  let workspaceEntries;
+  try {
+    workspaceEntries = await fs.readdir(openclawRoot, { withFileTypes: true });
+  } catch (error: any) {
+    result.errors.push({ path: openclawRoot, message: error?.message || String(error) });
+    return result;
+  }
+
+  for (const workspaceEntry of workspaceEntries) {
+    if (!workspaceEntry.isDirectory() || !ASSISTANT_WORKSPACE_RE.test(workspaceEntry.name)) continue;
+    result.scannedWorkspaces += 1;
+    const skillsRoot = path.join(openclawRoot, workspaceEntry.name, ".user", "skills");
+    let skillEntries;
+    try {
+      skillEntries = await fs.readdir(skillsRoot, { withFileTypes: true });
+      await recoverRepairResidues(skillsRoot, skillEntries, result);
+      skillEntries = await fs.readdir(skillsRoot, { withFileTypes: true });
+    } catch (error: any) {
+      if (error?.code !== "ENOENT") {
+        result.errors.push({ path: skillsRoot, message: error?.message || String(error) });
+      }
+      continue;
+    }
+
+    for (const skillEntry of skillEntries) {
+      if (!skillEntry.isDirectory() || skillEntry.name.startsWith(".")) continue;
+      const outerDir = path.join(skillsRoot, skillEntry.name);
+
+      try {
+        const candidates: Array<{ dir: string; version: string }> = [];
+        const outerHasSkill = await isRegularFile(path.join(outerDir, "SKILL.md"));
+        if (outerHasSkill) {
+          const version = await readSkillVersion(outerDir);
+          if (!version) {
+            result.skipped.push(outerDir);
+            continue;
+          }
+          candidates.push({ dir: outerDir, version });
+        }
+
+        let cursor = outerDir;
+        let nestedCount = 0;
+        while (true) {
+          const nestedDir = path.join(cursor, skillEntry.name);
+          const nestedStat = await lstatOrUndefined(nestedDir);
+          if (!nestedStat) break;
+          if (nestedStat.isSymbolicLink()) {
+            throw new Error(`拒绝跟随同名符号链接: ${nestedDir}`);
+          }
+          if (!nestedStat.isDirectory()) break;
+          cursor = nestedDir;
+
+          const skillMd = path.join(nestedDir, "SKILL.md");
+          const skillStat = await lstatOrUndefined(skillMd);
+          if (skillStat?.isSymbolicLink()) {
+            throw new Error(`拒绝读取符号链接 SKILL.md: ${skillMd}`);
+          }
+          if (!skillStat?.isFile()) continue;
+          nestedCount += 1;
+          const version = await readSkillVersion(nestedDir);
+          if (!version) {
+            result.skipped.push(outerDir);
+            candidates.length = 0;
+            break;
+          }
+          candidates.push({ dir: nestedDir, version });
+        }
+
+        if (nestedCount === 0 || candidates.length === 0) continue;
+        if (candidates.some((candidate) => !isComparableVersion(candidate.version))) {
+          result.skipped.push(outerDir);
+          continue;
+        }
+        let source = candidates[0];
+        for (const candidate of candidates.slice(1)) {
+          // 同版本也选择更深层，确保把异常同名子目录收敛掉。
+          if (compareVersions(candidate.version, source.version) >= 0) source = candidate;
+        }
+        if (source.dir === outerDir) {
+          result.skipped.push(outerDir);
+          continue;
+        }
+
+        await promoteNestedSkill(source.dir, outerDir);
+        result.repaired.push(outerDir);
+      } catch (error: any) {
+        result.errors.push({ path: outerDir, message: error?.message || String(error) });
+      }
+    }
+  }
+
+  return result;
+}

package/src/index.ts

@@ -15,11 +15,12 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
 import type { PluginConfig } from "./types.ts";
-import { resolvePaths } from "./paths.ts";
+import { openclawHome, resolvePaths } from "./paths.ts";
 import { ActiveSkills } from "./active-skills.ts";
 import { SkillUpdater } from "./updater.ts";
 import { ConfigSync } from "./config-sync.ts";
 import { Reporter } from "./reporter.ts";
+import { repairNestedExpertSkillLayouts } from "./expert-skill-layout.ts";
 
 // 启动长连接中枢
 import { GatewayWsClient } from "./ws-client.ts";
@@ -87,6 +88,26 @@ const definition = {
     const reporter = new Reporter({ paths, getConfig });
     const hooks = new Hooks(reporter, configSync, activeSkills, getConfig);
 
+    let expertSkillLayoutRepair: Promise<void> | undefined;
+    const repairExpertSkillLayouts = () => {
+      if (expertSkillLayoutRepair) return expertSkillLayoutRepair;
+      expertSkillLayoutRepair = (async () => {
+        const result = await repairNestedExpertSkillLayouts(openclawHome());
+        if (result.repaired.length > 0) {
+          console.log(`[skill-logger-plugin] 已修复 ${result.repaired.length} 个专家 Skill 嵌套目录`);
+        }
+        for (const skippedPath of result.skipped) {
+          console.warn(`[skill-logger-plugin] 专家 Skill 嵌套目录版本无法安全提升，已保留现场: ${skippedPath}`);
+        }
+        for (const error of result.errors) {
+          console.warn(`[skill-logger-plugin] 修复专家 Skill 目录失败: ${error.path}`, error.message);
+        }
+      })().finally(() => {
+        expertSkillLayoutRepair = undefined;
+      });
+      return expertSkillLayoutRepair;
+    };
+
     let reconcileTimer: ReturnType<typeof setInterval> | undefined;
     const sessionUpdatedSkills = new Set<string>();
 
@@ -152,13 +173,13 @@ const definition = {
           updater: updater,
           enableFileLog: currentConfig.enableFileLog // 将日志开关透传给客户端模块
         });
-        wsClient.connect();
       }
       // =========================================================
 
-      // 启动即跑一次：先 load 缓存 → 本地对账（扫描+匹配配置）
-      void configSync
-        .load()
+      // 连接中控前先修复存量异常，避免服务端上线重投与目录迁移并发写入同一路径。
+      void repairExpertSkillLayouts()
+        .then(() => wsClient?.connect())
+        .then(() => configSync.load())
         .then(() => configSync.reconcile())
         .catch((err) => console.warn("[skill-logger-plugin] 启动初始化异常", err));
       reporter.startTimer();

package/src/semver.test.ts

@@ -1,6 +1,16 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { compareVersions, isOutdated } from "./semver.ts";
+import { compareVersions, isComparableVersion, isOutdated } from "./semver.ts";
+
+describe("isComparableVersion", () => {
+  it("仅接受可安全进行数值排序的版本", () => {
+    assert.equal(isComparableVersion("2.10.0"), true);
+    assert.equal(isComparableVersion("v2.10"), true);
+    assert.equal(isComparableVersion("2.10.0-beta"), true);
+    assert.equal(isComparableVersion("2.9.x"), false);
+    assert.equal(isComparableVersion("2.1.4 修订版"), false);
+  });
+});
 
 describe("compareVersions", () => {
   it("数值逐段比较：1.10 > 1.9", () => assert.equal(compareVersions("1.10.0", "1.9.0"), 1));

package/src/semver.ts

@@ -21,6 +21,11 @@ function parseCore(v: string): number[] | null {
   return nums.length > 0 ? nums : null;
 }
 
+/** 是否可按数值版本段安全排序；自动目录迁移不能对其他字符串臆测新旧。 */
+export function isComparableVersion(v: string): boolean {
+  return parseCore(v) !== null;
+}
+
 /**
  * 比较 a 与 b：a<b 返回 -1，a>b 返回 1，相等返回 0。
  * 两侧都能解析为点分数字时按数值逐段比较；否则退化为字符串比较。

package/src/updater.test.ts

@@ -72,6 +72,72 @@ const outdatedFor = (target: string): OutdatedCopy[] => [
 ];
 
 describe("SkillUpdater", () => {
+  it("手动安装拒绝路径穿越 code，且不下载、不创建越界目录", async () => {
+    const calls: string[] = [];
+    const skillsRoot = path.join(dir, "workspace", "skills");
+    const updater = new SkillUpdater({
+      getConfig: () => ({ platformBaseUrl: "https://api" }),
+      fetchImpl: makeFetch({ calls }),
+      unzip: makeUnzip("1.0.0"),
+      tmpDir: dir,
+    });
+
+    const result = await updater.manualInstall({
+      code: "../outside",
+      url: "https://pkg.example/skill.zip",
+      force: true,
+      targetDir: skillsRoot,
+    });
+
+    assert.equal(result.success, false);
+    assert.match(result.message, /非法的 Skill code/);
+    assert.deepEqual(calls, []);
+    assert.equal(await fileExists(path.join(dir, "workspace", "outside")), false);
+  });
+
+  it("专家安装会剥离 ZIP 顶层目录，并校验专家根文件契约", async () => {
+    const expertTarget = path.join(dir, "workspace-assistant-12345", ".user", "experts", "demo");
+    const updater = new SkillUpdater({
+      getConfig: () => ({ platformBaseUrl: "https://api" }),
+      fetchImpl: makeFetch(),
+      unzip: async (_zipPath, destDir) => {
+        const root = path.join(destDir, "demo-expert");
+        await fs.mkdir(root, { recursive: true });
+        await fs.writeFile(path.join(root, "AGENTS.md"), "agents");
+        await fs.writeFile(path.join(root, "SOUL.md"), "soul");
+      },
+      tmpDir: dir,
+    });
+
+    const result = await updater.installExpertZipFromUrl("https://pkg.example/expert.zip", expertTarget);
+
+    assert.equal(result.success, true);
+    assert.equal(await fs.readFile(path.join(expertTarget, "AGENTS.md"), "utf8"), "agents");
+    assert.equal(await fs.readFile(path.join(expertTarget, "SOUL.md"), "utf8"), "soul");
+    assert.equal(await fileExists(path.join(expertTarget, "demo-expert")), false);
+  });
+
+  it("专家安装拒绝缺少根文件的 ZIP，不覆盖旧专家", async () => {
+    const expertTarget = path.join(dir, "workspace-assistant-12345", ".user", "experts", "demo");
+    await fs.mkdir(expertTarget, { recursive: true });
+    await fs.writeFile(path.join(expertTarget, "AGENTS.md"), "old");
+    const updater = new SkillUpdater({
+      getConfig: () => ({ platformBaseUrl: "https://api" }),
+      fetchImpl: makeFetch(),
+      unzip: async (_zipPath, destDir) => {
+        await fs.mkdir(path.join(destDir, "bad-expert"), { recursive: true });
+        await fs.writeFile(path.join(destDir, "bad-expert", "AGENTS.md"), "new");
+      },
+      tmpDir: dir,
+    });
+
+    const result = await updater.installExpertZipFromUrl("https://pkg.example/expert.zip", expertTarget);
+
+    assert.equal(result.success, false);
+    assert.match(result.message, /AGENTS\.md 和 SOUL\.md/);
+    assert.equal(await fs.readFile(path.join(expertTarget, "AGENTS.md"), "utf8"), "old");
+  });
+
   it("手动更新可复用同一次下载，同时覆盖用户与内置模板目录并记录关键阶段", async () => {
     const calls: string[] = [];
     const traces: Array<{ stage: string; data?: Record<string, unknown> }> = [];
@@ -125,6 +191,57 @@ describe("SkillUpdater", () => {
     );
   });
 
+  it("专家 Skill 连续更新始终覆盖单层目录，不会继续拼接 code", async () => {
+    const normalSkillsDir = path.join(dir, "workspace-assistant-12345", "skills");
+    const expertSkillsRoot = path.join(dir, "workspace-assistant-12345", ".user", "skills");
+    const expertSkillDir = path.join(expertSkillsRoot, "demo");
+    await fs.mkdir(expertSkillDir, { recursive: true });
+    await fs.writeFile(path.join(expertSkillDir, "SKILL.md"), "---\nname: demo\nversion: 2.1.1\n---\nOLD\n");
+
+    for (const version of ["2.1.4", "2.1.5"]) {
+      const updater = new SkillUpdater({
+        getConfig: () => ({ platformBaseUrl: "https://api" }),
+        fetchImpl: makeFetch(),
+        unzip: makeUnzip(version),
+        tmpDir: dir,
+      });
+      const result = await updater.manualInstall({
+        code: "demo",
+        url: `https://pkg.example/demo-${version}.zip`,
+        version,
+        force: true,
+        targetDir: normalSkillsDir,
+        additionalTargetDirs: [expertSkillsRoot],
+      });
+      assert.equal(result.success, true);
+    }
+
+    assert.match(await fs.readFile(path.join(expertSkillDir, "SKILL.md"), "utf8"), /version: 2\.1\.5/);
+    await assert.rejects(fs.access(path.join(expertSkillDir, "demo")), { code: "ENOENT" });
+  });
+
+  it("专家依赖首次安装会剥离 ZIP 自带的顶层目录", async () => {
+    const expertSkillsRoot = path.join(dir, "workspace-assistant-12345", ".user", "skills");
+    const updater = new SkillUpdater({
+      getConfig: () => ({ platformBaseUrl: "https://api" }),
+      fetchImpl: makeFetch(),
+      unzip: makeUnzip("1.0.0"),
+      tmpDir: dir,
+    });
+
+    const result = await updater.manualInstall({
+      code: "demo",
+      url: "https://pkg.example/demo-1.0.0.zip",
+      version: "1.0.0",
+      force: true,
+      targetDir: expertSkillsRoot,
+    });
+
+    assert.equal(result.success, true);
+    assert.match(await fs.readFile(path.join(expertSkillsRoot, "demo", "SKILL.md"), "utf8"), /version: 1\.0\.0/);
+    await assert.rejects(fs.access(path.join(expertSkillsRoot, "demo", "skill-root")), { code: "ENOENT" });
+  });
+
   it("普通手动安装未传附加目录时只覆盖用户目录", async () => {
     const userSkillsDir = path.join(dir, "workspace-assistant-12345", "skills");
     const templateSkillsDir = path.join(dir, "workspace-xgjk-assistant-template", "skills");