agent-syncer 0.1.0 → 0.1.1

package/lib/install.js

@@ -0,0 +1,239 @@
+// @ts-check
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ITEM_KINDS, SUPPORT_DIR, itemPath, parseItem } from './manifest.js';
+import { CONTENT_ROOT } from './target.js';
+
+/** 条目在项目里的落点：.agents/<仓库目录名>/<id>[ext] */
+export function projectItemPath(projectRoot, kind, id) {
+  const cfg = ITEM_KINDS[kind];
+  return path.resolve(
+    projectRoot,
+    CONTENT_ROOT,
+    cfg.dir,
+    cfg.ext === null ? id : `${id}${cfg.ext}`,
+  );
+}
+
+/**
+ * 目录树的稳定指纹：所有文件的「相对路径 + 内容哈希」，按路径排序。
+ * 单文件则直接返回内容哈希。
+ *
+ * 用它而不是 mtime 来判断「变了没有」——内容仓库重新克隆后 mtime 全变，
+ * 但内容其实一模一样，那时不该报「更新」。
+ *
+ * ⚠️ **按原始字节算，所以换行符差异（CRLF / LF）会被算成「变了」。**
+ * 检出成 CRLF 的那份和内容仓库里的 LF 对不上，sync 会多报一次「更新」并把文件
+ * 重写回 LF，之后自愈（实测：第二遍就报「已是最新」）。
+ *
+ * 会不会污染 git，取决于**项目仓库自己的配置**，与本工具无关：
+ * - `core.autocrlf=true` → `git status` 会短暂显示 M，但 `git add` 不产生内容差异
+ * - `core.autocrlf=false` → 行尾改动作会被当成真改动提交进去
+ *
+ * 根治办法是项目里放一份 `.gitattributes`（`* text=auto`），让行尾行为不再取决于
+ * 每个人各自的 core.autocrlf。内容仓库那边已经有这个要求，项目仓库这边同样需要。
+ *
+ * @param {string} p
+ */
+function fingerprint(p) {
+  const st = fs.statSync(p);
+  if (!st.isDirectory()) {
+    return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  }
+
+  /** @type {string[]} */
+  const parts = [];
+  const walk = (dir, base) => {
+    const entries = fs
+      .readdirSync(dir, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(abs, rel);
+      else parts.push(`${rel}:${crypto.createHash('sha256').update(fs.readFileSync(abs)).digest('hex')}`);
+    }
+  };
+  walk(p, '');
+  return parts.join('\n');
+}
+
+/** new = 项目里还没有；same = 内容一致；update = 有差异会被覆盖 */
+function statusOf(from, to) {
+  if (!fs.existsSync(to)) return 'new';
+  try {
+    return fingerprint(from) === fingerprint(to) ? 'same' : 'update';
+  } catch {
+    // 目标不是常规文件/目录（比如是链接），一律当作会被覆盖，让上层去拦
+    return 'update';
+  }
+}
+
+/** 判断路径是不是链接——是的话绝不能覆盖 */
+function isLink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 递归列出目录下的所有文件（相对路径，正斜杠）。
+ * @param {string} dir @returns {string[]}
+ */
+function walkFiles(dir) {
+  /** @type {string[]} */
+  const out = [];
+  const walk = (d, base) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(d, e.name), rel);
+      else out.push(rel);
+    }
+  };
+  walk(dir, '');
+  return out.sort();
+}
+
+/**
+ * 本次选择里有没有 hook 或 mcp —— **只有这两类会引用 `scripts/` 里的文件**。
+ * @param {string[]} items
+ */
+function wantsSupport(items) {
+  return items.some((spec) => {
+    const { kind } = parseItem(spec);
+    return kind === 'hook' || kind === 'mcp';
+  });
+}
+
+/**
+ * `scripts/` 是支撑目录：hook 和 mcp 都按路径引用脚本，单独挑拣容易漏，
+ * 所以整目录同步。它不参与 bundle 的条目挑选。
+ *
+ * 「整目录」指的是**在 scripts/ 内部不再细分**，而不是「无条件同步」——
+ * 要不要同步它，由 `planInstall` 按本次选择决定，见那里的注释。
+ */
+function collectSupport(repoRoot, projectRoot) {
+  const from = path.resolve(repoRoot, SUPPORT_DIR);
+  if (!fs.existsSync(from)) return [];
+
+  return walkFiles(from).map((rel) => {
+    const src = path.join(from, rel);
+    const dst = path.resolve(projectRoot, CONTENT_ROOT, SUPPORT_DIR, rel);
+    return {
+      spec: `script:${rel}`,
+      kind: 'script',
+      id: rel,
+      from: src,
+      to: dst,
+      status: statusOf(src, dst),
+    };
+  });
+}
+
+/**
+ * 算出「要装什么、每个的当前状态」，但不写盘。
+ * @param {string} repoRoot @param {string} projectRoot @param {string[]} items
+ */
+export function planInstall(repoRoot, projectRoot, items) {
+  /** @type {{spec: string, kind: string, id: string, from: string, to: string, status: string}[]} */
+  const entries = [];
+
+  for (const spec of items) {
+    const { kind, id } = parseItem(spec);
+    const from = itemPath(repoRoot, kind, id);
+    const to = projectItemPath(projectRoot, kind, id);
+    entries.push({ spec, kind, id, from, to, status: statusOf(from, to) });
+  }
+
+  // `scripts/` 只在**本轮真的选了 hook 或 mcp** 时才同步。
+  //
+  // 「整目录同步」的理由是「hook / mcp 按路径引用脚本，逐个挑拣容易漏，漏了就是
+  // 运行时静默失败」——那个理由只在有 hook / mcp 的时候成立。一个都没选的时候，
+  // `.agents/` 里没有任何东西会去引用它们，同步过去只是把一堆用不上的文件塞进
+  // 每个项目，而**它们是要提交进版本库的**。
+  //
+  // 注意判据是 `items`（本次选择），不是滤掉 protect 之后的计划：锁住的 hook
+  // 仍然躺在 `.agents/hooks/` 里，它引用的脚本还得留着。
+  if (wantsSupport(items)) entries.push(...collectSupport(repoRoot, projectRoot));
+
+  // 目标是链接的一律拦下——那多半是 link 命令建的反向链接，
+  // 覆盖它等于把内容仓库的东西写进一个链接指向的地方
+  for (const e of entries) {
+    if (isLink(e.to)) e.status = 'blocked';
+  }
+
+  return entries;
+}
+
+/**
+ * 落盘。
+ *
+ * 覆盖策略：先整体删掉目标再拷。不能用 `cpSync` 的 force——它只覆盖同名文件，
+ * 内容仓库里**删掉的文件**会残留在项目里，越积越多。
+ *
+ * @param {ReturnType<typeof planInstall>} entries
+ * @param {{dryRun?: boolean}} [opts]
+ */
+export function applyInstall(entries, opts = {}) {
+  const { dryRun = false } = opts;
+  let written = 0;
+  const skipped = entries.filter((e) => e.status === 'same').length;
+  /** @type {{spec: string, message: string}[]} */
+  const problems = [];
+
+  if (dryRun) {
+    return { written: 0, skipped, problems };
+  }
+
+  for (const e of entries) {
+    if (e.status === 'same' || e.status === 'blocked') continue;
+    try {
+      fs.mkdirSync(path.dirname(e.to), { recursive: true });
+      fs.rmSync(e.to, { recursive: true, force: true });
+      fs.cpSync(e.from, e.to, { recursive: true });
+      written += 1;
+    } catch (err) {
+      problems.push({ spec: e.spec, message: /** @type {Error} */ (err).message });
+    }
+  }
+
+  return { written, skipped, problems };
+}
+
+/**
+ * 找出项目 `.agents/` 下、但不在本次安装清单里的条目。
+ *
+ * 只报告、不删除——无法区分「上次装完残留的」和「用户自己加的」，
+ * 代用户做删除决定风险太大。
+ *
+ * 不检查 `scripts/`：它随内容一起整体同步，不属于任何 bundle 条目，
+ * 列进来只会每次误报。
+ *
+ * @param {string} projectRoot @param {string[]} items
+ */
+export function findOrphans(projectRoot, items) {
+  const wanted = new Set(items.map((s) => parseItem(s)).map(({ kind, id }) => `${kind}:${id}`));
+  /** @type {string[]} */
+  const orphans = [];
+
+  for (const [kind, cfg] of Object.entries(ITEM_KINDS)) {
+    const dir = path.resolve(projectRoot, CONTENT_ROOT, cfg.dir);
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      const id = cfg.ext === null ? e.name : e.name.endsWith(cfg.ext) ? e.name.slice(0, -cfg.ext.length) : null;
+      if (id === null) continue;
+      if (!wanted.has(`${kind}:${id}`)) orphans.push(`${kind}:${id}`);
+    }
+  }
+
+  return orphans.sort();
+}

package/lib/manifest.js

@@ -0,0 +1,420 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 当前支持的内容仓库 schema 版本 */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * 条目的六种类型。
+ *
+ * 注意这里的 `kind` 是**单数**（`skill:code-style`），而内容仓库里的目录名是复数。
+ * 两套词汇故意分开：仓库目录结构可以变，条目 id 是稳定的对外契约。
+ *
+ * @type {Record<string, {dir: string, ext: string|null, label: string}>}
+ */
+export const ITEM_KINDS = {
+  skill: { dir: 'skills', ext: null, label: '技能' },
+  rule: { dir: 'rules', ext: '.md', label: '规则' },
+  command: { dir: 'commands', ext: '.md', label: '命令' },
+  agent: { dir: 'agents', ext: '.md', label: '子代理' },
+  hook: { dir: 'hooks', ext: '.json', label: 'Hook' },
+  mcp: { dir: 'mcp', ext: '.json', label: 'MCP' },
+};
+
+export const ITEM_KIND_NAMES = Object.keys(ITEM_KINDS);
+
+/** hooks / mcp 靠路径引用脚本，所以 scripts/ 作为支撑目录整体同步，不参与条目挑选 */
+export const SUPPORT_DIR = 'scripts';
+
+/**
+ * 条目在内容仓库里的绝对路径。
+ * skill 是目录，其余是「<id><ext>」单文件。
+ * @param {string} repoRoot @param {string} kind @param {string} id
+ */
+export function itemPath(repoRoot, kind, id) {
+  const cfg = ITEM_KINDS[kind];
+  if (!cfg) throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  return path.resolve(repoRoot, cfg.dir, cfg.ext === null ? id : `${id}${cfg.ext}`);
+}
+
+/**
+ * 解析 `kind:id` 形式的条目引用。
+ * @param {string} entry
+ * @returns {{kind: string, id: string}}
+ */
+export function parseItem(entry) {
+  if (typeof entry !== 'string') {
+    throw new Error(`条目必须是字符串，收到 ${JSON.stringify(entry)}`);
+  }
+  const colon = entry.indexOf(':');
+  if (colon === -1) {
+    throw new Error(`条目 ${JSON.stringify(entry)} 格式不对，应为 "类型:名字"，例如 "skill:code-style"`);
+  }
+  const kind = entry.slice(0, colon).trim();
+  const id = entry.slice(colon + 1).trim();
+  if (!Object.hasOwn(ITEM_KINDS, kind)) {
+    throw new Error(`未知条目类型 "${kind}"（可用：${ITEM_KIND_NAMES.join('、')}）`);
+  }
+  if (id === '') throw new Error(`条目 ${JSON.stringify(entry)} 缺少名字`);
+  return { kind, id };
+}
+
+/**
+ * 加载并校验内容仓库的根清单。
+ * @param {string} repoRoot
+ */
+export function loadRepo(repoRoot) {
+  const p = path.resolve(repoRoot, 'dept.json');
+  if (!fs.existsSync(p)) {
+    throw new Error(`${repoRoot} 不是内容仓库：找不到 dept.json`);
+  }
+
+  /** @type {any} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`dept.json 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
+  }
+
+  if (raw?.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `内容仓库的 schemaVersion 是 ${JSON.stringify(raw?.schemaVersion)}，` +
+        `本工具只支持 ${SCHEMA_VERSION}。请升级 agent-syncer。`,
+    );
+  }
+  return { name: raw.name, version: raw.version, description: raw.description, root: path.resolve(repoRoot) };
+}
+
+/**
+ * 扫描内容仓库，列出每类条目下有哪些 id。
+ * @param {string} repoRoot
+ * @returns {Record<string, string[]>}
+ */
+export function listItems(repoRoot) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+
+  for (const [kind, cfg] of Object.entries(ITEM_KINDS)) {
+    const dir = path.resolve(repoRoot, cfg.dir);
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      out[kind] = [];
+      continue;
+    }
+
+    out[kind] = entries
+      .filter((e) => (cfg.ext === null ? e.isDirectory() : e.isFile() && e.name.endsWith(cfg.ext)))
+      .map((e) => (cfg.ext === null ? e.name : e.name.slice(0, -cfg.ext.length)))
+      .sort();
+  }
+
+  return out;
+}
+
+/**
+ * 列出所有可选的 bundle。
+ * @param {string} repoRoot
+ */
+export function listBundles(repoRoot) {
+  const dir = path.resolve(repoRoot, 'bundles');
+  /** @type {{name: string, title?: string, description?: string}[]} */
+  const out = [];
+
+  /** @type {string[]} */
+  let files;
+  try {
+    files = fs.readdirSync(dir);
+  } catch {
+    return out;
+  }
+
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const name = f.slice(0, -'.json'.length);
+    /** @type {any} */
+    let raw;
+    try {
+      raw = JSON.parse(fs.readFileSync(path.resolve(dir, f), 'utf8'));
+    } catch (e) {
+      out.push({ name, description: `（文件损坏：${/** @type {Error} */ (e).message}）` });
+      continue;
+    }
+    out.push({ name, title: raw?.title, description: raw?.description });
+  }
+
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 规整顶层的 `bundle` 字段：单个字符串和字符串数组都收，统一成数组。
+ *
+ * 单个字符串也接受，理由和项目根一样——没道理为了加第二个模板先加方括号。
+ * 语义与项目根 `agents.json` 的 `bundle` 字段**完全一致**：被引用的每个模板
+ * 各自完整解析，然后取并集。
+ *
+ * @param {string} file 出错时用来指明是哪个文件，光说"bundle 格式不对"没法照着修
+ * @param {any} value
+ * @returns {string[]}
+ */
+function normalizeBundleField(file, value) {
+  if (value === undefined || value === null) return [];
+  if (typeof value !== 'string' && !Array.isArray(value)) {
+    throw new Error(`${file} 的 bundle 必须是字符串或字符串数组，收到 ${JSON.stringify(value)}`);
+  }
+
+  const arr = Array.isArray(value) ? value : [value];
+  /** @type {string[]} */
+  const out = [];
+  for (const [i, n] of arr.entries()) {
+    if (typeof n !== 'string') {
+      throw new Error(`${file} 的 bundle[${i}] 必须是字符串，收到 ${JSON.stringify(n)}`);
+    }
+    // 去空白、丢空串、去重、保序——**和项目根那份（config.js 的 normalizeList）
+    // 规则必须一模一样**。文档里说两层「字段名和含义一字不差」，那 `"common "`
+    // 和 `["common"]` 在两边就得是同一件事；不一致的后果很隐蔽：同一份配置写进
+    // 模板文件能用、写进 agents.json 就报「找不到模板 "common "」。
+    const s = n.trim();
+    if (s !== '' && !out.includes(s)) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * 模板名只能是**一个文件名**，不能是路径。
+ *
+ * `readBundle` 拿名字去拼 `bundles/<名字>.json`。不拦的话，内容仓库里一句
+ * `"bundle": ["../../../../某处的配置"]` 就能读到仓库外的任意 JSON——而且
+ * 读出来的片段还会进报错信息，等于把那个文件的内容写进日志。
+ *
+ * 影响不算大（内容仓库通常是团队自有的，能读到的多半也只是 JSON），但
+ * 「内容仓库可以指定读仓库外的文件」这一条本身就不该成立，拦下来只要几行。
+ *
+ * @param {string} name
+ */
+function assertBundleName(name) {
+  if (name === '' || name === '.' || name === '..' || /[\\/]/.test(name) || name.includes('\0')) {
+    throw new Error(
+      `模板名必须是一个简单的名字，不能带路径：收到 ${JSON.stringify(name)}（例如 "common"）`,
+    );
+  }
+}
+
+/** 读一个 bundle 文件 */
+function readBundle(repoRoot, name) {
+  assertBundleName(name);
+  const p = path.resolve(repoRoot, 'bundles', `${name}.json`);
+  if (!fs.existsSync(p)) {
+    const available = listBundles(repoRoot).map((b) => b.name);
+    throw new Error(
+      `找不到模板 "${name}"。可用：${available.length > 0 ? available.join('、') : '（仓库里没有任何 bundle）'}`,
+    );
+  }
+  /** @type {any} */
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    throw new Error(`bundles/${name}.json 不是合法的 JSON：${/** @type {Error} */ (e).message}`);
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`bundles/${name}.json 的顶层必须是一个对象`);
+  }
+  if (raw.include !== undefined && !Array.isArray(raw.include)) {
+    throw new Error(`bundles/${name}.json 的 include 必须是数组`);
+  }
+  if (raw.exclude !== undefined && !Array.isArray(raw.exclude)) {
+    throw new Error(`bundles/${name}.json 的 exclude 必须是数组`);
+  }
+  // 顺手把 bundle 字段规整成数组，后面按同一套流水线走，不必再关心它是怎么写进来的
+  raw.bundle = normalizeBundleField(`bundles/${name}.json`, raw.bundle);
+  return raw;
+}
+
+/**
+ * 把一条 include / exclude 展开成条目列表。
+ *
+ * 支持两种写法：
+ * - `类型:*`      —— 该类型下的全部条目
+ * - `类型:名字`    —— 单个条目
+ *
+ * **模板之间的组合不走这里**，走顶层的 `bundle` 字段（`"bundle": ["common"]`）。
+ * 老写法 `@common` 已经移除，见到就直接抛错——静默忽略会让「引用没生效」
+ * 变成一个没人查得出来的哑谜，而错误信息里的新写法能让人当场改对。
+ *
+ * `lenient` 只放宽一件事：**条目在仓库里不存在时返回空、改成告警，而不是抛错**。
+ * 这专给 exclude 用——"排除一个当前不存在的东西"是合法的空操作，
+ * 而项目级的 exclude 是叠在模板之上的最后一层，模板内容一变动就把所有人的
+ * 配置搞崩，代价太大。类型写错、语法写错、`@` 老写法，这些一律照旧抛错，绝不放过。
+ *
+ * @param {string} repoRoot @param {string} entry
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts]
+ * @returns {string[]}
+ */
+function expandEntry(repoRoot, entry, opts = {}) {
+  const { lenient = false, warnings = [] } = opts;
+
+  if (typeof entry === 'string' && entry.startsWith('@')) {
+    throw new Error(
+      `${JSON.stringify(entry)} 这种写法已经移除。模板之间的组合改用顶层字段：\n` +
+        '  "bundle": ["common"]\n' +
+        '（bundles/*.json 和 agents.json 里用的是同一个字段，include / exclude 不再接受 "@名字"）',
+    );
+  }
+
+  const { kind, id } = parseItem(entry);
+
+  if (id === '*') {
+    return listItems(repoRoot)[kind].map((x) => `${kind}:${x}`);
+  }
+
+  const p = itemPath(repoRoot, kind, id);
+  if (!fs.existsSync(p)) {
+    const available = listItems(repoRoot)[kind];
+    const detail =
+      `条目 ${JSON.stringify(entry)} 在内容仓库里不存在（找的是 ${path.relative(repoRoot, p)}）。` +
+      `该类型下现有：${available.length > 0 ? available.join('、') : '（空）'}`;
+    if (lenient) {
+      warnings.push(`${detail}（作为 exclude 跳过，不影响其它条目）`);
+      return [];
+    }
+    throw new Error(detail);
+  }
+  return [`${kind}:${id}`];
+}
+
+/**
+ * 展开一组条目引用（保序、去重）。
+ * @param {string} repoRoot @param {string[]} entries
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts]
+ * @returns {string[]}
+ */
+function expandEntries(repoRoot, entries, opts = {}) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of entries) {
+    for (const item of expandEntry(repoRoot, entry, opts)) {
+      if (!out.includes(item)) out.push(item);
+    }
+  }
+  return out;
+}
+
+/**
+ * 「模板并集 → 叠加 include → 最后过 exclude」这套三步流水线的共用实现。
+ *
+ * 模板内部（`resolveBundle`）和项目级（`resolveSelection`）走的是**同一套**：
+ * 两处各写一份的话，迟早会长出两套规则，而使用者根本分不清「模板里的 bundle」
+ * 和「agents.json 里的 bundle」能有什么区别——它们本来就该是同一个东西。
+ *
+ * 第 1 步刻意是"各自解析再取并集"，而不是把多个模板的 include 倒进一个池子
+ * 再统一过 exclude：模板应当是自洽的，A 模板的 exclude 不该悄悄砍掉 B 模板的内容，
+ * 否则 `bundle: ["a", "b"]` 的结果会依赖组合顺序和谁的 exclude 更宽，没法推理。
+ *
+ * @param {string} repoRoot
+ * @param {{bundle?: string[], include?: string[], exclude?: string[]}} spec
+ * @param {string[]} stack 循环引用的引用链，由 resolveBundle 维护
+ * @param {{lenient?: boolean, warnings?: string[]}} [opts] 只作用于本层的 exclude
+ * @returns {{items: string[], dropped: string[]}}
+ */
+function resolvePipeline(repoRoot, spec, stack, opts = {}) {
+  const { bundle = [], include = [], exclude = [] } = spec;
+  const { lenient = false, warnings = [] } = opts;
+
+  /** @type {string[]} */
+  const items = [];
+  const add = (list) => {
+    for (const item of list) if (!items.includes(item)) items.push(item);
+  };
+
+  // 1. 每个被引用的模板各自完整解析（递归地含它自己的 bundle / include / exclude），取并集
+  for (const name of bundle) add(resolveBundle(repoRoot, name, stack));
+
+  // 2. 本层的 include 叠在并集之上
+  add(expandEntries(repoRoot, include));
+
+  // 3. 本层的 exclude 最后过一遍 —— 它能砍掉上面任何一步加进来的东西
+  const excluded = new Set(expandEntries(repoRoot, exclude, { lenient, warnings }));
+  const dropped = items.filter((item) => excluded.has(item));
+
+  return { items: items.filter((item) => !excluded.has(item)), dropped };
+}
+
+/**
+ * 解析一个 bundle，得到最终要安装的条目清单（保序、去重）。
+ *
+ * 流水线见 resolvePipeline，和项目级完全一致：
+ *   1. 本文件 `bundle` 引用的每个模板各自完整解析 → 取并集
+ *   2. 叠加本文件的 `include`
+ *   3. 最后过本文件的 `exclude`
+ *
+ * 也就是说**模板自己就是个小号的 agents.json**——`bundle` / `include` / `exclude`
+ * 三个字段的名字和含义都和项目根一模一样，不用记两套。
+ *
+ * @param {string} repoRoot @param {string} name @param {string[]} [stack]
+ * @returns {string[]}
+ */
+export function resolveBundle(repoRoot, name, stack = []) {
+  if (stack.includes(name)) {
+    throw new Error(`bundle 循环引用：${[...stack, name].join(' → ')}`);
+  }
+
+  const bundle = readBundle(repoRoot, name);
+  stack.push(name);
+
+  try {
+    return resolvePipeline(repoRoot, bundle, stack).items;
+  } finally {
+    stack.pop();
+  }
+}
+
+/**
+ * 解析一次完整的安装选择，得到最终条目清单。
+ *
+ * 流水线（每一步都在上一步的结果上做增删，实现在 resolvePipeline）：
+ *
+ *   1. 每个 bundle 各自解析（递归地含它自己的 bundle → include → exclude），然后取**并集**
+ *   2. 加上项目级 include
+ *   3. 减掉项目级 exclude —— 最后过一遍，它能砍掉上面任何一步加进来的东西
+ *
+ * 与模板唯一的差别是 exclude 更宽容：项目级的 exclude 指着一条已经不在的条目，
+ * 只告警不报错（理由见 expandEntry）。
+ *
+ * @param {string} repoRoot
+ * @param {{bundles?: string[], include?: string[], exclude?: string[]}} selection
+ * @returns {{items: string[], dropped: string[], warnings: string[]}}
+ */
+export function resolveSelection(repoRoot, selection = {}) {
+  const { bundles = [], include = [], exclude = [] } = selection;
+  /** @type {string[]} */
+  const warnings = [];
+
+  const { items, dropped } = resolvePipeline(
+    repoRoot,
+    { bundle: bundles, include, exclude },
+    [],
+    { lenient: true, warnings },
+  );
+
+  return { items, dropped, warnings };
+}
+
+/**
+ * 按类型把条目分组，方便安装时逐类处理。
+ * @param {string[]} items
+ * @returns {Record<string, string[]>}
+ */
+export function groupByKind(items) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const item of items) {
+    const { kind, id } = parseItem(item);
+    (out[kind] ??= []).push(id);
+  }
+  return out;
+}