@spzhongwin/skill-logger-plugin 1.0.14 → 1.0.16

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/global.d.ts

@@ -0,0 +1,4 @@
+declare module 'node:assert/strict' {
+  import assert from 'node:assert';
+  export default assert;
+}