@jackss119/shelf 1.0.0 → 1.2.0

package/bin/shelf.mjs

@@ -1,78 +1,90 @@
-#!/usr/bin/env node
-import {
-  cmdShelfBrowse,
-  cmdShelfPull,
-  cmdShelfPush,
-  cmdShelfCreate,
-  cmdShelfSync,
-  cmdShelfInit,
-  cmdShelfHome,
-} from "../lib/commands/shelf.mjs";
-
-function usage() {
-  console.log(`shelf — 个人内容货架 CLI（别名 atk）
-
-Usage:
-  shelf                  交互浏览货架（数字进目录，p 1,3-5 拉取，a 全部）
-  shelf pull <路径...>    按路径拉取，如 shelf pull skills/common/intj
-                         [--dest <目录>]
-  shelf create <本地路径> 上架新货：全架查重名，交互选位（m <名> 建目录，
-                         d 放下）[--to <货架目录>] [--yes]
-  shelf push <本地路径>   更新已有货：按记账/名字自动定位
-                         [--yes] [--force] [--force-secret]
-  shelf sync [--dry-run] 按账本对账：库上新版自动更新本地；本地有改动
-                         则显示 diff 由你决定推上库还是覆盖本地
-  shelf init             初始化工作区（.shelf.json + shelf-ops 手册）
-  shelf home [--update]  查看货架在哪、什么模式；--update 拉取最新
-
-货架定位：SHELF_HOME 环境变量 > 本 clone > ~/.shelfrc > 托管档口 ~/.shelf/home
-免 clone 直跑：npx -y -p github:Jackzz119/my-workspace shelf <命令>`);
-}
-
-const argv = process.argv.slice(2);
-const sub = argv[0];
-const rest = argv.slice(1);
-
-try {
-  switch (sub) {
-    case undefined:
-    case "browse":
-      await cmdShelfBrowse();
-      break;
-    case "pull":
-      await cmdShelfPull(rest);
-      break;
-    case "create":
-      await cmdShelfCreate(rest);
-      break;
-    case "push":
-      await cmdShelfPush(rest);
-      break;
-    case "sync":
-      await cmdShelfSync(rest);
-      break;
-    case "init":
-      await cmdShelfInit(rest);
-      break;
-    case "home":
-      await cmdShelfHome(rest);
-      break;
-    case "-h":
-    case "--help":
-    case "help":
-      usage();
-      break;
-    case "skills":
-    case "list":
-      console.error(`'shelf ${sub}' 已随老版技能命令清退：浏览用 shelf，按路径拉取用 shelf pull <路径> --dest .claude/skills，保持最新用 shelf sync`);
-      process.exit(1);
-      break;
-    default:
-      console.error(`Unknown command: ${sub}\n`);
-      usage();
-      process.exit(1);
-  }
-} catch (err) {
-  console.error(err.message || err);
-  process.exit(1);
-}
+#!/usr/bin/env node
+import {
+  cmdShelfBrowse,
+  cmdShelfPull,
+  cmdShelfPush,
+  cmdShelfCreate,
+  cmdShelfSync,
+  cmdShelfInit,
+  cmdShelfAgents,
+  cmdShelfAdopt,
+  cmdShelfHome,
+} from "../lib/commands/shelf.mjs";
+
+function usage() {
+  console.log(`shelf — 个人内容货架 CLI（别名 atk）
+
+Usage:
+  shelf                  交互浏览货架（数字进目录，p 1,3-5 拉取，a 全部）
+  shelf pull <路径...>    按路径拉取，如 shelf pull skills/common/intj
+                         [--dest <目录>]
+  shelf create <本地路径> 上架新货：全架查重名，交互选位（m <名> 建目录，
+                         d 放下）[--to <货架目录>] [--yes]
+  shelf push <本地路径>   更新已有货：按记账/名字自动定位
+                         [--yes] [--force] [--force-secret]
+  shelf sync [--dry-run] 按账本对账：库上新版自动更新本地；本地有改动
+                         则显示 diff 由你决定推上库还是覆盖本地
+  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
+免 clone 直跑：npx -y -p github:Jackzz119/my-workspace shelf <命令>`);
+}
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+const rest = argv.slice(1);
+
+try {
+  switch (sub) {
+    case undefined:
+    case "browse":
+      await cmdShelfBrowse();
+      break;
+    case "pull":
+      await cmdShelfPull(rest);
+      break;
+    case "create":
+      await cmdShelfCreate(rest);
+      break;
+    case "push":
+      await cmdShelfPush(rest);
+      break;
+    case "sync":
+      await cmdShelfSync(rest);
+      break;
+    case "init":
+      await cmdShelfInit(rest);
+      break;
+    case "agents":
+      await cmdShelfAgents(rest);
+      break;
+    case "adopt":
+      await cmdShelfAdopt(rest);
+      break;
+    case "home":
+      await cmdShelfHome(rest);
+      break;
+    case "-h":
+    case "--help":
+    case "help":
+      usage();
+      break;
+    case "skills":
+    case "list":
+      console.error(`'shelf ${sub}' 已随老版技能命令清退：浏览用 shelf，按路径拉取用 shelf pull <路径> --dest .claude/skills，保持最新用 shelf sync`);
+      process.exit(1);
+      break;
+    default:
+      console.error(`Unknown command: ${sub}\n`);
+      usage();
+      process.exit(1);
+  }
+} catch (err) {
+  console.error(err.message || err);
+  process.exit(1);
+}

package/lib/commands/shelf.mjs

@@ -732,33 +732,365 @@ export async function cmdShelfCreate(argv) {
   }
 }
 
-// ---- 子命令：init ----
+// ---- init 植入协议（SHELF 决策 #21/#22/#23）----
+
+// gitignore 补行：只补缺失的，其余不动；目录行同时认 ".claude" 与 ".claude/"
+function ensureGitignore(cwd, lines) {
+  const p = path.join(cwd, ".gitignore");
+  const content = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  const NL = String.fromCharCode(10);
+  const CR = String.fromCharCode(13);
+  const have = new Set(content.split(NL).map((l) => l.replaceAll(CR, "").trim()));
+  const missing = lines.filter((l) => {
+    const bare = l.endsWith("/") ? l.slice(0, -1) : l;
+    return !have.has(bare) && !have.has(bare + "/");
+  });
+  if (missing.length === 0) return [];
+  const sep = content === "" || content.endsWith(NL) ? "" : NL;
+  fs.writeFileSync(p, content + sep + "# shelf init: agent 资产不入项目库" + NL + missing.join(NL) + NL, "utf8");
+  return missing;
+}
+
+// ---- agent 目标与技能正本（SHELF 决策 #24/#26）----
+
+// 项目里技能的唯一正本；所有 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"] },
+  codex: { skillsDir: ".codex/skills", doc: { input: "agents/codex/AGENTS.md", dest: "AGENTS.md" }, ignore: [".codex/", "AGENTS.md"] },
+  kimi: { skillsDir: ".kimi/skills", doc: { input: "agents/codex/AGENTS.md", dest: "AGENTS.md" }, ignore: [".kimi/", "AGENTS.md"] },
+};
+const TARGET_PRIORITY = ["claude", "codex", "kimi"];
+
+// "claude,codex" / "all" → 校验并按固定顺序去重
+function parseTargetNames(spec) {
+  const names = spec === "all"
+    ? [...TARGET_PRIORITY]
+    : String(spec).split(",").map((x) => x.trim()).filter(Boolean);
+  const bad = names.filter((n) => !AGENT_TARGETS[n]);
+  if (bad.length) {
+    console.error("✗ 未知 agent 目标: " + bad.join(", ") + "（可选: " + TARGET_PRIORITY.join(" / ") + " / all）");
+    process.exit(1);
+  }
+  return TARGET_PRIORITY.filter((n) => names.includes(n));
+}
+
+async function askTargets() {
+  const rl = makeLineReader();
+  try {
+    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 + "）");
+    });
+    while (true) {
+      const raw = await rl.question("选择编号，逗号分隔（如 1,2）；a=全部 > ");
+      if (raw === null) return null;
+      const ans = raw.trim().toLowerCase();
+      if (ans === "a") return [...TARGET_PRIORITY];
+      const idx = parseIndices(ans, TARGET_PRIORITY.length);
+      if (idx && idx.length) return idx.map((i) => TARGET_PRIORITY[i]);
+      console.log("  没看懂。例如: 1,2 或 a");
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// 把 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) {
+    const doc = AGENT_TARGETS[n].doc;
+    if (seenDoc.has(doc.dest)) continue; // codex/kimi 共用 AGENTS.md，只植一份
+    seenDoc.add(doc.dest);
+    plan.push({ input: doc.input, dest: doc.dest });
+  }
+  plan.push({ input: "multica", dest: "multica", optional: true });
+  plan.push({ input: "docs/JASKILL.md", dest: "ai/JASKILL.md" });
+
+  const common = resolveShelfPath(ctx.shelfDir, "skills/common");
+  if (common) {
+    for (const e of fs.readdirSync(common.abs, { withFileTypes: true })) {
+      if (!e.isDirectory() || IGNORE_NAMES.has(e.name)) continue;
+      plan.push({
+        input: common.realRel + "/" + e.name,
+        dest: CANONICAL_SKILLS_DIR + "/" + e.name,
+      });
+    }
+  }
+
+  const counters = newCounters();
+  for (const item of plan) {
+    const hit = resolveShelfPath(ctx.shelfDir, item.input);
+    if (!hit) {
+      console.log(item.optional
+        ? "- 货架上暂无 " + item.input + "，跳过"
+        : "✗ 货架上找不到 " + item.input + "（检查货架是否最新）");
+      continue;
+    }
+    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, linksMade, added };
+}
+
+function printPlantResult(targets, r) {
+  printSummary(r.counters);
+  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  基础技能名册");
+  console.log("  " + CANONICAL_SKILLS_DIR + "/  技能唯一正本（改技能、拉技能都在这）");
+  console.log("  " + targets.map((n) => AGENT_TARGETS[n].skillsDir).join(" · ") + "  → 指向正本的链接");
+  console.log("  .shelf.json  记账本（进项目 git，队友 clone 后 shelf init 即还原）");
+}
+
+export async function cmdShelfInit(argv = []) {
+  let rest = argv;
+  let agentsFlag;
+  ({ args: rest, value: agentsFlag } = takeFlag(rest, "--agents", true));
 
-export async function cmdShelfInit() {
   const ctx = resolveShelfContext();
   try {
+    if (path.resolve(process.cwd()) === path.resolve(ctx.root)) {
+      console.error("✗ 这里就是货架 home 本体，不能对它 init（防止把忽略规则写进货架仓库）");
+      process.exit(1);
+    }
     const manifest = loadManifest();
     manifest.source ??= remoteUrl(ctx.root) || toPosix(ctx.root);
 
-    const hit = resolveShelfPath(ctx.shelfDir, "skills/common/shelf-ops");
-    if (!hit) {
-      console.error("✗ 货架上找不到 skills/common/shelf-ops（操作手册 skill），检查 shelf 是否最新");
-      process.exit(1);
+    let targets;
+    if (agentsFlag !== undefined) {
+      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）");
+    } else if (INTERACTIVE) {
+      targets = await askTargets();
+      if (!targets || !targets.length) {
+        console.log("已取消。");
+        return;
+      }
+    } else {
+      console.error("✗ 非交互环境首次 init 需指定 --agents claude,codex,kimi（或 all）。已中止。");
+      process.exit(2);
     }
-    const counters = newCounters();
-    const dest = path.join(process.cwd(), ".claude", "skills", "shelf-ops");
-    await pullEntry(ctx, hit.realRel, manifest, counters, safeAsk, dest);
+
+    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();
+  }
+}
 
-    console.log("");
-    console.log("工作区已就绪:");
-    console.log("  .shelf.json               版本追踪 manifest");
-    console.log("  .claude/skills/shelf-ops  货架操作手册（agent 据此执行 pull/push）");
+// ---- 子命令：agents（查看/添加 agent 目标，SHELF 决策 #24）----
+
+export async function cmdShelfAgents(argv) {
+  const manifest = loadManifest();
+  const current = TARGET_PRIORITY.filter((n) => (manifest.agents ?? []).includes(n));
+  const sub = argv[0];
+
+  if (sub === undefined) {
+    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("添加: shelf agents add <名>");
+    return;
+  }
+  if (sub !== "add" || argv.length < 2) {
+    console.error("用法: shelf agents             查看已配置/可用目标");
+    console.error("      shelf agents add <名>   添加目标（claude / codex / kimi / all）");
+    process.exit(1);
+  }
+
+  const adding = parseTargetNames(argv.slice(1).join(","));
+  const targets = TARGET_PRIORITY.filter((n) => current.includes(n) || adding.includes(n));
+  if (targets.join() === current.join()) {
+    console.log("= 目标已包含，无需变更（" + current.join(", ") + "）");
+    return;
+  }
+
+  const ctx = resolveShelfContext();
+  try {
+    const result = await plantForTargets(ctx, manifest, targets);
+    manifest.agents = targets;
+    saveManifest(manifest);
+    printPlantResult(targets, result);
+    console.log("✓ agent 目标: " + (current.join(", ") || "（无）") + " → " + targets.join(", "));
   } finally {
     ctx.cleanup();
   }
 }
 
+// ---- 本地技能台账（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) {
@@ -789,165 +1121,180 @@ export async function cmdShelfHome(argv) {
     ctx.cleanup();
   }
 }
-
-// ---- 子命令：sync（按账本与货架对账，SHELF 决策 #19）----
-
-// 逐行内容 diff 直通终端（git 自带着色），方向：库上 → 本地
-function showLineDiff(shelfAbs, localAbs, shown) {
-  console.log(`—— ${shown}  diff（库上 → 本地）——`);
-  spawnSync("git", ["diff", "--no-index", "--color=always", "--", shelfAbs, localAbs], { stdio: "inherit" });
-}
-
-export async function cmdShelfSync(argv) {
-  let rest = argv;
-  let dryRun;
-  ({ args: rest, value: dryRun } = takeFlag(rest, "--dry-run"));
-
-  const ctx = resolveShelfContext({ forWrite: true }); // 对账必须对着真最新：等同写操作，强制刷新
-  let keepEphemeral = false;
-  try {
-    const manifest = loadManifest();
-    const entries = Object.entries(manifest.shelf ?? {});
-    if (entries.length === 0) {
-      console.log("账本为空（.shelf.json 没有 shelf 段记录）——先 shelf pull / create。");
-      return;
-    }
-
-    const c = { same: 0, updated: 0, pushed: 0, skipped: 0, cleaned: 0 };
-    const pending = [];
-
-    for (const [key, rec] of entries) {
-      let effKey = key;
-      let target = path.join(ctx.shelfDir, ...effKey.split("/"));
-      let shown = displayPath(effKey);
-      const localAbs = path.resolve(process.cwd(), rec.localPath ?? "");
-      const localExists = !!rec.localPath && fs.existsSync(localAbs);
-
-      // 情形 5：库上路径没了 → 按名字找回（搬家）或报告下架
-      if (!fs.existsSync(target)) {
-        const name = path.basename(effKey);
-        const hits = findByBasename(ctx.shelfDir, name);
-        if (hits.length === 1) {
-          if (dryRun) {
-            console.log(`↪ ${shown} 已被移动到 ${displayPath(hits[0])}（--dry-run，暂不改账）`);
-          } else {
-            delete manifest.shelf[effKey];
-            manifest.shelf[hits[0]] = rec;
-            console.log(`↪ ${shown} 已被移动到 ${displayPath(hits[0])}，记账已更新`);
-          }
-          effKey = hits[0];
-          target = path.join(ctx.shelfDir, ...effKey.split("/"));
-          shown = displayPath(effKey);
-        } else {
-          const label = hits.length === 0 ? "已从货架移除" : `同名多义（${hits.length} 处）`;
-          if (!INTERACTIVE || dryRun) {
-            console.log(`⚠ 待决 ${shown}：${label}`);
-            pending.push(`${shown}（${label}）`);
-            continue;
-          }
-          const act = await choose(`⚠ ${shown} ${label}。[r]清记账 / [s]跳过? `, [{ key: "r" }, { key: "s" }]);
-          if (act === "r") {
-            delete manifest.shelf[effKey];
-            console.log(`✓ 已清记账 ${shown}（本地文件未动；想重新上架用 shelf create）`);
-            c.cleaned++;
-          } else c.skipped++;
-          continue;
-        }
-      }
-
-      // 情形 6：本地文件没了 → 孤儿记账
-      if (!localExists) {
-        if (!INTERACTIVE || dryRun) {
-          console.log(`⚠ 待决 ${shown}：本地文件不存在（${rec.localPath ?? "无 localPath"}）`);
-          pending.push(`${shown}（本地文件不存在）`);
-          continue;
-        }
-        const act = await choose(
-          `⚠ ${shown} 的本地文件不存在（${rec.localPath ?? "无 localPath"}）。[p]重新拉取 / [r]清记账 / [s]跳过? `,
-          [{ key: "p" }, { key: "r" }, { key: "s" }],
-        );
-        if (act === "p") {
-          fs.mkdirSync(path.dirname(localAbs), { recursive: true });
-          copyFiltered(target, localAbs);
-          manifest.shelf[effKey] = { ...rec, contentHash: contentHash(target), sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
-          console.log(`↓ 已重新拉取 ${shown}`);
-          c.updated++;
-        } else if (act === "r") {
-          delete manifest.shelf[effKey];
-          console.log(`✓ 已清记账 ${shown}`);
-          c.cleaned++;
-        } else c.skipped++;
-        continue;
-      }
-
-      const S = contentHash(target);
-      const L = contentHash(localAbs);
-      const R = rec.contentHash;
-
-      if (S === R && L === R) { c.same++; continue; }
-
-      // 情形 2：库上有新版、本地没动 → 自动覆盖本地（零损失）
-      if (S !== R && L === R) {
-        if (dryRun) {
-          console.log(`↓ 将更新本地：${shown}`);
-          c.updated++;
-          continue;
-        }
-        fs.rmSync(localAbs, { recursive: true, force: true });
-        copyFiltered(target, localAbs);
-        manifest.shelf[effKey] = { ...rec, contentHash: S, sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
-        console.log(`↓ 已更新本地：${shown}`);
-        c.updated++;
-        continue;
-      }
-
-      // 情形 3/4：本地有改动（本地领先，或双方都改）
-      const both = S !== R;
-      const tag = both ? "双方都改过" : "本地领先";
-      if (!INTERACTIVE || dryRun) {
-        const d = diffSummary(target, localAbs);
-        console.log(`⚠ 待决 ${shown}（${tag}）：本地相对库上 新增 ${d.added.length} / 删除 ${d.removed.length} / 修改 ${d.changed.length}`);
-        pending.push(`${shown}（${tag}）`);
-        continue;
-      }
-
-      showLineDiff(target, localAbs, shown);
-      const act = await choose(`${shown}（${tag}）。[p]本地推上库 / [o]库覆盖本地 / [s]跳过? `, [{ key: "p" }, { key: "o" }, { key: "s" }]);
-      if (act === "s") { c.skipped++; continue; }
-      if (act === "o") {
-        fs.rmSync(localAbs, { recursive: true, force: true });
-        copyFiltered(target, localAbs);
-        manifest.shelf[effKey] = { ...rec, contentHash: S, sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
-        console.log(`↓ 已用库上版本覆盖本地：${shown}`);
-        c.updated++;
-        continue;
-      }
-      // p：本地推上库
-      if (both) {
-        const confirm = await choose(`库上的改动将被你的本地版本覆盖，确认? [y]es / [n]o? `, [{ key: "y" }, { key: "n" }]);
-        if (confirm === "n") { c.skipped++; continue; }
-      }
-      const { secrets } = guardScan(localAbs);
-      if (secrets.length > 0) {
-        console.log(`✗ ${shown} 含疑似凭据文件（${secrets.map((x) => x.rel).join(", ")}），sync 不代推，已跳过——确要推请单独 shelf push --force-secret`);
-        c.skipped++;
-        continue;
-      }
-      keepEphemeral = applyAndCommit(ctx, effKey, localAbs, manifest, "update") || keepEphemeral;
-      c.pushed++;
-    }
-
-    if (!dryRun) saveManifest(manifest);
-    console.log("");
-    console.log(
-      `Sync${dryRun ? "（dry-run）" : ""}: ${c.same} 一致, ${c.updated} 更新本地, ${c.pushed} 推上库, ` +
-      `${c.cleaned} 清账, ${c.skipped} 跳过, ${pending.length} 待决`,
-    );
-    if (pending.length) {
-      for (const x of pending) console.log(`  · ${x}`);
-      if (!INTERACTIVE && !dryRun) process.exit(2);
-    }
-  } finally {
-    if (!keepEphemeral) ctx.cleanup();
-  }
-}
+
+// ---- 子命令：sync（按账本与货架对账，SHELF 决策 #19）----
+
+// 逐行内容 diff 直通终端（git 自带着色），方向：库上 → 本地
+function showLineDiff(shelfAbs, localAbs, shown) {
+  console.log(`—— ${shown}  diff（库上 → 本地）——`);
+  spawnSync("git", ["diff", "--no-index", "--color=always", "--", shelfAbs, localAbs], { stdio: "inherit" });
+}
+
+export async function cmdShelfSync(argv) {
+  let rest = argv;
+  let dryRun;
+  ({ args: rest, value: dryRun } = takeFlag(rest, "--dry-run"));
+
+  const ctx = resolveShelfContext({ forWrite: true }); // 对账必须对着真最新：等同写操作，强制刷新
+  let keepEphemeral = false;
+  try {
+    const manifest = loadManifest();
+    const entries = Object.entries(manifest.shelf ?? {});
+    if (entries.length === 0) {
+      console.log("账本为空（.shelf.json 没有 shelf 段记录）——先 shelf pull / create。");
+      return;
+    }
+
+    const c = { same: 0, updated: 0, pushed: 0, skipped: 0, cleaned: 0 };
+    const pending = [];
+
+    for (const [key, rec] of entries) {
+      let effKey = key;
+      let target = path.join(ctx.shelfDir, ...effKey.split("/"));
+      let shown = displayPath(effKey);
+      const localAbs = path.resolve(process.cwd(), rec.localPath ?? "");
+      const localExists = !!rec.localPath && fs.existsSync(localAbs);
+
+      // 情形 5：库上路径没了 → 按名字找回（搬家）或报告下架
+      if (!fs.existsSync(target)) {
+        const name = path.basename(effKey);
+        const hits = findByBasename(ctx.shelfDir, name);
+        if (hits.length === 1) {
+          if (dryRun) {
+            console.log(`↪ ${shown} 已被移动到 ${displayPath(hits[0])}（--dry-run，暂不改账）`);
+          } else {
+            delete manifest.shelf[effKey];
+            manifest.shelf[hits[0]] = rec;
+            console.log(`↪ ${shown} 已被移动到 ${displayPath(hits[0])}，记账已更新`);
+          }
+          effKey = hits[0];
+          target = path.join(ctx.shelfDir, ...effKey.split("/"));
+          shown = displayPath(effKey);
+        } else {
+          const label = hits.length === 0 ? "已从货架移除" : `同名多义（${hits.length} 处）`;
+          if (!INTERACTIVE || dryRun) {
+            console.log(`⚠ 待决 ${shown}：${label}`);
+            pending.push(`${shown}（${label}）`);
+            continue;
+          }
+          const act = await choose(`⚠ ${shown} ${label}。[r]清记账 / [s]跳过? `, [{ key: "r" }, { key: "s" }]);
+          if (act === "r") {
+            delete manifest.shelf[effKey];
+            console.log(`✓ 已清记账 ${shown}（本地文件未动；想重新上架用 shelf create）`);
+            c.cleaned++;
+          } else c.skipped++;
+          continue;
+        }
+      }
+
+      // 情形 6：本地文件没了 → 孤儿记账
+      if (!localExists) {
+        if (!INTERACTIVE || dryRun) {
+          console.log(`⚠ 待决 ${shown}：本地文件不存在（${rec.localPath ?? "无 localPath"}）`);
+          pending.push(`${shown}（本地文件不存在）`);
+          continue;
+        }
+        const act = await choose(
+          `⚠ ${shown} 的本地文件不存在（${rec.localPath ?? "无 localPath"}）。[p]重新拉取 / [r]清记账 / [s]跳过? `,
+          [{ key: "p" }, { key: "r" }, { key: "s" }],
+        );
+        if (act === "p") {
+          fs.mkdirSync(path.dirname(localAbs), { recursive: true });
+          copyFiltered(target, localAbs);
+          manifest.shelf[effKey] = { ...rec, contentHash: contentHash(target), sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
+          console.log(`↓ 已重新拉取 ${shown}`);
+          c.updated++;
+        } else if (act === "r") {
+          delete manifest.shelf[effKey];
+          console.log(`✓ 已清记账 ${shown}`);
+          c.cleaned++;
+        } else c.skipped++;
+        continue;
+      }
+
+      const S = contentHash(target);
+      const L = contentHash(localAbs);
+      const R = rec.contentHash;
+
+      if (S === R && L === R) { c.same++; continue; }
+
+      // 情形 2：库上有新版、本地没动 → 自动覆盖本地（零损失）
+      if (S !== R && L === R) {
+        if (dryRun) {
+          console.log(`↓ 将更新本地：${shown}`);
+          c.updated++;
+          continue;
+        }
+        fs.rmSync(localAbs, { recursive: true, force: true });
+        copyFiltered(target, localAbs);
+        manifest.shelf[effKey] = { ...rec, contentHash: S, sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
+        console.log(`↓ 已更新本地：${shown}`);
+        c.updated++;
+        continue;
+      }
+
+      // 情形 3/4：本地有改动（本地领先，或双方都改）
+      const both = S !== R;
+      const tag = both ? "双方都改过" : "本地领先";
+      if (!INTERACTIVE || dryRun) {
+        const d = diffSummary(target, localAbs);
+        console.log(`⚠ 待决 ${shown}（${tag}）：本地相对库上 新增 ${d.added.length} / 删除 ${d.removed.length} / 修改 ${d.changed.length}`);
+        pending.push(`${shown}（${tag}）`);
+        continue;
+      }
+
+      showLineDiff(target, localAbs, shown);
+      const act = await choose(`${shown}（${tag}）。[p]本地推上库 / [o]库覆盖本地 / [s]跳过? `, [{ key: "p" }, { key: "o" }, { key: "s" }]);
+      if (act === "s") { c.skipped++; continue; }
+      if (act === "o") {
+        fs.rmSync(localAbs, { recursive: true, force: true });
+        copyFiltered(target, localAbs);
+        manifest.shelf[effKey] = { ...rec, contentHash: S, sourceCommit: headCommit(ctx.root), pulledAt: todayISO() };
+        console.log(`↓ 已用库上版本覆盖本地：${shown}`);
+        c.updated++;
+        continue;
+      }
+      // p：本地推上库
+      if (both) {
+        const confirm = await choose(`库上的改动将被你的本地版本覆盖，确认? [y]es / [n]o? `, [{ key: "y" }, { key: "n" }]);
+        if (confirm === "n") { c.skipped++; continue; }
+      }
+      const { secrets } = guardScan(localAbs);
+      if (secrets.length > 0) {
+        console.log(`✗ ${shown} 含疑似凭据文件（${secrets.map((x) => x.rel).join(", ")}），sync 不代推，已跳过——确要推请单独 shelf push --force-secret`);
+        c.skipped++;
+        continue;
+      }
+      keepEphemeral = applyAndCommit(ctx, effKey, localAbs, manifest, "update") || keepEphemeral;
+      c.pushed++;
+    }
+
+    // 链接完整性（决策 #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} 跳过, ${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}`);
+      if (!INTERACTIVE && !dryRun) process.exit(2);
+    }
+  } finally {
+    if (!keepEphemeral) ctx.cleanup();
+  }
+}

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.0.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": {