@netpilot/skills 0.3.2

package/scripts/sync.mjs

@@ -0,0 +1,699 @@
+import { createHash, randomUUID } from "node:crypto";
+import { copyFile, lstat, mkdir, open, readFile, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateCodexAgentDirectory } from "./validate.mjs";
+
+const HOST_DESTINATIONS = {
+  codex: [".agents", "skills"],
+  claude: [".claude", "skills"],
+};
+
+const CODEX_AGENT_DESTINATION = [".codex", "agents"];
+
+const ALL_HOSTS = Object.freeze(Object.keys(HOST_DESTINATIONS));
+const ALL_COMPONENTS = Object.freeze(["skills", "agents"]);
+const SUPPORT_FILE_NAMES = Object.freeze(["LICENSE", "THIRD_PARTY_NOTICES.md"]);
+
+export class SyncConflictError extends Error {
+  constructor(conflicts) {
+    super(`发现 ${conflicts.length} 个未受管理或已被用户修改的冲突文件`);
+    this.name = "SyncConflictError";
+    this.conflicts = conflicts;
+  }
+}
+
+export function parseArgs(argv) {
+  let apply = false;
+  let homeDir = os.homedir();
+  let hosts = [...ALL_HOSTS];
+  let components = ["skills"];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--apply") {
+      apply = true;
+      continue;
+    }
+    if (argument === "--host") {
+      const host = argv[index + 1];
+      if (!host) throw new Error("--host 需要 codex、claude 或 all");
+      index += 1;
+      if (host === "all") {
+        hosts = [...ALL_HOSTS];
+      } else if (host in HOST_DESTINATIONS) {
+        hosts = [host];
+      } else {
+        throw new Error(`不支持的宿主：${host}`);
+      }
+      continue;
+    }
+    if (argument === "--component") {
+      const component = argv[index + 1];
+      if (!component) throw new Error("--component 需要 skills、agents 或 all");
+      index += 1;
+      if (component === "all") {
+        components = [...ALL_COMPONENTS];
+      } else if (ALL_COMPONENTS.includes(component)) {
+        components = [component];
+      } else {
+        throw new Error(`不支持的组件：${component}`);
+      }
+      continue;
+    }
+    if (argument === "--home") {
+      const requestedHome = argv[index + 1];
+      if (!requestedHome || requestedHome.startsWith("-")) {
+        throw new Error("--home 需要一个目录路径");
+      }
+      index += 1;
+      homeDir = path.resolve(requestedHome);
+      continue;
+    }
+    throw new Error(`未知参数：${argument}`);
+  }
+
+  return { apply, homeDir, hosts, components };
+}
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function hashFile(filePath) {
+  return sha256(await readFile(filePath));
+}
+
+async function readManifest(manifestPath) {
+  try {
+    const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    if (
+      manifest.schemaVersion !== 1 ||
+      manifest.managedBy !== "netpilot-skills" ||
+      typeof manifest.files !== "object" ||
+      manifest.files === null ||
+      !Object.values(manifest.files).every(
+        (hash) => typeof hash === "string" && /^[a-f0-9]{64}$/u.test(hash),
+      )
+    ) {
+      throw new Error("manifest schema 不受支持");
+    }
+    return manifest;
+  } catch (error) {
+    if (error.code === "ENOENT") return { schemaVersion: 1, managedBy: "netpilot-skills", files: {} };
+    throw new Error(`无法读取同步 manifest：${manifestPath}\n${error.message}`, { cause: error });
+  }
+}
+
+async function listFiles(directory, prefix = "") {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const absolutePath = path.join(directory, entry.name);
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) {
+      throw new Error(`skill 中不允许符号链接：${absolutePath}`);
+    }
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(absolutePath, relativePath)));
+    } else if (entry.isFile()) {
+      files.push({ absolutePath, relativePath });
+    }
+  }
+
+  return files;
+}
+
+async function discoverSourceFiles(rootDir) {
+  const skillsRoot = path.join(rootDir, "skills");
+  const skillsRootStats = await lstat(skillsRoot);
+  if (!skillsRootStats.isDirectory() || skillsRootStats.isSymbolicLink()) {
+    throw new Error(`skills 根目录必须是普通目录：${skillsRoot}`);
+  }
+  const entries = await readdir(skillsRoot, { withFileTypes: true });
+  const sourceFiles = [];
+
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (entry.isSymbolicLink()) throw new Error(`skill 目录不允许符号链接：${path.join(skillsRoot, entry.name)}`);
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const skillDir = path.join(skillsRoot, entry.name);
+    const files = await listFiles(skillDir);
+    if (!files.some((file) => file.relativePath === "SKILL.md")) {
+      throw new Error(`缺少 SKILL.md：${skillDir}`);
+    }
+    for (const file of files) {
+      sourceFiles.push({ skillName: entry.name, ...file });
+    }
+  }
+
+  if (sourceFiles.length === 0) throw new Error(`没有发现可同步的 skill：${skillsRoot}`);
+  return sourceFiles;
+}
+
+async function discoverCodexAgentFiles(rootDir) {
+  const agentsRoot = path.join(rootDir, "agents", "codex");
+  const agentsRootStats = await lstat(agentsRoot);
+  if (!agentsRootStats.isDirectory() || agentsRootStats.isSymbolicLink()) {
+    throw new Error(`Codex agents 根目录必须是普通目录：${agentsRoot}`);
+  }
+  const entries = await readdir(agentsRoot, { withFileTypes: true });
+  const sourceFiles = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const absolutePath = path.join(agentsRoot, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Codex agent 不允许符号链接：${absolutePath}`);
+    if (!entry.isFile() || !entry.name.endsWith(".toml")) {
+      throw new Error(`Codex agents 目录只允许 .toml 文件：${absolutePath}`);
+    }
+    sourceFiles.push({
+      component: "agents",
+      assetName: entry.name.slice(0, -".toml".length),
+      relativePath: entry.name,
+      absolutePath,
+    });
+  }
+  if (sourceFiles.length === 0) throw new Error(`没有发现可同步的 Codex agent：${agentsRoot}`);
+  return sourceFiles;
+}
+
+async function discoverSupportFiles(rootDir) {
+  const supportFiles = [];
+  for (const relativePath of SUPPORT_FILE_NAMES) {
+    const absolutePath = path.join(rootDir, relativePath);
+    const stats = await lstat(absolutePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+      throw new Error(`同步声明必须是普通文件：${absolutePath}`);
+    }
+    supportFiles.push({ skillName: "notices", relativePath, absolutePath });
+  }
+  return supportFiles;
+}
+
+async function inspectTarget(targetPath) {
+  try {
+    const stats = await lstat(targetPath);
+    if (!stats.isFile()) return { exists: true, regularFile: false, hash: null };
+    return { exists: true, regularFile: true, hash: await hashFile(targetPath) };
+  } catch (error) {
+    if (error.code === "ENOENT") return { exists: false, regularFile: false, hash: null };
+    throw error;
+  }
+}
+
+async function inspectAncestorPath(basePath, targetDirectory) {
+  const relativePath = path.relative(basePath, targetDirectory);
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return { safe: false, path: targetDirectory, reason: "目标目录超出 home 边界" };
+  }
+
+  let currentPath = basePath;
+  for (const segment of relativePath.split(path.sep).filter(Boolean)) {
+    currentPath = path.join(currentPath, segment);
+    try {
+      const stats = await lstat(currentPath);
+      if (stats.isSymbolicLink()) {
+        return { safe: false, path: currentPath, reason: "目标父目录是 symlink 或 junction" };
+      }
+      if (!stats.isDirectory()) {
+        return { safe: false, path: currentPath, reason: "目标父路径不是目录" };
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") return { safe: true };
+      throw error;
+    }
+  }
+
+  return { safe: true };
+}
+
+function manifestKey(host, component, assetName, relativePath) {
+  if (component === "skills") return `${host}/${assetName}/${relativePath}`;
+  if (component === "agents") return `${host}/agents/${assetName}/${relativePath}`;
+  return `${host}/${assetName}/${relativePath}`;
+}
+
+async function planFileOperation({
+  host,
+  component,
+  assetName,
+  skillName = assetName,
+  relativePath,
+  sourcePath,
+  targetPath,
+  manifest,
+  homeDir,
+}) {
+  const key = manifestKey(host, component, assetName, relativePath);
+  const sourceHash = await hashFile(sourcePath);
+  const ancestor = await inspectAncestorPath(homeDir, path.dirname(targetPath));
+  const target = ancestor.safe
+    ? await inspectTarget(targetPath)
+    : { exists: false, regularFile: false, hash: null };
+  const previousHash = manifest.files[key] ?? null;
+  let action;
+  let reason = null;
+
+  if (!ancestor.safe) {
+    action = "conflict";
+    reason = `${ancestor.reason}：${ancestor.path}`;
+  } else if (!target.exists) {
+    action = "create";
+  } else if (!target.regularFile) {
+    action = "conflict";
+    reason = "目标路径不是普通文件";
+  } else if (target.hash === sourceHash && previousHash) {
+    action = "unchanged";
+  } else if (target.hash === sourceHash) {
+    action = "conflict";
+    reason = "同名文件不受本项目管理，即使内容相同也不会自动接管";
+  } else if (previousHash && target.hash === previousHash) {
+    action = "update";
+  } else {
+    action = "conflict";
+    reason = previousHash ? "文件在上次同步后被修改" : "同名文件不受本项目管理";
+  }
+
+  return {
+    host,
+    component,
+    assetName,
+    skillName,
+    relativePath,
+    sourcePath,
+    targetPath,
+    sourceHash,
+    targetHash: target.hash,
+    previousHash,
+    action,
+    reason,
+    manifestKey: key,
+  };
+}
+
+async function collectChangedTargetConflicts(operations, homeDir) {
+  const conflicts = [];
+  for (const operation of operations) {
+    const ancestor = await inspectAncestorPath(homeDir, path.dirname(operation.targetPath));
+    if (!ancestor.safe) {
+      conflicts.push({
+        ...operation,
+        action: "conflict",
+        reason: `${ancestor.reason}：${ancestor.path}`,
+      });
+      continue;
+    }
+
+    const target = await inspectTarget(operation.targetPath);
+    if (operation.action === "create" && target.exists) {
+      conflicts.push({ ...operation, action: "conflict", reason: "目标在预检后被创建" });
+    } else if (
+      operation.action === "update" &&
+      (!target.regularFile || target.hash !== operation.targetHash)
+    ) {
+      conflicts.push({ ...operation, action: "conflict", reason: "目标在预检后发生变化" });
+    } else if (
+      operation.action === "unchanged" &&
+      (!target.regularFile || target.hash !== operation.sourceHash)
+    ) {
+      conflicts.push({ ...operation, action: "conflict", reason: "目标在预检后发生变化" });
+    }
+  }
+  return conflicts;
+}
+
+async function applyOperationsTransactional({ operations, homeDir, manifestPath }) {
+  const stateDir = path.dirname(manifestPath);
+  await mkdir(stateDir, { recursive: true });
+  const stateSafety = await inspectAncestorPath(homeDir, stateDir);
+  if (!stateSafety.safe) {
+    throw new SyncConflictError([
+      {
+        host: "state",
+        skillName: "manifest",
+        relativePath: "manifest.json",
+        targetPath: manifestPath,
+        action: "conflict",
+        reason: `${stateSafety.reason}：${stateSafety.path}`,
+      },
+    ]);
+  }
+
+  const stagingDir = path.join(stateDir, "staging");
+  const stagingSafety = await inspectAncestorPath(homeDir, stagingDir);
+  if (!stagingSafety.safe) {
+    throw new SyncConflictError([
+      {
+        host: "state",
+        skillName: "staging",
+        relativePath: "staging",
+        targetPath: stagingDir,
+        action: "conflict",
+        reason: `${stagingSafety.reason}：${stagingSafety.path}`,
+      },
+    ]);
+  }
+
+  const lockPath = path.join(stateDir, "sync.lock");
+  let lockHandle;
+  try {
+    lockHandle = await open(lockPath, "wx");
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error(`已有同步进程持有锁：${lockPath}`);
+    throw error;
+  }
+  try {
+    await lockHandle.writeFile(`${process.pid}\n`, "utf8");
+  } catch (error) {
+    await lockHandle.close();
+    await rm(lockPath, { force: true });
+    throw error;
+  }
+
+  const stageRoot = path.join(stateDir, "staging", randomUUID());
+  const stagedPaths = new Map();
+  const applied = [];
+  const rollbackErrors = [];
+  let manifestBackupPath = null;
+  let manifestExisted = false;
+  let manifestChanged = false;
+  let preserveStage = false;
+
+  try {
+    await mkdir(stageRoot, { recursive: true });
+    const stageRootSafety = await inspectAncestorPath(homeDir, stageRoot);
+    const realStateDir = await realpath(stateDir);
+    const realStageRoot = await realpath(stageRoot);
+    const realStageRelative = path.relative(realStateDir, realStageRoot);
+    if (
+      !stageRootSafety.safe ||
+      realStageRelative.startsWith("..") ||
+      path.isAbsolute(realStageRelative)
+    ) {
+      preserveStage = true;
+      throw new SyncConflictError([
+        {
+          host: "state",
+          skillName: "staging",
+          relativePath: path.basename(stageRoot),
+          targetPath: stageRoot,
+          action: "conflict",
+          reason: "事务暂存目录解析到同步状态目录之外",
+        },
+      ]);
+    }
+
+    for (const operation of operations) {
+      if (operation.action !== "create" && operation.action !== "update") continue;
+      const stagedPath = path.join(stageRoot, "next", ...operation.manifestKey.split("/"));
+      await mkdir(path.dirname(stagedPath), { recursive: true });
+      await copyFile(operation.sourcePath, stagedPath);
+      if ((await hashFile(stagedPath)) !== operation.sourceHash) {
+        throw new Error(`暂存文件校验失败：${operation.sourcePath}`);
+      }
+      stagedPaths.set(operation.manifestKey, stagedPath);
+    }
+
+    const lockedManifest = await readManifest(manifestPath);
+    const manifestTarget = await inspectTarget(manifestPath);
+    if (manifestTarget.exists && !manifestTarget.regularFile) {
+      throw new Error(`同步 manifest 不是普通文件：${manifestPath}`);
+    }
+    if (manifestTarget.exists) {
+      manifestExisted = true;
+      manifestBackupPath = path.join(stageRoot, "backups", "manifest.json");
+      await mkdir(path.dirname(manifestBackupPath), { recursive: true });
+      await copyFile(manifestPath, manifestBackupPath);
+    }
+
+    const changedTargetConflicts = await collectChangedTargetConflicts(operations, homeDir);
+    if (changedTargetConflicts.length > 0) throw new SyncConflictError(changedTargetConflicts);
+
+    for (const operation of operations) {
+      if (operation.action !== "create" && operation.action !== "update") continue;
+      let backupPath = null;
+      if (operation.action === "update") {
+        backupPath = path.join(stageRoot, "backups", ...operation.manifestKey.split("/"));
+        await mkdir(path.dirname(backupPath), { recursive: true });
+        await copyFile(operation.targetPath, backupPath);
+        if ((await hashFile(backupPath)) !== operation.targetHash) {
+          throw new Error(`目标备份校验失败：${operation.targetPath}`);
+        }
+      }
+
+      applied.push({ operation, backupPath });
+      await mkdir(path.dirname(operation.targetPath), { recursive: true });
+      await copyFile(stagedPaths.get(operation.manifestKey), operation.targetPath);
+      if ((await hashFile(operation.targetPath)) !== operation.sourceHash) {
+        throw new Error(`同步后校验失败：${operation.targetPath}`);
+      }
+    }
+
+    const nextFiles = { ...lockedManifest.files };
+    for (const operation of operations) nextFiles[operation.manifestKey] = operation.sourceHash;
+    const nextManifest = {
+      schemaVersion: 1,
+      managedBy: "netpilot-skills",
+      updatedAt: new Date().toISOString(),
+      files: Object.fromEntries(Object.entries(nextFiles).sort(([left], [right]) => left.localeCompare(right))),
+    };
+    const stagedManifestPath = path.join(stageRoot, "next-manifest.json");
+    await mkdir(path.dirname(stagedManifestPath), { recursive: true });
+    await writeFile(stagedManifestPath, `${JSON.stringify(nextManifest, null, 2)}\n`, "utf8");
+    JSON.parse(await readFile(stagedManifestPath, "utf8"));
+    manifestChanged = true;
+    await copyFile(stagedManifestPath, manifestPath);
+    JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    for (const { operation, backupPath } of [...applied].reverse()) {
+      try {
+        if (backupPath) {
+          await copyFile(backupPath, operation.targetPath);
+        } else {
+          await rm(operation.targetPath, { force: true });
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(`${operation.targetPath}: ${rollbackError.message}`);
+      }
+    }
+
+    if (manifestChanged) {
+      try {
+        if (manifestExisted) {
+          await copyFile(manifestBackupPath, manifestPath);
+        } else {
+          await rm(manifestPath, { force: true });
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(`${manifestPath}: ${rollbackError.message}`);
+      }
+    }
+
+    if (rollbackErrors.length > 0) {
+      preserveStage = true;
+      throw new Error(
+        `同步失败且回滚不完整；暂存保留在 ${stageRoot}\n${rollbackErrors.join("\n")}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  } finally {
+    try {
+      await lockHandle.close();
+    } finally {
+      await rm(lockPath, { force: true });
+    }
+    if (!preserveStage) await rm(stageRoot, { recursive: true, force: true });
+  }
+}
+
+export async function syncSkills({
+  rootDir,
+  homeDir,
+  hosts = [...ALL_HOSTS],
+  components = ["skills"],
+  apply = false,
+}) {
+  const selectedHosts = [...new Set(hosts)];
+  const selectedComponents = [...new Set(components)];
+  for (const host of selectedHosts) {
+    if (!(host in HOST_DESTINATIONS)) throw new Error(`不支持的宿主：${host}`);
+  }
+  for (const component of selectedComponents) {
+    if (!ALL_COMPONENTS.includes(component)) throw new Error(`不支持的组件：${component}`);
+  }
+  if (
+    selectedComponents.includes("agents") &&
+    (selectedHosts.length !== 1 || selectedHosts[0] !== "codex")
+  ) {
+    throw new Error("Codex agents 组件只支持显式选择 --host codex");
+  }
+
+  const resolvedRoot = path.resolve(rootDir);
+  const resolvedHome = path.resolve(homeDir);
+  const manifestPath = path.join(resolvedHome, ".netpilot-skills", "manifest.json");
+  const stateDir = path.dirname(manifestPath);
+  const stateSafety = await inspectAncestorPath(resolvedHome, stateDir);
+  if (!stateSafety.safe) {
+    throw new SyncConflictError([
+      {
+        host: "state",
+        skillName: "manifest",
+        relativePath: "manifest.json",
+        targetPath: manifestPath,
+        action: "conflict",
+        reason: `${stateSafety.reason}：${stateSafety.path}`,
+      },
+    ]);
+  }
+  const manifestTarget = await inspectTarget(manifestPath);
+  if (manifestTarget.exists && !manifestTarget.regularFile) {
+    throw new SyncConflictError([
+      {
+        host: "state",
+        skillName: "manifest",
+        relativePath: "manifest.json",
+        targetPath: manifestPath,
+        action: "conflict",
+        reason: "同步 manifest 不是普通文件",
+      },
+    ]);
+  }
+  const manifest = await readManifest(manifestPath);
+  const sourceFiles = selectedComponents.includes("skills")
+    ? await discoverSourceFiles(resolvedRoot)
+    : [];
+  let codexAgentFiles = [];
+  if (selectedComponents.includes("agents")) {
+    const codexAgentRoot = path.join(resolvedRoot, "agents", "codex");
+    const agentValidation = await validateCodexAgentDirectory(codexAgentRoot);
+    if (agentValidation.errors.length > 0) {
+      throw new Error(`Codex agents 校验失败：\n- ${agentValidation.errors.join("\n- ")}`);
+    }
+    codexAgentFiles = await discoverCodexAgentFiles(resolvedRoot);
+  }
+  const supportFiles = await discoverSupportFiles(resolvedRoot);
+  const operations = [];
+
+  if (selectedComponents.includes("skills")) {
+    for (const host of selectedHosts) {
+      const hostRoot = path.join(resolvedHome, ...HOST_DESTINATIONS[host]);
+      for (const source of sourceFiles) {
+        const targetPath = path.join(hostRoot, source.skillName, ...source.relativePath.split("/"));
+        operations.push(await planFileOperation({
+          host,
+          component: "skills",
+          assetName: source.skillName,
+          skillName: source.skillName,
+          relativePath: source.relativePath,
+          sourcePath: source.absolutePath,
+          targetPath,
+          manifest,
+          homeDir: resolvedHome,
+        }));
+      }
+    }
+  }
+
+  if (selectedComponents.includes("agents")) {
+    const agentRoot = path.join(resolvedHome, ...CODEX_AGENT_DESTINATION);
+    for (const source of codexAgentFiles) {
+      operations.push(await planFileOperation({
+        host: "codex",
+        component: "agents",
+        assetName: source.assetName,
+        skillName: source.assetName,
+        relativePath: source.relativePath,
+        sourcePath: source.absolutePath,
+        targetPath: path.join(agentRoot, source.relativePath),
+        manifest,
+        homeDir: resolvedHome,
+      }));
+    }
+  }
+
+  for (const support of supportFiles) {
+    operations.push(await planFileOperation({
+      host: "state",
+      component: "support",
+      assetName: support.skillName,
+      skillName: support.skillName,
+      relativePath: support.relativePath,
+      sourcePath: support.absolutePath,
+      targetPath: path.join(stateDir, "notices", support.relativePath),
+      manifest,
+      homeDir: resolvedHome,
+    }));
+  }
+
+  const conflicts = operations.filter((operation) => operation.action === "conflict");
+  const result = {
+    mode: apply ? "apply" : "dry-run",
+    homeDir: resolvedHome,
+    manifestPath,
+    operations,
+    conflicts,
+  };
+
+  if (!apply) return result;
+  if (conflicts.length > 0) throw new SyncConflictError(conflicts);
+  await applyOperationsTransactional({ operations, homeDir: resolvedHome, manifestPath });
+
+  return result;
+}
+
+function printHelp() {
+  console.log(`用法：
+  netpilot-skills install [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
+  npm run sync -- [--host codex|claude|all] [--component skills|agents|all] [--home PATH] [--apply]
+
+默认执行 dry-run，只展示计划。只有传入 --apply 才会写入用户级目录。
+Codex 目标：~/.agents/skills
+Claude Code 目标：~/.claude/skills
+Codex agents 目标：~/.codex/agents（必须显式选择 --component agents 或 all）`);
+}
+
+function printPlan(result) {
+  for (const operation of result.operations) {
+    const reason = operation.reason ? `（${operation.reason}）` : "";
+    const component = operation.component === "skills" ? "skills" : operation.component;
+    console.log(`[${operation.action}] ${operation.host} ${component} ${operation.assetName}/${operation.relativePath}${reason}`);
+  }
+  const counts = Object.fromEntries(
+    ["create", "update", "unchanged", "conflict"].map((action) => [
+      action,
+      result.operations.filter((operation) => operation.action === action).length,
+    ]),
+  );
+  console.log(`汇总：新增 ${counts.create}，更新 ${counts.update}，不变 ${counts.unchanged}，冲突 ${counts.conflict}`);
+  if (result.mode === "dry-run") console.log("当前为 dry-run；确认计划后追加 --apply。 ");
+}
+
+async function main() {
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    printHelp();
+    return;
+  }
+  const options = parseArgs(process.argv.slice(2));
+  const rootDir = fileURLToPath(new URL("..", import.meta.url));
+  try {
+    const result = await syncSkills({ rootDir, ...options });
+    printPlan(result);
+    if (result.conflicts.length > 0) process.exitCode = 2;
+  } catch (error) {
+    if (error instanceof SyncConflictError) {
+      for (const conflict of error.conflicts) {
+        console.error(`[conflict] ${conflict.targetPath}（${conflict.reason}）`);
+      }
+      console.error(error.message);
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}