agent-syncer 0.1.0 → 0.1.2

package/lib/config.js

@@ -1,170 +1,377 @@
 // @ts-check
 import fs from 'node:fs';
 import path from 'node:path';
-import {
-  KINDS,
-  TOOL_NAMES,
-  allSpecs,
-  contentDir,
-  isTool,
-  parseSpec,
-  toolsOfSpecs,
-} from './target.js';
+import { ITEM_KINDS, ITEM_KIND_NAMES, SUPPORT_DIR } from './manifest.js';
+// 借 merge.js 的两样东西：原子写和剥 BOM。
+//
+// 这个文件的依赖方向确实有点逆（config 比 merge 底层），但两个都是**安全原语**
+// ——「tmp + rename」和「JSON 文本怎么读」，再抄一份出来比这个方向更糟：
+// link.js 里还有一份内联的原子写，而 BOM 这件事原先在三处各有一个说法，
+// record.js 那份干脆没有，于是记事本改一下记录就让归属全丢。
+import { isMissingPath, stripBom, writeJsonFile } from './merge.js';
+import { TOOL_NAMES, isTool, sortTools, specsOfTools } from './target.js';
 
 export const CONFIG_FILENAME = 'agents.json';
 
+/**
+ * 读 `agents.json` 的原文。三种结果分得很开，**混起来就是上次那个 blocker**：
+ *
+ * - 文件不存在 → `null`（调用方按「还没配过」处理）
+ * - 有东西但**读不到**（权限 / IO）→ 抛
+ * - 读到了但**不是合法 JSON** → 抛
+ *
+ * 后两种一旦被降级成「不存在」，调用方拿到一份空配置、紧接着就是**整份重写**，
+ * 用户的 `content` / `bundle` / `include` / `protect` 会一次被抹掉。判据和
+ * `merge.js` 里那条一样：读失败装作不存在、然后接着写，是**进攻方向**。
+ *
+ * @param {string} projectRoot
+ * @returns {string|null}
+ */
+function readConfigText(projectRoot) {
+  const p = path.resolve(projectRoot, CONFIG_FILENAME);
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    const err = /** @type {any} */ (e);
+    if (isMissingPath(err)) return null;
+    throw new Error(`${CONFIG_FILENAME} 读不了（${err.code ?? err.message}）：${p}`);
+  }
+}
+
+/**
+ * 解析配置正文。顺带把「顶层必须是一个对象」这条也收在这里——
+ * 它和「不是合法 JSON」是同一类事：文件写得不对，而不是配置项写得不对。
+ *
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+function parseConfigText(text) {
+  /** @type {any} */
+  let parsed;
+  try {
+    parsed = JSON.parse(stripBom(text));
+  } catch (e) {
+    throw new Error(`${CONFIG_FILENAME} 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${CONFIG_FILENAME} 的顶层必须是一个对象`);
+  }
+  return parsed;
+}
+
 /**
  * 读取项目配置 agents.json。
  *
- * 两种写法都支持：
- *   { "links": ["claude/skills", "trae/skills"] }   ← 精确到目录（推荐，交互式勾选写出的就是它）
- *   { "tools": ["claude", "trae"] }                 ← 等价于这些工具的全部条目
+ * links 里写的是**工具名**，不是某个目录：
+ *
+ *   { "links": ["claude", "trae"] }
  *
- * 文件不存在时按「项目里已有哪些工具目录 + .agents/ 下已有哪些内容」推断，
- * 本轮只做推断、不落盘——让交互式命令去问用户。
+ * 选用一个工具就是全量适配——想要 Claude Code 就四个目录一起要，
+ * 没有「只要 .claude/rules 不要 .claude/skills」这种真实场景。
+ * 因此配置里不提供目录级的开关；条目形式（"claude/skills"）只在内部表示里用。
+ *
+ * **完全不做推断。** 没写 links（或者压根没有配置文件）时 `tools` 就是空的，
+ * `toolsDeclared` 为 false，由调用方决定怎么办——`link` 的做法是当场问用户，
+ * 问不了就把可选项和写法列出来。读配置和决定用哪些工具是两件事，不混在一起。
  *
  * @param {string} projectRoot
- * @returns {{links: string[], tools: string[], path: string, exists: boolean, inferred: boolean, warnings: string[]}}
+ * @returns {{tools: string[], specs: string[], content: string|null, ref: string|null, bundles: string[], include: string[], exclude: string[], protect: string[], path: string, exists: boolean, toolsDeclared: boolean, warnings: string[]}}
  */
 export function loadConfig(projectRoot) {
   const cfgPath = path.resolve(projectRoot, CONFIG_FILENAME);
   /** @type {string[]} */
   const warnings = [];
 
-  if (!fs.existsSync(cfgPath)) {
-    const links = inferLinks(projectRoot);
+  const text = readConfigText(projectRoot);
+
+  // 「文件不存在」才走这一条。**读不了是抛错，不是「没有」**——两者混起来，
+  // 调用方会拿一份空配置去整份重写，把用户写的东西抹掉。
+  if (text === null) {
     return {
-      links,
-      tools: toolsOfSpecs(links),
+      tools: [],
+      specs: [],
+      content: null,
+      ref: null,
+      bundles: [],
+      include: [],
+      exclude: [],
+      protect: [],
       path: cfgPath,
       exists: false,
-      inferred: true,
+      toolsDeclared: false,
       warnings,
     };
   }
 
-  /** @type {any} */
-  let raw;
-  try {
-    raw = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-  } catch (e) {
-    throw new Error(`${CONFIG_FILENAME} 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
-  }
-
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new Error(`${CONFIG_FILENAME} 的顶层必须是一个对象`);
-  }
+  const raw = parseConfigText(text);
 
-  /** @type {string[]} */
-  let links;
-  if (raw.links !== undefined) {
-    links = normalizeLinks(raw.links, warnings);
-  } else if (raw.tools !== undefined) {
-    // 与 links 分支保持一致的排序，否则两种写法会产出不同顺序的 diff
-    links = sortSpecs(normalizeTools(raw.tools, warnings).flatMap(allSpecs));
-  } else {
-    warnings.push(`${CONFIG_FILENAME} 里既没有 links 也没有 tools`);
-    links = [];
-  }
+  // 没有 links 就**留空**，不按已有目录猜。「这个项目用 Trae」是个持久事实，
+  // 从「目录恰好存在」猜出来的东西用户既没同意过、也看不见，
+  // 而且猜错的方向很糟：给一个其实不用的工具建了链接。
+  //
+  // 调用方（link）拿到 toolsDeclared === false 时该去问用户，或者告诉他怎么写。
+  const toolsDeclared = raw.links !== undefined;
+  const tools = toolsDeclared ? normalizeLinks(raw.links, warnings) : [];
 
   return {
-    links,
-    tools: toolsOfSpecs(links),
+    tools,
+    specs: specsOfTools(tools),
+    // sync 用：内容来源、版本与选中的模板。
+    // content 既可以是本地路径，也可以是 git 地址，由 source.js 自动判别。
+    content: typeof raw.content === 'string' ? raw.content.trim() : null,
+    ref: typeof raw.ref === 'string' ? raw.ref.trim() : null,
+    // bundle 允许写一个，也允许写数组（多个模板取并集）
+    bundles: normalizeList(raw.bundle, 'bundle'),
+    // 项目级的增删，叠在模板之上；exclude 最后过一遍
+    include: normalizeListArray(raw.include, 'include'),
+    exclude: normalizeListArray(raw.exclude, 'exclude'),
+    // 锁定的条目：sync 不覆盖也不删。写错了必须立刻报错——
+    // 这是用户用来保护自己劳动成果的声明，静默忽略比报错危险得多
+    protect: normalizeProtect(raw.protect),
     path: cfgPath,
     exists: true,
-    inferred: false,
+    toolsDeclared,
     warnings,
   };
 }
 
 /**
- * 写入配置。按固定顺序（工具顺序 → 内容类型顺序）排列，
+ * 读出配置文件里的**原始对象**，一个字段都不校验、不归一化。
+ *
+ * 两个用处：
+ * - `saveConfig` 靠它保住用户自己写的字段（include / exclude / protect，
+ *   以及本工具还不认识的将来字段）
+ * - `init` 靠它拼出「将要写入的整份配置」给用户过目——那份预览必须和真写下去的
+ *   东西长得一模一样，所以走的是同一份原始数据
+ *
+ * **只有文件真的不存在才返回空对象**，读不了和不是合法 JSON 都**抛**。
+ *
+ * 第一版这里是个 `catch {}`，把三种情况一起降成 `{}`——那是**进攻方向**：
+ * 调用方（`saveConfig`）拿到空对象后紧接着就是整份重写，用户的
+ * `content` / `bundle` / `include` / `protect` 会一次没掉。当时靠「调用方都先
+ * loadConfig 过」来兜底，但那是一条**约定**，不是一道**保证**——多一个调用方
+ * 就多一个漏的机会。判据和 `merge.js` 那条 blocker 完全一样。
+ *
+ * @param {string} projectRoot
+ * @returns {Record<string, any>}
+ */
+export function readConfigRaw(projectRoot) {
+  const text = readConfigText(projectRoot);
+  return text === null ? {} : parseConfigText(text);
+}
+
+/**
+ * 把一份改动叠到已有配置上，返回**要写进文件的完整对象**。纯函数。
+ *
+ * patch 里每个字段都是三态的，这个区别很要紧：
+ *
+ * - `undefined` —— 没问过这一项，**保持文件里的原样**（比如内容仓库不是 git 仓库，
+ *   ref 那一步跳过了，就不能把人家写好的 ref 抹掉）
+ * - `null` —— 明确要清掉这个字段（用户在下拉里选了「不指定」）
+ * - 其它值 —— 覆盖
+ *
+ * `bundle` 清空时**删掉键**而不是写 `[]`：两句话意思一样，但空数组会让
+ * 文件里多一行解释不清的东西。工具名按 TOOL_NAMES 的固定顺序排列，
  * 这样每次勾选后产生的 diff 是稳定的，不会因为点击顺序变来变去。
- * @param {string} projectRoot @param {string[]} links
+ *
+ * @param {Record<string, any>} existing @param {Record<string, any>} patch
+ * @returns {Record<string, any>}
  */
-export function saveConfig(projectRoot, links) {
-  const p = path.resolve(projectRoot, CONFIG_FILENAME);
-  const sorted = sortSpecs(links);
-  fs.writeFileSync(p, `${JSON.stringify({ links: sorted }, null, 2)}\n`);
-  return p;
+export function mergeConfig(existing, patch) {
+  /** @type {Record<string, any>} */
+  const next = { ...existing };
+
+  /** @param {string} key @param {any} value */
+  const set = (key, value) => {
+    if (value === undefined) return;
+    if (value === null || value === '') delete next[key];
+    else next[key] = value;
+  };
+
+  set('content', patch.content);
+  set('ref', patch.ref);
+
+  if (patch.bundle !== undefined) {
+    const list = patch.bundle === null ? [] : normalizeList(patch.bundle, 'bundle');
+    if (list.length === 0) delete next.bundle;
+    // 只选了一个就写成裸字符串：和文档里的例子一致，也省得用户为了加第二个
+    // 模板再去找方括号的位置（loadConfig 两种都认）
+    else next.bundle = list.length === 1 ? list[0] : list;
+  }
+
+  if (patch.links !== undefined) next.links = sortTools(patch.links ?? []);
+
+  return next;
 }
 
-/** 按 工具顺序 → 内容类型顺序 排序并去重 */
-export function sortSpecs(specs) {
-  const parsed = specs.map((s) => ({ spec: s, ...parseSpec(s) }));
-  parsed.sort((a, b) => {
-    const t = TOOL_NAMES.indexOf(a.tool) - TOOL_NAMES.indexOf(b.tool);
-    return t !== 0 ? t : KINDS.indexOf(a.kind) - KINDS.indexOf(b.kind);
-  });
-  return [...new Set(parsed.map((p) => p.spec))];
+/**
+ * 写入配置。会保留文件里已有的其它字段——覆盖式写入是个一旦踩到就很难查的坑
+ * （用户的 include / exclude / protect 会被悄悄抹掉）。
+ *
+ * 两种调用方式都认：
+ *
+ *     saveConfig(root, ['claude'])                 // 老写法：只改 links
+ *     saveConfig(root, { content, ref, bundle, links })   // init 用的完整写法
+ *
+ * 数组是 `{ links }` 的简写，老调用方和测试不必跟着改。
+ *
+ * @param {string} projectRoot
+ * @param {string[]|{content?: string|null, ref?: string|null, bundle?: string[]|string|null, links?: string[]}} config
+ */
+export function saveConfig(projectRoot, config) {
+  const patch = Array.isArray(config) ? { links: config } : config;
+  return writeConfig(projectRoot, mergeConfig(readConfigRaw(projectRoot), patch));
 }
 
 /**
- * 校验并归一化 links 字段
- * @param {unknown} value @param {string[]} warnings
+ * 把一份**已经算好的**配置写下去。原子写（同目录 tmp + rename）。
+ *
+ * 为什么不像 `record.js` / `gitignore.js` 那样直接 `writeFileSync`——那里的分界
+ * 不是「谁高谁低」，而是**这份文件丢了能不能自己重生**：
+ *
+ * | 文件 | 丢了会怎样 |
+ * | --- | --- |
+ * | 链接、合并产物 | 重跑 `sync` / `link` 就回来了 |
+ * | `.agents/.agent-sync.json` | 退化成「不再自动清理」，内容还在 |
+ * | **`agents.json`** | `content` / `ref` / `include` / `exclude` / `protect` **没有第二处能推导出来** |
+ *
+ * 而且 `writeFileSync` 是先截断再写：写到一半崩掉，旧内容**一并没了**，
+ * 此后 `loadConfig` 对**所有**命令都抛「不是合法的 JSON」，整个项目卡死到有人
+ * 手工修好为止。方向是反的，所以这个文件按 `merge.js` 的标准来。
+ *
+ * 单独留一个「写算好的对象」的入口，还为了让 init 的**预览**和**落盘**用的是
+ * 同一个对象，而不是各读一次文件（两次读之间文件可能被别人改）。
+ *
+ * @param {string} projectRoot @param {Record<string, any>} next
+ */
+export function writeConfig(projectRoot, next) {
+  const p = path.resolve(projectRoot, CONFIG_FILENAME);
+  writeJsonFile(p, next);
+  return p;
+}
+
+/**
+ * 字符串列表归一化：去空白、丢空串、去重、保序。
+ *
+ * 字段缺失返回空数组。单个字符串也接受——`"bundle": "common"` 和
+ * `"bundle": ["common"]` 都好写，没有理由要求用户为了加第二个模板先加方括号。
+ *
+ * @param {unknown} value @param {string} field
  * @returns {string[]}
  */
-export function normalizeLinks(value, warnings = []) {
-  if (!Array.isArray(value)) {
-    throw new Error('links 必须是字符串数组，例如 ["claude/skills", "trae/skills"]');
-  }
+function normalizeList(value, field) {
+  if (value === undefined || value === null) return [];
+  const arr = Array.isArray(value) ? value : [value];
   /** @type {string[]} */
   const out = [];
-  for (const item of value) {
+  for (const item of arr) {
     if (typeof item !== 'string') {
-      throw new Error(`links 里出现了非字符串项：${JSON.stringify(item)}`);
+      throw new Error(`${field} 里出现了非字符串项：${JSON.stringify(item)}`);
     }
-    const spec = item.trim();
-    try {
-      parseSpec(spec);
-    } catch (e) {
-      warnings.push(`忽略无效条目 "${item}"：${/** @type {Error} */ (e).message}`);
+    const s = item.trim();
+    if (s !== '' && !out.includes(s)) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * include / exclude 归一化。
+ *
+ * 与 bundle 不同，这里**要求写成数组**——它是给人手写的精细控制，
+ * 写成裸字符串多半是笔误（`"include": "skill:x"`），报错比默默接受好。
+ *
+ * @param {unknown} value @param {string} field
+ * @returns {string[]}
+ */
+function normalizeListArray(value, field) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} 必须是字符串数组，例如 ["skill:api-conventions"]`);
+  }
+  return normalizeList(value, field);
+}
+
+/**
+ * 校验并归一化 protect 字段。
+ *
+ * 条目写成 `"kind:id"`：`"skill:my-customized"`；脚本写成 `"script:相对路径"`，
+ * 和 `sync --prune` 输出里用的是同一套词。
+ *
+ * **不支持 `*` 通配**（对 include / exclude 是支持的）。`protect` 是「这个我要
+ * 自己留着」的声明，`skill:*` 那种整体锁定实际含义是「这个项目不要用 sync」，
+ * 说成通配只会让人以为只是顺手省几个字。要那样就别跑 sync。
+ *
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+function normalizeProtect(value) {
+  const list = normalizeListArray(value, 'protect');
+  for (const entry of list) {
+    const colon = entry.indexOf(':');
+    const kind = colon === -1 ? '' : entry.slice(0, colon).trim();
+    const id = colon === -1 ? '' : entry.slice(colon + 1).trim();
+
+    if (kind === 'script') {
+      if (id === '') throw new Error(`protect 里的 ${JSON.stringify(entry)} 少了脚本路径`);
       continue;
     }
-    if (!out.includes(spec)) out.push(spec);
+    const known = /** @type {Record<string, unknown>} */ (ITEM_KINDS)[kind];
+    if (!known) {
+      throw new Error(
+        `protect 里的 ${JSON.stringify(entry)} 类型不对：应为 "类型:名字"，` +
+          `类型可用 ${ITEM_KIND_NAMES.join('、')}，脚本写 "script:${SUPPORT_DIR}/ 下的相对路径"`,
+      );
+    }
+    if (id === '') throw new Error(`protect 里的 ${JSON.stringify(entry)} 少了名字`);
+    if (id === '*') {
+      throw new Error(
+        `protect 不支持通配：把 ${JSON.stringify(entry)} 拆成具体条目。` +
+          '想整个类型都不让 sync 管，那这个项目就不该跑 sync。',
+      );
+    }
   }
-  return sortSpecs(out);
+  return list;
 }
 
 /**
- * 校验并归一化 tools 字段
+ * 校验并归一化 links 字段。
+ *
+ * 值必须是工具名。写明目录的旧写法（"claude/skills"）直接抛错而不是静默接受：
+ * 用户写下的是一个**比实际行为更窄**的东西，若默默按整个工具处理，
+ * 他事后会以为自己只启用了 skills。这种误解必须当场说清楚。
+ *
  * @param {unknown} value @param {string[]} warnings
  * @returns {string[]}
  */
-export function normalizeTools(value, warnings = []) {
+export function normalizeLinks(value, warnings = []) {
   if (!Array.isArray(value)) {
-    throw new Error('tools 必须是字符串数组，例如 ["claude", "trae", "codex"]');
+    throw new Error('links 必须是字符串数组，例如 ["claude", "trae"]');
   }
   /** @type {string[]} */
   const out = [];
   for (const item of value) {
     if (typeof item !== 'string') {
-      throw new Error(`tools 里出现了非字符串项：${JSON.stringify(item)}`);
+      throw new Error(`links 里出现了非字符串项：${JSON.stringify(item)}`);
     }
     const name = item.trim().toLowerCase();
+    if (name.includes('/')) {
+      throw new Error(
+        `links 里只写工具名：把 "${item.trim()}" 改成 "${name.split('/')[0]}"。\n` +
+          '  选用一个工具就是该工具全部类型的适配，配置里不再细化到单个目录。',
+      );
+    }
     if (!isTool(name)) {
       warnings.push(`忽略未知工具 "${item}"（可用值：${TOOL_NAMES.join(', ')}）`);
       continue;
     }
     if (!out.includes(name)) out.push(name);
   }
-  return out;
+  return sortTools(out);
 }
 
-/**
- * 没有配置时的推断：只推断「工具目录已存在」且「内容目录已存在」的组合。
- * 两者缺一都不猜——多猜一个就会凭空建出一个没人要的目录。
- * @param {string} projectRoot
+/*
+ * 这里本来有一个 inferTools()：项目里存在哪些工具目录，就推断出哪些工具。
+ * 已经删掉了——理由见 loadConfig 里那段注释。别再把它加回来：
+ * 它猜错的代价是**给一个其实不用的工具建了链接**，而用户看不见这件事发生过。
+ * 现在由 link 命令负责问，或者告诉用户怎么写。
  */
-function inferLinks(projectRoot) {
-  /** @type {string[]} */
-  const links = [];
-  for (const tool of TOOL_NAMES) {
-    if (!fs.existsSync(path.resolve(projectRoot, `.${tool}`))) continue;
-    for (const spec of allSpecs(tool)) {
-      const { kind } = parseSpec(spec);
-      if (fs.existsSync(contentDir(projectRoot, kind))) links.push(spec);
-    }
-  }
-  return links;
-}

package/lib/gitignore.js

@@ -1,7 +1,9 @@
 // @ts-check
 import fs from 'node:fs';
 import path from 'node:path';
-import { CONTENT_ROOT, KINDS, TOOLS, parseSpec } from './target.js';
+import { isSymlink } from './link.js';
+import { RECORD_REL } from './record.js';
+import { CONTENT_DIRS, CONTENT_ROOT, TOOLS, kindsOf } from './target.js';
 
 export const BEGIN_MARK = '# >>> agent-sync >>>';
 export const END_MARK = '# <<< agent-sync <<<';
@@ -13,15 +15,19 @@ export const END_MARK = '# <<< agent-sync <<<';
  * 提交上去在别人的机器上全是错的；更危险的是 git 会**穿透链接**，
  * 把 .agents/ 里的内容原样再提交一份，仓库里出现两套内容。
  *
- * 只忽略**确实建了链接**的目录：如果某个目录是用户自己的实体目录，
- * 忽略它会导致内容进不了版本库，那是帮倒忙。
+ * 只忽略**确实建了链接**的目录，两条判断缺一不可：
+ *
+ * - **内容不存在 → 不忽略。** link 会跳过没有内容的类型，也就不会建链接。
+ *   配置里写的是工具名（全量适配），四个目录里可能只有一个有内容。
+ * - **目标已是实体目录 → 不忽略。** link 拒绝覆盖实体目录，那就是用户自己的东西；
+ *   忽略它会导致人家写的东西进不了版本库，是帮倒忙。
  *
  * 注意：.claude/settings.json 与 .claude/hooks/ **不能**忽略——
  * 那些是项目真实配置，需要进版本库。
  *
- * @param {string[]} specs 形如 "claude/skills"
+ * @param {string} projectRoot @param {string[]} tools 工具名列表
  */
-export function buildBlock(specs) {
+export function buildBlock(projectRoot, tools) {
   /** @type {string[]} */
   const lines = [
     BEGIN_MARK,
@@ -29,18 +35,29 @@ export function buildBlock(specs) {
     `${CONTENT_ROOT}/*`,
   ];
 
-  // 白名单：只放行真正的内容目录，其余（临时文件、缓存）一律忽略
-  for (const kind of KINDS) {
+  // 白名单：放行所有真实内容目录，其余（临时文件、缓存）一律忽略。
+  // 必须用 CONTENT_DIRS 而非 KINDS —— hooks / mcp / scripts 不参与链接，
+  // 但同样是必须提交的真实文件，漏掉它们会让别人克隆下来只剩空壳。
+  for (const kind of CONTENT_DIRS) {
     lines.push(`!${CONTENT_ROOT}/${kind}/`);
     lines.push(`!${CONTENT_ROOT}/${kind}/*`);
   }
 
+  // 「装过什么」的记录也要进版本库：它描述的是 .agents/ 的内容，与机器无关。
+  // 不提交的话队友克隆下来，sync 就认不出哪些是本工具装的了，清理功能等于失效。
+  // 它被上面的 `.agents/*` 忽略，所以必须单独放行。
+  lines.push(`!${RECORD_REL}`);
+
   /** @type {string[]} */
   const targets = [];
-  for (const spec of specs) {
-    const { tool, kind } = parseSpec(spec);
-    const rel = TOOLS[tool].links[kind];
-    if (!targets.includes(rel)) targets.push(rel);
+  for (const tool of tools) {
+    for (const kind of kindsOf(tool)) {
+      if (!fs.existsSync(path.resolve(projectRoot, CONTENT_ROOT, kind))) continue;
+      const rel = TOOLS[tool].links[kind];
+      const abs = path.resolve(projectRoot, rel);
+      if (fs.existsSync(abs) && !isSymlink(abs)) continue;
+      if (!targets.includes(rel)) targets.push(rel);
+    }
   }
   lines.push(...targets);
 
@@ -60,9 +77,9 @@ export function readGitignore(projectRoot) {
 
 /**
  * 只读检查：托管段是否存在、缺哪些条目。
- * @param {string} projectRoot @param {string[]} specs
+ * @param {string} projectRoot @param {string[]} tools
  */
-export function checkBlock(projectRoot, specs) {
+export function checkBlock(projectRoot, tools) {
   const content = readGitignore(projectRoot);
   const start = content.indexOf(BEGIN_MARK);
   const end = content.indexOf(END_MARK);
@@ -71,24 +88,35 @@ export function checkBlock(projectRoot, specs) {
     return { present: false, missing: [], extra: [] };
   }
 
-  const block = content.slice(start, end);
-  const expected = buildBlock(specs)
-    .split('\n')
-    .filter((l) => l && !l.startsWith('#'));
-  const missing = expected.filter((l) => !block.includes(l));
+  /** 逐行拆出来：注释和空行不算，两边都用这把尺子 */
+  const linesIn = (/** @type {string} */ text) =>
+    text
+      .split('\n')
+      .map((l) => l.trim())
+      .filter((l) => l !== '' && !l.startsWith('#'));
+
+  const expected = linesIn(buildBlock(projectRoot, tools));
+  const found = linesIn(content.slice(start + BEGIN_MARK.length, end));
+
+  // 按行比，不用 `block.includes(l)` 那种子串判断：期望项 `.claude/rules` 会被
+  // 段里的一行 `.claude/rules-old` 命中，于是「缺了这条」永远报不出来。
+  const missing = expected.filter((l) => !found.includes(l));
+  // 段里多出来的行。`writeBlock` 是**整段重建**的，这几行会在下一次 link 时
+  // 无声消失——报出来，别让「写在托管段里也能生效」变成一个事后才发现不成立的假设。
+  const extra = found.filter((l) => !expected.includes(l));
 
-  return { present: true, missing, extra: [] };
+  return { present: true, missing, extra };
 }
 
 /**
  * 写入 / 更新托管段。幂等。
- * @param {string} projectRoot @param {string[]} specs
+ * @param {string} projectRoot @param {string[]} tools
  * @param {{dryRun?: boolean}} [opts]
  */
-export function writeBlock(projectRoot, specs, opts = {}) {
+export function writeBlock(projectRoot, tools, opts = {}) {
   const p = path.resolve(projectRoot, '.gitignore');
   const current = readGitignore(projectRoot);
-  const block = buildBlock(specs);
+  const block = buildBlock(projectRoot, tools);
 
   const start = current.indexOf(BEGIN_MARK);
   const end = current.indexOf(END_MARK);