agent-syncer 0.1.1 → 0.1.2

package/README.md

@@ -359,12 +359,19 @@ agent-syncer link --src/--dst
 ✅ .claude/skills  已创建
 
 这条链接不在托管范围内：status 看不到它，--prune 也不会清理它。
+注意：这个落点在某个工具的托管目录里——之后跑批量 link 会认为它「指向别处」
+      而拒绝接管。那是它在保护这条链接，别照着 --force 的提示把它覆盖掉。
 ```
 
 相对路径按**当前目录**解析（`--cwd` 可改），绝对路径原样用。源必须已经存在且是目录。
 安全检查和不带参数时**完全一样**：拒绝覆盖实体目录或文件、只删链接、指向别处的链接要
 `--force` 才接管、创建后校验。`--dry-run` 同样有效。
 
+**两种模式会互相看见，但不会互相接管。** 落点落在某个工具的托管目录里（上面那个例子
+就是）时，之后跑批量 `link` 会把它当成「指向别处」而拒绝——那是它在保护这条链接，
+不要顺手加 `--force` 覆盖掉，那会把这条特意建的链接换成指向 `.agents/` 的。
+反过来，`link` 的提示里也会说清 `--force` 是**换成**而不是「修好」。
+
 **它刻意不在托管范围内。** 不写 `.gitignore` 托管段、不进 `.agent-sync.json`、
 `status` 看不见它、`--prune` 也不碰它。理由是托管那一整套的前提是「内容都从
 `.agents/` 来」——`findStaleLinks` 只认指向本项目 `.agents/<kind>/` 的链接，记录文件
@@ -385,11 +392,14 @@ agent-syncer link --src/--dst
 | `sync` | 从内容仓库挑一个模板装进 `.agents/`，然后建链接 | 是（支持 `--dry-run`） |
 | `link` | 只建目录链接并维护 `.gitignore`；没写 `links` 时会问你或告诉你怎么写。加 `--src`/`--dst` 则是单独建一条链接，不读配置 | 是（支持 `--dry-run`） |
 | `list` | 内容仓库里有哪些条目和模板 | 否 |
-| `status` | 每个链接是否健康、`.agents/` 下各有多少内容、hooks/mcp 合并没有 | 否 |
-| `doctor` | 运行环境、链接能力实测、`.gitignore`、`.gitattributes`、合并产物、MCP 批没批准、各工具是否存在 | 否 |
+| `status` | 每个链接是否健康、`.agents/` 下各有多少内容、装过什么、hooks/mcp 合并没有、有没有「不再使用的链接 / 合并产物」 | 否 |
+| `doctor` | 运行环境、链接能力实测、内容、**记录文件**、项目配置、`.gitignore`、`.gitattributes`、合并产物、MCP 批没批准、各工具是否存在 | 否 |
 
 选项：`--from=<路径>`　`--bundle=<名字>`　`--kind=<类型>`　`--ref=<版本>`　`--src=<目录>`　`--dst=<路径>`　`--dry-run`　`--force`　`--prune`　`--yes`　`--no-save`　`--cwd=<路径>`　`--help`
 
+选项一律写成 `--名字=值`。**空格分隔不支持**（`--src ../shared/prompts`）——本工具会
+当场提醒你写成等号，而不是把它当成「没给这个选项」。
+
 ## 目录约定
 
 ```
@@ -482,6 +492,13 @@ agent-syncer link --src/--dst
 **绝不删除有内容的目录。** 路径上已经有用户自己的目录或文件时，`link` 一律拒绝并报错，
 退出码非零。指向别处的链接需要显式 `--force` 才接管，且 `--force` 也只删链接、不删实体目录。
 
+**路径上有链接就不往里写。** `sync` 落每一份内容之前，会看路径**自己**和它的**每一层
+上层目录**：哪一段是链接就拒绝，并报出是哪一段。原先只看最后那一段，于是
+`.agents/skills` 自己是链接（比如你把它指向了别处的共享目录）时，`.agents/skills/alpha`
+并不是链接，守卫整条放过——内容顺着链接写进了那个目录，退出码还是 0。而那里的内容
+很可能**还有别的项目在管**（每个项目的记录各管各的），这边 `--prune` 一删，那边就凭空少东西。
+上溯只到**项目根**为止：项目根自己的祖先是不是链接（macOS 上 `/tmp` 就是）不归本工具管。
+
 `--prune` 会收掉被删空的目录，但那和上面这条不矛盾：`fs.rmdirSync` **只对空目录成功**，
 非空一律报错，所以「有内容的目录删不掉」不是靠判断维持的，是内核挡在那儿——
 判断逻辑写错了也删不掉。另外只认**实体**目录，`lstat` 一看是链接就放手：
@@ -497,6 +514,9 @@ Windows 上 `RemoveDirectoryW` 对 junction 的语义是「摘掉重解析点」
 东西进不了版本库）。配置写的是工具名，一个工具最多带出四个目标，所以这两条判断是必需的
 ——不然会给一堆根本没建链接的路径平白加上忽略规则。
 
+段是**整段重建**的：你在段里手写的行会在下一次 `link` 时无声消失。所以 `status` / `doctor`
+会把它们报出来（「托管段里有 N 行不是本工具生成的」），而不是报一句「完整」了事。
+
 **只存一份状态，而且只存推不出来的那部分。** 链接、内容、`ref` 全从文件系统推，
 不额外记。唯一的例外是 `.agents/.agent-sync.json`，见下节——因为它回答的问题
 （「这份内容是本工具装的吗」）**光看文件系统推不出来**。
@@ -553,7 +573,14 @@ sync 就认不出哪些是本工具装的，清理功能等于失效。`.gitigno
 键序**——工具自己重排一次键序就触发一次写入的话，那个文件会一直抖。
 
 记录坏了、或者 `schemaVersion` 对不上，一律当作「没有记录」：**什么都不会删**，
-下次 sync 重新写一份。
+下次 sync 重新写一份——**写之前先把坏的那份备份成 `.agent-sync.json.bak`**（只备一次，
+不把最初那份越冲越远）。这份文件里记的归属没有第二处能推导出来，直接盖掉是不可逆的。
+
+⚠️ 「当作没有记录」对**删除**是保守的，对**归属**却是破坏性的：`merged` 一丢，本工具就
+认不出 `.mcp.json` 里哪条是自己写的了，下一轮会把它报成「与记录之外的 server 重名」，
+劝你「删掉那一份，或写进 protect」——而那份本来就是它自己写的。所以 `doctor` 会专门查
+这份文件，`status` 也会报。顺带一提，带 BOM 的记录（记事本、PowerShell 的 `>` 都会写）
+照常读得出来，不会走到这条路。
 
 > 首次升级到带记录功能的版本时，`.agents/` 里已有的内容**不会被认领**——sync 分不清
 > 它们是谁的。那一次它会照老规矩把「不在本模板里」的条目全列出来，之后写下的记录

package/bin/agent-sync.js

@@ -2,7 +2,7 @@
 // @ts-check
 import path from 'node:path';
 import process from 'node:process';
-import { bold, dim, fail, plain, title } from '../lib/log.js';
+import { bold, dim, fail, plain } from '../lib/log.js';
 import { TOOL_NAMES } from '../lib/target.js';
 
 const USAGE = `${bold('agent-syncer')} — 把 .agents/ 下的 AI 资产分发到各编码工具的配置目录
@@ -16,10 +16,13 @@ ${bold('命令')}
   link      只建目录链接并维护 .gitignore；没有 agents.json 时会先让你勾选
             带上 --src/--dst 则退化成「在这儿建一条链接」，不读任何项目配置
   list      只读报告：内容仓库里有哪些条目和模板（自定义 include 之前先看这个）
-  status    只读报告：每个链接当前是否健康、.agents/ 下各有多少内容
-  doctor    只读自检：运行环境、链接能力、.gitignore、行尾、各工具是否存在
+  status    只读报告：每个链接是否健康、.agents/ 下各有多少内容、装过什么、
+            有没有「不再使用的链接 / 合并产物」
+  doctor    只读自检：运行环境、链接能力、内容、记录、.gitignore、行尾、
+            合并产物、MCP 批没批准、各工具是否存在
 
 ${bold('选项')}
+  ${dim('一律写成 --名字=值。空格分隔不支持（--src ../x）——那样写会被当成位置参数，本工具会当场提醒。')}
   --from=<来源>    内容仓库位置（本地路径或 git 地址），覆盖 agents.json 里的 content
   --ref=<版本>     分支名 / 标签名 / 提交 SHA，覆盖 agents.json 里的 ref
   --bundle=<名字>  装哪个模板，覆盖 agents.json 里的 bundle；多个用逗号分隔
@@ -188,6 +191,40 @@ function parseArgs(argv) {
   return flags;
 }
 
+/**
+ * 取值型选项：写这几个必须用 `--名字=值`。
+ *
+ * 写成空格分隔（`--src shared/prompts`）时，手写解析器会把 `shared/prompts`
+ * 收进位置参数、把 `--src` 置成 `true`，于是**报出一句和事实相反的话**——
+ * `link --src shared/prompts` 得到的是「--src 和 --dst 要一起给（少了 --src）」
+ * （实测过）。人明明写了 src，被告知没写，只会去怀疑自己敲错了命令名。
+ */
+const VALUE_FLAGS = ['from', 'ref', 'bundle', 'kind', 'src', 'dst', 'cwd'];
+
+/**
+ * 把「空格分隔」这件事当场说清楚，而不是放宽语法。
+ *
+ * 支持空格分隔就得回答「后面那个位置参数到底是不是这个选项的值」，而本工具的
+ * 命令行里命令名、路径、选项混在一起，靠猜只会引入更难查的错。所以只认
+ * `--名字=值`，但**必须在用户写错时立刻指出来**——静默变成 `true` 是最坏的一种。
+ *
+ * @param {Record<string, any>} args
+ */
+function checkValueFlags(args) {
+  const bad = VALUE_FLAGS.filter((k) => args[k] === true);
+  if (bad.length === 0) return true;
+
+  const k = bad[0];
+  fail(`--${k} 后面要用等号，写成 --${k}=<值>`);
+  plain(
+    `  本工具只认 ${bold('--名字=值')} 这一种写法。你敲的 \`--${k}\` 后面那个词被当成了位置参数——` +
+      `等于没给 ${dim(`--${k}`)}。`,
+  );
+  plain(dim('  例如： agent-syncer link --src=../shared/prompts --dst=.claude/skills'));
+  plain(dim('  值本身带空格的话，整个包在引号里：--bundle="a b"'));
+  return false;
+}
+
 const COMMANDS = /** @type {const} */ ({
   init: '../lib/commands/init.js',
   sync: '../lib/commands/sync.js',
@@ -214,6 +251,9 @@ async function main() {
     return 0;
   }
 
+  // 放在 --help 之后：写明「怎么看帮助」的人应当先看到帮助。
+  if (!checkValueFlags(args)) return 1;
+
   const loader = /** @type {Record<string, string>} */ (COMMANDS)[cmd];
   if (!loader) {
     fail(`未知命令：${cmd}`);

package/lib/commands/doctor.js

@@ -8,18 +8,9 @@ import { CONFIG_FILENAME, loadConfig } from '../config.js';
 import { checkBlock } from '../gitignore.js';
 import { probeLinkCapability, samePath } from '../link.js';
 import { dim, fail, ok, plain, skip, title, warn } from '../log.js';
-import { ITEM_KINDS } from '../manifest.js';
-import { checkMergeAll, presentIn, sourcesFromDisk } from '../merge.js';
-import { readRecord } from '../record.js';
-import {
-  CONTENT_ROOT,
-  MERGE_KINDS,
-  TOOLS,
-  TOOL_NAMES,
-  mergeKindsOf,
-  mergeTarget,
-  toolDir,
-} from '../target.js';
+import { checkMergeView } from '../merge.js';
+import { RECORD_REL, readRecord, unparsableKeys } from '../record.js';
+import { CONTENT_ROOT, TOOLS, TOOL_NAMES, mergeKindsOf, mergeTarget, toolDir } from '../target.js';
 
 /**
  * `.gitattributes` 里有没有一条「统一按文本处理」的规则。
@@ -172,7 +163,34 @@ export async function run({ cwd }) {
     warned += 1;
   }
 
-  // ---- 4. 项目配置 ----
+  // ---- 4. 记录（哪些内容是本工具装的）----
+  //
+  // 这份文件坏了**不报错**，但会让清理功能静默失效：sync 认不出哪些内容是自己
+  // 装的，`--prune` 于是什么都不删；合并产物的归属（merged）也跟着丢。症状只会
+  // 以「怎么清不掉」的形式很晚才浮出来——而 doctor 的职责正是提前把话说清楚。
+  title('记录');
+  const record = readRecord(cwd);
+  if (record.usable) {
+    ok(`${RECORD_REL} 可读`);
+    // 解析不了的条目映射不到路径，清理会少管它们——说一声，别让它变成一份
+    // 「看起来完整、实际漏了几条」的记录
+    const broken = unparsableKeys(record);
+    if (broken.length > 0) {
+      warn(`记录里有 ${broken.length} 项名字解析不了：${broken.join('、')}`);
+      plain(dim('    它们不会被清理，也不会被覆盖——多半是手改记录时改坏的。'));
+      warned += 1;
+    }
+  } else if (record.reason) {
+    warn(record.reason);
+    plain(dim('    后果：清理功能会失效（认不出哪些内容是本工具装的）。'));
+    plain(dim('    sync 会先把它备份成 .bak，再重建一份新的。'));
+    warned += 1;
+  } else {
+    skip(`还没有 ${RECORD_REL}`);
+    plain(dim('    下次 sync 会写下它，之后就能认出哪些内容是本工具装的了。'));
+  }
+
+  // ---- 5. 项目配置 ----
   title('项目配置');
   const config = loadConfig(cwd);
   if (config.exists) {
@@ -189,7 +207,7 @@ export async function run({ cwd }) {
   }
   for (const w of config.warnings) warn(w);
 
-  // ---- 5. .gitignore ----
+  // ---- 6. .gitignore ----
   title('.gitignore');
   const gi = checkBlock(cwd, config.tools);
   if (!gi.present) {
@@ -199,6 +217,11 @@ export async function run({ cwd }) {
     warn(`托管段缺少 ${gi.missing.length} 个条目，运行 link 会补齐`);
     for (const m of gi.missing) plain(dim(`    · ${m}`));
     warned += 1;
+  } else if (gi.extra.length > 0) {
+    // 托管段是整段重建的，这几行会在下一次 link 时无声消失
+    warn(`托管段里有 ${gi.extra.length} 行不是本工具生成的，运行 link 会被清掉`);
+    for (const e of gi.extra) plain(dim(`    · ${e}`));
+    warned += 1;
   } else {
     ok('托管段完整');
   }
@@ -209,7 +232,7 @@ export async function run({ cwd }) {
     ),
   );
 
-  // ---- 6. .gitattributes ----
+  // ---- 7. .gitattributes ----
   //
   // 为什么要在意：`sync` 判断「内容变没变」是按字节比的，于是检出成 CRLF 的那份
   // 会被当成「变了」。危害不大（多报一次「更新」，第二遍自愈），但每次克隆后
@@ -235,54 +258,28 @@ export async function run({ cwd }) {
     ok('已声明 text=auto，行尾行为不再取决于各人本机配置');
   }
 
-  // ---- 7. 合并产物（hooks / mcp）----
+  // ---- 8. 合并产物（hooks / mcp）----
   //
   // 这一节查的**不是「我写了吗」，是「生效了吗」**。写进 `.mcp.json` 只是第一步，
   // 后面还有批准、还有「它进不进得了版本库」两道关。
   title('合并产物（hooks / mcp）');
-  const record = readRecord(cwd);
-  const mergedRecord = record.merged ?? {};
-  const present = Object.fromEntries(MERGE_KINDS.map((d) => [d, presentIn(cwd, d)]));
-  const presentCount = MERGE_KINDS.reduce((n, d) => n + (present[d]?.length ?? 0), 0);
+
+  // 判断整个交给 merge.js 的 checkMergeView——status 用的是同一份。两个只读命令
+  // 对同一份现场给出相反结论，是以前真出过的事（见 checkMergeAll 的注释）。
+  const view = checkMergeView({ projectRoot: cwd, config, record });
 
   // 「目录读不出来」和「目录是空的」是两件事。前者我们根本不知道里面有什么，
   // 打成「没有 hooks / mcp 内容，不需要合并」就是替它说一句我们没资格说的话。
-  for (const d of MERGE_KINDS) {
-    if (present[d] === null) {
-      warn(`读不了 ${CONTENT_ROOT}/${d}/——里面有什么、能不能合，判断不了`);
-      warned += 1;
-    }
+  for (const d of view.unreadable) {
+    warn(`读不了 ${CONTENT_ROOT}/${d}/——里面有什么、能不能合，判断不了`);
+    warned += 1;
   }
 
-  // 读不了的目录不算「没有内容」——那是两句完全不同的话
-  const anyUnreadable = MERGE_KINDS.some((d) => present[d] === null);
-
-  if (presentCount === 0 && !anyUnreadable && Object.keys(mergedRecord).length === 0) {
+  if (!view.hasWork) {
     // 空项目不该因为「`.mcp.json` 不存在」就吃一笔警告，否则小结没人看
     skip('没有 hooks / mcp 内容，不需要合并');
   } else {
-    const sourcesByKind = Object.fromEntries(
-      MERGE_KINDS.map((d) => [d, sourcesFromDisk(cwd, record, d)]),
-    );
-    /** @type {Record<string, string[]>} */
-    const keepByKind = Object.fromEntries(MERGE_KINDS.map((d) => [d, []]));
-    for (const key of config.protect) {
-      const colon = key.indexOf(':');
-      if (colon === -1) continue;
-      // 「条目类型 → 目录」这张表只在 ITEM_KINDS 里有一份。这里原先用
-      // `/^hook:/`、`/^mcp:/` 又写了一遍，sync / status 走的是表——加一类内容时
-      // 漏改一处，protect 就会在这里静默失效。
-      const dir = ITEM_KINDS[key.slice(0, colon)]?.dir;
-      if (dir && MERGE_KINDS.includes(dir)) keepByKind[dir].push(key.slice(colon + 1));
-    }
-
-    for (const r of checkMergeAll({
-      projectRoot: cwd,
-      tools: config.tools,
-      sourcesByKind,
-      keepByKind,
-      prevMerged: mergedRecord,
-    })) {
+    for (const r of view.rows) {
       const label = `${TOOLS[r.tool].label} · ${r.rel}`.padEnd(28);
       if (r.state === 'ok') {
         ok(`${label} ${dim('和内容一致')}`);
@@ -311,30 +308,19 @@ export async function run({ cwd }) {
     }
 
     // 声明的工具里有没有承接不了这类内容的（codex 的 mcp 就是）
-    for (const tool of config.tools) {
-      for (const dir of MERGE_KINDS) {
-        if (mergeTarget(tool, dir)) continue;
-        const n = present[dir]?.length ?? 0;
-        if (n > 0) {
-          warn(`${TOOLS[tool].label} 没有 ${dir} 的合并目标——这 ${n} 条装了不会生效`);
-          warned += 1;
-        }
-      }
+    for (const u of view.unsupported) {
+      warn(`${TOOLS[u.tool].label} 没有 ${u.dir} 的合并目标——这 ${u.count} 条装了不会生效`);
+      warned += 1;
     }
 
     // 没实证的那条路不能报得跟 Claude 那条一样肯定
-    for (const tool of config.tools) {
-      for (const dir of mergeKindsOf(tool)) {
-        const t = mergeTarget(tool, dir);
-        if (t && !t.verified) {
-          plain(dim(`    ⚠️ ${TOOLS[tool].label} 的 ${t.rel} 未经实证（本机没装），可能不生效`));
-        }
-      }
+    for (const u of view.unverified) {
+      plain(dim(`    ⚠️ ${TOOLS[u.tool].label} 的 ${u.rel} 未经实证（本机没装），可能不生效`));
     }
 
     // ---- 写进去了，生效了吗 ----
-    if (config.tools.includes('claude') && (present.mcp?.length ?? 0) > 0) {
-      const ap = claudeApproval(cwd, present.mcp ?? []);
+    if (config.tools.includes('claude') && (view.present.mcp?.length ?? 0) > 0) {
+      const ap = claudeApproval(cwd, view.present.mcp ?? []);
       if (ap.state === 'ok') {
         ok('Claude Code 已批准项目里的 MCP server');
       } else if (ap.state === 'pending') {
@@ -385,7 +371,7 @@ export async function run({ cwd }) {
     }
 
     // ---- hook 在 Windows 上靠 sh ----
-    if ((present.hooks?.length ?? 0) > 0 && process.platform === 'win32') {
+    if ((view.present.hooks?.length ?? 0) > 0 && process.platform === 'win32') {
       if (hasSh()) ok('sh 可用（Windows 上 hook 靠它执行）');
       else {
         warn('PATH 里找不到 sh —— hook 会静默不跑');
@@ -395,7 +381,7 @@ export async function run({ cwd }) {
     }
   }
 
-  // ---- 8. 各工具是否存在 ----
+  // ---- 9. 各工具是否存在 ----
   title('工具');
   for (const name of TOOL_NAMES) {
     const dir = path.resolve(cwd, toolDir(name));

package/lib/commands/link.js

@@ -130,7 +130,12 @@ function applyOne({ label, source, target, rel, srcLabel }, { dryRun, force }) {
 
   if (before.status === STATUS.ELSEWHERE && !force) {
     fail(`${label}  已是指向别处的链接 → ${before.actual}`);
-    return { status: 'failed', problem: `${rel} 指向别处，确认无误后加 --force 覆盖` };
+    // 直连模式（`link --src/--dst`）建的链接正好落进这一支。得说清 `--force`
+    // 是**换掉**它而不是「修好」它——否则这句提示会被当成一个修问题的按钮，
+    // 把用户昨天特意建的那条链接顺手覆盖掉，还以为自己是在修配置。
+    plain(dim('     它可能是你特意建的（link --src/--dst），也可能是别处留的'));
+    plain(dim(`     --force 会把它换成指向 ${srcLabel}，原来那条链接就没了`));
+    return { status: 'failed', problem: `${rel} 指向别处；确认要换成 ${srcLabel} 再加 --force` };
   }
 
   // 走到这里只可能是 ABSENT / BROKEN / (ELSEWHERE + --force)，
@@ -230,6 +235,16 @@ function runDirect({ cwd, src, dst, dryRun, force, prune }) {
   }
 
   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;
 }

package/lib/commands/status.js

@@ -4,30 +4,42 @@ import path from 'node:path';
 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 { ITEM_KINDS } from '../manifest.js';
-import { checkMergeAll, presentIn, sourcesFromDisk } from '../merge.js';
-import { RECORD_REL, checkRecord, readRecord } from '../record.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,
-  MERGE_KINDS,
-  TOOLS,
-  TOOL_NAMES,
-  mergeTarget,
-  plannedLinks,
-} from '../target.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' };
   }
 }
 
@@ -50,21 +62,32 @@ 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 {
     // 遍历 CONTENT_DIRS 而不是 KINDS：hooks / mcp / scripts 不参与链接，
     // 但它们同样是 sync 装下来的内容，只报四类会让人以为 sync 把后三类漏了。
     // doctor 本来就列全部子目录，这里跟上，两条命令的口径才一致。
     for (const kind of CONTENT_DIRS) {
-      const n = countEntries(path.resolve(contentRoot, kind));
+      const r = countEntries(path.resolve(contentRoot, kind));
       const label = kind.padEnd(9);
-      if (n === null) {
-        // 空出数字列的宽度，好让「无此目录」和上面的「N 项」对成一张表
+      // 空出数字列的宽度，好让这两行和上面的「N 项」对成一张表
+      if (r.state === 'missing') {
         skip(`${label}    无此目录`);
         continue;
       }
-      ok(`${label} ${String(n).padStart(3)} 项`);
+      if (r.state === 'unreadable') {
+        // **不算问题**——和下一节「合并」读不了时一个口径：判断不了的事如实说，
+        // 但不把它变成用户要去点一下的修复项（那会是个他不会采纳的修复）。
+        warn(`${label}    读不了——有多少条目判断不了`);
+        continue;
+      }
+      ok(`${label} ${String(r.count).padStart(3)} 项`);
     }
   }
 
@@ -86,6 +109,13 @@ export async function run({ cwd }) {
     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 有没有真的写进工具自己的配置 ----
@@ -93,50 +123,22 @@ export async function run({ cwd }) {
   // 这两类不建链接，而是合并进 `.mcp.json` / `.claude/settings.json`。
   // 五态各有各的说法，别混成一句「有问题」：
   //   一致 / 还没生成 / 漂移 / 读不了 / 有本工具没动的地方
-  const sourcesByKind = Object.fromEntries(MERGE_KINDS.map((d) => [d, sourcesFromDisk(cwd, record, d)]));
-
-  // 目录里**有没有这类内容**，和记录无关。两件事要分开：
-  // 「该不该合」看记录（sync 只合选中的），「有没有东西合不了」看目录。
-  // 混成一个的话，还没写过记录的新项目就不会被告知「codex 没有 MCP 目标」。
-  const present = Object.fromEntries(MERGE_KINDS.map((d) => [d, presentIn(cwd, d)]));
-  const presentCount = MERGE_KINDS.reduce((n, d) => n + (present[d]?.length ?? 0), 0);
+  // 判断整个交给 merge.js 的 checkMergeView——doctor 用的是同一份。两个只读
+  // 命令对同一份现场给出相反结论，是以前真出过的事（见 checkMergeAll 的注释）。
+  const view = checkMergeView({ projectRoot: cwd, config, record });
 
   // 「目录读不出来」和「目录是空的」是两件事，不能一声不吭当成后者：
   // 前者我们根本不知道里面有什么，也就答不了「该合的合了没有」。
   // 报一声，但**不算问题**——和下面「记录读不了」一个口径：判断不了的事
   // 如实说，不把它变成用户要去点一下的修复项（那会是个他不会采纳的修复）。
-  for (const d of MERGE_KINDS) {
-    if (present[d] === null) {
-      warn(`${CONTENT_ROOT}/${d}/ 读不了——里面有什么、能不能合，判断不了`);
-    }
+  for (const d of view.unreadable) {
+    warn(`${CONTENT_ROOT}/${d}/ 读不了——里面有什么、能不能合，判断不了`);
   }
 
-  // 读不了的目录也算「有话要说」：这时候一句都不说，就变成「看起来没事、
-  // 实际上没人在管」——上面那声 warn 已经打了，这里让这一节照样进来
-  const anyUnreadable = MERGE_KINDS.some((d) => present[d] === null);
-
-  if (
-    config.tools.length > 0 &&
-    (presentCount > 0 || anyUnreadable || Object.keys(record.merged ?? {}).length > 0)
-  ) {
+  if (config.tools.length > 0 && view.hasWork) {
     title('合并（hooks / mcp）');
 
-    /** @type {Record<string, string[]>} */
-    const keepByKind = Object.fromEntries(MERGE_KINDS.map((d) => [d, []]));
-    for (const key of config.protect) {
-      const colon = key.indexOf(':');
-      if (colon === -1) continue;
-      const dir = ITEM_KINDS[key.slice(0, colon)]?.dir;
-      if (dir && MERGE_KINDS.includes(dir)) keepByKind[dir].push(key.slice(colon + 1));
-    }
-
-    for (const r of checkMergeAll({
-      projectRoot: cwd,
-      tools: config.tools,
-      sourcesByKind,
-      keepByKind,
-      prevMerged: record.merged ?? {},
-    })) {
+    for (const r of view.rows) {
       const label = `${TOOLS[r.tool].label} · ${r.rel}`.padEnd(30);
 
       switch (r.state) {
@@ -173,17 +175,11 @@ export async function run({ cwd }) {
     }
 
     // 合并器做完之后，这是唯一还会为「装了没生效」说话的地方
-    for (const tool of config.tools) {
-      for (const dir of MERGE_KINDS) {
-        if (mergeTarget(tool, dir)) continue;
-        const n = present[dir]?.length ?? 0;
-        if (n > 0) {
-          warn(`${TOOLS[tool].label} 没有 ${dir} 的合并目标——这 ${n} 条装了不会生效`);
-        }
-      }
+    for (const u of view.unsupported) {
+      warn(`${TOOLS[u.tool].label} 没有 ${u.dir} 的合并目标——这 ${u.count} 条装了不会生效`);
     }
 
-    if (config.tools.includes('claude') && (present.mcp?.length ?? 0) > 0) {
+    if (config.tools.includes('claude') && (view.present.mcp?.length ?? 0) > 0) {
       plain(
         dim('  注意：MCP server 还要在 Claude Code 里逐条批准才生效——批准记录存在本机，不随仓库共享。'),
       );
@@ -211,20 +207,39 @@ export async function run({ cwd }) {
   }
 
   // ---- 链接 ----
+  //
+  // 收尾统一走这里。**`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(`未声明任何工具——${CONFIG_FILENAME} 里没有 links`);
     plain(dim('  可选：' + TOOL_NAMES.join('、')));
     plain(dim('  写进配置里，或在终端里跑一次 agent-syncer link 让它问你要用哪些。'));
-    return 0;
+    return finish();
   }
   if (!config.exists) {
     plain(dim(`（未找到 agents.json：${config.warnings.join('；')}）`));
   }
 
   const plan = plannedLinks(cwd, config.specs);
-  let healthy = 0;
-  let absent = 0;
 
   // 按工具分组展示，读起来比一条长清单清楚
   for (const tool of config.tools) {
@@ -296,22 +311,13 @@ export async function run({ cwd }) {
   } 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();
 }