agent-syncer 0.1.0 → 0.1.2

package/lib/merge.js

@@ -0,0 +1,1255 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { isSymlink } from './link.js';
+import { ITEM_KINDS, parseItem } from './manifest.js';
+import {
+  CONTENT_ROOT,
+  MERGE_KINDS,
+  PROJECT_DIR_ALIASES,
+  TOOLS,
+  isTool,
+  mergeKindsOf,
+  mergeTarget,
+  projectDirOf,
+} from './target.js';
+
+/**
+ * 合并器：把 `.agents/hooks/*.json` 和 `.agents/mcp/*.json` 写进各工具自己的配置文件。
+ *
+ * ## 为什么不能像 skills 那样建链接
+ *
+ * `.claude/skills` 是指向 `.agents/skills/` 的 junction，内容只存一份。但
+ * `.mcp.json` 和 `.claude/settings.json` 里**还有用户自己的东西**，整份覆盖等于
+ * 把它们删了。所以这两类只能**读—改—写**：保留用户的一切，只动我们负责的那部分。
+ *
+ * ## 归属问题：整个模块的核心
+ *
+ * 「我们负责的那部分」不能靠推断。有条看起来能走的捷径——「`.agent-sync.json`
+ * 的 `installed` 里有 `mcp:foo`，所以 `.mcp.json` 里的 `foo` 就是我们写的」。
+ * **它是错的**：`installed` 说的是「`.agents/mcp/foo.json` 这个文件是本工具放的」，
+ * 而用户完全可能在自己的 `.mcp.json` 里写一个同名的 server。两者会分叉，
+ * 于是**第二轮 sync 就会把用户那份静默吃掉**。
+ *
+ * 所以归属来自 `merged` 记录（见 `record.js`），而且**是被验证的**：
+ * 「记录说是我写的」还不够，还要「**现场确实还是我写的那份**」才动。
+ * 现场对不上 → 判为用户改过 → 保留 + 报告。这个安全阀是刻意做的：
+ * 宁可少清理，不可多删除。
+ *
+ * ## 一条铁律：绝不静默降级
+ *
+ * 转不过去的条目（`url` 没有 `type`、套了 `mcpServers` 包装、事件名拼错……）
+ * 一律**报出来**。一个「看起来配好了但不生效」的 MCP server 比没有更糟——
+ * 这是 `CONTENT-REPO.md` 已经写在 rules 那节的口径。
+ *
+ * ## 分层
+ *
+ * 上半部分是**纯函数**（不碰磁盘、不打印），下半部分是 fs 层。
+ * 命令层只跟 `applyMerge()` 和 `checkMerge()` 打交道。
+ *
+ * ## 三个入参的意思（整个模块都按这套说法）
+ *
+ * - `desired`：这一轮**要写进去**的，`id → 值`。调用方已经把选中和 `protect` 过滤过了
+ * - `keep`：**整个不碰**的 id。两种来源：`protect` 锁住的，以及**这一轮不想摘的**
+ *   （没加 `--prune` 时，掉出选择的那些）。两种都不改目标文件，而且**归属一直留着**
+ * - `prev`：上一轮我们写了什么（`merged[tool][kind]`）
+ *
+ * **要摘掉的 = `prev` 里有、但 `desired` 和 `keep` 里都没有的**。由这条推出来，
+ * 不需要调用方再算一遍——少一个能算错的地方。
+ */
+
+/** JSON 意义上的「一个对象」——null 和数组都不算 */
+function isPlain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * 有 BOM 就剥掉。
+ *
+ * Windows 上记事本、PowerShell 的 `>` 重定向默认都写带 BOM 的 UTF-8，而
+ * `JSON.parse` 见 BOM 直接抛。**这份知识以前散在好几个地方**：merge.js 在
+ * `readJsonFile` 里内联做了一次，config.js 抄了一份（还注明「merge.js 早就这么
+ * 处理了，这里跟上」），而 record.js 压根没做——于是记事本改一下
+ * `.agents/.agent-sync.json`，记录当场判为「不可用」，合并产物的归属跟着全丢。
+ * 收在这里一处，谁读 JSON 谁拿去用。
+ *
+ * @param {string} text
+ */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * 这个错误是不是「路径上真的没有东西」。
+ *
+ * **只有 `ENOENT` / `ENOTDIR` 算不存在，其余（`EPERM` / `EACCES` / `EBUSY` /
+ * `ELOOP`…）一律是「有东西，但读不到」。** 别逐个列举权限类错误码：Windows 上
+ * 同一件事可能是 EPERM 也可能是 EACCES，漏一个就退化成「不存在」。
+ *
+ * 这个区分不是洁癖，两个方向都出过事：
+ *
+ * - **降级成「不存在」→ 接着写。** `readJsonFile` 的 blocker 就是这么来的：
+ *   读不到被当成「这文件没有」，调用方走「没坏、可以写」那条分支，把用户已有的
+ *   `.mcp.json` 整份覆盖掉。
+ * - **降级成「不存在」→ 报给用户看。** `status` 的内容计数原先 `catch` 一律返回
+ *   null，于是权限错、IO 错都打成「无此目录」——用户看到的是「这儿没东西」，
+ *   而真相是「这儿的东西我看不到」。
+ *
+ * 全项目四处要做这个判断（`readJsonFile`、`presentIn`、`config.js` 读配置、
+ * `status.js` 数内容），所以收在这里一份。文件在 merge.js 而不是某个新模块：
+ * 那三个调用方本来就都从 merge.js 拿东西，不用为此新增一条依赖边。
+ *
+ * @param {unknown} err
+ */
+export function isMissingPath(err) {
+  const code = /** @type {NodeJS.ErrnoException} */ (err)?.code;
+  return code === 'ENOENT' || code === 'ENOTDIR';
+}
+
+/**
+ * 路径是否存在，**断链也算存在**。
+ *
+ * 不能用 `fs.existsSync`：它跟的是链接目标，断链因此返回 false，而我们两道
+ * 「不碰用户的链接」的守卫都以「存在」为前提。守卫被整条跳过之后，`rename`
+ * 会**直接把那个断链换成我们的文件**——POSIX 上静默生效，Windows 上则报
+ * 一句莫名其妙的 `写入失败：EPERM … rename`。`lstat` 不跟目标，所以断链
+ * 在这里照样算「有东西」。
+ *
+ * `link.js` 里有一个同名的内部工具，但它没导出，也不该为了这一处把它的
+ * 可见性放大——这里只需要「在不在」这一个问题。
+ *
+ * @param {string} p
+ */
+function lexists(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 结构相等，**对象键序无关**。
+ *
+ * 必须无序：工具自己重写配置文件时可能重排键序。按序比会把它误判成
+ * 「用户改了我们的东西」，于是走保护分支、那份记录**永远不再参与清理**——
+ * 一个很难查的卡死。
+ */
+export function deepEqualJSON(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqualJSON(x, b[i]));
+  }
+  if (!isPlain(a) || !isPlain(b)) return false;
+
+  const ka = Object.keys(a);
+  if (ka.length !== Object.keys(b).length) return false;
+  return ka.every((k) => Object.hasOwn(b, k) && deepEqualJSON(a[k], b[k]));
+}
+
+/** `prev` 里有、`desired` 和 `keep` 里都没有的 —— 这一轮该摘掉的 */
+function removalIds(prev, desired, keep) {
+  const protectedIds = new Set(keep);
+  return Object.keys(prev).filter((id) => !protectedIds.has(id) && !Object.hasOwn(desired, id));
+}
+
+/**
+ * 把内容里写的项目根变量换成 `tool` 自己的写法。
+ *
+ * 内容仓库的铁律是「只描述这是什么，不描述写到哪」，所以里面不该出现某个具体
+ * 工具的变量名。但引用项目内脚本时又确实需要一个「项目根」的写法，各工具叫法
+ * 还不同。解法是一张**别名表**（`PROJECT_DIR_ALIASES`）：写哪个都认，到这里
+ * 统一翻译。于是已经写下的 `${CLAUDE_PROJECT_DIR}` 不会作废，写
+ * `${workspaceFolder}` 的内容也能在 Claude 上跑。
+ *
+ * **只认表里那几个**。`${DEPT_WIKI_TOKEN}` 这类环境变量原样留着——它们由工具
+ * 自己的进程环境在运行时展开，不归我们管。
+ *
+ * @param {string} s @param {string} tool
+ */
+function translateString(s, tool) {
+  const target = projectDirOf(tool)?.var;
+  if (!target) return s;
+
+  let out = s;
+  for (const alias of PROJECT_DIR_ALIASES) {
+    if (alias === target) continue;
+    // 用 split/join 而不是正则：变量名里没有需要转义的字符，少一类边界
+    out = out.split(`\${${alias}}`).join(`\${${target}}`);
+  }
+  return out;
+}
+
+/** 深度遍历，翻译所有字符串值 */
+function translateValue(value, tool) {
+  if (typeof value === 'string') return translateString(value, tool);
+  if (Array.isArray(value)) return value.map((v) => translateValue(v, tool));
+  if (isPlain(value)) {
+    /** @type {Record<string, any>} */
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = translateValue(v, tool);
+    return out;
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// 内容文件 → 该写进目标的值
+// ---------------------------------------------------------------------------
+
+/**
+ * 校验并翻译一条 MCP 定义。
+ *
+ * 三条硬规则，漏了就是「静默不生效」：
+ *
+ * 1. **不能套 `mcpServers` 包装**。那是配置文件里的层级，不是内容文件里的。
+ *    套了的话我们会写出一个名叫 `mcpServers` 的 server——`CONTENT-REPO.md`
+ *    的 FAQ 把这列为头号作者错误。
+ * 2. **有 `url` 就必须有 `type`**。实测过：只有 `url` 没有 `type` 的配置会被
+ *    Claude 当成 stdio server 读，然后跳过。**不替它补**——Trae 的 schema 我们
+ *    没实证，多写一个 `type` 有可能直接让它拒收。顺手补一个 `type: "stdio"`
+ *    正是把「我们以为对」当成「它一定对」。
+ * 3. 顶层必须是对象。
+ *
+ * 其余一律原样透传，只做变量翻译。**不注入 `type: "stdio"`**：Claude 缺
+ * `type` 本来就按 stdio 读，多写一个键纯属多余。
+ *
+ * @param {any} raw @param {string} tool
+ * @returns {{value: Record<string, any>}|{error: string}}
+ */
+export function buildMcpEntry(raw, tool) {
+  if (!isPlain(raw)) {
+    return { error: '顶层必须是一个对象（单个 server 的定义）' };
+  }
+  if (Object.hasOwn(raw, 'mcpServers')) {
+    return {
+      error:
+        '内容文件里不要套 mcpServers 包装——那是配置文件里的层级。' +
+        '直接写 server 自己的字段（command / args / env，或 type / url / headers）',
+    };
+  }
+  if (typeof raw.url === 'string' && typeof raw.type !== 'string') {
+    return {
+      error:
+        '有 url 却没有 type——这样写会被当成 stdio server 读然后**静默跳过**。' +
+        '请补上 "type"（远端传输用 "http"），本工具不替你猜',
+    };
+  }
+  return { value: translateValue(raw, tool) };
+}
+
+/**
+ * 已知的 hook 事件名。**尽力而为的清单，不是权威**——CLI 版本更新会加新事件。
+ * 列出来只为了抓「Sessionstart 拼错了」这类静默失效：事件名写错不会报错，
+ * 那个 hook 就是永远不跑。
+ */
+const KNOWN_HOOK_EVENTS = new Set([
+  'PreToolUse',
+  'PostToolUse',
+  'Notification',
+  'UserPromptSubmit',
+  'Stop',
+  'SubagentStop',
+  'PreCompact',
+  'SessionStart',
+  'SessionEnd',
+]);
+
+/** 明显是文件级元数据的键。它们绝不该出现在 hook 内容文件里——合并过去就是脏数据 */
+const HOOK_META_KEYS = new Set(['description', '$schema', 'title']);
+
+/**
+ * 校验并翻译一个 hook 片段。
+ *
+ * @param {any} raw @param {string} tool
+ * @returns {{value: Record<string, any[]>, warnings: string[]}|{error: string}}
+ */
+export function buildHooksEntry(raw, tool) {
+  if (!isPlain(raw)) {
+    return { error: '顶层必须是一个对象，键是事件名（如 SessionStart / PostToolUse）' };
+  }
+
+  /** @type {Record<string, any[]>} */
+  const events = {};
+  /** @type {string[]} */
+  const warnings = [];
+
+  for (const [name, entries] of Object.entries(raw)) {
+    if (HOOK_META_KEYS.has(name) || name.startsWith('_')) {
+      return {
+        error:
+          `顶层键 "${name}" 不是事件名。文件级的说明写文档，别写在这里——` +
+          '它会被原样合并进 settings.json 变成脏数据',
+      };
+    }
+    if (!Array.isArray(entries)) {
+      return { error: `事件 "${name}" 的值必须是数组` };
+    }
+    if (!KNOWN_HOOK_EVENTS.has(name)) {
+      warnings.push(`事件名 "${name}" 不在已知列表里——如果这是拼错的，那个 hook 永远不会跑`);
+    }
+    events[name] = translateValue(entries, tool);
+  }
+
+  return { value: events, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// 纯函数核：算下一轮该写成什么
+// ---------------------------------------------------------------------------
+
+/**
+ * `.mcp.json` / `.trae/mcp.json` 的合并。
+ *
+ * @param {{
+ *   current: Record<string, any>, desired: Record<string, any>,
+ *   keep: string[], prev: Record<string, any>,
+ * }} input
+ * @returns {{next: Record<string, any>, recorded: Record<string, any>, conflicts: string[], problems: string[]}}
+ */
+function mergeMcp({ current, desired, keep, prev }) {
+  /** @type {string[]} */
+  const conflicts = [];
+  /** @type {string[]} */
+  const problems = [];
+
+  // `mcpServers` 在，但根本不是普通对象。**整段不碰，也不去「修好」它。**
+  //
+  // 为什么是「不动」而不是「修好」：那个值是用户写下的形态，我们猜不出他的本意
+  // （也许是将来某个版本支持的新写法），按自己的理解重写「成对象」就等于把他写的
+  // 东西直接抹掉。实测过的老行为更难堪——`{"mcpServers":"x"}` 会被当成空的，
+  // 然后写成 `{}`，值凭空消失，`problems` 还一声不吭。
+  //
+  // 记录里的归属照旧留着（同下面「锁住的不碰」那条口径）：读不懂现场就无从验证，
+  // 抹掉才是真的失联。
+  if (Object.hasOwn(current, 'mcpServers') && !isPlain(current.mcpServers)) {
+    problems.push('mcpServers 不是一个对象——结构不认识，没动它');
+    return { next: { ...current }, recorded: { ...prev }, conflicts, problems };
+  }
+
+  // 这一轮压根没有要合的东西。什么都不动，于是 `next` 和读到的完全相同，调用方
+  // 自然不会去写盘——用户的 `{"mcpServers":{}}` 也就不会被「顺手」删成 `{}`。
+  //
+  // 只在**真的动过东西之后**才收掉空壳（见下面 `delete next.mcpServers`）：
+  // 那是「我们的条目摘干净了，别留个空架子」，和「本轮无事可做却重写一遍文件」
+  // 是两件事。
+  if (Object.keys(desired).length === 0 && Object.keys(prev).length === 0) {
+    return { next: { ...current }, recorded: {}, conflicts, problems };
+  }
+
+  /** @type {Record<string, any>} */
+  const next = { ...current };
+  /** @type {Record<string, any>} */
+  const servers = { ...(isPlain(current.mcpServers) ? current.mcpServers : {}) };
+
+  /** @type {Record<string, any>} */
+  const recorded = {};
+
+  // ---- 1. 该摘的摘 ----
+  for (const id of removalIds(prev, desired, keep)) {
+    const was = prev[id];
+    if (!Object.hasOwn(servers, id)) continue; // 现场本来就没了，不用管
+
+    if (deepEqualJSON(servers[id], was)) {
+      delete servers[id];
+    } else {
+      // 现场和记录对不上 —— 有人改过。判为用户的，保留，但**继续记着**：
+      // 沿用 P2 那条口径，认得出的残留要一直留在记录里，抹掉就等于失联。
+      recorded[id] = was;
+      conflicts.push(`mcp:${id} 被改过，没有删除`);
+    }
+  }
+
+  // ---- 2. 锁住的 / 这一轮暂不摘的：整个不碰，但**归属一直留着** ----
+  //
+  // 必须**无条件**保留 `prev` 里的值，不能写成「对得上才记」：
+  // 对不上说明用户改过它，而改过的**更要**说得出它本来是我们的——否则这一条
+  // 从此失联，将来加 `--prune` 也找不到它，更不会告诉你它为什么还在。
+  // 「没删掉的残留要一直留在记录里」是 P2 就定下的口径。
+  //
+  // 自我清理：下一轮真去摘它的时候，现场已经没有这个键的话它不会进 recorded，
+  // 记录里不会越积越多。
+  for (const id of keep) {
+    if (prev[id] !== undefined) recorded[id] = prev[id];
+  }
+
+  // ---- 3. 该写的写 ----
+  for (const [id, want] of Object.entries(desired)) {
+    const was = prev[id];
+    const has = Object.hasOwn(servers, id);
+
+    if (has && was === undefined) {
+      // 目标里已经有了，但记录里没有。**绝不覆盖**，而且不记进 recorded，
+      // 所以下一轮它还是「不是我们的」。
+      //
+      // 两种来路都要说清楚，别只说「你自己写的」：除了用户手写的那份，
+      // **升级前本工具写过的**也会落到这里——老记录只有 `installed`，没有
+      // `merged` 那一段（见 record.js 开头）。把后者说成「你自己写的」，
+      // 用户会一头雾水地去找一个他从没写过的 server。
+      conflicts.push(
+        `mcp:${id} 与记录之外的 server 重名——没有覆盖。` +
+          '它可能是你自己写进配置文件的，也可能是更早版本的记录里还没有 merged 那一段、' +
+          '而本工具当时写下的。要本工具接管就先删掉那一份，要保住它就写进 protect',
+      );
+      continue;
+    }
+    if (has && !deepEqualJSON(servers[id], was)) {
+      // 是我们写的，但被人改过。同样保留 + 报告，不覆盖回去。
+      recorded[id] = was;
+      conflicts.push(`mcp:${id} 被改过——保留你的改动没覆盖。想彻底由你管就写进 protect`);
+      continue;
+    }
+
+    servers[id] = want;
+    recorded[id] = want;
+  }
+
+  if (Object.keys(servers).length > 0) next.mcpServers = servers;
+  else delete next.mcpServers;
+
+  return { next, recorded, conflicts, problems };
+}
+
+/**
+ * `.claude/settings.json` 的 `hooks` 段合并。
+ *
+ * 难点在于事件数组里**我们和用户的条目混在一起**，而 JSON 没有注释可用、
+ * 也不能加 `_source` 之类的标记键（会变成脏数据）。所以只能靠记录：
+ *
+ * 1. 先把 `prev` 里记着的（即上一轮我们自己追加的）**按深度相等全部摘掉**，
+ *    剩下的就都是用户的
+ * 2. 再把这一轮 `desired` 的追加进去
+ *
+ * 「按深度相等」意味着：用户改过的那一条匹配不上，会留在「用户的」那一堆里
+ * 被保留下来——这正是我们要的。**改过的就归用户。**
+ *
+ * ⚠️ 第 1 步必须摘**全部** `prev`，不能只摘「要被删掉的」那几个：还在选择里的
+ * 条目也要先摘再重新追加，否则第 2 步会因为「列表里已经有了」而跳过，那一条
+ * 就不会进 `recorded`——归属当场丢失，下一轮再也清不掉。
+ *
+ * @param {{
+ *   current: Record<string, any>, desired: Record<string, any>,
+ *   keep: string[], prev: Record<string, any>,
+ * }} input
+ * @returns {{next: Record<string, any>, recorded: Record<string, any>, conflicts: string[], problems: string[]}}
+ */
+function mergeHooks({ current, desired, keep, prev }) {
+  /** @type {Record<string, any>} */
+  const next = { ...current };
+  /** @type {string[]} */
+  const conflicts = [];
+  /** @type {string[]} */
+  const problems = [];
+
+  // `hooks` 在，但不是普通对象 —— 和 mcp 那一侧同一个道理：结构不认识就整段不碰，
+  // 报出来让用户自己决定，而不是按我们的理解把它重写成一个对象。
+  // 老行为会把它替换成 `{}` / `{SessionStart:[]}`，用户写的东西直接消失。
+  if (Object.hasOwn(current, 'hooks') && !isPlain(current.hooks)) {
+    problems.push('hooks 不是一个对象——结构不认识，没动它');
+    return { next, recorded: { ...prev }, conflicts, problems };
+  }
+
+  // 这一轮没有要合的东西（内容一条没选、记录里也一条没写过）：什么都不动。
+  // `{"hooks":{"SessionStart":"字符串"}}` 这种不认识的值才不会被改写成
+  // `{"SessionStart":[]}`，`{"hooks":{}}` 也不会被顺手删成 `{}`。
+  if (Object.keys(desired).length === 0 && Object.keys(prev).length === 0) {
+    return { next, recorded: {}, conflicts, problems };
+  }
+
+  const hookEntries = isPlain(current.hooks) ? current.hooks : {};
+  /** @type {Record<string, any>} */
+  const hooks = { ...hookEntries };
+
+  const keepSet = new Set(keep);
+
+  /** 要碰的事件名：上一轮写过的 + 这一轮要写的 */
+  const touched = new Set();
+  for (const src of [prev, desired]) {
+    for (const events of Object.values(src)) {
+      if (isPlain(events)) for (const e of Object.keys(events)) touched.add(e);
+    }
+  }
+
+  // 值不是数组的事件名：结构不认识。**这一轮不碰它**，只报一声。
+  // `[...(hooks[e] ?? [])]` 展开一个字符串会得到一堆单字，然后 splice 掉——
+  // 那就不是「没动它」了，是把它拆了。
+  /** @type {string[]} */
+  const mergeable = [];
+  for (const e of touched) {
+    if (Array.isArray(hookEntries[e]) || hookEntries[e] === undefined) mergeable.push(e);
+    else problems.push(`hook 事件 "${e}" 不是一个数组——结构不认识，没动它`);
+  }
+
+  // ---- 1. 按记录把自己上一轮追加的摘掉，剩下的归用户 ----
+  /** @type {Record<string, any[]>} */
+  const userOwned = {};
+  /** 记录说我们写过、现场却找不到的 id。稍后要**留在记录里**，见下面。 */
+  const lost = new Set();
+  for (const e of mergeable) {
+    const list = [...(hookEntries[e] ?? [])];
+
+    for (const [id, events] of Object.entries(prev)) {
+      if (keepSet.has(id)) continue; // 锁住的条目不碰，它们的条目留在原处
+      for (const entry of events[e] ?? []) {
+        const at = list.findIndex((x) => deepEqualJSON(x, entry));
+        if (at === -1) {
+          // 记录说是我们写的，现场却找不到：被删了，或者被改过。现场留下的那份
+          // 当用户的——但**归属继续留在记录里**。
+          //
+          // 这条以前只报一次就彻底失联，而 mcp 那一侧同样情形是「一直留着、每轮都
+          // 报」。两边必须一致：抹掉归属就等于「用户漏看一次就永远找不回来」，
+          // 将来 `--prune` 也找不到它、更不会解释它为什么还在。代价是这声警告
+          // 每轮重复——可以接受，`status` / `doctor` 里本来就该一直看得见。
+          lost.add(id);
+          conflicts.push(
+            `hook:${id} 在 ${e} 里有一条找不到了（可能被改过或删过）——` +
+              '现场留下的那份按你的保留，记录里继续记着它，不会被悄悄忘掉',
+          );
+          continue;
+        }
+        list.splice(at, 1);
+      }
+    }
+    userOwned[e] = list;
+  }
+
+  // ---- 2. 把这一轮的追加进去（用户已有的不重复加）----
+  /** @type {Record<string, any>} */
+  const appended = {};
+  for (const e of mergeable) {
+    const list = userOwned[e];
+    for (const [id, events] of Object.entries(desired)) {
+      for (const entry of events[e] ?? []) {
+        if (list.some((x) => deepEqualJSON(x, entry))) continue;
+        list.push(entry);
+        ((appended[id] ??= {})[e] ??= []).push(entry);
+      }
+    }
+    if (list.length > 0) hooks[e] = list;
+    else delete hooks[e];
+  }
+
+  // ---- 3. 丢失的、锁住的、这一轮暂不摘的：整个不碰，但**归属一直留着** ----
+  //
+  // 同 mcp 那一侧：无条件保留，不能「对得上才记」。对不上说明用户改过，
+  // 而改过的更要说得出来它本来是我们的，否则将来 `--prune` 找不到它，
+  // 也不会告诉你它为什么还在。
+  //
+  // 起点是**只记我们实际追加的**：用户原本就有的（哪怕长得一模一样）不认领——
+  // 认领了的话，将来清理会把他的东西删掉。
+  /** @type {Record<string, any>} */
+  const recorded = { ...appended };
+  for (const id of lost) {
+    if (prev[id] !== undefined) recorded[id] = prev[id];
+  }
+  for (const id of keep) {
+    if (prev[id] !== undefined) recorded[id] = prev[id];
+  }
+
+  if (Object.keys(hooks).length > 0) next.hooks = hooks;
+  else delete next.hooks;
+
+  return { next, recorded, conflicts, problems };
+}
+
+/** `MERGE_KINDS` 里的类型 → 合并实现 */
+const MERGERS = { mcp: mergeMcp, hooks: mergeHooks };
+
+/**
+ * 算一个工具的一类内容合并之后该是什么样。**纯函数，不碰磁盘。**
+ *
+ * `problems` 里是「现场的结构我们不认识，所以一个字都没动」这类事——它和
+ * `conflicts`（现场像你的东西，保留）不是一回事，别混：`conflicts` 是正常的
+ * 保护行为，`problems` 是「本该写进去的没写进去」，调用方要当成故障报出来。
+ *
+ * @param {{
+ *   kind: string, current: Record<string, any>, desired: Record<string, any>,
+ *   keep?: string[], prev: Record<string, any>,
+ * }} input
+ * @returns {{next: Record<string, any>, recorded: Record<string, any>, conflicts: string[], problems: string[]}}
+ */
+export function planMerge({ kind, current, desired, keep = [], prev }) {
+  const merge = MERGERS[kind];
+  if (!merge) {
+    throw new Error(`未知的合并类型 "${kind}"（可用：${Object.keys(MERGERS).join('、')}）`);
+  }
+  return merge({ current, desired, keep, prev });
+}
+
+// ---------------------------------------------------------------------------
+// fs 层
+// ---------------------------------------------------------------------------
+
+/**
+ * 读一个 JSON 配置文件。**「不存在」「空文件」「坏文件」「读不到」是四件事。**
+ *
+ * 坏文件绝不能被当成空的然后覆盖写——那是在用户配置已经坏了的时候再补一刀。
+ * 「读不到」同理，而且更隐蔽：`EPERM` / `EACCES` / `EBUSY` / `ELOOP` 这些错误
+ * 一概当成「文件不存在」的话，`applyMerge` 就会以为「没坏、可以写」，
+ * 把用户那份配置**整份覆盖掉**（实测过：给 `.mcp.json` 加一条拒绝读取的 ACL，
+ * 回来的是 `problems: []`、`changed: true`，用户自己的内容没了）。
+ *
+ * @param {string} abs
+ * @returns {{exists: boolean, empty: boolean, bom: boolean, value: any, error: string|null}}
+ */
+export function readJsonFile(abs) {
+  /** @type {string} */
+  let raw;
+  try {
+    raw = fs.readFileSync(abs, 'utf8');
+  } catch (e) {
+    const code = /** @type {NodeJS.ErrnoException} */ (e).code;
+    // ENOENT：真的没有。ENOTDIR：路径中间被一个文件挡住了（`.mcp.json/x`）——
+    // 对我们的用途来说同样等于「这个路径上没有文件」（判据见 isMissingPath）。
+    if (isMissingPath(e)) {
+      return { exists: false, empty: false, bom: false, value: {}, error: null };
+    }
+    // 其余一律是「有东西，但读不到」。**绝不能降级成「不存在」**：那会让调用方
+    // 走「没坏、可以写」那条分支。Windows 上权限问题可能是 EPERM 也可能是 EACCES，
+    // 所以这里不逐个列举，凡不是上面两种的都算。
+    return {
+      exists: true,
+      empty: false,
+      bom: false,
+      value: null,
+      error: `读不到（${code ?? '未知错误'}）：${/** @type {Error} */ (e).message}`,
+    };
+  }
+
+  // Windows 上的编辑器加 UTF-8 BOM 很常见，JSON.parse 会直接抛错。
+  // 写回时保持原样，别去动用户的编码习惯。
+  const bom = raw.charCodeAt(0) === 0xfeff;
+  const body = bom ? raw.slice(1) : raw;
+
+  if (body.trim() === '') {
+    return { exists: true, empty: true, bom, value: {}, error: null };
+  }
+
+  /** @type {any} */
+  let value;
+  try {
+    value = JSON.parse(body);
+  } catch (e) {
+    return {
+      exists: true,
+      empty: false,
+      bom,
+      value: null,
+      error: `不是合法的 JSON：${/** @type {Error} */ (e).message}`,
+    };
+  }
+  if (!isPlain(value)) {
+    return { exists: true, empty: false, bom, value: null, error: '顶层必须是一个 JSON 对象' };
+  }
+  return { exists: true, empty: false, bom, value, error: null };
+}
+
+/**
+ * 原子写：先写同目录的临时文件，再 rename 过去。
+ *
+ * 和 `link.js` 建链接同一个标准——写坏 `.claude/settings.json` 等于用户的
+ * Claude 起不来，这里不该比建链接更草率。失败时原文件一个字节都没动过。
+ *
+ * 临时文件名里带 `process.pid`。**这就够了，不需要引入锁**：进程内不会并发
+ * 写同一个文件（sync 从头到尾是顺序执行的），而跨进程 pid 必不相同，于是各写
+ * 各的临时文件。用固定名字时，两个进程会互相踩：A 的收尾清理（写失败那条路径
+ * 上的 `rmSync`）会把 B 正在写的那个删掉，然后 B 的 rename 报一个跟真实原因
+ * 毫无关系的错。带 pid 之后最坏情况只剩「两个进程都 rename 成功、后一个赢」——
+ * 那是原子写本来就接受的结果，而且两份内容本来就是同一份。
+ *
+ * @param {string} abs @param {any} value @param {{bom?: boolean}} [opts]
+ */
+export function writeJsonFile(abs, value, opts = {}) {
+  const text = `${JSON.stringify(value, null, 2)}\n`;
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+
+  const tmp = `${abs}.agent-sync.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, opts.bom ? `\ufeff${text}` : text);
+    fs.renameSync(tmp, abs);
+  } catch (e) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // 临时文件都清不掉的话，报原来那个错更有用
+    }
+    throw e;
+  }
+}
+
+/** 只读地读一批内容文件，逐个校验。返回 {desired, problems, warnings} */
+function readSources({ tool, kind, sources }) {
+  /** @type {Record<string, any>} */
+  const desired = {};
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {string[]} */
+  const warnings = [];
+
+  for (const [id, src] of Object.entries(sources)) {
+    const read = readJsonFile(src);
+    if (!read.exists) {
+      problems.push(`${kind}:${id} 的内容文件读不到（${src}）`);
+      continue;
+    }
+    if (read.error) {
+      problems.push(`${kind}:${id}：${read.error}`);
+      continue;
+    }
+
+    const built =
+      kind === 'mcp' ? buildMcpEntry(read.value, tool) : buildHooksEntry(read.value, tool);
+    if ('error' in built) {
+      problems.push(`${kind}:${id}：${built.error}`);
+      continue;
+    }
+    for (const w of built.warnings ?? []) warnings.push(`${kind}:${id}：${w}`);
+    desired[id] = built.value;
+  }
+
+  return { desired, problems, warnings };
+}
+
+/**
+ * 一个工具的一类内容：读内容文件 → 合并 → （必要时）写。
+ *
+ * @param {{
+ *   projectRoot: string, tool: string, kind: string,
+ *   sources: Record<string, string>,   // id → 内容文件的绝对路径
+ *   prev: Record<string, any>,         // merged[tool][kind]，上一轮我们写了什么
+ *   keep?: string[],                   // protect 锁住的 id，整个不碰
+ *   dryRun?: boolean,
+ * }} input
+ * @returns {{
+ *   rel: string, verified: boolean, changed: boolean, created: boolean,
+ *   recorded: Record<string, any>, problems: string[], conflicts: string[], warnings: string[],
+ * }}
+ */
+export function applyMerge({ projectRoot, tool, kind, sources, prev, keep = [], dryRun = false }) {
+  const target = mergeTarget(tool, kind);
+  if (!target) {
+    throw new Error(`${tool} 没有 ${kind} 的合并目标——调用方该先用 mergeTarget() 判断`);
+  }
+
+  const label = `${TOOLS[tool].label} · ${target.rel}`;
+  const abs = path.resolve(projectRoot, target.rel);
+
+  // 诊断一律在这里加「哪个工具、哪个文件」的前缀，**加一次**。
+  // 以前两处各加一遍，同一句话里会出现 `Claude Code（.mcp.json）：Claude Code · .mcp.json …`。
+  /** @param {string} m */
+  const tag = (m) => `${label}：${m}`;
+
+  const { desired, problems: sourceProblems, warnings: sourceWarnings } = readSources({
+    tool,
+    kind,
+    sources,
+  });
+  const problems = sourceProblems.map(tag);
+  const warnings = sourceWarnings.map(tag);
+
+  /**
+   * 收工：把已经攒下的诊断带上，别让调用方以为一切正常。
+   *
+   * **`recorded` 的默认值是「上一轮那份」，不是空。** 走到这几条早退路径
+   * （目标是链接 / 是目录 / 读不了）时文件一个字节都没动过，而
+   * **「没动过」不等于「不是我们写的」**——抹掉归属是不可逆的：下一轮 `prev`
+   * 成了 `{}`，那几个 id 立刻落进「与记录之外的 server 重名」那一支，sync 会
+   * 劝用户「删掉那一份，或写进 protect」，而那份本来就是它自己写的。
+   *
+   * 触发方式简单到离谱（实测过）：`.mcp.json` 里多一个尾逗号 → 读不了 →
+   * 归属当场消失，把文件修好也回不来。
+   *
+   * 同一条口径在 mergeMcp / mergeHooks 里也写着（读不懂现场时 `recorded: {...prev}`），
+   * 只有这里漏了。写失败那条路仍然显式传 `recorded`（那时确实是我们算出来的新归属）。
+   */
+  const done = (extra = {}) => ({
+    rel: target.rel,
+    verified: target.verified,
+    changed: false,
+    created: false,
+    recorded: { ...prev },
+    problems,
+    conflicts: [],
+    warnings,
+    ...extra,
+  });
+
+  // ---- 目标文件能写吗 ----
+  //
+  // 判「在不在」用 lstat（见 lexists），**不能用 `fs.existsSync`**：它跟链接目标，
+  // 断链返回 false，于是下面这道守卫被整条跳过——POSIX 上紧接着的 rename 会
+  // 直接把那个断链替换掉，用户指向 dotfiles 仓库的链接就没了；Windows 上则
+  // 报一句看不出所以然的 `写入失败：EPERM … rename`。
+  if (lexists(abs)) {
+    if (isSymlink(abs)) {
+      // `.claude/settings.json` 指向 dotfiles 仓库是合法且常见的配置。
+      // 我们只能改工作区里这一份，改不了别人仓库里的，所以拒绝。
+      problems.push(tag('是一个链接（指向别处），本工具不碰——请自行维护'));
+      return done();
+    }
+    if (fs.lstatSync(abs).isDirectory()) {
+      problems.push(tag('是个目录，不是文件'));
+      return done();
+    }
+  }
+
+  const read = readJsonFile(abs);
+  if (read.error) {
+    // **一个字都不写。** 绝不能「解析失败 / 读不到就当空的然后覆盖写」。
+    problems.push(tag(`${read.error}——没有改动它`));
+    return done();
+  }
+  if (read.empty) warnings.push(tag('是空文件，按空对象处理'));
+
+  // ---- 合并 ----
+  const { next, recorded, conflicts, problems: planProblems } = planMerge({
+    kind,
+    current: read.value,
+    desired,
+    keep,
+    prev,
+  });
+  // 「结构不认识，没动它」是故障不是保护：本该写进去的没写进去，必须说出来
+  for (const p of planProblems) problems.push(tag(p));
+
+  // ---- 该不该写 ----
+  //
+  // 按**解析后的结构**比，不按文本比。否则用户的 4 空格缩进、工具重排键序
+  // 都会触发一次重写，那个文件在 git 里反复出现。第一次写完之后就再也不抖。
+  //
+  // 「没有东西要写就一个字都不写」也由这条兜住：`planMerge` 在没有内容可合时
+  // 原样返回，next 与读到的逐字段相同，changed 为假——用户的 `{"mcpServers":{}}`
+  // 不会被改成 `{}`，也不会平白多出一个空壳。
+  const changed = !deepEqualJSON(next, read.value);
+
+  if (changed && !dryRun) {
+    try {
+      writeJsonFile(abs, next, { bom: read.bom });
+    } catch (e) {
+      problems.push(tag(`写入失败：${/** @type {Error} */ (e).message}`));
+      return done({ recorded });
+    }
+  }
+
+  return {
+    rel: target.rel,
+    verified: target.verified,
+    changed,
+    created: changed && !read.exists,
+    recorded,
+    problems,
+    conflicts,
+    warnings,
+  };
+}
+
+/**
+ * 只读检查：现在盘上的结果和我们期望的是不是一致。
+ *
+ * 给 `status` / `doctor` 用，**不写盘**。和写入侧共用 `deepEqualJSON`，
+ * 保证「报漂移」和「会不会真写」是同一个判断——两处各写一套迟早对不上。
+ *
+ * @param {{
+ *   projectRoot: string, tool: string, kind: string,
+ *   sources: Record<string, string>, prev: Record<string, any>, keep?: string[],
+ * }} input
+ * @returns {{state: 'ok'|'drift'|'missing'|'unreadable'|'conflict', detail: string}}
+ */
+export function checkMerge({ projectRoot, tool, kind, sources, prev, keep = [] }) {
+  const target = mergeTarget(tool, kind);
+  if (!target) return { state: 'conflict', detail: '这个工具没有对应的合并目标' };
+
+  const abs = path.resolve(projectRoot, target.rel);
+  const hasWork = Object.keys(sources).length > 0 || Object.keys(prev).length > 0;
+
+  // 和写入侧同一道守卫：existsSync 对断链返回 false，会把「这是个链接」整个漏掉，
+  // 于是 status / doctor 打出「还没生成——跑一次 sync」，而 sync 去了会被拒绝。
+  if (!lexists(abs)) {
+    return hasWork
+      ? { state: 'missing', detail: `${target.rel} 还不存在——跑一次 sync 生成` }
+      : { state: 'ok', detail: '' };
+  }
+  if (isSymlink(abs)) {
+    return { state: 'conflict', detail: `${target.rel} 是一个链接，本工具不碰` };
+  }
+
+  const read = readJsonFile(abs);
+  if (read.error) return { state: 'unreadable', detail: `${target.rel} ${read.error}` };
+
+  const { desired, problems: sourceProblems } = readSources({ tool, kind, sources });
+
+  // **内容文件本身坏了**：它不在 `desired` 里，于是下一步会算出「漂移」，
+  // 报出去是「跑一次 sync 重新合并」——而 sync 去了只会再报一次同样的错，
+  // 用户被指去跑一条注定失败的命令。直接把真正的原因说出来。
+  if (sourceProblems.length > 0) {
+    return { state: 'unreadable', detail: sourceProblems.join('；') };
+  }
+
+  const { next, conflicts, problems } = planMerge({ kind, current: read.value, desired, keep, prev });
+
+  // 结构不认识的报成「有本工具没动的地方」，而**不是 ok**：后者会在 status 里打出
+  // 一句「✅ 一致」，而实际上一个字都没合过——正是这个模块开头想避免的那句话。
+  if (problems.length > 0) return { state: 'conflict', detail: problems.join('；') };
+  if (conflicts.length > 0) return { state: 'conflict', detail: conflicts.join('；') };
+  if (!deepEqualJSON(next, read.value)) {
+    return { state: 'drift', detail: `${target.rel} 和 .agents/ 里的内容对不上` };
+  }
+  return { state: 'ok', detail: '' };
+}
+
+// ---------------------------------------------------------------------------
+// 按 [工具 × 类型] 展开
+// ---------------------------------------------------------------------------
+
+/**
+ * 把 `agents.json` 的 `protect` 折算成**合并层**的「整个不碰」名单。
+ *
+ * `protect` 是条目层的写法（`"hook:dept-hooks"`），合并层按目录分组（`hooks`），
+ * 中间要过一次 `ITEM_KINDS` 的映射。
+ *
+ * **这段原先在 sync / status / doctor 里各写了一遍**——三份一模一样的语义判断。
+ * 加一类合并内容时漏改任何一处，那一处的 `protect` 就会静默失效（用户以为锁上了，
+ * 实际照删），而这正是 `ITEM_KINDS` 那张表存在的理由。
+ *
+ * @param {string[]} [protect]
+ * @returns {Record<string, string[]>} 目录名 → 锁住的 id
+ */
+export function keepByProtect(protect = []) {
+  /** @type {Record<string, string[]>} */
+  const out = Object.fromEntries(MERGE_KINDS.map((d) => [d, /** @type {string[]} */ ([])]));
+  for (const key of protect) {
+    const colon = key.indexOf(':');
+    if (colon === -1) continue;
+    const dir = ITEM_KINDS[key.slice(0, colon)]?.dir;
+    if (dir && MERGE_KINDS.includes(dir)) out[dir].push(key.slice(colon + 1));
+  }
+  return out;
+}
+
+/**
+ * 一次完整的合并：声明了的每个工具 × 每一类内容，各走一遍 `applyMerge`。
+ *
+ * `sourcesByKind` 由调用方给，因为「这一轮该装什么」只有 sync 知道：
+ * `--dry-run` 时 `applyInstall` 没执行，`.agents/` 里可能还是上一轮的旧内容，
+ * 从那儿读会让预演报「无变化」而真跑大改。
+ *
+ * ## 不传 `--prune` 时不摘
+ *
+ * 和内容层一个口径：本工具**默认只报告不删**。掉出选择的条目会被塞进 `keep`，
+ * 于是「整个不碰」——它们继续留在 `recorded` 里，下一轮还是我们说得出归属的。
+ * 加 `--prune` 才真摘。
+ *
+ * @param {{
+ *   projectRoot: string, tools: string[],
+ *   sourcesByKind: Record<string, Record<string, string>>,  // 类型 → {id → 内容文件绝对路径}
+ *   keepByKind?: Record<string, string[]>,                  // 类型 → protect 锁住的 id
+ *   prevMerged?: Record<string, any>,
+ *   dryRun?: boolean, prune?: boolean,
+ * }} input
+ */
+export function applyMergeAll({
+  projectRoot,
+  tools,
+  sourcesByKind,
+  keepByKind = {},
+  prevMerged = {},
+  dryRun = false,
+  prune = false,
+}) {
+  /** @type {Record<string, any>} */
+  const merged = {};
+  /** @type {{tool: string, kind: string, rel: string, verified: boolean, changed: boolean, created: boolean, conflicts: string[]}[]} */
+  const applied = [];
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {{tool: string, kind: string, rel: string, messages: string[]}[]} */
+  const conflicts = [];
+  /** @type {{tool: string, kind: string, ids: string[]}[]} */
+  const stale = [];
+  /** @type {{tool: string, kind: string, count: number}[]} */
+  const unsupported = [];
+
+  // **也要遍历「已经不声明、但记录里还有」的工具。**
+  //
+  // 只遍历 `tools` 的话，某个工具从 `links` 里去掉之后，我们以前写进它配置
+  // 文件里的条目**没有任何代码路径会去清**——而那个文件是提交进版本库的。
+  // 这和 `findStaleLinks` 要解决的是同一类问题。
+  const allTools = [...new Set([...tools, ...Object.keys(prevMerged ?? {})])];
+
+  // 记录里可能有**本版本不认识**的工具名：同事用了更新的版本、手改过记录、
+  // 或者将来加了新工具。它们绝不能进下面那个循环——`TOOLS[tool].label` 会当场
+  // 抛 TypeError，而 sync 崩的位置正好是「内容已写、配置文件已建、记录还没写下去」，
+  // 下一轮我们自己的条目就会被判成「与记录之外的 server 重名」，永久不再更新。
+  //
+  // 所以过滤掉，并且**明确报出来**：跳过不等于没有这回事，那几条以后没人清理。
+  // 报成 warning 而不是 problem：内容本身没问题，本轮该做的都做完了，拿一个
+  // 退出码逼用户去改一个可能是同事写下的记录，不划算（sync 会把它打出来）。
+  const knownTools = allTools.filter(isTool);
+  const unknownTools = allTools.filter((t) => !isTool(t));
+  if (unknownTools.length > 0) {
+    warnings.push(
+      `记录里有 ${unknownTools.length} 个本版本不认识的名字：${unknownTools.join('、')}——已跳过，` +
+        '用其它版本的本工具写下的记录会这样；本轮不会去动它们的配置',
+    );
+  }
+
+  for (const tool of knownTools) {
+    const label = TOOLS[tool].label;
+    // 没被声明的工具：什么都不该再写进去，于是 desired 为空，我们以前写的全进待摘名单
+    const declared = tools.includes(tool);
+
+    for (const kind of MERGE_KINDS) {
+      const sources = declared ? (sourcesByKind[kind] ?? {}) : {};
+      const keep = declared ? (keepByKind[kind] ?? []) : [];
+
+      // 该工具根本没有这一类内容的合并目标（codex 的 mcp）。
+      // **必须报警**——删掉 status 里那句「合并器未实现」之后，这是唯一会说话的地方。
+      if (!mergeTarget(tool, kind)) {
+        const n = Object.keys(sources).length;
+        if (n > 0) unsupported.push({ tool, kind, count: n });
+        continue;
+      }
+
+      const prev = prevMerged?.[tool]?.[kind] ?? {};
+      const notWanted = Object.keys(prev).filter((id) => !Object.hasOwn(sources, id) && !keep.includes(id));
+      if (notWanted.length > 0) stale.push({ tool, kind, ids: notWanted });
+
+      const r = applyMerge({
+        projectRoot,
+        tool,
+        kind,
+        sources,
+        prev,
+        // 不加 --prune 时把它们也「锁住」，等于整个不碰，但报告里会列出来
+        keep: prune ? keep : [...keep, ...notWanted],
+        dryRun,
+      });
+
+      // 诊断在 applyMerge 里已经统一带了「工具 · 文件」前缀，这里**不再拼一遍**：
+      // 两层前缀拼出来的 `Claude Code（.mcp.json）：Claude Code · .mcp.json …`
+      // 看着像两条不同的消息，实际是一条。
+      for (const p of r.problems) problems.push(p);
+      for (const w of r.warnings) warnings.push(w);
+
+      const recorded = Object.keys(r.recorded).length > 0 ? r.recorded : null;
+      if (recorded) merged[tool] = { ...(merged[tool] ?? {}), [kind]: recorded };
+
+      if (r.conflicts.length > 0) conflicts.push({ tool, kind, rel: r.rel, messages: r.conflicts });
+      if (r.changed || r.created) {
+        applied.push({
+          tool,
+          kind,
+          rel: r.rel,
+          verified: r.verified,
+          changed: r.changed,
+          created: r.created,
+          conflicts: r.conflicts,
+        });
+      }
+    }
+  }
+
+  return { merged, applied, problems, warnings, conflicts, stale, unsupported };
+}
+
+/**
+ * `.agents/<dir>/` 下有哪些 `*.json`（**只看目录，不看记录**）。
+ *
+ * 用它回答「有没有东西需要合并」；用 `sourcesFromDisk` 回答「该合并哪些」。
+ * 两件事分开：混成一个的话，还没写过记录的新项目就不会被告知
+ * 「声明的工具里没有一个能承接这类内容」。
+ *
+ * **「没有这个目录」和「读不了这个目录」是两件事**，和 `readJsonFile` 一个口径：
+ * 前者返回 `[]`，后者返回 `null`。把权限 / IO 错误吞成 `[]` 的话，`doctor` 会
+ * 打出一句「没有 hooks / mcp 内容，不需要合并」、`status` 整节跳过——目录读不
+ * 出来的事就一声不吭了，而那正是「看起来没事、实际上没人在管」的形状。
+ *
+ * @param {string} projectRoot @param {string} dir
+ * @returns {string[]|null} null 表示「有东西但读不了」
+ */
+export function presentIn(projectRoot, dir) {
+  /** @type {string[]} */
+  let names;
+  try {
+    names = fs.readdirSync(path.resolve(projectRoot, CONTENT_ROOT, dir));
+  } catch (e) {
+    if (isMissingPath(e)) return [];
+    return null;
+  }
+  return names.filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -'.json'.length));
+}
+
+/**
+ * 从 `.agents/<dir>/` 里挑出**记录说装过的**内容文件，给只读检查当「期望内容」。
+ *
+ * 为什么只挑记录里的：`sync` 也只合并本次选中的那些。把用户自己丢进
+ * `.agents/mcp/` 的 server 也算进来的话，`status` 会报一堆「漂移」——
+ * 而 `sync` 根本不会去动它们，那是虚惊。
+ *
+ * 只读命令（status / doctor）读不到内容仓库，所以「期望内容」只能取
+ * `.agents/` 里现成的——和链接那一节同一个边界。
+ *
+ * @param {string} projectRoot @param {{usable: boolean, installed: string[]}} record @param {string} dir
+ * @returns {Record<string, string>}
+ */
+export function sourcesFromDisk(projectRoot, record, dir) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!record.usable) return out;
+
+  for (const key of record.installed) {
+    let parsed;
+    try {
+      parsed = parseItem(key);
+    } catch {
+      continue;
+    }
+    if (ITEM_KINDS[parsed.kind]?.dir !== dir) continue;
+    const abs = path.resolve(projectRoot, CONTENT_ROOT, dir, `${parsed.id}.json`);
+    if (fs.existsSync(abs)) out[parsed.id] = abs;
+  }
+  return out;
+}
+
+/**
+ * `applyMergeAll` 的只读版，供 `status` / `doctor` 用。
+ *
+ * 和写入侧共用 `checkMerge`，所以「报漂移」和「会不会真写」是同一个判断——
+ * 两处各写一套迟早会对不上。
+ *
+ * ## `keep` 必须和写入侧算得一模一样
+ *
+ * 写入侧不加 `--prune` 时会把「这一轮不想摘的」也塞进 `keep`（等于整个不碰）。
+ * 只读侧少了这一步的话，两边对同一份现场会给出相反的结论：`status` 报 `drift`、
+ * 建议「跑一次 sync」，而 `sync` 故意不写——用户卡在退出码 1，**没有任何命令
+ * 能修好**（实测过：掉出选择 + 手删 `.agents/mcp/srv.json` 之后，`status` 三轮
+ * 都报问题，`sync` 三轮都说无事可做）。所以这里照着 `applyMergeAll` 再算一遍，
+ * 包括 `prune` 这个开关。
+ *
+ * @param {{
+ *   projectRoot: string, tools: string[],
+ *   sourcesByKind: Record<string, Record<string, string>>,
+ *   keepByKind?: Record<string, string[]>, prevMerged?: Record<string, any>,
+ *   prune?: boolean,
+ * }} input
+ * @returns {{tool: string, kind: string, rel: string, state: string, detail: string, ids: string[]}[]}
+ */
+export function checkMergeAll({
+  projectRoot,
+  tools,
+  sourcesByKind,
+  keepByKind = {},
+  prevMerged = {},
+  prune = false,
+}) {
+  /** @type {{tool: string, kind: string, rel: string, state: string, detail: string}[]} */
+  const out = [];
+
+  for (const tool of tools) {
+    for (const kind of MERGE_KINDS) {
+      const target = mergeTarget(tool, kind);
+      if (!target) continue; // 不支持由调用方单独报，这里只报「支持但状态不对」
+
+      const sources = sourcesByKind[kind] ?? {};
+      const keep = keepByKind[kind] ?? [];
+      const prev = prevMerged?.[tool]?.[kind] ?? {};
+
+      // **没有东西该合就跳过，判据和目标文件在不在无关。**
+      // 用「文件在不在」当判据的话，用户自己往 `.agents/mcp/` 丢一个不在记录里的
+      // 文件、自己写一份 `.mcp.json`，就会得到一句「✅ Claude Code · .mcp.json 一致」
+      // ——而压根没有任何东西被合过。那正是这个模块开头想避免的话。
+      const hasWork = Object.keys(sources).length > 0 || Object.keys(prev).length > 0;
+      if (!hasWork) continue;
+
+      const notWanted = Object.keys(prev).filter((id) => !Object.hasOwn(sources, id) && !keep.includes(id));
+
+      const r = checkMerge({
+        projectRoot,
+        tool,
+        kind,
+        sources,
+        prev,
+        // 和 applyMergeAll 同一行算法，别在这里另写一套
+        keep: prune ? keep : [...keep, ...notWanted],
+      });
+
+      // 「有不再需要的、但默认不会摘」要单独说，**不能混进 `drift`**：
+      // `drift` 在 status 里会把人指去「跑一次 sync」，而 sync 默认压根不会动它
+      // ——那正是上面那段注释要躲的死循环。用 `stale`，让人看到该加 `--prune`。
+      const state = r.state === 'ok' && !prune && notWanted.length > 0 ? 'stale' : r.state;
+      out.push({ tool, kind, rel: target.rel, state, detail: r.detail, ids: notWanted });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * `status` / `doctor` 共用的「合并产物」只读检查。
+ *
+ * 两个命令原先各写一遍（各三十多行），只有文案不同：读记录 → `presentIn` →
+ * 按 `protect` 折算 keep → `checkMergeAll` → 没有合并目标的工具 → 未实证的路径。
+ * 文案各写各的没问题，**判断必须是同一份**——两处各写一套的下场，就是
+ * `checkMergeAll` 注释里记的那种「status 报 drift、sync 故意不写，用户卡在
+ * 退出码 1 没有任何命令能修好」。
+ *
+ * @param {{
+ *   projectRoot: string,
+ *   config: {tools: string[], protect: string[]},
+ *   record: {usable: boolean, installed: string[], merged?: Record<string, any>},
+ * }} input
+ */
+export function checkMergeView({ projectRoot, config, record }) {
+  const merged = record?.merged ?? {};
+  const present = Object.fromEntries(MERGE_KINDS.map((d) => [d, presentIn(projectRoot, d)]));
+  const presentCount = MERGE_KINDS.reduce((n, d) => n + (present[d]?.length ?? 0), 0);
+  // 「读不了」和「是空的」是两件事：前者我们根本不知道里面有什么，
+  // 也就答不了「该合的合了没有」——调用方要各自说一句，别当成空
+  const unreadable = MERGE_KINDS.filter((d) => present[d] === null);
+
+  /** 该工具根本没有这一类内容的合并目标（codex 的 mcp）——删掉 status 里那句
+   *  「合并器未实现」之后，这是唯一还会为「装了不生效」说话的地方 */
+  const unsupported = [];
+  for (const tool of config.tools) {
+    for (const dir of MERGE_KINDS) {
+      if (mergeTarget(tool, dir)) continue;
+      const count = present[dir]?.length ?? 0;
+      if (count > 0) unsupported.push({ tool, dir, count });
+    }
+  }
+
+  /** 没实证的路径（目前只有 Trae）——不能报得跟 Claude 那条一样肯定 */
+  const unverified = [];
+  for (const tool of config.tools) {
+    for (const dir of mergeKindsOf(tool)) {
+      const t = mergeTarget(tool, dir);
+      if (t && !t.verified) unverified.push({ tool, rel: t.rel });
+    }
+  }
+
+  return {
+    present,
+    presentCount,
+    unreadable,
+    /** 这一节有没有值得显示的东西——空项目不该因为「文件不存在」吃一笔警告 */
+    hasWork: presentCount > 0 || unreadable.length > 0 || Object.keys(merged).length > 0,
+    rows: checkMergeAll({
+      projectRoot,
+      tools: config.tools,
+      sourcesByKind: Object.fromEntries(
+        MERGE_KINDS.map((d) => [d, sourcesFromDisk(projectRoot, record, d)]),
+      ),
+      keepByKind: keepByProtect(config.protect),
+      prevMerged: merged,
+    }),
+    unsupported,
+    unverified,
+  };
+}