agent-syncer 0.1.0 → 0.1.2

package/lib/source.js

@@ -0,0 +1,312 @@
+// @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';
+
+/**
+ * 判断 `content` 给的是 git 地址还是本地路径。
+ *
+ * 先排除本地路径的写法（Windows 盘符、绝对路径、相对路径），再看协议前缀。
+ * 顺序很重要：`C:/x/foo.git` 以 .git 结尾，但它显然是本地路径。
+ *
+ * @param {string} value
+ */
+export function isGitUrl(value) {
+  const s = value.trim();
+  if (s === '') return false;
+
+  // 本地路径的三种写法：盘符、POSIX 绝对路径、相对路径
+  if (/^[a-zA-Z]:[\\/]/.test(s)) return false;
+  if (s.startsWith('/') || s.startsWith('\\')) return false;
+  if (s.startsWith('.')) return false;
+
+  return (
+    /^(https?|git|ssh|file):\/\//i.test(s) ||
+    /^[^\s/@]+@[^\s/]+:/.test(s) || // scp 风格：git@host:path
+    s.endsWith('.git')
+  );
+}
+
+/** git 是否可用 */
+export function hasGit() {
+  const res = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  return res.status === 0;
+}
+
+/**
+ * `git clone` 的超时（毫秒）。
+ *
+ * `GIT_TERMINAL_PROMPT=0` 堵的是「停下来等人输密码」，堵不住**网络黑洞**——
+ * 连得上、但不回话（代理 / VPN 不通、对面的 git server 挂着、被墙的 host）。
+ * 那种情况下 clone 会一直等下去，在 CI 或 postinstall 里就是永久挂起。
+ *
+ * 比 `ls-remote` 那个 15 秒宽松得多：那一步是「问了才用」的下拉列表，早点放弃没损失；
+ * 这一步**失败就是整条 sync 失败**，而内容仓库可能不小、浅克隆也不一定快。
+ * 60 秒远大于实测（内容仓库不到 1 秒），等于「只有真的连不上才会触发」。
+ *
+ * 超时之后**不重试、也不退回上次的内容**：后者要把缓存引回来，而缓存正是
+ * `fetchRepo` 刻意不要的东西。直接报错，让用户知道是网络而不是他的 URL 写错了。
+ */
+const CLONE_TIMEOUT_MS = 60_000;
+
+/** 这个 spawnSync 结果是不是「超时被杀」。超时时 `status` 是 null、`error.code` 是 ETIMEDOUT */
+function isTimeout(res) {
+  return /** @type {any} */ (res.error)?.code === 'ETIMEDOUT';
+}
+
+/**
+ * 第一次 clone 失败之后，要不要退回**完整克隆**再试一次。
+ *
+ * 退回的理由只有一个：`--branch` 不认裸 SHA，那一次失败得快且无辜，换完整克隆是正解。
+ * 所以**超时不在此列**——超时说明网络已经不行了，而完整克隆（没有 `--depth 1`）
+ * 比刚才那次更慢，再发起一次等于把一次黑洞拖成两次。
+ *
+ * 判据单独拿出来，是因为它值得被钉死，而端到端**造不出**这个场景：要造「连得上、
+ * 不回话」，得有一个只接受连接、永不回话的本地 server，可本机实测下来 git 对
+ * loopback 的连接根本不完成（对**正在监听**的 server 也一样），代理 / 防火墙各家
+ * 又不一样——那种测试会变成环境的函数。
+ *
+ * @param {any} res @param {string|null|undefined} ref
+ */
+export function shouldRetryFullClone(res, ref) {
+  if (!ref) return false; // 没有 ref 就没有「--branch 不认 SHA」这回事
+  if (res.error) return false; // 超时、被信号杀掉、git 起不来——都不是 ref 的锅
+  return res.status !== 0;
+}
+
+/**
+ * 按 ref 取一份克隆；必要时退回完整克隆再检出。
+ *
+ * 把执行方式 (`run`) 从参数传进来，**只为能测**：这段的分支（`--branch` 不认裸 SHA、
+ * 超时不重试）只有「克隆真的失败了」才走得到，而真造一次失败要么靠网络、要么靠一个
+ * 挂住的假 git，两头都不稳。第一版就是因为它内联在 `fetchRepo` 里测不着，于是写了条
+ * 「耗时小于 1 秒」的假测试——**还原掉整个防重试逻辑，它照样是绿的**。
+ *
+ * 导出也是为了测。`fetchRepo` 用的是同一个函数，不是复制一份。
+ *
+ * @param {{
+ *   run: (args: string[], timeoutMs?: number) => any,
+ *   url: string, dest: string, ref?: string|null, timeoutMs: number,
+ * }} p
+ * @returns {any} 最后一次 `run` 的结果
+ */
+export function cloneWithFallback({ run, url, dest, ref, timeoutMs }) {
+  /** @type {string[]} */
+  const args = ['clone', '--quiet', '--depth', '1'];
+  if (ref) args.push('--branch', ref);
+  args.push('--', url, dest);
+
+  const first = run(args, timeoutMs);
+  if (!shouldRetryFullClone(first, ref)) return first;
+
+  // `--branch` 只认分支名和标签名，不认裸 SHA。这时退回完整克隆再检出。
+  // 失败时可能留下半个目标目录，重试前必须先清掉，否则克隆会因「目录非空」再失败一次。
+  fs.rmSync(dest, { recursive: true, force: true });
+  const full = run(['clone', '--quiet', '--', url, dest], timeoutMs);
+  return full.status === 0 ? run(['-C', dest, 'checkout', '--quiet', '--detach', ref]) : full;
+}
+
+/**
+ * 把一个 git 仓库的某个 ref 取到临时目录。
+ *
+ * 取完即用、用完即删——不做本地缓存。多花的是一次 clone 的时间（内容仓库通常很小），
+ * 换来的是没有「缓存过期」这类说不清的状态。
+ *
+ * **`GIT_TERMINAL_PROMPT=0` 是必须的**：否则遇到需要凭据的仓库时 git 会停下来等输入，
+ * 在 CI 或 postinstall 里就是永久挂起——和交互式提示一样危险。
+ *
+ * @param {{url: string, ref?: string|null, timeoutMs?: number}} opts
+ *   `timeoutMs` 只为测试而开：正常调用别传，用默认值（见 `CLONE_TIMEOUT_MS`）。
+ * @returns {{root: string, cleanup: () => void}}
+ */
+export function fetchRepo({ url, ref, timeoutMs = CLONE_TIMEOUT_MS }) {
+  if (!hasGit()) {
+    throw new Error('找不到 git 命令。请先安装 git，或把 content 指向一个本地已克隆的目录。');
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-syncer-src-'));
+  const dest = path.join(tmpRoot, 'repo');
+  const cleanup = () => fs.rmSync(tmpRoot, { recursive: true, force: true });
+
+  const baseEnv = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0', // 绝不等待输入
+    GIT_ASKPASS: 'echo',
+  };
+
+  /**
+   * @param {string[]} args @param {number} [timeoutMs]
+   *   `timeoutMs` 只在 clone 那条路上给。`checkout` 是纯本地操作，套上超时没有意义。
+   */
+  const run = (args, timeoutMs) =>
+    spawnSync('git', args, {
+      encoding: 'utf8',
+      env: baseEnv,
+      // 不用 inherit：clone 的进度输出对使用者没有价值，失败时我们再完整打印 stderr
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(timeoutMs ? { timeout: timeoutMs } : {}),
+    });
+
+  const res = cloneWithFallback({ run, url, dest, ref, timeoutMs });
+
+  if (res.status !== 0) {
+    cleanup();
+    // 超时说成「拉取失败」，用户第一反应是去查自己的 URL 写错了没有。
+    // 这是两回事：地址是对的，是网络没回话。
+    if (isTimeout(res)) {
+      throw new Error(
+        `拉取超时：${url}${ref ? ` @ ${ref}` : ''}\n` +
+          `  git 连上了，但 ${Math.round(timeoutMs / 1000)} 秒没有回话——` +
+          '多半是代理 / VPN 不通，或者对面的 git server 挂了。\n' +
+          '  也可以把 content 指向一个本地已克隆的目录：不联网、更快，改完内容立刻能试。',
+      );
+    }
+    const detail = (res.stderr || res.stdout || '').trim();
+    throw new Error(
+      `拉取失败：${url}${ref ? ` @ ${ref}` : ''}\n` +
+        (detail ? `  git 说：${detail}` : '  （git 没有输出更多信息）'),
+    );
+  }
+
+  return { root: dest, cleanup };
+}
+
+/**
+ * 列表类 git 调用的超时（毫秒）。
+ *
+ * 取 refs 是**问了才用**的一步：内容仓库连不上时，用户宁可看到「跳过这一步」
+ * 也不愿意对着一个不动的光标等下去。凭据那条路已经由 GIT_TERMINAL_PROMPT=0 堵死，
+ * 这里堵的是「连得上但不回话」——网络黑洞、被墙的 host、挂掉的 git server。
+ */
+const REF_LIST_TIMEOUT_MS = 15_000;
+
+/**
+ * 解析 `git` 列出来的 ref 行，分成分支和标签。
+ *
+ * 两种来源共用：`ls-remote` 给的是 `<sha>\t<ref>`，`for-each-ref` 给的是裸的
+ * `<ref>`。所以只认「最后一个字段」，前缀对不上的一律丢掉。
+ *
+ * 标签要去掉 `^{}` 后缀：注解标签在 `ls-remote` 里会出现两行（标签本身和它
+ * 指向的提交），不处理的话列表里会多出一个 `v1^{}`。
+ *
+ * @param {string} text
+ * @returns {{branches: string[], tags: string[]}}
+ */
+function parseRefs(text) {
+  /** @type {string[]} */
+  const branches = [];
+  /** @type {string[]} */
+  const tags = [];
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const parts = trimmed.split(/\s+/);
+    const ref = parts[parts.length - 1];
+    if (ref.startsWith('refs/heads/')) {
+      branches.push(ref.slice('refs/heads/'.length));
+    } else if (ref.startsWith('refs/tags/')) {
+      const name = ref.slice('refs/tags/'.length).replace(/\^\{\}$/, '');
+      if (name !== '' && !tags.includes(name)) tags.push(name);
+    }
+  }
+
+  return { branches, tags };
+}
+
+/**
+ * 本地路径配了 `ref` 时该说的那句话。
+ *
+ * `sync` 对本地路径读的是那个目录的**工作树**（这正是本地路径「改完内容立刻能试」
+ * 的来由），`ref` 一个字都用不上。写进配置却不生效，比不写更糟——用户会以为版本
+ * 被钉住了，实际拿到的还是他当前检出的那份，而且**全程没有任何提示**。
+ *
+ * 想钉版本就把 `content` 写成 git 地址（`file:///…` 也算，那会走 clone）。
+ *
+ * @param {string} source @param {string|null|undefined} ref
+ * @returns {string|null} 要说的话；没什么要说的返回 null
+ */
+export function localRefWarning(source, ref) {
+  if (!ref || isGitUrl(source)) return null;
+  return (
+    `"ref": "${ref}" 对本地路径不生效——读的是那个目录的工作树，不是某个提交。` +
+    '要钉版本请把 content 写成 git 地址'
+  );
+}
+
+/**
+ * 列出内容仓库有哪些分支和标签。
+ *
+ * 远端走 `git ls-remote`（**不克隆**，只问一句），本地路径走 `git for-each-ref`。
+ * 本地路径不是 git 仓库、git 没装、离线、要凭据、超时——**一律返回 null，
+ * 不抛错**。这一条是刻意的：调用方（init）问这个问题只是为了给用户一个下拉列表，
+ * 取不到就该安静跳过，绝不能让「列不出 refs」把整个流程拦下来。
+ *
+ * `GIT_TERMINAL_PROMPT=0` 与 fetchRepo 同一个理由：要密码的仓库必须当场失败，
+ * 不能停下来等人输入——CI 里那就是永久挂起。
+ *
+ * @param {{source: string, cwd?: string}} opts `source` 是本地路径或 git 地址
+ * @returns {{branches: string[], tags: string[]}|null}
+ */
+export function listRefs({ source, cwd = process.cwd() }) {
+  if (typeof source !== 'string' || source.trim() === '') return null;
+  if (!hasGit()) return null;
+
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_ASKPASS: 'echo',
+  };
+  const opts = {
+    encoding: /** @type {const} */ ('utf8'),
+    env,
+    stdio: /** @type {const} */ (['ignore', 'pipe', 'pipe']),
+    timeout: REF_LIST_TIMEOUT_MS,
+  };
+
+  const res = isGitUrl(source)
+    ? spawnSync('git', ['ls-remote', '--heads', '--tags', '--', source], opts)
+    : spawnSync('git', ['-C', path.resolve(cwd, source), 'for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/tags'], opts);
+
+  // timeout 时 spawnSync 会把 status 置成 null 并给出 error，一并当作「取不到」
+  if (res.error || res.status !== 0) return null;
+  return parseRefs(res.stdout ?? '');
+}
+
+/**
+ * 把分支和标签排成下拉列表里的顺序。纯函数，单独测。
+ *
+ * 顺序是有讲究的，不是随便排的：
+ *
+ *   1. `main`、`master` —— 用户十有八九要选的就是它，而且 main 在 master 前面
+ *      （新仓库用 main，老仓库才是 master）
+ *   2. **标签** —— 想钉版本的人一眼能看到；这类名字（v1.2.3）和分支名不会混
+ *   3. 其它分支 —— 最不常选，垫底
+ *
+ * 组内按 `numeric` 的自然序排（v1.2 < v1.10，而不是字典序的 v1.10 < v1.2），
+ * 并且**排一次序**：输入顺序取决于 git 的返回顺序，那东西不稳定，而
+ * 下拉列表每次长得不一样会让人怀疑自己是不是点错了。
+ *
+ * 同名去重，保留先出现的那个——分支 `v1` 和标签 `v1` 撞名时按上面的优先级走。
+ *
+ * @param {{branches?: string[], tags?: string[]}} refs
+ * @returns {string[]}
+ */
+export function orderRefs({ branches = [], tags = [] } = {}) {
+  // 自然序：不带 numeric 的话 v1.10 会排在 v1.2 前面，而标签里这种名字最常见
+  const cmp = (/** @type {string} */ a, /** @type {string} */ b) =>
+    a.localeCompare(b, 'en', { numeric: true });
+
+  const rank = (/** @type {string} */ name) => (name === 'main' ? 0 : name === 'master' ? 1 : 2);
+  const head = branches.filter((b) => rank(b) < 2).sort((a, b) => rank(a) - rank(b) || cmp(a, b));
+  const rest = branches.filter((b) => rank(b) === 2).sort(cmp);
+
+  /** @type {string[]} */
+  const out = [];
+  for (const name of [...head, ...[...tags].sort(cmp), ...rest]) {
+    if (name !== '' && !out.includes(name)) out.push(name);
+  }
+  return out;
+}

package/lib/stale.js

@@ -0,0 +1,130 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { STATUS, inspect, samePath } from './link.js';
+import { deepEqualJSON, readJsonFile } from './merge.js';
+import { MERGE_KINDS, TOOLS, TOOL_NAMES, contentDir, kindsOf, mergeTarget } from './target.js';
+
+/**
+ * 找出「已经建好、但当前配置里不再需要」的链接。
+ *
+ * 为什么必须有这一步：**link 只加不减**。把某个工具从 agents.json 的 links 里
+ * 去掉，已经建好的 junction 会原地留下，而 .gitignore 托管段却已经不忽略它们了。
+ * 于是 git 会穿透这些链接，把 .agents/ 的内容**再提交一份**——托管段存在的
+ * 唯一目的就此被绕过，全程没有任何提示。
+ *
+ * 只认**指向本项目 .agents/<kind>/ 的链接**：指向别处的链接不是本工具建的，
+ * 该不该删与本次配置无关，交给用户自己判断。
+ *
+ * 断链也算——链接指着 .agents/rules、而 .agents/rules 已经被删掉，
+ * 同样是该清理的残留。
+ *
+ * 纯只读，不修改任何东西。
+ *
+ * @param {string} projectRoot
+ * @param {string[]} tools 当前配置里要保留的工具
+ * @returns {{tool: string, kind: string, rel: string, target: string}[]}
+ */
+export function findStaleLinks(projectRoot, tools) {
+  /** @type {Set<string>} */
+  const wanted = new Set();
+  for (const tool of tools) {
+    for (const kind of kindsOf(tool)) wanted.add(TOOLS[tool].links[kind]);
+  }
+
+  /** @type {{tool: string, kind: string, rel: string, target: string}[]} */
+  const out = [];
+
+  for (const tool of TOOL_NAMES) {
+    for (const kind of kindsOf(tool)) {
+      const rel = TOOLS[tool].links[kind];
+      if (wanted.has(rel)) continue;
+
+      const target = path.resolve(projectRoot, rel);
+      const expected = contentDir(projectRoot, kind);
+      const st = inspect(target, expected);
+
+      const ours =
+        st.status === STATUS.HEALTHY ||
+        (st.status === STATUS.BROKEN && st.actual !== undefined && samePath(st.actual, expected));
+      if (!ours) continue;
+
+      out.push({ tool, kind, rel, target });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * 文件里还找得到这一条吗。找不到就别报，免得虚惊一场。
+ *
+ * mcp 按 id 查键；hook 没有 id 这个概念（条目按事件名排），只能在对应事件
+ * 里按深度相等找我们记下的那些条目。
+ *
+ * @param {Record<string, any>} cfg @param {string} kind @param {string} id @param {any} value
+ */
+function stillPresent(cfg, kind, id, value) {
+  if (kind === 'mcp') {
+    const servers = cfg.mcpServers;
+    return (
+      servers !== null && typeof servers === 'object' && !Array.isArray(servers) && Object.hasOwn(servers, id)
+    );
+  }
+
+  const hooks = cfg.hooks;
+  if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) return false;
+  for (const [event, entries] of Object.entries(value ?? {})) {
+    const list = Array.isArray(hooks[event]) ? hooks[event] : [];
+    for (const entry of entries ?? []) {
+      if (list.some((x) => deepEqualJSON(x, entry))) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 找出「本工具合进过、但当前配置里已经不要那个工具了」的合并产物。
+ *
+ * 和 `findStaleLinks` 完全同构，后果也一样：`.mcp.json` 是我们写的、已经提交
+ * 进版本库，而那个工具从 `links` 里去掉之后**没有任何东西会去清它**——文件里
+ * 留着一条谁也不认识的 server 定义，一句提示都没有。
+ *
+ * 判定只用记录里的 `merged`（「我们往哪个文件里写了什么」），不看文件里
+ * 「有没有像我们的东西」——后者是猜，而这个项目一贯的立场是拿不准就不动。
+ * 另外要求那条**现在还在文件里**，否则用户自己删过了还报「有残留」就是虚惊。
+ *
+ * 纯只读。
+ *
+ * @param {string} projectRoot
+ * @param {string[]} tools 当前配置里要保留的工具
+ * @param {Record<string, any>} merged 记录里的 merged
+ * @returns {{tool: string, kind: string, rel: string, ids: string[]}[]}
+ */
+export function findStaleMerges(projectRoot, tools, merged) {
+  const keep = new Set(tools);
+  /** @type {{tool: string, kind: string, rel: string, ids: string[]}[]} */
+  const out = [];
+
+  for (const tool of TOOL_NAMES) {
+    if (keep.has(tool)) continue;
+
+    for (const kind of MERGE_KINDS) {
+      const target = mergeTarget(tool, kind);
+      if (!target) continue;
+
+      const recorded = merged?.[tool]?.[kind] ?? {};
+      if (Object.keys(recorded).length === 0) continue;
+
+      const abs = path.resolve(projectRoot, target.rel);
+      if (!fs.existsSync(abs)) continue; // 文件都删了，没有残留可言
+      const read = readJsonFile(abs);
+      if (read.error) continue; // 读不了就别乱说
+
+      const ids = Object.keys(recorded).filter((id) => stillPresent(read.value, kind, id, recorded[id]));
+      if (ids.length > 0) out.push({ tool, kind, rel: target.rel, ids });
+    }
+  }
+
+  return out;
+}

package/lib/target.js

@@ -7,14 +7,69 @@ import path from 'node:path';
  */
 export const CONTENT_ROOT = '.agents';
 
-/** 内容类型。与 .agents/ 下的子目录名一一对应。 */
+/** 可链接的内容类型。与 .agents/ 下的子目录名一一对应。 */
 export const KINDS = ['skills', 'rules', 'commands', 'agents'];
 
+/**
+ * 工具的配置目录名（相对项目根）：claude → `.claude`。
+ *
+ * 「工具名就是目录名去掉点」这条约定原先在 link.js（拼表格）、doctor.js
+ * （PACKAGE_TOOL_HINTS）各写了一遍，现在收到这里单点维护——它和下面的 TOOLS
+ * 属于同一类知识：哪个工具把东西放哪。
+ *
+ * @param {string} tool
+ */
+export function toolDir(tool) {
+  return `.${tool}`;
+}
+
+/**
+ * 合并层认的内容类型。**用的是目录名（复数）**，不是条目类型名。
+ *
+ * 这个项目里有两套词汇，是故意的：
+ *
+ * - **选择层**用单数条目名（`skill` / `hook` / `mcp`）——那是 `include` 里要写的词，
+ *   见 `manifest.js` 的 `ITEM_KINDS`
+ * - **文件层**用复数目录名（`skills` / `hooks` / `mcp`）——那是 `.agents/` 下的路径
+ *
+ * 合并器在**文件层**干活（读 `.agents/mcp/*.json`、写工具自己的配置文件），
+ * 所以这里和记录里的 `merged` 一律用复数。**这个坑真踩过**：`list` 初版按目录名
+ * 过滤，而数据是单数类型名，那句「装了不生效」的警告一声不吭。
+ */
+export const MERGE_KINDS = ['mcp', 'hooks'];
+
+/**
+ * 项目根在内容里的写法。**不引入新的中性占位符**，改成一张别名表：
+ * 内容里写哪个都认，合并时统一翻译成目标工具自己的写法。
+ *
+ * 理由是这个项目的铁律——内容只描述「这是什么」，不描述「写到哪」。而
+ * `args` / `env` / `headers` 里引用项目内的脚本时又确实需要一个「项目根」的
+ * 写法，各工具叫法还不同。别名表让两边都成立：已经写下的
+ * `${CLAUDE_PROJECT_DIR}` 不会作废，写 `${workspaceFolder}` 的内容也能在
+ * Claude 上跑。
+ */
+export const PROJECT_DIR_ALIASES = ['CLAUDE_PROJECT_DIR', 'workspaceFolder'];
+
+/**
+ * .agents/ 下**需要提交到版本库**的全部目录。
+ *
+ * 前四类是可链接的（见 KINDS）；hooks / mcp / scripts 不链接到任何工具目录，
+ * 它们由合并器读取、或被 hook 命令直接引用，但同样是真实文件而非链接。
+ *
+ * .gitignore 的白名单漏掉这三个，会导致 hook 脚本和 MCP 配置根本提交不上去——
+ * 别人克隆下来只有一个空壳。
+ */
+export const CONTENT_DIRS = [...KINDS, 'hooks', 'mcp', 'scripts'];
+
 /**
  * 工具 → 目标路径映射表。
  *
  * 这是全项目唯一需要关心「哪个工具把内容放哪」的地方——
- * link.js / status.js / doctor.js 都不得出现 if-tool 分支。
+ * link.js / status.js / doctor.js / merge.js 都不得出现 if-tool 分支。
+ *
+ * `links` 管**目录链接**（skills / rules / commands / agents），
+ * `merges` 管**合并进工具自己的配置文件**（hooks / mcp）——两套机制，
+ * 两套键，别互相污染。`merges` **缺键即不支持**，见 `mergeTarget()`。
  *
  * - claude：skills / rules / commands / agents 四类都是目录
  *   （rules 目录的有效性已在本机 Claude Code 2.1.267 上实测确认，含嵌套子目录）
@@ -37,6 +92,14 @@ export const TOOLS = {
       commands: '.claude/commands',
       agents: '.claude/agents',
     },
+    // 本机 Claude Code 2.1.267 实测：`claude mcp add --scope project` 写的就是
+    // 项目根的 `.mcp.json`，顶层是 `mcpServers` 对象。插件根目录下的 `.mcp.json`
+    // 用的是**扁平形式**（没有包装），那是插件特有的，别混。
+    merges: {
+      mcp: { rel: '.mcp.json' },
+      hooks: { rel: '.claude/settings.json' },
+    },
+    projectDir: { var: 'CLAUDE_PROJECT_DIR' },
   },
   trae: {
     label: 'Trae',
@@ -45,12 +108,23 @@ export const TOOLS = {
       rules: '.trae/rules',
       commands: '.trae/commands',
     },
+    // ⚠️ 本机没装 Trae，下面这两项**都没有实证**，来自网络资料。写错了的后果是
+    // 这个文件不生效（不会破坏别的东西），但 doctor 不该把它报成「一切正常」——
+    // 见 mergeTarget() 的 verified。
+    merges: {
+      mcp: { rel: '.trae/mcp.json', verified: false },
+    },
+    projectDir: { var: 'workspaceFolder', verified: false },
   },
   codex: {
     label: 'Codex CLI',
     links: {
       skills: '.codex/skills',
     },
+    // **没有 merges，是有意的**：Codex 的 MCP 配置是 `~/.codex/config.toml` 那样的
+    // TOML，项目级 `.codex/config.toml` 又只在**受信任项目**里加载，而且
+    // `codex mcp add` 只能写用户级（上游 issue #23487 还开着）。
+    // 缺键 = 不支持，调用方据此明确报警，而不是静默跳过。
   },
 };
 
@@ -66,27 +140,100 @@ export function contentDir(projectRoot, kind) {
   return path.resolve(projectRoot, CONTENT_ROOT, kind);
 }
 
+/** 取工具配置。未知工具一律抛错——静默忽略一份写错的配置太危险 */
+function toolCfg(tool) {
+  const cfg = TOOLS[tool];
+  if (!cfg) throw new Error(`未知工具：${tool}。可用值：${TOOL_NAMES.join(', ')}`);
+  return cfg;
+}
+
 /**
  * 某工具支持的内容类型列表
  * @param {string} tool
  * @returns {string[]}
  */
 export function kindsOf(tool) {
-  const cfg = TOOLS[tool];
-  if (!cfg) throw new Error(`未知工具：${tool}。可用值：${TOOL_NAMES.join(', ')}`);
+  const cfg = toolCfg(tool);
   return KINDS.filter((k) => Object.hasOwn(cfg.links, k));
 }
 
+/**
+ * 某工具对某一类内容有没有合并目标。**没有就是「不支持」**。
+ *
+ * 「没有这个文件」有三种截然不同的意思，别混成一种：
+ *
+ * 1. 该工具这次没被 `links` 选中 → 什么都不该说
+ * 2. 选中了，但该工具根本没有这个机制（codex 的 mcp）→ **必须报警**
+ *    「内容装上了，但没有地方能合，不会生效」
+ * 3. 支持，但目标文件还不存在 → 正常，创建
+ *
+ * `verified: false` 表示「这条路没有实证」（目前只有 Trae）。调用方拿它去
+ * 决定该报 `ok` 还是「未实证」——**不能把没验证过的东西报成一切正常**。
+ *
+ * @param {string} tool @param {string} kind MERGE_KINDS 之一
+ * @returns {{rel: string, verified: boolean}|null}
+ */
+export function mergeTarget(tool, kind) {
+  const m = toolCfg(tool).merges?.[kind];
+  if (!m) return null;
+  return { rel: m.rel, verified: m.verified !== false };
+}
+
+/**
+ * 某工具支持合并的内容类型。
+ * @param {string} tool
+ * @returns {string[]}
+ */
+export function mergeKindsOf(tool) {
+  const cfg = toolCfg(tool);
+  return MERGE_KINDS.filter((k) => Object.hasOwn(cfg.merges ?? {}, k));
+}
+
+/**
+ * 项目根变量在该工具里该写成什么。**没有合并目标的工具返回 `null`**——
+ * 它压根没有需要写路径的地方（codex 的 MCP 是 TOML，本工具不做）。
+ *
+ * @param {string} tool
+ * @returns {{var: string, verified: boolean}|null}
+ */
+export function projectDirOf(tool) {
+  const p = toolCfg(tool).projectDir;
+  return p ? { var: p.var, verified: p.verified !== false } : null;
+}
+
 /** 条目的规范写法："claude/skills" */
 export function specOf(tool, kind) {
   return `${tool}/${kind}`;
 }
 
-/** 某工具支持的全部条目（用于 `tools` 形式的配置展开） */
+/** 某工具支持的全部条目 */
 export function allSpecs(tool) {
   return kindsOf(tool).map((k) => specOf(tool, k));
 }
 
+/**
+ * 把工具名列表展开成条目列表。
+ *
+ * 配置里只写工具名（`"links": ["claude", "trae"]`）——选用一个工具就是全量适配，
+ * 细化到单个目录没有实际意义。条目形式（"claude/skills"）仅作为内部表示存在，
+ * 由这个函数单点展开，别处不再各自拼。
+ *
+ * @param {string[]} tools
+ */
+export function specsOfTools(tools) {
+  return tools.flatMap(allSpecs);
+}
+
+/**
+ * 按 TOOL_NAMES 的固定顺序排序工具名，顺带去重。
+ * 固定顺序是为了让每次写出的配置 diff 稳定，不随勾选顺序变化。
+ * @param {string[]} tools
+ */
+export function sortTools(tools) {
+  const set = new Set(tools);
+  return TOOL_NAMES.filter((t) => set.has(t));
+}
+
 /**
  * 解析 "claude/skills" 形式的条目。非法即抛错——配置写错时要立刻说清楚，
  * 不能静默忽略，否则用户会以为已经生效。
@@ -134,11 +281,3 @@ export function plannedLinks(projectRoot, specs) {
   });
 }
 
-/**
- * 条目里出现过哪些工具，按 TOOL_NAMES 的固定顺序返回
- * @param {string[]} specs
- */
-export function toolsOfSpecs(specs) {
-  const seen = new Set(specs.map((s) => parseSpec(s).tool));
-  return TOOL_NAMES.filter((t) => seen.has(t));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-syncer",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "把 .agents/ 下的 AI 资产（skills / rules / commands）分发到 Claude Code、Trae、Codex 等工具的配置目录",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "README.md"
+    "README.md",
+    "CONTENT-REPO.md"
   ],
   "engines": {
     "node": ">=20.11.0"