@netpilot/skills 0.4.0 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -4,13 +4,13 @@
   "owner": {
     "name": "NetPilot"
   },
-  "description": "NetPilot 个人 AI 工程协作插件目录",
+  "description": "NetPilot AI 工程协作插件目录",
   "plugins": [
     {
       "name": "netpilot-skills",
       "source": "./",
       "description": "中文工程协作 skills 与可组合工作流",
-      "version": "0.4.0",
+      "version": "0.6.0",
       "author": {
         "name": "NetPilot"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "netpilot-skills",
   "displayName": "NetPilot Skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "面向 Claude Code 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "netpilot-skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "面向 Codex 的中文工程协作 skills 与可组合工作流",
   "author": {
     "name": "NetPilot"

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ## Unreleased
 
+## 0.6.0
+
+- 将用户级与项目级安装状态迁移到中性的 `.agents/.state/skills-installer`；旧 `.netpilot-skills` 在 apply 时经锁保护、目录身份复核后原子迁移，preview 仅报告计划。旧版客户端留下的精确空目录可安全自愈，真实双状态或目标冲突仍整批停止。
+- 项目安装继续只写入 `.agents/skills`，不安装项目级 Agents；用户级默认仍安装 Codex Skills 与少量 Codex Agents。
+- 与 `@netpilot/harness` 协调发布同一 `v0.6.0` 标签，便于在新电脑或新项目中识别兼容的一组安装器能力；两个包仍保持独立职责和发布契约。
+
 ## 0.4.0
 
 - 将工程与生产力方法扩展为 21 个去个人化 skills，按上游原有结构恢复完整工作流、步骤内门禁、方法自身的反模式，以及有实际价值的 `references/` 和跨平台脚本；不再为每个 skill 强加统一尾部章节。

package/README.md

@@ -42,7 +42,7 @@ npm install --global @netpilot/skills
 netpilot-skills
 ```
 
-安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。项目范围只安装 Skills，项目级 Agents 仍由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
+安装器不会覆盖未受管理或用户修改过的同名文件；发生冲突时整批停止。同步状态保存在 `.agents/.state/skills-installer`：用户安装位于 home，项目安装位于项目根；旧 `.netpilot-skills` 会在下一次实际安装时原子迁移，预览只展示计划。旧版安装器在新状态旁留下的空旧目录会安全自愈，含内容的双状态仍会阻断。项目范围只安装 Skills，项目级 Agents 仍由 [NetPilot Harness](https://github.com/netpilot-z/harness) 管理。
 
 ## 核心用法
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netpilot/skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "面向 Codex 与 Claude Code 的中文工程协作 skills 与可选 Codex agents",
   "keywords": [
     "codex",

package/scripts/sync.mjs

@@ -24,6 +24,10 @@ const HOST_DESTINATIONS = {
 };
 
 const CODEX_AGENT_DESTINATION = [".codex", "agents"];
+const CURRENT_STATE_DESTINATION = [".agents", ".state", "skills-installer"];
+const LEGACY_STATE_DESTINATION = [".netpilot-skills"];
+const LAYOUT_LOCK_DIRECTORY = [".agents", ".state"];
+const LAYOUT_LOCK_NAME = "skills-installer.layout.lock";
 
 const ALL_HOSTS = Object.freeze(Object.keys(HOST_DESTINATIONS));
 const ALL_COMPONENTS = Object.freeze(["skills", "agents"]);
@@ -354,6 +358,100 @@ async function assertSafeHomeRoot(homeDir) {
   ]);
 }
 
+function resolveStatePaths(homeDir) {
+  const currentStateDir = path.join(homeDir, ...CURRENT_STATE_DESTINATION);
+  const legacyStateDir = path.join(homeDir, ...LEGACY_STATE_DESTINATION);
+  return {
+    currentStateDir,
+    currentManifestPath: path.join(currentStateDir, "manifest.json"),
+    legacyStateDir,
+    legacyManifestPath: path.join(legacyStateDir, "manifest.json"),
+    layoutLockDir: path.join(homeDir, ...LAYOUT_LOCK_DIRECTORY),
+  };
+}
+
+function stateLayoutConflict(homeDir, reason, targetPath = homeDir) {
+  return new SyncConflictError([
+    {
+      host: "state",
+      component: "layout",
+      assetName: "state-layout",
+      skillName: "state-layout",
+      relativePath: ".",
+      targetPath,
+      action: "conflict",
+      reason,
+    },
+  ]);
+}
+
+async function inspectStateDirectory(homeDir, targetPath) {
+  const ancestor = await inspectAncestorPath(homeDir, targetPath);
+  if (!ancestor.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${ancestor.reason}：${ancestor.path}`,
+      targetPath,
+    );
+  }
+  try {
+    const stats = await lstat(targetPath);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw stateLayoutConflict(
+        homeDir,
+        "状态路径必须是非符号链接目录",
+        targetPath,
+      );
+    }
+    return {
+      exists: true,
+      path: targetPath,
+      identity: { dev: stats.dev, ino: stats.ino },
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") return { exists: false, path: targetPath };
+    throw error;
+  }
+}
+
+function sameStateDirectoryIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+async function inspectStateLayout(homeDir, paths = resolveStatePaths(homeDir)) {
+  const [current, legacy] = await Promise.all([
+    inspectStateDirectory(homeDir, paths.currentStateDir),
+    inspectStateDirectory(homeDir, paths.legacyStateDir),
+  ]);
+  if (current.exists && legacy.exists) {
+    const legacyEntries = await readdir(legacy.path);
+    const latestLegacy = await inspectStateDirectory(homeDir, legacy.path);
+    if (
+      legacyEntries.length === 0 &&
+      latestLegacy.exists &&
+      sameStateDirectoryIdentity(legacy.identity, latestLegacy.identity)
+    ) {
+      return {
+        kind: "current-with-empty-legacy",
+        current,
+        legacy: latestLegacy,
+        paths,
+      };
+    }
+    throw stateLayoutConflict(
+      homeDir,
+      "新旧状态目录同时存在，拒绝自动合并 ownership",
+      paths.currentStateDir,
+    );
+  }
+  return {
+    kind: current.exists ? "current" : legacy.exists ? "legacy" : "fresh",
+    current,
+    legacy,
+    paths,
+  };
+}
+
 function parseLockRecord(content) {
   const trimmed = content.trim();
   if (/^[1-9][0-9]*$/u.test(trimmed)) {
@@ -411,9 +509,13 @@ async function moveLockForCompare({ lockPath, expectedContent, stateDir, purpose
   throw error;
 }
 
-async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
-  await mkdir(stateDir, { recursive: true });
-  const stateSafety = await inspectAncestorPath(homeDir, stateDir);
+async function acquireSyncLock({
+  homeDir,
+  stateDir,
+  lockName = "sync.lock",
+  beforeLockPublish,
+}) {
+  let stateSafety = await inspectAncestorPath(homeDir, stateDir);
   if (!stateSafety.safe) {
     throw new SyncConflictError([
       {
@@ -421,15 +523,24 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
         component: "lock",
         assetName: "sync",
         skillName: "sync",
-        relativePath: "sync.lock",
-        targetPath: path.join(stateDir, "sync.lock"),
+        relativePath: lockName,
+        targetPath: path.join(stateDir, lockName),
         action: "conflict",
         reason: `${stateSafety.reason}：${stateSafety.path}`,
       },
     ]);
   }
+  await mkdir(stateDir, { recursive: true });
+  stateSafety = await inspectAncestorPath(homeDir, stateDir);
+  if (!stateSafety.safe) {
+    throw stateLayoutConflict(
+      homeDir,
+      `${stateSafety.reason}：${stateSafety.path}`,
+      stateDir,
+    );
+  }
 
-  const lockPath = path.join(stateDir, "sync.lock");
+  const lockPath = path.join(stateDir, lockName);
   const owner = randomUUID();
   const recordContent = `${JSON.stringify({
     schemaVersion: 1,
@@ -437,7 +548,10 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
     owner,
     createdAt: new Date().toISOString(),
   })}\n`;
-  const stagedLockPath = path.join(stateDir, `sync-lock-${owner}.tmp`);
+  const stagedLockPath = path.join(
+    stateDir,
+    `${lockName.replaceAll(".", "-")}-${owner}.tmp`,
+  );
   await writeFile(stagedLockPath, recordContent, { encoding: "utf8", flag: "wx" });
   if ((await readFile(stagedLockPath, "utf8")) !== recordContent) {
     await rm(stagedLockPath, { force: true });
@@ -445,7 +559,7 @@ async function acquireSyncLock({ homeDir, stateDir, transactionHooks = {} }) {
   }
 
   try {
-    await transactionHooks.beforeLockPublish?.();
+    await beforeLockPublish?.();
     for (let attempt = 0; attempt < 3; attempt += 1) {
       try {
         await link(stagedLockPath, lockPath);
@@ -1303,6 +1417,111 @@ async function applyOperationsTransactional({
   }
 }
 
+async function migrateLegacyState({
+  homeDir,
+  paths,
+  transactionHooks,
+}) {
+  let syncLock = await acquireSyncLock({
+    homeDir,
+    stateDir: paths.legacyStateDir,
+    beforeLockPublish: transactionHooks.beforeLockPublish,
+  });
+  let moved = false;
+  try {
+    const freshLayout = await inspectStateLayout(homeDir, paths);
+    if (freshLayout.kind !== "legacy") {
+      throw stateLayoutConflict(
+        homeDir,
+        "获取旧状态锁后布局发生变化，拒绝继续迁移",
+        paths.legacyStateDir,
+      );
+    }
+    const lockedSourceIdentity = freshLayout.legacy.identity;
+    const legacyManifest = await inspectTarget(paths.legacyManifestPath);
+    if (!legacyManifest.exists || !legacyManifest.regularFile) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录缺少可信的普通 manifest.json",
+        paths.legacyManifestPath,
+      );
+    }
+    await readManifest(paths.legacyManifestPath);
+    await transactionHooks.beforeStateMigrationRename?.();
+    const beforeRename = await inspectStateLayout(homeDir, paths);
+    if (
+      beforeRename.kind !== "legacy" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        beforeRename.legacy.identity,
+      )
+    ) {
+      throw stateLayoutConflict(
+        homeDir,
+        "旧状态目录身份在迁移提交前发生变化",
+        paths.currentStateDir,
+      );
+    }
+    try {
+      await rename(paths.legacyStateDir, paths.currentStateDir);
+    } catch (error) {
+      if (error.code === "EXDEV") {
+        throw stateLayoutConflict(
+          homeDir,
+          "新旧状态目录不在同一文件系统，拒绝退化为非原子复制",
+          paths.currentStateDir,
+        );
+      }
+      if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+        throw stateLayoutConflict(
+          homeDir,
+          "新状态目录在原子迁移前已出现",
+          paths.currentStateDir,
+        );
+      }
+      throw error;
+    }
+    moved = true;
+    syncLock = {
+      ...syncLock,
+      stateDir: paths.currentStateDir,
+      lockPath: path.join(paths.currentStateDir, "sync.lock"),
+    };
+    const migratedLayout = await inspectStateLayout(homeDir, paths);
+    if (
+      migratedLayout.kind !== "current" ||
+      !sameStateDirectoryIdentity(
+        lockedSourceIdentity,
+        migratedLayout.current.identity,
+      )
+    ) {
+      const error = new Error("状态目录迁移后的目标身份不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    const migratedManifest = await inspectTarget(paths.currentManifestPath);
+    if (
+      !migratedManifest.regularFile ||
+      migratedManifest.hash !== legacyManifest.hash
+    ) {
+      const error = new Error("状态目录迁移后 manifest digest 不一致");
+      error.preserveEvidence = true;
+      throw error;
+    }
+    await transactionHooks.afterStateMigrationRename?.();
+    return syncLock;
+  } catch (error) {
+    try {
+      await releaseSyncLock(syncLock);
+    } catch (releaseError) {
+      error.releaseError = releaseError;
+      error.preserveEvidence = true;
+    }
+    if (moved) error.stateMigrationCommitted = true;
+    throw error;
+  }
+}
+
 export async function syncSkills({
   rootDir,
   homeDir,
@@ -1329,14 +1548,114 @@ export async function syncSkills({
   const resolvedRoot = path.resolve(rootDir);
   const resolvedHome = path.resolve(homeDir);
   await assertSafeHomeRoot(resolvedHome);
-  const manifestPath = path.join(resolvedHome, ".netpilot-skills", "manifest.json");
-  const stateDir = path.dirname(manifestPath);
-  const syncLock = apply
-    ? await acquireSyncLock({ homeDir: resolvedHome, stateDir, transactionHooks })
-    : null;
+  const statePaths = resolveStatePaths(resolvedHome);
+  let stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+  let stateDir =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyStateDir
+      : statePaths.currentStateDir;
+  let manifestPath =
+    stateLayout.kind === "legacy"
+      ? statePaths.legacyManifestPath
+      : statePaths.currentManifestPath;
+  let stateMigration =
+    stateLayout.kind === "legacy"
+      ? {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        }
+      : null;
+  let stateRepair =
+    stateLayout.kind === "current-with-empty-legacy"
+      ? {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        }
+      : null;
+  let layoutLock = null;
+  let syncLock = null;
   let syncError = null;
 
   try {
+    if (apply) {
+      layoutLock = await acquireSyncLock({
+        homeDir: resolvedHome,
+        stateDir: statePaths.layoutLockDir,
+        lockName: LAYOUT_LOCK_NAME,
+        beforeLockPublish: transactionHooks.beforeLayoutLockPublish,
+      });
+      stateLayout = await inspectStateLayout(resolvedHome, statePaths);
+      if (stateLayout.kind === "current-with-empty-legacy") {
+        stateRepair = {
+          action: "remove-empty-legacy-state",
+          target: statePaths.legacyStateDir,
+        };
+        const expectedCurrentIdentity = stateLayout.current.identity;
+        try {
+          await rmdir(statePaths.legacyStateDir);
+        } catch (error) {
+          if (["ENOTEMPTY", "EEXIST"].includes(error.code)) {
+            throw stateLayoutConflict(
+              resolvedHome,
+              "空旧状态目录在清理前出现内容，拒绝继续",
+              statePaths.legacyStateDir,
+            );
+          }
+          throw error;
+        }
+        const repairedLayout = await inspectStateLayout(
+          resolvedHome,
+          statePaths,
+        );
+        if (
+          repairedLayout.kind !== "current" ||
+          !sameStateDirectoryIdentity(
+            expectedCurrentIdentity,
+            repairedLayout.current.identity,
+          )
+        ) {
+          throw stateLayoutConflict(
+            resolvedHome,
+            "清理旧状态残留后当前状态目录身份发生变化",
+            statePaths.currentStateDir,
+          );
+        }
+        stateLayout = repairedLayout;
+      }
+      if (stateLayout.kind === "legacy") {
+        stateMigration = {
+          action: "move",
+          from: statePaths.legacyStateDir,
+          to: statePaths.currentStateDir,
+        };
+        syncLock = await migrateLegacyState({
+          homeDir: resolvedHome,
+          paths: statePaths,
+          transactionHooks,
+        });
+      } else {
+        syncLock = await acquireSyncLock({
+          homeDir: resolvedHome,
+          stateDir: statePaths.currentStateDir,
+          beforeLockPublish: transactionHooks.beforeLockPublish,
+        });
+      }
+      const lockedLayout = await inspectStateLayout(
+        resolvedHome,
+        statePaths,
+      );
+      if (lockedLayout.kind !== "current") {
+        throw stateLayoutConflict(
+          resolvedHome,
+          "获取同步锁后项目状态布局发生变化，拒绝继续",
+          statePaths.currentStateDir,
+        );
+      }
+      stateLayout = lockedLayout;
+      stateDir = statePaths.currentStateDir;
+      manifestPath = statePaths.currentManifestPath;
+    }
     if (syncLock) await transactionHooks.afterLockAcquired?.();
   const stateSafety = await inspectAncestorPath(resolvedHome, stateDir);
   if (!stateSafety.safe) {
@@ -1468,7 +1787,12 @@ export async function syncSkills({
   const result = {
     mode: apply ? "apply" : "dry-run",
     homeDir: resolvedHome,
-    manifestPath,
+    manifestPath: statePaths.currentManifestPath,
+    ...(manifestPath !== statePaths.currentManifestPath
+      ? { sourceManifestPath: manifestPath }
+      : {}),
+    ...(stateMigration ? { stateMigration } : {}),
+    ...(stateRepair ? { stateRepair } : {}),
     operations,
     conflicts,
   };
@@ -1488,18 +1812,21 @@ export async function syncSkills({
     syncError = error;
     throw error;
   } finally {
-    if (syncLock) {
+    let releaseFailure = null;
+    for (const lock of [syncLock, layoutLock]) {
+      if (!lock) continue;
       try {
-        await releaseSyncLock(syncLock);
+        await releaseSyncLock(lock);
       } catch (releaseError) {
         if (syncError) {
           syncError.releaseError = releaseError;
           syncError.preserveEvidence = true;
         } else {
-          throw releaseError;
+          releaseFailure ??= releaseError;
         }
       }
     }
+    if (!syncError && releaseFailure) throw releaseFailure;
   }
 }
 
@@ -1518,6 +1845,16 @@ Claude Code 目标：~/.claude/skills（选择 --host claude 时默认只安装
 }
 
 function printPlan(result) {
+  if (result.stateRepair) {
+    console.log(
+      `[remove-empty] state ${result.stateRepair.target}`,
+    );
+  }
+  if (result.stateMigration) {
+    console.log(
+      `[move] state ${result.stateMigration.from} -> ${result.stateMigration.to}`,
+    );
+  }
   for (const operation of result.operations) {
     const reason = operation.reason ? `（${operation.reason}）` : "";
     const component = operation.component === "skills" ? "skills" : operation.component;