@jackss119/shelf 1.0.0 → 1.1.0

package/bin/shelf.mjs

@@ -1,78 +1,84 @@
-#!/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,
+  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 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 "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,28 +732,228 @@ export async function cmdShelfCreate(argv) {
   }
 }
 
+// ---- 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;
+}
+
+// 镜像跟随正本：缺失或内容不一致就整体重刷；返回是否动了
+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;
+}
+
 // ---- 子命令：init ----
 
-export async function cmdShelfInit() {
+// ---- agent 目标（SHELF 决策 #24）----
+
+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？（决定植入哪些技能目录与协议文档）");
+    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();
+  }
+}
+
+// 植入引擎（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);
+
+  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: primaryDir + "/" + e.name,
+        mirrors: mirrorDirs.map((d) => d + "/" + e.name),
+      });
+    }
+  }
+
+  const counters = newCounters();
+  let mirrored = 0;
+  for (const item of plan) {
+    const hit = resolveShelfPath(ctx.shelfDir, item.input);
+    if (!hit) {
+      console.log(item.optional
+        ? "- 货架上暂无 " + item.input + "，跳过"
+        : "✗ 货架上找不到 " + 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++;
+      }
+    }
+  }
+
+  const ignoreLines = [...new Set(targets.flatMap((n) => AGENT_TARGETS[n].ignore))];
+  const added = ensureGitignore(process.cwd(), ignoreLines);
+  return { counters, mirrored, added };
+}
+
+function printPlantResult(targets, r) {
+  printSummary(r.counters);
+  if (r.mirrored) console.log("≡ 镜像刷新 " + r.mirrored + " 项");
+  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("  .shelf.json  记账本（进项目 git，队友 clone 后 shelf init 即还原）");
+}
+
+export async function cmdShelfInit(argv = []) {
+  let rest = argv;
+  let agentsFlag;
+  ({ args: rest, value: agentsFlag } = takeFlag(rest, "--agents", true));
+
   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;
     saveManifest(manifest);
+    printPlantResult(targets, result);
+  } 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("已配置: " + (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();
   }
@@ -789,165 +989,177 @@ 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++;
+    }
+
+    // 镜像校对（决策 #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++;
+        }
+      }
+    }
+
+    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} 待决`,
+    );
+    if (pending.length) {
+      for (const x of pending) console.log(`  · ${x}`);
+      if (!INTERACTIVE && !dryRun) process.exit(2);
+    }
+  } finally {
+    if (!keepEphemeral) ctx.cleanup();
+  }
+}

package/package.json

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