agent-syncer 0.1.0 → 0.1.2

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 资产分发到各编码工具的配置目录
@@ -11,38 +11,170 @@ ${bold('用法')}
   agent-syncer <命令> [选项]
 
 ${bold('命令')}
-  link      建好目录链接并维护 .gitignore；没有 agents.json 时会先让你勾选
-  status    只读报告：每个链接当前是否健康，.agents/ 下各有多少内容
-  doctor    只读自检：运行环境、链接能力、.gitignore、各工具是否存在
+  init      交互式生成 agents.json（问内容仓库、版本、模板、要适配的工具）
+  sync      从内容仓库挑一个模板装进 .agents/，然后建好链接（一条命令搞定）
+  link      只建目录链接并维护 .gitignore；没有 agents.json 时会先让你勾选
+            带上 --src/--dst 则退化成「在这儿建一条链接」，不读任何项目配置
+  list      只读报告：内容仓库里有哪些条目和模板（自定义 include 之前先看这个）
+  status    只读报告：每个链接是否健康、.agents/ 下各有多少内容、装过什么、
+            有没有「不再使用的链接 / 合并产物」
+  doctor    只读自检：运行环境、链接能力、内容、记录、.gitignore、行尾、
+            合并产物、MCP 批没批准、各工具是否存在
 
 ${bold('选项')}
-  --dry-run       只打印计划，不写盘（link 支持）
-  --force         覆盖指向别处的链接（绝不删除实体目录）
-  --yes           不询问，直接按已有目录推断（CI / postinstall 用）
-  --no-save       交互式勾选后不写入 agents.json
-  --cwd=<路径>    指定项目根，默认当前目录
-  --help          显示本帮助
+  ${dim('一律写成 --名字=值。空格分隔不支持（--src ../x）——那样写会被当成位置参数，本工具会当场提醒。')}
+  --from=<来源>    内容仓库位置（本地路径或 git 地址），覆盖 agents.json 里的 content
+  --ref=<版本>     分支名 / 标签名 / 提交 SHA，覆盖 agents.json 里的 ref
+  --bundle=<名字>  装哪个模板，覆盖 agents.json 里的 bundle；多个用逗号分隔
+                   list --bundle=<名字> 则展开这个模板，看它最终会装哪些条目
+  --kind=<类型>    只给 list 用：只看一类条目（单复数都行，如 skill / skills）
+  --src=<目录>     只给 link 用：只建一条链接，这是内容源；与 --dst 配对。
+  --dst=<路径>     两个一起给时**不读 agents.json**，就是「在这儿建一个链接」。
+                   相对路径按 --cwd 解析，绝对路径原样用。
+                   ⚠️ 这样建的链接**不在托管范围内**：不写 .gitignore 托管段、
+                   status 看不到它、--prune 也不清理它。落点在 git 仓库里时记得
+                   自己把落点写进 .gitignore——git 会穿透链接把源的内容再提交一份。
+  --dry-run        只打印计划，不写盘
+  --force          覆盖指向别处的链接（绝不删除实体目录）
+  --prune          清理不再需要的链接和内容（默认只报告不删，见「不再需要的东西」）
+  --yes            不询问（CI / postinstall 用）。它只是不弹提示，**不负责猜**：
+                   links 没写在 agents.json 里时直接报错并告诉你怎么写
+  --no-save        交互式勾选后不写入 agents.json
+  --cwd=<路径>     指定项目根（--src/--dst 模式下是工作目录），默认当前目录
+  --help           显示本帮助
 
 ${bold('内容约定')}
   所有内容只在 ${bold('.agents/')} 下保存一份：
-    .agents/skills/<名字>/SKILL.md
-    .agents/rules/<名字>.md
-    .agents/commands/<名字>.md
-    .agents/agents/<名字>.md
-  再由本工具在各工具目录建链接指过来，因此永远只有一份真源。
+    .agents/skills/<名字>/SKILL.md      链接给各工具
+    .agents/rules/<名字>.md             链接给各工具
+    .agents/commands/<名字>.md          链接给各工具
+    .agents/agents/<名字>.md            链接给各工具
+    .agents/hooks/<名字>.json           合并进 .claude/settings.json 的 hooks 段
+    .agents/mcp/<名字>.json             合并进 .mcp.json / .trae/mcp.json
+    .agents/scripts/                    被 hooks / mcp 按路径引用（选了它们才同步）
+    .agents/.agent-sync.json            本工具写的：记着哪些内容是它装的（要提交）
+  前四类在各工具目录建**链接**指过来，因此永远只有一份真源；
+  后两类没法链接（那些文件里还有你自己的东西），只能读—改—写地${bold('合并')}进去，
+  本工具只动自己写过的那些条目。
+
+  ${bold('合并产物要提交进版本库')}：.mcp.json 和 .claude/settings.json 都是团队共享的
+  配置，密钥一律写成 ${'${环境变量}'} 占位符，别写死。
+
+  ${bold('MCP 写进去了不等于生效')}：Claude Code 要你逐条批准才会连。批准记录
+  存在你本机的 ~/.claude.json 里，${bold('不随仓库共享')}——队友要各自批一次。
+
+  ${bold('项目根怎么写')}：内容里引用项目内脚本时，写 ${'${CLAUDE_PROJECT_DIR}'}
+  还是 ${'${workspaceFolder}'} 都认，合并时按目标工具翻译成它自己的写法。
+  别的 ${'${VAR}'} 原样保留，由工具自己在运行时展开。
+
+${bold('第一次用：init')}
+  没有 agents.json 的项目，跑 agent-syncer init 会依次问四件事：
+
+    1. 内容仓库在哪（本地路径 或 git 地址）
+    2. 用哪个版本（分支 / 标签）。**本地路径不问**——sync 读的是那个目录的工作树，
+       ref 不生效，让你选一个不生效的版本比不让你选更糟。不是 git 仓库、离线
+       或要凭据时也跳过。要钉版本请把内容仓库写成 git 地址（file:///… 也算）
+    3. 装哪些模板（可以一个都不选，之后用 include 逐条挑）
+    4. 适配哪些编码工具（写进 "links"）
+
+  然后把将要写入的整份配置打印出来让你确认，${bold('确认过才落盘')}，
+  最后问一句要不要立刻 sync。中途 Ctrl-C 退出，一个文件都不会写。
+
+  ${bold('在终端里直接跑 sync 也一样')}：没有 agents.json 时会先带你走一遍 init。
+  --from / --ref / --bundle 传进来的值会当作对应问题的${bold('预填值')}，不必重答。
+  非交互环境（管道、CI、postinstall）和 --yes ${bold('都不会')}弹提示，还是照旧
+  报错并告诉你配置怎么写——在那些地方弹提示会永久挂住。
+
+${bold('项目配置 agents.json')}（init 生成，也可以手写；放项目根）
+  {
+    "content": "<内容仓库：本地路径或 git 地址>",
+    "ref": "<分支 / 标签 / 提交 SHA，可省略>",
+    "bundle": "java-backend",
+    "include": ["skill:extra"],
+    "exclude": ["hook:dept-hooks"],
+    "protect": ["skill:my-customized"],
+    "links": ["claude", "trae"]
+  }
+  注意 links 里写的是${bold('工具名')}，不是目录。选用一个工具就是它的
+  全部类型一起适配——没有「只要 .claude/rules 不要 .claude/skills」这种场景，
+  所以配置里不提供目录级开关。
+
+  ${bold('links 没写会怎样')}：link 不猜。在终端里跑它会列出来让你勾选；
+  非交互环境（管道、CI、--yes）则报错，并把可选项和写法一起列出来。
+  「这个项目用 Trae」是个持久事实，从「目录恰好存在」推出来的东西
+  用户既没同意过、也看不见，猜错还会给一个其实不用的工具建链接。
+
+${bold('挑内容：模板 + 项目级增删')}
+  bundle 可以是一个模板，也可以是数组（多个模板的结果取并集）：
+
+    "bundle": ["common", "frontend"]
+
+  一个模板都不写也行，只用 include 逐条挑，这就是"自定义"用法。
+  项目级的 include / exclude 叠在模板之上，exclude ${bold('最后过一遍')}：
+
+    模板并集 → +include → −exclude
+
+  所以 exclude 能砍掉上面任何一步加进来的东西，包括 include 刚加的。
+  多个模板之间互不干扰：各自解析完再取并集，A 模板的 exclude 不会
+  影响 B 模板——否则结果会取决于组合顺序，没法推理。模板里再套
+  模板也一样（"bundle": ["a", "b"] 写进 bundles/*.json 后用同一条规则）。
+
+  include / exclude 只认这两种写法：
+    "skill:code-style"   单个条目
+    "skill:*"            该类型全部
+
+  引用别的模板一律用 bundle 字段，**模板文件里也一样**：
+    "bundle": ["common"]        项目根和 bundles/*.json 用的是同一个字段
+
+  早期那种写进 include 的 "@common" 已经移除，写了会当场报错并给出新写法。
+  代价是 exclude 排不掉一整个模板了（以前 exclude: ["@common"] 可以），
+  只能逐条列、或者把那个模板拆小。
+
+${bold('不再需要的东西')}
+  换工具会留下链接和合并产物，换模板（或内容仓库改版）会留下内容。
+  它们都不会自动消失，而且不清理是有实际后果的：残留的链接已不在 .gitignore
+  托管段里，git 会顺着它们把 .agents/ 的内容再提交一份。
+
+  三者都默认只报告，确认后加 --prune：
+
+    agent-syncer sync --prune      # 内容、链接、合并产物一起清
+    agent-syncer link --prune      # 只清链接
+
+  界限划得很死：链接只删链接；内容只删「记录里说本工具装过的」；
+  合并产物只摘掉「记录说本工具写进去的」。**你自己写的一律不碰。**
+  删空之后剩下的空目录会顺手收掉，**但一个非空的目录都删不掉**
+  （rmdir 只对空目录成功，这是内核挡的，不是靠判断）。
+
+  合并那一边还有个更硬的规矩：**归属是被验证的，不是被断言的。**
+  记录说某条是本工具写的还不够，还要现场确实还是当初写的那份才动——
+  你改过它，本工具就保留你的改动并报一声，不会覆盖回去。
+
+  除了上面那些，「装过的条目里哪些你改过」本工具是认不出的——想保住就自己声明：
+
+    "protect": ["skill:my-customized", "script:tools/legacy.sh", "mcp:dept-wiki"]
+
+  锁 = 本工具整个不碰它：sync 不覆盖、--prune 不删、也不合并进工具配置。
+  写法与 --prune 输出里的条目名一致，不支持通配，写错会直接报错。
 
 ${bold('可用工具')}
   ${TOOL_NAMES.join('、')}
 
 ${bold('示例')}
+  agent-syncer init                   # 没有配置时跑这个，一路问下来就有 agents.json 了
+  agent-syncer init --from=../dept-content   # 把已知的值预填进问题里
+  agent-syncer sync --from=http://git.example.com/team/dept-content.git --ref=v2.0.0 --bundle=java-backend
+  agent-syncer sync --from=../dept-content --bundle=java-backend
+  agent-syncer sync --bundle=frontend --dry-run
   agent-syncer status
+  agent-syncer list --kind=skill     # 有哪些技能可以挑
+  agent-syncer list --bundle=java-backend   # 这个模板最终装哪些条目
   agent-syncer link                  # 没有配置时会让你勾选要建立哪些链接
-  agent-syncer link --dry-run
-  agent-syncer link --force
   agent-syncer link --yes            # 不询问，适合脚本
+  agent-syncer link --src=../shared/prompts --dst=.claude/skills   # 只建这一条，不读配置
+  agent-syncer sync --prune          # 清掉不再需要的内容和链接
 `;
 
-/** 手写参数解析，与 iqcs_web/scripts 下的既有风格一致（不引第三方依赖） */
+/** 手写参数解析——本工具零依赖，不引第三方命令行库 */
 function parseArgs(argv) {
   /** @type {Record<string, string|boolean> & {_: string[]}} */
   const flags = { _: [] };
@@ -59,8 +191,45 @@ 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',
   link: '../lib/commands/link.js',
+  list: '../lib/commands/list.js',
   status: '../lib/commands/status.js',
   doctor: '../lib/commands/doctor.js',
 });
@@ -82,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

@@ -1,19 +1,115 @@
 // @ts-check
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { CONFIG_FILENAME, loadConfig } from '../config.js';
 import { checkBlock } from '../gitignore.js';
-import { probeLinkCapability } from '../link.js';
+import { probeLinkCapability, samePath } from '../link.js';
 import { dim, fail, ok, plain, skip, title, warn } from '../log.js';
-import { CONTENT_ROOT, TOOLS, TOOL_NAMES } 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';
 
-/** @type {string[]} */
-const PACKAGE_TOOL_HINTS = {
-  claude: '.claude',
-  trae: '.trae',
-  codex: '.codex',
-};
+/**
+ * `.gitattributes` 里有没有一条「统一按文本处理」的规则。
+ *
+ * 只认 `text` 和 `text=auto` 这两种写法，**不认 `-text`**——那是「当成二进制，
+ * 别动它」，方向正好相反。`*.png binary` 这类也不会误伤，`binary` 是
+ * `-text -diff` 的别名，字面上没有 `text` 这个属性。
+ *
+ * @param {string} content
+ */
+function hasTextAuto(content) {
+  for (const line of content.split(/\r?\n/)) {
+    const s = line.trim();
+    if (s === '' || s.startsWith('#')) continue;
+    // 第一列是路径匹配式，后面才是属性
+    for (const attr of s.split(/\s+/).slice(1)) {
+      if (attr === 'text' || attr === 'text=auto') return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Claude Code 批没批准项目里的这几位 MCP server。
+ *
+ * 为什么这一条最值钱：合并成功之后最可能的失败**不是**「文件没写对」，而是
+ * 「文件写对了、一个人都没生效」。写 `.mcp.json` 只是第一步——Claude Code
+ * 要你逐条批准才会连，而批准记录存在**你自己机器**上的 `~/.claude.json` 里，
+ * 不随仓库共享。所以这一节回答的是「生效了吗」，而「文件在不在」回答不了。
+ *
+ * 只读、只看当前项目那一格、不打印文件内容。字段名没有权威依据，探测不到
+ * 就如实说「无法判断」，**绝不猜**。
+ *
+ * @param {string} cwd @param {string[]} names 我们合进去的 server 名
+ * @returns {{state: 'ok'|'pending'|'never'|'unknown', detail: string}}
+ */
+function claudeApproval(cwd, names) {
+  if (names.length === 0) return { state: 'ok', detail: '' };
+
+  /** @type {any} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.resolve(os.homedir(), '.claude.json'), 'utf8'));
+  } catch {
+    return { state: 'unknown', detail: '读不到 ~/.claude.json（没装 Claude Code，或还没跑过）' };
+  }
+
+  const projects = raw?.projects;
+  if (projects === null || typeof projects !== 'object') {
+    return { state: 'unknown', detail: '~/.claude.json 的结构和预期不一样，无法判断' };
+  }
+
+  // 项目的键是绝对路径；Windows 上大小写和斜杠都可能和这里的不一样
+  const key = Object.keys(projects).find((k) => samePath(path.resolve(k), cwd));
+  if (key === undefined) {
+    return { state: 'never', detail: 'Claude Code 还没在这个项目里跑过' };
+  }
+
+  const entry = projects[key] ?? {};
+  const enabled = Array.isArray(entry.enabledMcpjsonServers) ? entry.enabledMcpjsonServers : [];
+  const missing = names.filter((n) => !enabled.includes(n));
+  if (missing.length === 0) return { state: 'ok', detail: '' };
+
+  return { state: 'pending', detail: `还有 ${missing.length} 条没批准：${missing.join('、')}` };
+}
+
+/**
+ * 一个文件在 git 眼里是什么状态。
+ *
+ * **先看有没有被跟踪**：`.gitignore` 对已跟踪的文件完全无效，只看
+ * `check-ignore` 会把「早就提交过了」误报成「被忽略了」。
+ *
+ * 不是 git 仓库、或者没有 git，就什么都不说（返回 `skipped`）。
+ *
+ * @param {string} cwd @param {string} rel
+ * @returns {{state: 'tracked'|'untracked'|'ignored'|'skipped', rule?: string}}
+ */
+function gitStatusOf(cwd, rel) {
+  /** @param {string[]} args */
+  const run = (args) =>
+    spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+
+  if (run(['rev-parse', '--is-inside-work-tree']).status !== 0) return { state: 'skipped' };
+  if (run(['ls-files', '--error-unmatch', '--', rel]).status === 0) return { state: 'tracked' };
+
+  const ignored = run(['check-ignore', '-v', '--', rel]);
+  if (ignored.status === 0) return { state: 'ignored', rule: (ignored.stdout ?? '').trim() };
+
+  return { state: 'untracked' };
+}
+
+/**
+ * Windows 上 hook 靠 `sh` 执行（由 Git Bash 提供）。它不在 PATH 里的话，
+ * hook 会**静默不跑**——这是「hook 配了没反应」最常见的真实原因之一。
+ * 检查成本极低，而且不碰任何文件。
+ */
+function hasSh() {
+  return spawnSync('sh', ['-c', 'exit 0'], { stdio: 'ignore' }).status === 0;
+}
 
 /**
  * agent-syncer doctor —— 纯只读的环境自检。
@@ -67,23 +163,53 @@ 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) {
     ok(`${CONFIG_FILENAME} 存在`);
-    if (config.links.length > 0) plain(dim(`    links：${config.links.join('、')}`));
-    else warn('links 为空');
+    if (config.toolsDeclared) plain(dim(`    links：${config.tools.join('、') || '（空）'}`));
+    else {
+      warn(`没有写 links——link 会问你要用哪些工具，本工具不替你猜`);
+      plain(dim(`    可选：${TOOL_NAMES.join('、')}`));
+      warned += 1;
+    }
   } else {
-    skip(`${CONFIG_FILENAME} 不存在（link 会交互式询问，或按已有目录推断）`);
-    if (config.links.length > 0) plain(dim(`    推断结果：${config.links.join('、')}`));
-    else plain(dim('    没有可推断的项——需要交互式勾选'));
+    skip(`${CONFIG_FILENAME} 不存在`);
+    plain(dim(`    link 会问你要用哪些工具（${TOOL_NAMES.join('、')}），或写进 ${CONFIG_FILENAME}`));
   }
   for (const w of config.warnings) warn(w);
 
-  // ---- 5. .gitignore ----
+  // ---- 6. .gitignore ----
   title('.gitignore');
-  const gi = checkBlock(cwd, config.links);
+  const gi = checkBlock(cwd, config.tools);
   if (!gi.present) {
     warn('未找到 agent-syncer 托管段，运行 link 会写入');
     warned += 1;
@@ -91,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('托管段完整');
   }
@@ -101,20 +232,168 @@ export async function run({ cwd }) {
     ),
   );
 
-  // ---- 6. 各工具是否存在 ----
+  // ---- 7. .gitattributes ----
+  //
+  // 为什么要在意：`sync` 判断「内容变没变」是按字节比的，于是检出成 CRLF 的那份
+  // 会被当成「变了」。危害不大（多报一次「更新」，第二遍自愈），但每次克隆后
+  // 第一次 sync 都会莫名报一堆「更新」，而且会不会顺带弄脏 git 完全取决于
+  // **各人本机的 core.autocrlf**——这不该是个因人而异的变量。
+  //
+  // **只提示，绝不代写。** `* text=auto` 改的是整个仓库所有文件的检出行为，
+  // 是仓库级的决定，得由人来做。
+  title('.gitattributes');
+  const gaPath = path.resolve(cwd, '.gitattributes');
+  if (!fs.existsSync(gaPath)) {
+    warn('未找到——行尾行为会取决于各人本机的 core.autocrlf，不同机器结果不一样');
+    plain(dim('    建议在项目根加一份，内容：'));
+    plain(dim('        * text=auto'));
+    plain(dim('    否则每次克隆后第一次 sync 会多报一遍「更新」（第二遍自愈）；'));
+    plain(dim('    而 core.autocrlf=false 的项目里，行尾改动作会被当成真改动提交进去。'));
+    warned += 1;
+  } else if (!hasTextAuto(fs.readFileSync(gaPath, 'utf8'))) {
+    warn('存在，但没有 text / text=auto 规则');
+    plain(dim('    行尾行为仍然取决于各人本机的 core.autocrlf，建议补一行：* text=auto'));
+    warned += 1;
+  } else {
+    ok('已声明 text=auto，行尾行为不再取决于各人本机配置');
+  }
+
+  // ---- 8. 合并产物（hooks / mcp）----
+  //
+  // 这一节查的**不是「我写了吗」，是「生效了吗」**。写进 `.mcp.json` 只是第一步，
+  // 后面还有批准、还有「它进不进得了版本库」两道关。
+  title('合并产物（hooks / mcp）');
+
+  // 判断整个交给 merge.js 的 checkMergeView——status 用的是同一份。两个只读命令
+  // 对同一份现场给出相反结论，是以前真出过的事（见 checkMergeAll 的注释）。
+  const view = checkMergeView({ projectRoot: cwd, config, record });
+
+  // 「目录读不出来」和「目录是空的」是两件事。前者我们根本不知道里面有什么，
+  // 打成「没有 hooks / mcp 内容，不需要合并」就是替它说一句我们没资格说的话。
+  for (const d of view.unreadable) {
+    warn(`读不了 ${CONTENT_ROOT}/${d}/——里面有什么、能不能合，判断不了`);
+    warned += 1;
+  }
+
+  if (!view.hasWork) {
+    // 空项目不该因为「`.mcp.json` 不存在」就吃一笔警告，否则小结没人看
+    skip('没有 hooks / mcp 内容，不需要合并');
+  } else {
+    for (const r of view.rows) {
+      const label = `${TOOLS[r.tool].label} · ${r.rel}`.padEnd(28);
+      if (r.state === 'ok') {
+        ok(`${label} ${dim('和内容一致')}`);
+      } else if (r.state === 'missing') {
+        warn(`${label} 还没生成——跑一次 sync`);
+        warned += 1;
+      } else if (r.state === 'drift') {
+        warn(`${label} 和 ${CONTENT_ROOT}/ 里的内容对不上——跑一次 sync`);
+        warned += 1;
+      } else if (r.state === 'unreadable') {
+        warn(`${label} ${r.detail}`);
+        warned += 1;
+      } else if (r.state === 'stale') {
+        // 「默认不摘」是设计，说清楚有这么几条躺着就行。
+        // 措辞留余地：里面可能混着你改过的，那几条按设计会被保留。
+        warn(
+          `${label} 有 ${r.ids.length} 条不再需要的：${r.ids.join('、')}` +
+            '（加 --prune 可摘，你改过的会保留）',
+        );
+        warned += 1;
+      } else {
+        // 冲突 = 这里有你自己的东西，本工具不碰。说清楚就行，不是故障。
+        warn(`${label} 有本工具没动的地方`);
+        plain(dim(`    ${r.detail}`));
+      }
+    }
+
+    // 声明的工具里有没有承接不了这类内容的（codex 的 mcp 就是）
+    for (const u of view.unsupported) {
+      warn(`${TOOLS[u.tool].label} 没有 ${u.dir} 的合并目标——这 ${u.count} 条装了不会生效`);
+      warned += 1;
+    }
+
+    // 没实证的那条路不能报得跟 Claude 那条一样肯定
+    for (const u of view.unverified) {
+      plain(dim(`    ⚠️ ${TOOLS[u.tool].label} 的 ${u.rel} 未经实证（本机没装），可能不生效`));
+    }
+
+    // ---- 写进去了，生效了吗 ----
+    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') {
+        warn(`Claude Code 还没批准这些 MCP server`);
+        plain(dim(`    ${ap.detail}`));
+        plain(dim('    在会话里用 /mcp 批准。这是逐人逐项目的——批准记录在你本机的'));
+        plain(dim('    ~/.claude.json 里，不随仓库共享，队友要各自批一次。'));
+        warned += 1;
+      } else if (ap.state === 'never') {
+        skip(`Claude Code 的批准状态未知：${ap.detail}`);
+      } else {
+        skip(`Claude Code 的批准状态无法判断：${ap.detail}`);
+      }
+    }
+
+    // ---- 进得了版本库吗 ----
+    //
+    // 和链接相反：合并产物**必须**提交（它们是团队共享的配置，正是 MCP
+    // 「配一次全组可用」的前提）。但用户自己的 .gitignore 里常有 .mcp.json。
+    // `.trae/mcp.json` 更绕——它在 .trae/ 里面，整个忽略 .trae/ 的话
+    // `!.trae/mcp.json` 是**没用**的（git 不允许重新包含被排除目录下的文件）。
+    // 所以这里只查、只报，**不往托管段里塞白名单**：一条时灵时不灵、失灵时
+    // 还没有任何信号的规则，比没有更糟。
+    /** @type {string[]} */
+    const ignored = [];
+    let checked = 0;
+    for (const tool of config.tools) {
+      for (const dir of mergeKindsOf(tool)) {
+        const rel = mergeTarget(tool, dir).rel;
+        if (!fs.existsSync(path.resolve(cwd, rel))) continue;
+
+        const g = gitStatusOf(cwd, rel);
+        if (g.state === 'skipped') continue;
+        checked += 1;
+        if (g.state === 'ignored') {
+          if (g.rule) ignored.push(`${rel}（命中 ${g.rule}）`);
+          else ignored.push(rel);
+        }
+      }
+    }
+    if (ignored.length > 0) {
+      warn(`${ignored.length} 个合并产物被 .gitignore 忽略了——它们应该提交进版本库`);
+      for (const i of ignored) plain(dim(`    · ${i}`));
+      plain(dim('    .gitignore 对已跟踪的文件无效；要让队友拿到这份配置就得放行。'));
+      warned += 1;
+    } else if (checked > 0) {
+      ok('合并产物都在版本库的范围内');
+    }
+
+    // ---- hook 在 Windows 上靠 sh ----
+    if ((view.present.hooks?.length ?? 0) > 0 && process.platform === 'win32') {
+      if (hasSh()) ok('sh 可用（Windows 上 hook 靠它执行）');
+      else {
+        warn('PATH 里找不到 sh —— hook 会静默不跑');
+        plain(dim('    装 Git for Windows，并确保 Git Bash 的 bin 目录在 PATH 里。'));
+        warned += 1;
+      }
+    }
+  }
+
+  // ---- 9. 各工具是否存在 ----
   title('工具');
   for (const name of TOOL_NAMES) {
-    const dir = path.resolve(cwd, /** @type {Record<string,string>} */ (PACKAGE_TOOL_HINTS)[name]);
+    const dir = path.resolve(cwd, toolDir(name));
     const onDisk = fs.existsSync(dir);
     const declared = config.tools.includes(name);
     const kinds = Object.keys(TOOLS[name].links).join('/');
     if (onDisk && declared) ok(`${TOOLS[name].label.padEnd(12)} 目录存在，已声明　${dim(kinds)}`);
-    else if (onDisk && !declared) warn(`${TOOLS[name].label.padEnd(12)} 目录存在，但未在 tools 里声明`);
+    else if (onDisk && !declared) warn(`${TOOLS[name].label.padEnd(12)} 目录存在，但未在 links 里声明`);
     else if (!onDisk && declared) {
-      const how = config.inferred ? '默认使用' : '已声明';
-      warn(`${TOOLS[name].label.padEnd(12)} ${how}，但项目里没有 ${'.' + name} 目录`);
-    }
-    else skip(`${TOOLS[name].label.padEnd(12)} 未使用`);
+      // 声明了但目录不在是正常的（link 会新建），所以只是提示不是问题
+      warn(`${TOOLS[name].label.padEnd(12)} 已声明，但项目里没有 ${toolDir(name)} 目录`);
+    } else skip(`${TOOLS[name].label.padEnd(12)} 未使用`);
   }
 
   // ---- 小结 ----