@jackss119/shelf 1.1.0 → 1.2.0

package/bin/shelf.mjs

@@ -7,6 +7,7 @@ import {
   cmdShelfSync,
   cmdShelfInit,
   cmdShelfAgents,
+  cmdShelfAdopt,
   cmdShelfHome,
 } from "../lib/commands/shelf.mjs";
 
@@ -26,6 +27,8 @@ Usage:
   shelf init             项目接入（幂等）：交互多选 agent 目标，或
                          --agents claude,codex,kimi / all
   shelf agents [add <名>] 查看 / 追加 agent 目标（claude / codex / kimi）
+  shelf adopt            收编外来技能：实体目录迁入正本重链 + 未记账技能
+                         登记进账本 local 段（不上货架）
   shelf home [--update]  查看货架在哪、什么模式；--update 拉取最新
 
 货架定位：SHELF_HOME 环境变量 > 本 clone > ~/.shelfrc > 托管档口 ~/.shelf/home
@@ -60,6 +63,9 @@ try {
     case "agents":
       await cmdShelfAgents(rest);
       break;
+    case "adopt":
+      await cmdShelfAdopt(rest);
+      break;
     case "home":
       await cmdShelfHome(rest);
       break;

package/lib/commands/shelf.mjs

@@ -751,19 +751,10 @@ function ensureGitignore(cwd, lines) {
   return missing;
 }
 
-// 镜像跟随正本：缺失或内容不一致就整体重刷；返回是否动了
-function refreshMirror(primaryAbs, mirrorAbs) {
-  if (!fs.existsSync(primaryAbs)) return false;
-  if (fs.existsSync(mirrorAbs) && contentHash(mirrorAbs) === contentHash(primaryAbs)) return false;
-  fs.rmSync(mirrorAbs, { recursive: true, force: true });
-  fs.mkdirSync(path.dirname(mirrorAbs), { recursive: true });
-  copyFiltered(primaryAbs, mirrorAbs);
-  return true;
-}
+// ---- agent 目标与技能正本（SHELF 决策 #24/#26）----
 
-// ---- 子命令：init ----
-
-// ---- agent 目标（SHELF 决策 #24）----
+// 项目里技能的唯一正本；所有 agent 目录都是指向它的链接
+const CANONICAL_SKILLS_DIR = "ai/jaSkills";
 
 const AGENT_TARGETS = {
   claude: { skillsDir: ".claude/skills", doc: { input: "agents/claude/CLAUDE.md", dest: "CLAUDE.md" }, ignore: [".claude/", "CLAUDE.md"] },
@@ -772,7 +763,7 @@ const AGENT_TARGETS = {
 };
 const TARGET_PRIORITY = ["claude", "codex", "kimi"];
 
-// "claude,codex" / "all" → 校验并按优先级排序去重
+// "claude,codex" / "all" → 校验并按固定顺序去重
 function parseTargetNames(spec) {
   const names = spec === "all"
     ? [...TARGET_PRIORITY]
@@ -788,7 +779,7 @@ function parseTargetNames(spec) {
 async function askTargets() {
   const rl = makeLineReader();
   try {
-    console.log("要接入哪些 agent？（决定植入哪些技能目录与协议文档）");
+    console.log("要接入哪些 agent？（各自的技能目录会链接到正本 " + CANONICAL_SKILLS_DIR + "/）");
     TARGET_PRIORITY.forEach((n, i) => {
       const t = AGENT_TARGETS[n];
       console.log("  " + (i + 1) + ". " + n + "  （" + t.skillsDir + "/ · " + t.doc.dest + "）");
@@ -807,12 +798,58 @@ async function askTargets() {
   }
 }
 
-// 植入引擎（init 与 agents add 共用）：协议文档去重植入 + multica/JASKILL + common 技能
-// 正本 = 所选目标中优先级最高者，其余目标目录挂 mirrors；gitignore 行随目标生成
-async function plantForTargets(ctx, manifest, targets) {
-  const primaryDir = AGENT_TARGETS[targets[0]].skillsDir;
-  const mirrorDirs = targets.slice(1).map((n) => AGENT_TARGETS[n].skillsDir);
+// 把 agent 的技能目录做成指向正本的链接（Windows junction 免管理员 / POSIX 相对 symlink）。
+// 遇到老式实体目录（复制镜像时代）自动迁移：内容并入正本（同名跳过），原地替换为链接。
+// 返回 "ok"（已正确）/ "created" / "fixed"
+function ensureSkillsLink(cwd, targetName) {
+  const rel = AGENT_TARGETS[targetName].skillsDir;
+  const linkPath = path.join(cwd, ...rel.split("/"));
+  const canonical = path.join(cwd, ...CANONICAL_SKILLS_DIR.split("/"));
+  fs.mkdirSync(canonical, { recursive: true });
+  fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+
+  let st = null;
+  try { st = fs.lstatSync(linkPath); } catch { st = null; }
+
+  if (st && st.isSymbolicLink()) {
+    try {
+      if (fs.realpathSync(linkPath) === fs.realpathSync(canonical)) return "ok";
+    } catch { /* 断链 → 重建 */ }
+    fs.rmSync(linkPath, { recursive: true, force: true });
+  } else if (st && st.isDirectory()) {
+    let moved = 0;
+    let skipped = 0;
+    for (const e of fs.readdirSync(linkPath, { withFileTypes: true })) {
+      if (IGNORE_NAMES.has(e.name)) continue;
+      const from = path.join(linkPath, e.name);
+      const to = path.join(canonical, e.name);
+      if (fs.existsSync(to)) {
+        skipped++;
+        continue;
+      }
+      fs.cpSync(from, to, { recursive: true });
+      moved++;
+    }
+    fs.rmSync(linkPath, { recursive: true, force: true });
+    if (moved || skipped) {
+      console.log("↪ " + rel + " 原为实体目录：迁入正本 " + moved + " 项"
+        + (skipped ? "，同名跳过 " + skipped + " 项" : "") + "，已替换为链接");
+    }
+  } else if (st) {
+    fs.rmSync(linkPath, { force: true });
+  }
 
+  if (process.platform === "win32") {
+    fs.symlinkSync(canonical, linkPath, "junction");
+  } else {
+    fs.symlinkSync(path.relative(path.dirname(linkPath), canonical), linkPath, "dir");
+  }
+  return st ? "fixed" : "created";
+}
+
+// 植入引擎（init 与 agents add 共用）：协议文档去重植入 + multica/JASKILL +
+// common 技能拉进正本 ai/jaSkills + 各目标技能目录链接化 + gitignore
+async function plantForTargets(ctx, manifest, targets) {
   const plan = [];
   const seenDoc = new Set();
   for (const n of targets) {
@@ -830,14 +867,12 @@ async function plantForTargets(ctx, manifest, targets) {
       if (!e.isDirectory() || IGNORE_NAMES.has(e.name)) continue;
       plan.push({
         input: common.realRel + "/" + e.name,
-        dest: primaryDir + "/" + e.name,
-        mirrors: mirrorDirs.map((d) => d + "/" + e.name),
+        dest: CANONICAL_SKILLS_DIR + "/" + e.name,
       });
     }
   }
 
   const counters = newCounters();
-  let mirrored = 0;
   for (const item of plan) {
     const hit = resolveShelfPath(ctx.shelfDir, item.input);
     if (!hit) {
@@ -846,35 +881,30 @@ async function plantForTargets(ctx, manifest, targets) {
         : "✗ 货架上找不到 " + item.input + "（检查货架是否最新）");
       continue;
     }
-    const destAbs = path.resolve(process.cwd(), item.dest);
-    await pullEntry(ctx, hit.realRel, manifest, counters, safeAsk, destAbs);
-    if (item.mirrors) {
-      const entry = manifest.shelf[hit.realRel];
-      if (entry) entry.mirrors = item.mirrors.map(toPosix);
-      for (const m of item.mirrors) {
-        if (refreshMirror(destAbs, path.resolve(process.cwd(), m))) mirrored++;
-      }
-    }
+    await pullEntry(ctx, hit.realRel, manifest, counters, safeAsk, path.resolve(process.cwd(), item.dest));
+  }
+
+  let linksMade = 0;
+  for (const n of targets) {
+    if (ensureSkillsLink(process.cwd(), n) !== "ok") linksMade++;
   }
 
   const ignoreLines = [...new Set(targets.flatMap((n) => AGENT_TARGETS[n].ignore))];
   const added = ensureGitignore(process.cwd(), ignoreLines);
-  return { counters, mirrored, added };
+  return { counters, linksMade, added };
 }
 
 function printPlantResult(targets, r) {
   printSummary(r.counters);
-  if (r.mirrored) console.log("≡ 镜像刷新 " + r.mirrored + " 项");
+  if (r.linksMade) console.log("⛓ 建立/修复链接 " + r.linksMade + " 个");
   if (r.added.length) console.log("✓ .gitignore 补行: " + r.added.join(", "));
   console.log("");
   console.log("工作区已接入货架（agent 目标: " + targets.join(" + ") + "）:");
   const docs = [...new Set(targets.map((n) => AGENT_TARGETS[n].doc.dest))].join(" / ");
   console.log("  " + docs + "  工作协议（真源在货架，shelf sync 保持最新）");
   console.log("  ai/JASKILL.md  基础技能名册");
-  const mirrorText = targets.length > 1
-    ? "；镜像: " + targets.slice(1).map((n) => AGENT_TARGETS[n].skillsDir + "/").join(" ")
-    : "";
-  console.log("  " + AGENT_TARGETS[targets[0]].skillsDir + "/  common 技能正本" + mirrorText);
+  console.log("  " + CANONICAL_SKILLS_DIR + "/  技能唯一正本（改技能、拉技能都在这）");
+  console.log("  " + targets.map((n) => AGENT_TARGETS[n].skillsDir).join(" · ") + "  → 指向正本的链接");
   console.log("  .shelf.json  记账本（进项目 git，队友 clone 后 shelf init 即还原）");
 }
 
@@ -897,7 +927,7 @@ export async function cmdShelfInit(argv = []) {
       targets = parseTargetNames(agentsFlag);
     } else if (manifest.agents?.length) {
       targets = TARGET_PRIORITY.filter((n) => manifest.agents.includes(n));
-      console.log("（沿用已配置的 agent 目标: " + targets.join(", ") + "；调整用 shelf agents add 或 --agents)");
+      console.log("（沿用已配置的 agent 目标: " + targets.join(", ") + "；调整用 shelf agents add 或 --agents）");
     } else if (INTERACTIVE) {
       targets = await askTargets();
       if (!targets || !targets.length) {
@@ -911,8 +941,27 @@ export async function cmdShelfInit(argv = []) {
 
     const result = await plantForTargets(ctx, manifest, targets);
     manifest.agents = targets;
+
+    // 账本还原（2026-08-30 用户确认）：标准植入清单之外、账上有而本地缺失的货架物品一并补拉，
+    // 换设备后一条 init 全就位，无需再跑 sync
+    let restored = 0;
+    for (const [key, rec] of Object.entries(manifest.shelf ?? {})) {
+      if (!rec.localPath) continue;
+      const destAbs = path.resolve(process.cwd(), rec.localPath);
+      if (fs.existsSync(destAbs)) continue;
+      const hit = resolveShelfPath(ctx.shelfDir, key);
+      if (!hit) {
+        console.log("⚠ 账上物品 " + displayPath(key) + " 在货架上已不在原位——跑 shelf sync 处理搬家/下架");
+        continue;
+      }
+      await pullEntry(ctx, hit.realRel, manifest, result.counters, safeAsk, destAbs);
+      restored++;
+    }
+
+    await reconcileLocalSkills(manifest);
     saveManifest(manifest);
     printPlantResult(targets, result);
+    if (restored) console.log("↺ 按账本补还原 " + restored + " 项（标准清单之外）");
   } finally {
     ctx.cleanup();
   }
@@ -926,10 +975,11 @@ export async function cmdShelfAgents(argv) {
   const sub = argv[0];
 
   if (sub === undefined) {
-    console.log("已配置: " + (current.length ? current.join(", ") : "（无——先跑 shelf init）"));
+    console.log("技能正本: " + CANONICAL_SKILLS_DIR + "/（改技能、拉技能都在这）");
+    console.log("已配置:   " + (current.length ? current.join(", ") : "（无——先跑 shelf init）"));
     for (const n of TARGET_PRIORITY) {
       const t = AGENT_TARGETS[n];
-      console.log("  " + (current.includes(n) ? "●" : "○") + " " + n + "  " + t.skillsDir + "/ · " + t.doc.dest);
+      console.log("  " + (current.includes(n) ? "●" : "○") + " " + n + "  " + t.skillsDir + "/ → 链接 · " + t.doc.dest);
     }
     console.log("添加: shelf agents add <名>");
     return;
@@ -959,6 +1009,88 @@ export async function cmdShelfAgents(argv) {
   }
 }
 
+// ---- 本地技能台账（SHELF 决策 #27 · 增量对账）----
+
+// local 段维护：在场→刷指纹；升格→移除；缺失→告警但保留记录（仅 adopt 交互提供清账）；
+// 新出现的未追踪目录→登记。init / sync / adopt 共用。
+async function reconcileLocalSkills(manifest, { allowPrune = false } = {}) {
+  const canonical = path.join(process.cwd(), ...CANONICAL_SKILLS_DIR.split("/"));
+  const tracked = new Set(
+    Object.values(manifest.shelf ?? {}).map((e) => toPosix(e.localPath ?? "")),
+  );
+  const prev = manifest.local ?? {};
+  const next = {};
+  const c = { registered: 0, refreshed: 0, missing: 0, graduated: 0 };
+
+  const dirs = fs.existsSync(canonical)
+    ? fs.readdirSync(canonical, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !IGNORE_NAMES.has(e.name))
+        .map((e) => e.name)
+    : [];
+  const present = new Set(dirs);
+
+  for (const [name, entry] of Object.entries(prev)) {
+    if (tracked.has(CANONICAL_SKILLS_DIR + "/" + name)) {
+      c.graduated++;
+      continue;
+    }
+    if (present.has(name)) {
+      const hash = contentHash(path.join(canonical, name));
+      if (hash !== entry.contentHash) c.refreshed++;
+      next[name] = { ...entry, contentHash: hash };
+      continue;
+    }
+    c.missing++;
+    console.log("⚠ 登记过的本地技能缺失: " + name + "（登记于 " + (entry.addedAt ?? "?")
+      + "，上次指纹 " + String(entry.contentHash ?? "").slice(7, 19) + "…）——重装后跑 shelf sync 即恢复入账");
+    if (allowPrune && INTERACTIVE) {
+      const act = await choose("  [k]保留记录 / [r]清账? ", [{ key: "k" }, { key: "r" }]);
+      if (act === "r") continue;
+    }
+    next[name] = entry;
+  }
+
+  for (const name of dirs) {
+    if (next[name] || tracked.has(CANONICAL_SKILLS_DIR + "/" + name)) continue;
+    next[name] = {
+      contentHash: contentHash(path.join(canonical, name)),
+      addedAt: todayISO(),
+      origin: "adopted",
+    };
+    console.log("✚ 登记本地技能: " + name);
+    c.registered++;
+  }
+
+  manifest.local = next;
+  return c;
+}
+
+// ---- 子命令：adopt（收编外来技能，SHELF 决策 #27）----
+
+export async function cmdShelfAdopt() {
+  const manifest = loadManifest();
+
+  // agent 技能目录若被外部安装器换成了实体目录：内容迁入正本，恢复链接
+  let relinked = 0;
+  for (const n of manifest.agents ?? []) {
+    if (!AGENT_TARGETS[n]) continue;
+    if (ensureSkillsLink(process.cwd(), n) !== "ok") relinked++;
+  }
+
+  const c = await reconcileLocalSkills(manifest, { allowPrune: true });
+  saveManifest(manifest);
+
+  console.log("");
+  console.log(
+    "Adopt: " + c.registered + " 新登记, " + c.refreshed + " 指纹更新, " + c.missing + " 缺失保留, "
+    + c.graduated + " 已升格/移除, " + relinked + " 目录收编重链；"
+    + "local 段共 " + Object.keys(manifest.local).length + " 个本地技能",
+  );
+  if (Object.keys(manifest.local).length) {
+    console.log("（本地技能不参与货架对账；想跨项目复用: shelf create " + CANONICAL_SKILLS_DIR + "/<名> --to skills/<包>）");
+  }
+}
+
 // ---- 子命令：home（查看/更新档口）----
 
 export async function cmdShelfHome(argv) {
@@ -1137,23 +1269,26 @@ export async function cmdShelfSync(argv) {
       c.pushed++;
     }
 
-    // 镜像校对（决策 #22）：正本处理完后统一核对，哈希不符即从正本重刷
-    let mirrorFixed = 0;
-    if (!dryRun) {
-      for (const [, rec] of Object.entries(manifest.shelf ?? {})) {
-        if (!rec.mirrors?.length || !rec.localPath) continue;
-        const primary = path.resolve(process.cwd(), rec.localPath);
-        for (const m of rec.mirrors) {
-          if (refreshMirror(primary, path.resolve(process.cwd(), m))) mirrorFixed++;
-        }
+    // 链接完整性（决策 #26）：已配置目标的技能目录必须是指向 ai/jaSkills 的链接
+    let linksFixed = 0;
+    if (!dryRun && manifest.agents?.length) {
+      for (const n of manifest.agents) {
+        if (!AGENT_TARGETS[n]) continue;
+        if (ensureSkillsLink(process.cwd(), n) !== "ok") linksFixed++;
       }
     }
 
+    let localStat = null;
+    if (!dryRun) localStat = await reconcileLocalSkills(manifest);
+
     if (!dryRun) saveManifest(manifest);
     console.log("");
     console.log(
       `Sync${dryRun ? "（dry-run）" : ""}: ${c.same} 一致, ${c.updated} 更新本地, ${c.pushed} 推上库, ` +
-      `${c.cleaned} 清账, ${c.skipped} 跳过, ${mirrorFixed} 镜像刷新, ${pending.length} 待决`,
+      `${c.cleaned} 清账, ${c.skipped} 跳过, ${linksFixed} 链接修复, ${pending.length} 待决` +
+      (localStat && (localStat.registered || localStat.refreshed || localStat.missing)
+        ? `；本地技能: ${localStat.registered} 新登记 / ${localStat.refreshed} 指纹更新 / ${localStat.missing} 缺失`
+        : ""),
     );
     if (pending.length) {
       for (const x of pending) console.log(`  · ${x}`);

package/lib/manifest.mjs

@@ -28,11 +28,13 @@ export function loadManifest(cwd = process.cwd()) {
       skillsDir: ".claude/skills",
       skills: {},
       shelf: {},
+      local: {},
     };
   }
   const data = JSON.parse(fs.readFileSync(file, "utf8"));
   data.skills ??= {};
   data.shelf ??= {};
+  data.local ??= {};
   return data;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackss119/shelf",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Personal content shelf CLI: browse, pull and push skills, templates, docs and snippets across every machine you work on.",
   "type": "module",
   "bin": {