agent-syncer 0.1.0 → 0.1.2

package/lib/commands/link.js

@@ -6,47 +6,255 @@ import { CONFIG_FILENAME, loadConfig, saveConfig } from '../config.js';
 import { writeBlock } from '../gitignore.js';
 import { STATUS, createLink, inspect, removeLink } from '../link.js';
 import { dim, fail, info, ok, plain, skip, title, warn } from '../log.js';
+import { rmdirIfEmpty } from '../prune.js';
 import { checkbox, isInteractive } from '../prompt.js';
-import { CONTENT_ROOT, TOOLS, specOf, plannedLinks, kindsOf, TOOL_NAMES } from '../target.js';
+import { findStaleLinks } from '../stale.js';
+import {
+  CONTENT_ROOT,
+  TOOLS,
+  TOOL_NAMES,
+  kindsOf,
+  plannedLinks,
+  specsOfTools,
+  toolDir,
+} from '../target.js';
 
 /**
- * 构造勾选项。
+ * 「有哪些工具可选」的清单，带各自会带出哪几个目录。
  *
- * 列出的是**链接目标**（如 .claude/skills），因为用户要判断的正是
- * 「哪些目录可以被这份内容接管」，而不是抽象的"用哪个工具"。
+ * 给的是**配置里该写的名字**在前，中文名和目录在后——用户要回答的问题是
+ * 「links 里填什么」，不是「这个工具叫什么」。
+ *
+ * @param {string[]} [declared] 已经声明了的，标成 ◉
+ */
+function toolTable(declared = []) {
+  const rows = TOOL_NAMES.map((tool) => {
+    const dir = toolDir(tool);
+    const dirs = kindsOf(tool).map((k) => TOOLS[tool].links[k].slice(dir.length + 1));
+    return { tool, dir: `${dir}/{${dirs.join(', ')}}`, on: declared.includes(tool) };
+  });
+  // 宽度按实际内容算——写死数字的话，将来加一个名字长一点的工具就错位了
+  const w = Math.max(...rows.map((r) => r.tool.length));
+  const w2 = Math.max(...rows.map((r) => TOOLS[r.tool].label.length));
+
+  return rows.map(
+    (r) =>
+      `    ${r.on ? '◉' : '◯'} ${r.tool.padEnd(w)}  ${TOOLS[r.tool].label.padEnd(w2)}  ${dim(r.dir)}`,
+  );
+}
+
+/**
+ * 要说清「还有哪些没启用」，光在配置里找不到线索时就得把选项摆出来。
+ * @param {string[]} declared
+ */
+function printToolTable(declared = []) {
+  for (const line of toolTable(declared)) plain(line);
+}
+
+/**
+ * 构造勾选项：**一个工具一项**。
+ *
+ * 粒度就到工具为止——选用一个工具就是它的全部类型一起适配。
+ * 拆到 `.claude/skills` 这一层给不出有用的选择：真正要回答的问题是
+ * 「这个项目用哪几个编码工具」，而不是「哪些目录可以被接管」。
  *
  * 与「怎么问」分开，是为了这一层能单独测试——渲染和按键由 prompt.js 负责。
  *
- * @param {string} cwd @param {string[]} preselected
+ * @param {string} cwd
+ * @param {string[]} [preselected] 已选的工具名。不推断，所以默认一个都不预先勾上——
+ *   预勾是「默认值」，而这里没有默认值，只有「你说了算」。
+ */
+export function buildLinkChoices(cwd, preselected = []) {
+  return TOOL_NAMES.map((tool) => {
+    const kinds = kindsOf(tool);
+    const notes = [];
+
+    const missing = kinds.filter((k) => !fs.existsSync(path.resolve(cwd, CONTENT_ROOT, k)));
+    if (missing.length === kinds.length) {
+      notes.push(`${CONTENT_ROOT}/ 下暂无该工具可用的内容`);
+    } else if (missing.length > 0) {
+      notes.push(`暂无内容：${missing.join('、')}`);
+    }
+    const dir = toolDir(tool);
+    if (!fs.existsSync(path.resolve(cwd, dir))) notes.push(`会新建 ${dir}/`);
+
+    const subs = kinds.map((k) => TOOLS[tool].links[k].slice(dir.length + 1));
+
+    return {
+      value: tool,
+      label: `${TOOLS[tool].label} · ${dir}/{${subs.join(', ')}}`,
+      note: notes.length > 0 ? `（${notes.join('，')}）` : '',
+      checked: preselected.includes(tool),
+    };
+  });
+}
+
+/**
+ * 建一条链接的完整流程：看现状 → 清理该清的 → 建 → 校验。
+ *
+ * 两条入口共用同一份安全逻辑：读 agents.json 的批量模式，和命令行 `--src`/`--dst`
+ * 的直连模式。**不能各写一份**——「拒绝覆盖实体目录」「只删链接」「创建后校验」
+ * 是这个工具的安全底线，抄成两份，将来改一处漏一处是迟早的事。
+ *
+ * 打印留在这里（每条的状态本来就是给人看的），计数交给调用方：批量模式要分
+ * 「新建 / 已存在 / 有问题」统计，直连模式只有一条，用不上那些计数器。
+ *
+ * @param {{label: string, source: string, target: string, rel: string, srcLabel: string}} item
+ *   `label` 是打印前缀；`rel` / `srcLabel` 是给人看的路径写法（批量模式写
+ *   `.agents/skills`，直连模式写相对工作目录的路径）
+ * @param {{dryRun: boolean, force: boolean}} opts
+ * @returns {{status: 'healthy'|'created'|'would-create'|'failed', problem?: string}}
  */
-export function buildLinkChoices(cwd, preselected) {
-  /** @type {{value: string, label: string, note: string, checked: boolean}[]} */
-  const choices = [];
-
-  for (const tool of TOOL_NAMES) {
-    const toolDirExists = fs.existsSync(path.resolve(cwd, `.${tool}`));
-    for (const kind of kindsOf(tool)) {
-      const spec = specOf(tool, kind);
-      const notes = [];
-      if (!fs.existsSync(path.resolve(cwd, CONTENT_ROOT, kind))) {
-        notes.push(`${CONTENT_ROOT}/${kind}/ 暂无内容`);
+function applyOne({ label, source, target, rel, srcLabel }, { dryRun, force }) {
+  const before = inspect(target, source);
+
+  if (before.status === STATUS.HEALTHY) {
+    ok(`${label}  已是最新`);
+    return { status: 'healthy' };
+  }
+
+  // 位置被实体目录/文件占了，绝不覆盖——那可能是用户自己的东西。
+  //
+  // 光说「拒绝覆盖」是把人晾在半路上：他不知道**后果**（这类内容根本没生效，
+  // 工具里看不到），也不知道**下一步做什么**，还可能去试一个没用的开关
+  // （--force 只对 ELSEWHERE 生效，对实体路径无效）。三件事一次说完。
+  if (before.status === STATUS.REPLACED) {
+    fail(`${label}  已存在实体目录/文件，不是链接，拒绝覆盖`);
+    plain(dim(`     ${srcLabel} 的内容不会生效；--force 对它也无效（不替你做删除决定）`));
+    plain(dim(`     想接管：把 ${rel} 的内容挪进 ${srcLabel}，再删掉 ${rel}`));
+    return {
+      status: 'failed',
+      problem: `${rel} 是实体目录，${srcLabel} 的内容未生效；挪走它并重跑 link 可接管`,
+    };
+  }
+
+  if (before.status === STATUS.ELSEWHERE && !force) {
+    fail(`${label}  已是指向别处的链接 → ${before.actual}`);
+    // 直连模式（`link --src/--dst`）建的链接正好落进这一支。得说清 `--force`
+    // 是**换掉**它而不是「修好」它——否则这句提示会被当成一个修问题的按钮，
+    // 把用户昨天特意建的那条链接顺手覆盖掉，还以为自己是在修配置。
+    plain(dim('     它可能是你特意建的（link --src/--dst），也可能是别处留的'));
+    plain(dim(`     --force 会把它换成指向 ${srcLabel}，原来那条链接就没了`));
+    return { status: 'failed', problem: `${rel} 指向别处；确认要换成 ${srcLabel} 再加 --force` };
+  }
+
+  // 走到这里只可能是 ABSENT / BROKEN / (ELSEWHERE + --force)，
+  // 三种情况都只涉及链接本身，删除是安全的
+  if (before.status === STATUS.BROKEN || before.status === STATUS.ELSEWHERE) {
+    if (dryRun) {
+      info(`${label}  将先移除现有链接（${before.status === STATUS.BROKEN ? '断链' : '指向别处'}）`);
+    } else {
+      const removed = removeLink(target);
+      if (!removed.ok) {
+        fail(`${label}  移除旧链接失败：${removed.message}`);
+        return { status: 'failed', problem: `${rel}：${removed.message}` };
       }
-      if (!toolDirExists) notes.push(`会新建 .${tool}/`);
-
-      choices.push({
-        value: spec,
-        label: `${TOOLS[tool].label} · ${TOOLS[tool].links[kind]}`,
-        note: notes.length > 0 ? `（${notes.join('，')}）` : '',
-        checked: preselected.includes(spec),
-      });
     }
   }
-  return choices;
+
+  const res = createLink(source, target, { dryRun });
+  if (!res.ok) {
+    fail(`${label}  创建失败：${res.message}`);
+    return { status: 'failed', problem: `${rel}：${res.message}` };
+  }
+
+  if (dryRun) {
+    info(`${label}  将创建 → ${srcLabel}`);
+    return { status: 'would-create' };
+  }
+
+  const after = inspect(target, source);
+  if (after.status === STATUS.HEALTHY) {
+    ok(`${label}  已创建`);
+    return { status: 'created' };
+  }
+  fail(`${label}  创建后校验失败（状态：${after.status}）`);
+  return { status: 'failed', problem: `${rel}：创建后校验未通过` };
+}
+
+/**
+ * `--src` / `--dst` 直连模式：在这儿建一条链接，**完全不碰项目配置**。
+ *
+ * 存在的理由和批量模式不同。批量模式回答「这个项目适配哪些工具」，内容有固定的
+ * 家（`.agents/<kind>/`）；这里回答的是「就这一处，建个链接」，源和目标都可以在
+ * 项目外，跟 `.agents/`、`agents.json` 全无关系。
+ *
+ * 因此也**不纳入托管**：不写 .gitignore 托管段、不进 `.agent-sync.json` 记录、
+ * `status` 看不见它、`--prune` 不碰它。这是刻意的——托管那套的前提是「内容都从
+ * `.agents/` 来」，硬把一条任意路径塞进去，等于让每个子系统都得认识一个例外。
+ * 想被管起来，把内容放进 `.agents/` 走批量模式。
+ *
+ * 相对路径按 `cwd` 解析：用户敲命令时看的就是当前目录。
+ *
+ * ⚠️ 不写托管段是有代价的：如果落点在某个 git 仓库里，git 会**穿透链接**把源的
+ * 内容在仓库里再提交一份。所以结尾要提醒一句。
+ *
+ * @param {{cwd: string, src: string|null, dst: string|null, dryRun: boolean, force: boolean, prune: boolean}} opts
+ */
+function runDirect({ cwd, src, dst, dryRun, force, prune }) {
+  title(`agent-syncer link --src/--dst${dryRun ? dim('（--dry-run，不会写盘）') : ''}`);
+  plain(dim(`工作目录：${cwd}`));
+
+  if (src === null || dst === null) {
+    fail(`--src 和 --dst 要一起给（少了 --${src === null ? 'src' : 'dst'}）`);
+    plain('  只给一个不知道该建什么——源和落点是两件事，都得说。例如：');
+    plain(dim('    agent-syncer link --src=../shared/prompts --dst=.claude/skills'));
+    plain(dim('  相对路径按上面那个工作目录解析，绝对路径原样用。'));
+    return 1;
+  }
+
+  if (prune) {
+    warn('--prune 是批量模式的选项，这里用不上——直连模式不托管任何东西');
+  }
+
+  const source = path.resolve(cwd, src);
+  const target = path.resolve(cwd, dst);
+
+  /**
+   * 显示用路径。上一层、上两层都用相对路径——用户刚敲的就是这个写法，
+   * 回显成对得上他才好核对自己有没有搞反方向。爬得太远（一串 `../` 数不清）
+   * 或者跨盘（Windows 上 `path.relative` 这时直接返回绝对路径）才写绝对的。
+   */
+  const shown = (p) => {
+    const r = path.relative(cwd, p);
+    if (r === '') return '.';
+    const up = r.split(path.sep).filter((s) => s === '..').length;
+    return up <= 2 ? r : p;
+  };
+
+  const rel = shown(target);
+  const srcLabel = shown(source);
+  plain(`\n${srcLabel} ${dim('→')} ${rel}\n`);
+
+  const r = applyOne({ label: rel, source, target, rel, srcLabel }, { dryRun, force });
+
+  if (r.status === 'failed') {
+    title('需要你处理');
+    plain(`  · ${r.problem}`);
+    return 1;
+  }
+
+  plain(dim('\n这条链接不在托管范围内：status 看不到它，--prune 也不会清理它。'));
+  // 反过来的那一面：落点正好落在工具托管目录里时，批量模式会把它当成「指向别处」
+  // 而拒绝接管。先说一句，免得用户照那句「加 --force 覆盖」把自己这条换掉。
+  const inToolDir = TOOL_NAMES.some((t) => {
+    const dir = path.resolve(cwd, toolDir(t));
+    return target !== dir && target.startsWith(dir + path.sep);
+  });
+  if (inToolDir) {
+    plain(dim('注意：这个落点在某个工具的托管目录里——之后跑批量 link 会认为它「指向别处」'));
+    plain(dim('      而拒绝接管。那是它在保护这条链接，别照着 --force 的提示把它覆盖掉。'));
+  }
+  if (dryRun) plain(dim('这是预演，未写盘。去掉 --dry-run 即可实际执行。'));
+  return 0;
 }
 
 /**
  * agent-syncer link —— 建好所有目录链接，并维护 .gitignore 的托管段。
  *
+ * 除了「建」还有一步「反向检查」：以前建过、这次配置里不再需要的链接会被列出来
+ * （见 stale.js）。默认只报告，加 --prune 才删——**且只删链接**。
+ *
  * 安全底线：**绝不删除实体目录或实体文件**。
  * 路径上已有非链接的东西时一律拒绝并报错，交由用户自己处置。
  *
@@ -57,8 +265,19 @@ export function buildLinkChoices(cwd, preselected) {
 export async function run({ cwd, flags, input = process.stdin, output = process.stdout }) {
   const dryRun = Boolean(flags['dry-run']);
   const force = Boolean(flags.force);
+
+  // --src / --dst 是另一条路：在这儿建一条链接，和项目配置毫无关系。
+  // 所以必须在「.agents/ 存不存在」这类项目检查**之前**分流——直连模式完全可以
+  // 在一个没有 .agents/、没有 agents.json 的目录里跑，那正是它的用处。
+  const src = typeof flags.src === 'string' ? flags.src : null;
+  const dst = typeof flags.dst === 'string' ? flags.dst : null;
+  if (src !== null || dst !== null) {
+    return runDirect({ cwd, src, dst, dryRun, force, prune: Boolean(flags.prune) });
+  }
+
   const assumeYes = Boolean(flags.yes);
   const noSave = Boolean(flags['no-save']);
+  const prune = Boolean(flags.prune);
 
   title(`agent-syncer link${dryRun ? dim('（--dry-run，不会写盘）') : ''}`);
   plain(dim(`项目根：${cwd}`));
@@ -72,48 +291,85 @@ export async function run({ cwd, flags, input = process.stdin, output = process.
 
   let config = loadConfig(cwd);
 
-  // 没有配置：交互式问一次，并把答案记下来，下次不再问
-  if (!config.exists && !assumeYes) {
-    if (!isInteractive(input, output)) {
-      warn(`未找到 ${CONFIG_FILENAME}，且当前不是交互终端——按已有目录推断`);
-      warn(`  推断结果：${config.links.join('、') || '（空）'}`);
-      plain(dim('  想自己选，请在终端里直接运行；或先手写一个 agents.json。'));
-    } else {
-      plain('');
-      const picked = await checkbox({
-        message: `没有找到 ${CONFIG_FILENAME}，请勾选要建立链接的目录：`,
-        choices: buildLinkChoices(cwd, config.links),
-        input,
-        output,
-      });
-
-      if (picked === null) {
-        plain(dim('已取消，未做任何改动。'));
-        return 0;
-      }
-      if (picked.length === 0) {
-        warn('没有勾选任何目录，无事可做');
-        return 0;
-      }
+  // 没声明过用哪些工具。**不猜**——「这个项目用 Trae」是个持久事实，
+  // 从「目录恰好存在」推出来的东西用户既没同意过也看不见，猜错还会给一个
+  // 其实不用的工具建链接。能做到的就是：问，或者把选项和写法摆出来。
+  if (!config.toolsDeclared) {
+    if (assumeYes || !isInteractive(input, output)) {
+      fail('不知道要给哪些工具建链接');
+      plain(
+        config.exists
+          ? `  ${CONFIG_FILENAME} 里没有 ${dim('links')}。`
+          : `  没有找到 ${CONFIG_FILENAME}。`,
+      );
+      plain(
+        assumeYes
+          ? dim('  --yes 只是「不询问」，它不负责猜——先把 links 写进配置。')
+          : '  当前不是交互终端，没法问你。',
+      );
 
-      if (dryRun || noSave) {
-        info(`将要建立 ${picked.length} 个链接（${dryRun ? '--dry-run' : '--no-save'}：不写入 ${CONFIG_FILENAME}）`);
-      } else {
-        const p = saveConfig(cwd, picked);
-        ok(`${CONFIG_FILENAME} 已写入 → ${path.relative(cwd, p)}`);
-      }
-      config = { ...config, links: picked, exists: true };
+      plain('\n  两种做法：');
+      plain(`    · 在 ${CONFIG_FILENAME} 里写一行，之后不用再管（推荐）`);
+      plain(dim('        "links": ["claude"]'));
+      plain('    · 或者在终端里直接跑 agent-syncer link，会列出来让你勾选');
+
+      plain(`\n  可用工具（${dim('links')} 里写名字，要多个就写成数组）：`);
+      printToolTable();
+
+      plain(dim('    例如： "links": ["claude", "trae"]'));
+      return 1;
+    }
+
+    plain('');
+    const picked = await checkbox({
+      message: config.exists
+        ? `${CONFIG_FILENAME} 里没有 links，请勾选这个项目使用哪些编码工具：`
+        : `没有找到 ${CONFIG_FILENAME}，请勾选这个项目使用哪些编码工具：`,
+      choices: buildLinkChoices(cwd),
+      input,
+      output,
+    });
+
+    if (picked === null) {
+      plain(dim('已取消，未做任何改动。'));
+      return 0;
+    }
+    if (picked.length === 0) {
+      warn('没有勾选任何工具，无事可做');
+      return 0;
     }
+
+    if (dryRun || noSave) {
+      info(`选中 ${picked.length} 个工具（${dryRun ? '--dry-run' : '--no-save'}：不写入 ${CONFIG_FILENAME}）`);
+    } else {
+      const p = saveConfig(cwd, picked);
+      ok(`${CONFIG_FILENAME} 已写入 → ${path.relative(cwd, p)}`);
+    }
+    config = { ...config, tools: picked, specs: specsOfTools(picked), exists: true, toolsDeclared: true };
   }
 
   for (const w of config.warnings) warn(w);
 
-  if (config.links.length === 0) {
-    warn('没有任何要建立的链接，无事可做');
+  // 用户是在一个工具都没声明的情况下进来的；显式写 "links": [] 是另一回事，
+  // 那是「我就要一个都不建」，照旧按无事可做处理
+  if (config.tools.length === 0) {
+    warn('没有选中任何工具，无事可做');
     return 0;
   }
 
-  const plan = plannedLinks(cwd, config.links);
+  // 顺带说一声还有哪些没启用——不然用户不一定会想到可以同时适配多个工具
+  ok(`工具：${config.tools.map((t) => `${t}（${TOOLS[t].label}）`).join('、')}`);
+  const rest = TOOL_NAMES.filter((t) => !config.tools.includes(t));
+  if (rest.length > 0) {
+    plain(
+      dim(
+        `   还支持 ${rest.map((t) => `${t}（${TOOLS[t].label}）`).join('、')}` +
+          `——想一起适配就加进 ${CONFIG_FILENAME} 的 "links"`,
+      ),
+    );
+  }
+
+  const plan = plannedLinks(cwd, config.specs);
   let created = 0;
   let alreadyOk = 0;
   let skipped = 0;
@@ -129,64 +385,79 @@ export async function run({ cwd, flags, input = process.stdin, output = process.
       continue;
     }
 
-    const before = inspect(item.target, item.source);
+    const r = applyOne(
+      {
+        label,
+        source: item.source,
+        target: item.target,
+        rel: item.rel,
+        srcLabel: `${CONTENT_ROOT}/${item.kind}`,
+      },
+      { dryRun, force },
+    );
 
-    if (before.status === STATUS.HEALTHY) {
-      ok(`${label}  已是最新`);
-      alreadyOk += 1;
-      continue;
-    }
-
-    if (before.status === STATUS.REPLACED) {
-      fail(`${label}  已存在实体目录/文件，拒绝覆盖`);
-      problems.push(`${item.rel} 是实体目录，请自行处理后再运行`);
-      continue;
-    }
+    if (r.status === 'healthy') alreadyOk += 1;
+    else if (r.status === 'created') created += 1;
+    else if (r.status === 'failed') problems.push(/** @type {string} */ (r.problem));
+  }
 
-    if (before.status === STATUS.ELSEWHERE && !force) {
-      fail(`${label}  已是指向别处的链接 → ${before.actual}`);
-      problems.push(`${item.rel} 指向别处，确认无误后加 --force 覆盖`);
-      continue;
-    }
+  // ---- 反向检查：以前建过、这次配置里不再需要的链接 ----
+  //
+  // link 只加不减，把工具从 links 里去掉不会动已建好的 junction，而托管段已经
+  // 不忽略它们了——git 会顺着这些链接把 .agents/ 的内容再提交一份。
+  //
+  // 默认只报告：分不清这是刚去掉的残留，还是用户自己建的链接。加 --prune 才删，
+  // 且 removeLink 本身就拒绝删实体目录，误伤不了用户自己的东西。
+  const stale = findStaleLinks(cwd, config.tools);
+  let pruned = 0;
+  // 链接删完之后空掉、并真的被收走的工具目录（如 .trae/）
+  /** @type {string[]} */
+  const emptied = [];
 
-    // 走到这里只可能是 ABSENT / BROKEN / (ELSEWHERE + --force)，
-    // 三种情况都只涉及链接本身，删除是安全的
-    if (before.status === STATUS.BROKEN || before.status === STATUS.ELSEWHERE) {
-      if (dryRun) {
-        info(`${label}  将先移除现有链接（${before.status === STATUS.BROKEN ? '断链' : '指向别处'}）`);
-      } else {
-        const removed = removeLink(item.target);
+  if (stale.length > 0) {
+    if (prune) {
+      for (const s of stale) {
+        const label = `${TOOLS[s.tool].label} ${dim('·')} ${s.rel}  ${dim('不再需要')}`;
+        if (dryRun) {
+          info(`${label}  将删除`);
+          continue;
+        }
+        const removed = removeLink(s.target);
         if (!removed.ok) {
-          fail(`${label}  移除旧链接失败：${removed.message}`);
-          problems.push(`${item.rel}：${removed.message}`);
+          fail(`${label}  删除失败：${removed.message}`);
+          problems.push(`${s.rel}：${removed.message}`);
           continue;
         }
+        if (removed.action === 'removed') {
+          ok(`${label}  已删除`);
+          pruned += 1;
+        } else {
+          info(`${label}  已不存在`);
+        }
       }
-    }
-
-    const res = createLink(item.source, item.target, { dryRun });
-    if (!res.ok) {
-      fail(`${label}  创建失败：${res.message}`);
-      problems.push(`${item.rel}：${res.message}`);
-      continue;
-    }
 
-    if (dryRun) {
-      info(`${label}  将创建 → ${CONTENT_ROOT}/${item.kind}`);
-    } else {
-      const after = inspect(item.target, item.source);
-      if (after.status === STATUS.HEALTHY) {
-        ok(`${label}  已创建`);
-        created += 1;
-      } else {
-        fail(`${label}  创建后校验失败（状态：${after.status}）`);
-        problems.push(`${item.rel}：创建后校验未通过`);
+      // 收掉因此空掉的工具目录。留着不影响版本库（git 不跟踪空目录），
+      // 但 doctor 见到 `.trae/` 还在就会报「目录存在，但未在 links 里声明」，
+      // 而这只是上一轮的残渣——白白让人以为自己配置写漏了。
+      // 非空目录一个都删不掉（rmdir 只对空目录成功），工具目录里有用户自己的
+      // 东西时天然安全。
+      if (!dryRun) {
+        for (const tool of new Set(stale.map((s) => s.tool))) {
+          const rel = toolDir(tool);
+          if (rmdirIfEmpty(path.resolve(cwd, rel))) emptied.push(rel);
+        }
+        if (emptied.length > 0) info(`顺带收掉空目录：${emptied.join('、')}`);
       }
+    } else {
+      warn(`发现 ${stale.length} 个不再使用的链接——不会自动删除`);
+      for (const s of stale) plain(dim(`    · ${s.rel}  →  ${CONTENT_ROOT}/${s.kind}`));
+      plain(dim('    它们已不在 .gitignore 托管段里，留着会让 git 把内容重复提交一份。'));
+      plain(dim('    确认不需要后加 --prune 删除（只删链接，不动实体目录）。'));
     }
   }
 
   // .gitignore：junction 记录绝对路径，必须忽略；否则 git 会穿透链接重复提交内容
-  const gi = writeBlock(cwd, config.links, { dryRun });
+  const gi = writeBlock(cwd, config.tools, { dryRun });
   if (gi.changed) {
     if (dryRun) info(`${dim('.gitignore')}  将写入托管段`);
     else ok(`${dim('.gitignore')}  托管段已更新`);
@@ -197,6 +468,9 @@ export async function run({ cwd, flags, input = process.stdin, output = process.
   title('小结');
   plain(
     `  新创建 ${created}　已存在 ${alreadyOk}　跳过 ${skipped}` +
+      `${pruned ? `　清理 ${pruned}` : ''}` +
+      `${emptied.length ? `　空目录 ${emptied.length}` : ''}` +
+      `${stale.length > 0 && !prune ? `　不再使用 ${stale.length}` : ''}` +
       `${problems.length ? `　问题 ${problems.length}` : ''}`,
   );
 
@@ -208,6 +482,8 @@ export async function run({ cwd, flags, input = process.stdin, output = process.
 
   if (dryRun) {
     plain(dim('\n这是预演，未写盘。去掉 --dry-run 即可实际执行。'));
+  } else if (stale.length > 0 && !prune) {
+    plain(dim('\n提示：不再使用的链接还留在原处，确认后运行 agent-syncer link --prune 清理。'));
   } else if (created > 0) {
     plain(dim('\n提示：这些链接已加入 .gitignore，别把它们提交上去。'));
   }