agent-syncer 0.1.0 → 0.1.2

package/lib/commands/list.js

@@ -0,0 +1,214 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_FILENAME, loadConfig } from '../config.js';
+import { dim, fail, info, ok, plain, skip, title, warn } from '../log.js';
+import {
+  ITEM_KINDS,
+  ITEM_KIND_NAMES,
+  SUPPORT_DIR,
+  listBundles,
+  listItems,
+  loadRepo,
+  resolveSelection,
+} from '../manifest.js';
+import { fetchRepo, isGitUrl, localRefWarning } from '../source.js';
+import { TOOLS, mergeTarget } from '../target.js';
+
+/**
+ * `--kind` 的写法归一成单数类型名。单复数都认——用户平时看的是
+ * `.agents/skills/`（复数目录名），而 include 里写的是 `skill:xxx`（单数），
+ * 两套词都得能用，不然就得先查文档才知道该写哪个。
+ *
+ * @param {string} value
+ * @returns {string|null} 认不出来返回 null
+ */
+function normalizeKind(value) {
+  const raw = value.trim().toLowerCase();
+  for (const kind of ITEM_KIND_NAMES) {
+    if (raw === kind || raw === ITEM_KINDS[kind].dir) return kind;
+  }
+  return null;
+}
+
+/**
+ * agent-syncer list —— 列出内容仓库里有哪些**条目**和**模板**。
+ *
+ * 存在的理由很具体：想用 `include` 逐条挑内容（"自定义"用法），得先知道 id 叫什么，
+ * 而在此之前只能去翻内容仓库的文件。`sync` 不带 `--bundle` 时只列模板名，
+ * 不列条目。
+ *
+ * 纯只读，但**不是离线的**——它读的是内容仓库而不是项目里的 `.agents/`，
+ * 因为要回答的问题正是「仓库里有什么可以挑」。内容仓库是 git 地址时先浅克隆。
+ *
+ * @param {{cwd: string, flags: Record<string, any>}} ctx
+ */
+export async function run({ cwd, flags }) {
+  title('agent-syncer list');
+  plain(dim(`项目根：${cwd}`));
+
+  const config = loadConfig(cwd);
+  const sourceArg = typeof flags.from === 'string' ? flags.from : config.content;
+  if (!sourceArg) {
+    fail('没有指定内容仓库');
+    plain(
+      `  在 ${CONFIG_FILENAME} 里写 ${dim('"content": "<本地路径 或 git 地址>"')}，` +
+        `或用 ${dim('--from=<路径>')}。`,
+    );
+    return 1;
+  }
+
+  const kindFlag = typeof flags.kind === 'string' ? flags.kind : null;
+  /** @type {string|null} */
+  let onlyKind = null;
+  if (kindFlag !== null) {
+    onlyKind = normalizeKind(kindFlag);
+    if (onlyKind === null) {
+      fail(`--kind 不认识 "${kindFlag}"`);
+      plain(dim(`  可用：${ITEM_KIND_NAMES.join('、')}（复数写法也行，如 skills）`));
+      // scripts 不是条目类型，是整目录同步的支撑目录——明说一句，
+      // 否则用户会以为是自己拼错了
+      plain(dim(`  注意 ${SUPPORT_DIR}/ 不是条目类型：它整目录同步，不参与 include / exclude。`));
+      return 1;
+    }
+  }
+
+  const ref = typeof flags.ref === 'string' ? flags.ref : config.ref;
+  const remote = isGitUrl(sourceArg);
+
+  // 和 sync 同一句话：ref 只对 git 地址生效，本地路径读的是那个目录的工作树。
+  // 两条命令对同一份配置给出不同的说法，比不说更让人糊涂。
+  const refWarning = localRefWarning(sourceArg, ref);
+  if (refWarning) warn(refWarning);
+  /** @type {(() => void)|null} */
+  let cleanup = null;
+
+  try {
+    /** @type {string} */
+    let repoRoot;
+    if (remote) {
+      info(`拉取 ${sourceArg}${ref ? ` @ ${ref}` : ''} …`);
+      try {
+        const fetched = fetchRepo({ url: sourceArg, ref });
+        repoRoot = fetched.root;
+        cleanup = fetched.cleanup;
+      } catch (e) {
+        fail(/** @type {Error} */ (e).message);
+        return 1;
+      }
+    } else {
+      repoRoot = path.resolve(cwd, sourceArg);
+    }
+
+    /** @type {{name: string, version?: string}} */
+    let repo;
+    try {
+      repo = loadRepo(repoRoot);
+    } catch (e) {
+      fail(/** @type {Error} */ (e).message);
+      return 1;
+    }
+    ok(
+      `内容仓库：${repo.name}${repo.version ? ` v${repo.version}` : ''}  ` +
+        dim(remote ? `${sourceArg}${ref ? ` @ ${ref}` : ''}` : repoRoot),
+    );
+
+    // ---- 条目 ----
+    const items = listItems(repoRoot);
+    title(onlyKind === null ? '条目' : `条目 · ${onlyKind}`);
+
+    const kinds = onlyKind === null ? ITEM_KIND_NAMES : [onlyKind];
+    let total = 0;
+    /** @type {string[]} */
+    const withContent = [];
+    for (const kind of kinds) {
+      const ids = items[kind] ?? [];
+      total += ids.length;
+      if (ids.length === 0) {
+        skip(`${kind.padEnd(10)} 没有`);
+        continue;
+      }
+      withContent.push(kind);
+      ok(`${kind.padEnd(10)} ${ids.length} 个`);
+      for (const id of ids) plain(`    ${id}`);
+    }
+    if (total === 0) {
+      plain(dim(onlyKind === null ? '  仓库里还没有任何条目。' : '  这一类里还没有任何条目。'));
+    }
+
+    // hooks / mcp 不是链接，是被**合并**进工具自己的配置文件的——说清楚，
+    // 不然用户挑了半天才发现某个工具根本没有对应机制。
+    // 注意类型名是**单数**（`hook`），别写成目录名 `hooks`。
+    const mergedKinds = withContent.filter((k) => k === 'hook' || k === 'mcp');
+    if (mergedKinds.length > 0) {
+      const dirs = mergedKinds.map((k) => ITEM_KINDS[k].dir);
+      info(`${mergedKinds.join(' / ')} 会合并进工具自己的配置文件，不是链接`);
+      for (const tool of config.tools) {
+        const missing = dirs.filter((d) => !mergeTarget(tool, d));
+        if (missing.length > 0) {
+          warn(`${TOOLS[tool].label} 没有 ${missing.join(' / ')} 的合并目标——装了不会生效`);
+        }
+      }
+    }
+    // scripts/ 不在上面那张表里（它不是条目类型），但用户找 hook 的脚本时会找它
+    if (fs.existsSync(path.resolve(repoRoot, SUPPORT_DIR))) {
+      info(`${SUPPORT_DIR}/ 整目录同步，不参与 include / exclude`);
+    }
+
+    // ---- 某个模板到底装了些什么 ----
+    //
+    // 和「列条目」是两个不同的问题：条目是「有哪些可挑」，模板是「这个组合
+    // 实际挑了哪些」。后者不展开就只能去读 bundles/*.json。
+    if (typeof flags.bundle === 'string' && flags.bundle.trim() !== '') {
+      const name = flags.bundle.trim();
+      title(`模板 ${name} 的最终内容`);
+      try {
+        const { items: resolved, dropped } = resolveSelection(repoRoot, {
+          bundles: [name],
+          include: config.include,
+          exclude: config.exclude,
+        });
+        if (resolved.length === 0) {
+          warn('这个模板（叠加项目级 include / exclude 之后）是空的');
+        } else {
+          ok(`${resolved.length} 个条目`);
+          for (const it of resolved) plain(`    ${it}`);
+        }
+        // 项目级的 include / exclude 会改结果，说一句免得和仓库文件对不上
+        const extra = [];
+        if (config.include.length > 0) extra.push(`include ${config.include.length} 条`);
+        if (dropped.length > 0) extra.push(`exclude 砍掉 ${dropped.length} 条`);
+        if (extra.length > 0) plain(dim(`    （含本项目的 ${extra.join('、')}）`));
+      } catch (e) {
+        fail(/** @type {Error} */ (e).message);
+        return 1;
+      }
+    }
+
+    // ---- 模板 ----
+    if (onlyKind === null) {
+      title('模板');
+      const bundles = listBundles(repoRoot);
+      if (bundles.length === 0) {
+        skip('仓库里没有任何模板（只能靠 include 逐条挑）');
+      } else {
+        // 宽度按实际内容算——写死数字的话，加一个名字长一点的模板就错位了
+        const w = Math.max(...bundles.map((b) => b.name.length));
+        const w2 = Math.max(...bundles.map((b) => (b.title ?? '').length));
+        for (const b of bundles) {
+          plain(`  ${b.name.padEnd(w)}  ${(b.title ?? '').padEnd(w2)}  ${dim(b.description ?? '')}`);
+        }
+      }
+    }
+
+    // ---- 怎么用 ----
+    plain('');
+    plain(dim('  条目名写进 agents.json 的 "include"，模板名写进 "bundle"：'));
+    plain(dim('      "include": ["skill:<名字>"]        "bundle": "<模板名>"'));
+    if (onlyKind === null) plain(dim('  只看一类：agent-syncer list --kind=skill'));
+    return 0;
+  } finally {
+    // 拉下来的临时目录用完即删——无论成功、失败还是抛错
+    if (cleanup) cleanup();
+  }
+}

package/lib/commands/status.js

@@ -1,37 +1,60 @@
 // @ts-check
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadConfig } from '../config.js';
+import { CONFIG_FILENAME, loadConfig } from '../config.js';
 import { checkBlock } from '../gitignore.js';
 import { STATUS, inspect } from '../link.js';
-import { dim, fail, info, ok, plain, skip, title, warn } from '../log.js';
-import { CONTENT_ROOT, KINDS, TOOLS, plannedLinks } from '../target.js';
+import { dim, fail, info, ok, plain, rel, skip, title, warn } from '../log.js';
+import { checkMergeView, isMissingPath } from '../merge.js';
+import { RECORD_REL, checkRecord, readRecord, unparsableKeys } from '../record.js';
+import { findStaleLinks, findStaleMerges } from '../stale.js';
+import { CONTENT_DIRS, CONTENT_ROOT, TOOLS, TOOL_NAMES, plannedLinks } from '../target.js';
 
-/** 统一的相对路径显示（正斜杠，跨平台一致） */
-const rel = (from, to) => path.relative(from, to).split(path.sep).join('/');
+/**
+ * 一个路径是「不存在」「读不了」还是「在」。
+ *
+ * 判据和 `merge.js` 的 `presentIn` 是同一个（`isMissingPath`）：**只有
+ * `ENOENT` / `ENOTDIR` 算不存在**，权限错、IO 错一律算读不到。
+ *
+ * @param {string} p @returns {'ok' | 'missing' | 'unreadable'}
+ */
+function pathState(p) {
+  try {
+    return fs.statSync(p).isDirectory() ? 'ok' : 'missing';
+  } catch (e) {
+    return isMissingPath(e) ? 'missing' : 'unreadable';
+  }
+}
 
-/** 统计目录下的条目数；目录不存在返回 null */
+/**
+ * 统计目录下的条目数。
+ *
+ * 「读不了」和「不存在」分开报，理由见上面 `pathState`：「无此目录」说的是
+ * 「这儿没东西」，而读不到时我们唯一知道的是「这儿的东西我看不到」——
+ * 这两句话对用户的意义完全不同。
+ *
+ * @param {string} dir @returns {{state: 'ok', count: number} | {state: 'missing' | 'unreadable'}}
+ */
 function countEntries(dir) {
   try {
-    return fs.readdirSync(dir).length;
-  } catch {
-    return null;
+    return { state: /** @type {const} */ ('ok'), count: fs.readdirSync(dir).length };
+  } catch (e) {
+    return { state: isMissingPath(e) ? 'missing' : 'unreadable' };
   }
 }
 
-const KIND_LABEL = {
-  skills: 'skills',
-  rules: 'rules',
-  commands: 'commands',
-  agents: 'agents',
-};
-
 /**
  * agent-syncer status —— 纯只读。报告内容清单与每个链接的健康状况。
  * @param {{cwd: string, flags: Record<string, any>}} ctx
  */
 export async function run({ cwd }) {
   const config = loadConfig(cwd);
+  /**
+   * 需要用户处理的问题。**唯一的退出码来源**——「内容存在但没生效」之类
+   * 不算问题（那是设计如此），只有「和配置描述的状态对不上」才算。
+   * @type {string[]}
+   */
+  const problems = [];
 
   title('agent-syncer status');
   plain(dim(`项目根：${cwd}`));
@@ -39,34 +62,184 @@ export async function run({ cwd }) {
   // ---- 内容 ----
   title(`内容（${CONTENT_ROOT}/）`);
   const contentRoot = path.resolve(cwd, CONTENT_ROOT);
-  if (!fs.existsSync(contentRoot)) {
+  // `fs.existsSync` 在这里不能用：它对**任何**错误都返回 false，于是权限错会被
+  // 报成「还没有任何内容」——和下一层那个「无此目录」是同一个病，只是高了一层。
+  const rootState = pathState(contentRoot);
+  if (rootState === 'unreadable') {
+    warn(`${CONTENT_ROOT}/ 读不了——里面有什么，判断不了`);
+  } else if (rootState === 'missing') {
     fail(`${CONTENT_ROOT}/ 不存在——还没有任何内容`);
   } else {
-    for (const kind of KINDS) {
-      const n = countEntries(path.resolve(contentRoot, kind));
-      if (n === null) {
-        skip(`${KIND_LABEL[kind].padEnd(9)} 无此目录`);
-      } else {
-        ok(`${KIND_LABEL[kind].padEnd(9)} ${String(n).padStart(3)} 项`);
+    // 遍历 CONTENT_DIRS 而不是 KINDS：hooks / mcp / scripts 不参与链接，
+    // 但它们同样是 sync 装下来的内容，只报四类会让人以为 sync 把后三类漏了。
+    // doctor 本来就列全部子目录，这里跟上，两条命令的口径才一致。
+    for (const kind of CONTENT_DIRS) {
+      const r = countEntries(path.resolve(contentRoot, kind));
+      const label = kind.padEnd(9);
+      // 空出数字列的宽度，好让这两行和上面的「N 项」对成一张表
+      if (r.state === 'missing') {
+        skip(`${label}    无此目录`);
+        continue;
+      }
+      if (r.state === 'unreadable') {
+        // **不算问题**——和下一节「合并」读不了时一个口径：判断不了的事如实说，
+        // 但不把它变成用户要去点一下的修复项（那会是个他不会采纳的修复）。
+        warn(`${label}    读不了——有多少条目判断不了`);
+        continue;
+      }
+      ok(`${label} ${String(r.count).padStart(3)} 项`);
+    }
+  }
+
+  // ---- 记录：哪些内容是本工具装的 ----
+  //
+  // 这一节回答的是「sync 认不认得这些内容」。不认得的话，内容仓库里删掉的
+  // 条目就永远清不掉——见 record.js 开头那段。status 读不到内容仓库（它是
+  // 离线命令），判断不了「该不该装」，但判断得了「还是不是当初那份」。
+  title(`本工具装的（${RECORD_REL}）`);
+  const record = readRecord(cwd);
+  if (!record.usable) {
+    if (record.reason) warn(record.reason);
+    else plain(dim('  还没有记录。下次 sync 会写下，之后就能认出哪些内容是本工具装的了。'));
+  } else {
+    const tracked = checkRecord(cwd, record);
+    const missing = tracked.filter((t) => !t.exists).length;
+    ok(`跟踪 ${tracked.length} 项`);
+    if (missing > 0) plain(dim(`    其中 ${missing} 项本地已不存在`));
+    if (config.protect.length > 0) {
+      plain(dim(`    另有 ${config.protect.length} 项被 protect 锁住，本工具不覆盖也不删`));
+    }
+    // 名字都解析不了的条目映射不到路径，只能跳过——但**跳过不等于没有这回事**：
+    // 清理功能会因此少管几项，而用户只看到「跟踪 N 项」莫名其妙变少了
+    const broken = unparsableKeys(record);
+    if (broken.length > 0) {
+      warn(`其中 ${broken.length} 项的名字解析不了：${broken.join('、')}`);
+      plain(dim('    它们不会被清理，也不会被覆盖——多半是手改记录时改坏的。'));
+    }
+  }
+
+  // ---- 合并：hooks / mcp 有没有真的写进工具自己的配置 ----
+  //
+  // 这两类不建链接，而是合并进 `.mcp.json` / `.claude/settings.json`。
+  // 五态各有各的说法，别混成一句「有问题」：
+  //   一致 / 还没生成 / 漂移 / 读不了 / 有本工具没动的地方
+  // 判断整个交给 merge.js 的 checkMergeView——doctor 用的是同一份。两个只读
+  // 命令对同一份现场给出相反结论，是以前真出过的事（见 checkMergeAll 的注释）。
+  const view = checkMergeView({ projectRoot: cwd, config, record });
+
+  // 「目录读不出来」和「目录是空的」是两件事，不能一声不吭当成后者：
+  // 前者我们根本不知道里面有什么，也就答不了「该合的合了没有」。
+  // 报一声，但**不算问题**——和下面「记录读不了」一个口径：判断不了的事
+  // 如实说，不把它变成用户要去点一下的修复项（那会是个他不会采纳的修复）。
+  for (const d of view.unreadable) {
+    warn(`${CONTENT_ROOT}/${d}/ 读不了——里面有什么、能不能合，判断不了`);
+  }
+
+  if (config.tools.length > 0 && view.hasWork) {
+    title('合并（hooks / mcp）');
+
+    for (const r of view.rows) {
+      const label = `${TOOLS[r.tool].label} · ${r.rel}`.padEnd(30);
+
+      switch (r.state) {
+        case 'ok':
+          ok(`${label} ${dim('一致')}`);
+          break;
+        case 'missing':
+          skip(`${label} ${dim('还没生成——跑一次 sync')}`);
+          break;
+        case 'drift':
+          warn(`${label} 和 ${CONTENT_ROOT}/ 里的内容对不上`);
+          problems.push(`${r.rel} 漂移了，跑一次 sync 重新合并`);
+          break;
+        case 'unreadable':
+          fail(`${label} ${r.detail}`);
+          problems.push(`${r.rel} ${r.detail}`);
+          break;
+        case 'stale':
+          // 「默认不摘」是设计（和内容层一个口径），所以**不算问题**——
+          // 但得让人知道有这么几条躺着，以及怎么摘。
+          //
+          // 措辞留了余地：里面可能混着**你改过的那几条**，按设计它们不会被摘
+          // （归属要现场对得上才动）。说成「跑 --prune 就没了」会让人以为一次
+          // 就能清干净，跑完发现还在，又不知道该信哪句。
+          warn(`${label} 有 ${r.ids.length} 条不再需要的：${r.ids.join('、')}`);
+          plain(dim('    默认不会摘。确认后跑 sync --prune——你改过的那几条会保留。'));
+          break;
+        default:
+          // 冲突不是「故障」，是「这里有你自己的东西，本工具不碰」。
+          // 不该让 status 退出码变成 1——那会逼着人去点一个他不会采纳的修复。
+          warn(`${label} 有本工具没动的地方`);
+          plain(dim(`    ${r.detail}`));
       }
     }
+
+    // 合并器做完之后，这是唯一还会为「装了没生效」说话的地方
+    for (const u of view.unsupported) {
+      warn(`${TOOLS[u.tool].label} 没有 ${u.dir} 的合并目标——这 ${u.count} 条装了不会生效`);
+    }
+
+    if (config.tools.includes('claude') && (view.present.mcp?.length ?? 0) > 0) {
+      plain(
+        dim('  注意：MCP server 还要在 Claude Code 里逐条批准才生效——批准记录存在本机，不随仓库共享。'),
+      );
+    }
+  }
+
+  // ---- 不再使用的合并产物 ----
+  //
+  // 和上面「不再使用的链接」同构：工具从 links 里去掉了，我们以前写进它配置
+  // 文件里的条目就没人管了——而那个文件是**提交进版本库**的。
+  //
+  // 这一段刻意不放在上面那个 `config.tools.length > 0` 的守卫里：把工具全删光
+  // 恰恰是最会产生这类残留的情形，而它前面还有个「未声明任何工具」的提前返回。
+  const staleMerges = findStaleMerges(cwd, config.tools, record.merged ?? {});
+  if (staleMerges.length > 0) {
+    title('不再使用的合并产物');
+    for (const s of staleMerges) {
+      warn(
+        `${s.rel.padEnd(22)} ${s.ids.length} 条 —— ${TOOLS[s.tool].label} 已不在配置里：${s.ids.join('、')}`,
+      );
+    }
+    plain(dim('  这些是本工具以前合进去的，留着不会再被更新。'));
+    plain(dim('  跑 sync --prune 摘掉（只摘我们写过的那些，你自己的不动）。'));
+    problems.push(`有 ${staleMerges.length} 处合并产物已不再需要，跑 sync --prune 摘掉`);
   }
 
   // ---- 链接 ----
+  //
+  // 收尾统一走这里。**`problems` 是唯一的退出码来源**，任何提前返回都得先把它
+  // 打出来：以前「一个工具都没声明」那条路是直接 `return 0` 的，于是前面几节
+  // （「不再使用的合并产物」正是会走到这一支的情形）攒下的问题会一声不吭地
+  // 消失——连小结都不打。
+  let healthy = 0;
+  let absent = 0;
+  const finish = () => {
+    title('小结');
+    plain(`  健康 ${healthy}　未创建 ${absent}${problems.length ? `　问题 ${problems.length}` : ''}`);
+    if (problems.length > 0) {
+      title('需要你处理');
+      for (const p of problems) plain(`  · ${p}`);
+      return 1;
+    }
+    if (absent > 0) {
+      info(`有 ${absent} 个链接未创建，运行 ${dim('agent-syncer link')} 即可建好`);
+    }
+    return 0;
+  };
+
   if (config.tools.length === 0) {
     title('链接');
-    warn('未声明任何工具');
-    return 0;
+    warn(`未声明任何工具——${CONFIG_FILENAME} 里没有 links`);
+    plain(dim('  可选：' + TOOL_NAMES.join('、')));
+    plain(dim('  写进配置里，或在终端里跑一次 agent-syncer link 让它问你要用哪些。'));
+    return finish();
   }
   if (!config.exists) {
     plain(dim(`（未找到 agents.json：${config.warnings.join('；')}）`));
   }
 
-  const plan = plannedLinks(cwd, config.links);
-  let healthy = 0;
-  let absent = 0;
-  /** @type {string[]} */
-  const problems = [];
+  const plan = plannedLinks(cwd, config.specs);
 
   // 按工具分组展示，读起来比一条长清单清楚
   for (const tool of config.tools) {
@@ -76,6 +249,13 @@ export async function run({ cwd }) {
       const target = rel(cwd, item.target);
       const source = rel(cwd, item.source);
 
+      // 配置里写的是工具名，会带出该工具的全部类型；没有内容的那些 link 根本不会建，
+      // 报成「未创建」会让人以为漏了——它们本来就不适用
+      if (!fs.existsSync(item.source)) {
+        skip(`${target.padEnd(20)} ${dim(`无内容（${source} 不存在）`)}`);
+        continue;
+      }
+
       switch (st.status) {
         case STATUS.HEALTHY:
           ok(`${target.padEnd(20)} ${dim(`→ ${source}`)}`);
@@ -95,7 +275,10 @@ export async function run({ cwd }) {
           break;
         case STATUS.REPLACED:
           warn(`${target.padEnd(20)} 是实体目录/文件，不是链接`);
-          problems.push(`${target} 是实体目录，link 不会覆盖它`);
+          // 和 link 命令一个口径：说清后果（这类内容没生效）和下一步，
+          // 否则用户只知道「不正常」，不知道该做什么
+          plain(dim(`      ${source} 的内容不会生效；link 不会覆盖它，--force 也一样`));
+          problems.push(`${target} 是实体目录，内容未生效；挪走它并重跑 link 可接管`);
           break;
         default:
           fail(`${target.padEnd(20)} 未知状态：${st.status}`);
@@ -104,30 +287,37 @@ export async function run({ cwd }) {
     }
   }
 
+  // ---- 不再使用的链接 ----
+  //
+  // 只遍历 config.tools 的话，被移出配置的工具留下的链接就彻底隐身了——
+  // 而它们恰恰是最危险的一类：托管段已经不忽略它们，git 会顺着链接把
+  // .agents/ 的内容再提交一份，且没有任何提示。
+  const stale = findStaleLinks(cwd, config.tools);
+  if (stale.length > 0) {
+    title('不再使用的链接');
+    for (const s of stale) {
+      const target = rel(cwd, s.target);
+      warn(`${target.padEnd(20)} → ${CONTENT_ROOT}/${s.kind}，但 ${TOOLS[s.tool].label} 已不在配置里`);
+      problems.push(`${target} 已不再需要，运行 link --prune 删除（只删链接）`);
+    }
+    plain(dim('  它们不在 .gitignore 托管段里，留着会让 git 把内容重复提交一份。'));
+  }
+
   // ---- .gitignore ----
   title('.gitignore 托管段');
-  const gi = checkBlock(cwd, config.links);
+  const gi = checkBlock(cwd, config.tools);
   if (!gi.present) {
     warn('未找到 agent-syncer 托管段，运行 link 会写入');
   } else if (gi.missing.length > 0) {
     warn(`托管段已存在，但缺少 ${gi.missing.length} 个条目，运行 link 会补齐`);
     for (const m of gi.missing) plain(dim(`    · ${m}`));
+  } else if (gi.extra.length > 0) {
+    // 托管段是整段重建的，这几行会在下一次 link 时无声消失
+    warn(`托管段里有 ${gi.extra.length} 行不是本工具生成的，运行 link 会被清掉`);
+    for (const e of gi.extra) plain(dim(`    · ${e}`));
   } else {
     ok('完整');
   }
 
-  // ---- 小结 ----
-  title('小结');
-  plain(`  健康 ${healthy}　未创建 ${absent}${problems.length ? `　问题 ${problems.length}` : ''}`);
-
-  if (problems.length > 0) {
-    title('需要你处理');
-    for (const p of problems) plain(`  · ${p}`);
-    return 1;
-  }
-
-  if (absent > 0) {
-    info(`有 ${absent} 个链接未创建，运行 ${dim('agent-syncer link')} 即可建好`);
-  }
-  return 0;
+  return finish();
 }