Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

26.6 KB
Raw Blame
/**
 * subagent 定义发现 —— 扫出用户手写的 subagent 文件,读出它们各自声明的 model。
 *
 * 一次扫描服务两个用途:
 *   1. 「Subagent 模型」设置的**真默认语义**(见 subagent-model-default.ts):判断本会话里
 *      有没有 agent 自己声明了 model,据此决定要不要设 `CLAUDE_CODE_SUBAGENT_MODEL`;
 *   2. **诊断**:agent 指定的模型拼错 / 供应商未连接 / 用了会漂移的裸别名时,给用户可读的原因。
 *
 * ## 为什么要自己扫
 *
 * Claude Code 的 model 解析顺序是
 * `CLAUDE_CODE_SUBAGENT_MODEL` → 每次调用的 model 参数 → frontmatter → 主会话模型。
 * env 变量位于**最高**优先级,平台**没有**「最低优先级默认值」这个位置,也没有「只对某几个
 * agent 生效」的粒度(env 是进程级的)。所以想让「设置 = 默认值、frontmatter 能盖过它」,
 * 唯一可行的做法是:host 自己先看清有没有人声明 model,有人声明就整个会话不设那个 env。
 * 这就要求 host 先知道每个 agent 声明了什么 —— 即本模块。
 *
 * (曾试过「不设 env + 经 `options.agents` 给未声明者补默认值」,实测走不通:同名时文件定义
 * 胜出。判别实验与结论记在 subagent-model-default.ts 的模块头,改这块前先读。)
 *
 * ## 扫描范围与它的边界
 *
 * 覆盖用户**手写**的两个作用域(平台优先级 3 / 4):
 *   - 项目:从 workingDir 向上逐级找 `.claude/agents`(平台也是向上走查,近者优先);
 *   - 用户:`<CLAUDE_CONFIG_DIR>/agents`,缺省 `~/.claude/agents`。
 * 两者都递归子目录 —— 平台允许用 `agents/review/` 这类子目录归类,身份只认 frontmatter
 * 的 `name`,与路径无关。
 *
 * **必须传子进程 env**:`CLAUDE_CONFIG_DIR` 在 host boot 期就被 stripSensitiveAnthropicEnv
 * 从 `process.env` 清掉了,host 要重定向配置目录只能由 auth adapter 往**子进程 env** 注入
 * (旧版 dev 多实例曾这样隔离到 `<userData>/claude-home`)。所以调用方要把最终交给 SDK 的
 * 那份 env 传进来,否则这里扫的是 `~/.claude/agents`,而 cc 读的是重定向后的 `agents`
 * ——判定与实际不符,声明照旧被覆盖。目录解析要同时看递入 env 与 host env,原因见
 * {@link userAgentsDir}(SDK spawn 是两份 env 合并)。
 *
 * **刻意不覆盖** managed settings 与插件的 `agents/` 目录:那是组织与插件分发的内容,
 * 不是用户手写的,host 不该替它们改模型;这两类继续走 env 覆盖(与本改动前一致,不是回退)。
 *
 * ## 启动期 IO 预算
 *
 * 本扫描位于会话启动的关键路径上(env 要在 sdkQuery 之前定好),而 `.claude/agents` 的内容
 * 完全由仓库决定:生成出来的大目录、几 MB 的 md、软链环、挂死的网络盘都可能把新会话拖成
 * 「假死」。因此深度、目录数、单目录条目数、文件数与总耗时都有上限,任一超限即抛
 * {@link SubagentScanBudgetError},由调用方降级成「照旧设 env」——宁可默认值语义退回改动前,
 * 也不让会话卡在启动上。
 *
 * 两条原则贯穿这些上限:
 *   - **超限一律抛,绝不静默截断**。半份结果会被上层当成「扫完了,没人声明 model」,于是又把
 *     覆盖用的 env 设回去 —— 正是本 PR 要修的 bug 换个触发条件。
 *   - **单个文件不设大小上限**,改成只读开头的有界前缀。按大小跳过看着安全,实则会漏掉长
 *     prompt 的合法定义,同样退化成上一条那个 bug。
 */

import type { Dirent, Stats } from 'node:fs';
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';

import { parseFrontmatter } from '../shared/customization-scanner.js';

/** 扫描到的单个 subagent 定义。 */
export interface DiscoveredSubagent {
  /** frontmatter 的 `name` —— 身份来源,与 cc 一致(缺失的定义 cc 不加载,这里也不收)。 */
  name: string;
  /** 定义文件绝对路径。 */
  filePath: string;
  /** 作用域:项目(优先级更高)或用户。 */
  scope: 'project' | 'user';
  /**
   * 该 agent 自己声明的 model。
   * `undefined` = 没写 / 写了 `inherit`(平台语义等同没写)—— 这类才需要补默认值。
   */
  declaredModel?: string;
  /**
   * frontmatter 原始数据(诊断用;host 不改写它,也不重发定义)。
   *
   * **刻意不带正文**:host 只需要知道「声明了什么 model」,正文(subagent 的 system prompt)
   * 一个字都用不上。不留这个字段,读取就能只取文件开头的有界前缀 —— 一份 5 MB 的 md 也只花
   * 一次定长读,不必在「整份读进内存」和「按大小跳过」之间选(跳过会漏掉声明 → 又误判
   * 「没人声明 model」)。
   */
  frontmatter: Record<string, unknown>;
}

/**
 * 扫描触及预算上限 —— 调用方应据此降级(见模块头「启动期 IO 预算」),不要当作
 * 「没有人声明 model」。
 */
export class SubagentScanBudgetError extends Error {
  constructor(readonly budget: string) {
    super(`subagent definition scan exceeded budget: ${budget}`);
    this.name = 'SubagentScanBudgetError';
  }
}

/** 目录递归深度上限:防软链环 / 异常深目录。 */
const MAX_DEPTH = 8;
/** 遍历到的 .md 文件数上限。真实用法是个位数到几十;上百已属异常。 */
const MAX_FILES = 200;
/** 访问的目录数上限(深度管不住广度)。 */
const MAX_DIRS = 200;
/**
 * 单个目录的条目数上限。
 *
 * 为什么单独设这一道:`readdir` 会把整个目录**一次性物化成数组**,后面再排序 —— 生成出来的
 * 十万条目录能在计数预算生效前就吃掉内存,而同步排序还会**堵住事件循环**,连外层定时器都没
 * 机会触发。所以改用 `opendir` 流式读并在这里就地封顶:一超即抛,不物化、不排序。
 */
const MAX_DIR_ENTRIES = 500;
/**
 * 单个定义文件读取的前缀字节数。
 *
 * 我们只要 frontmatter,而它一定在文件开头。定长前缀让「几 MB 的 md」既不占内存也不会被
 * 整条跳过 —— 跳过等于漏掉一份可能声明了 model 的定义。
 */
const MAX_FRONTMATTER_BYTES = 32 * 1024;
/** 整趟扫描的墙钟上限 —— 兜住慢盘 / 网络盘 / 病态目录。 */
const MAX_ELAPSED_MS = 1_500;

/** 预算账本。任一维度超限立即抛,不做「静默截断」——截断会让判定悄悄失真。 */
class ScanBudget {
  private files = 0;
  private dirs = 0;
  constructor(
    private readonly startedAt: number,
    private readonly deadlineMs: number,
    readonly maxDepth: number,
    readonly maxFiles: number,
    readonly maxDirEntries: number,
  ) {}

  countDir(): void {
    if (++this.dirs > MAX_DIRS) throw new SubagentScanBudgetError(`dirs>${MAX_DIRS}`);
    this.checkTime();
  }

  countFile(): void {
    if (++this.files > this.maxFiles) {
      throw new SubagentScanBudgetError(`files>${this.maxFiles}`);
    }
    this.checkTime();
  }

  checkTime(): void {
    if (Date.now() - this.startedAt > this.deadlineMs) {
      throw new SubagentScanBudgetError(`elapsed>${this.deadlineMs}ms`);
    }
  }
}

/**
 * 给整趟扫描套一个**真**超时。
 *
 * 为什么计数式的 checkTime() 不够:它只在两次 await 之间执行。落在网络盘 / 已失联的挂载点上
 * 的 `readdir` / `stat` / `readFile` 可以一直挂着不返回,此时代码根本走不到下一次检查 ——
 * 会话启动就跟着无限期卡住。所以必须让**等待方**自己放弃,而不是指望被等的操作回来。
 *
 * 放弃后底层 fs 操作仍会挂在 libuv 线程池里(没有取消语义),但我们不再等它:定时器一到就以
 * {@link SubagentScanBudgetError} 拒绝,调用方走既有的降级路径。定时器 unref,不拖住进程退出。
 */
async function withDeadline<T>(work: Promise<T>, deadlineMs: number): Promise<T> {
  let timer: NodeJS.Timeout | undefined;
  try {
    return await Promise.race([
      work,
      new Promise<never>((_resolve, reject) => {
        timer = setTimeout(
          () => reject(new SubagentScanBudgetError(`deadline>${deadlineMs}ms`)),
          deadlineMs,
        );
        timer.unref?.();
      }),
    ]);
  } finally {
    if (timer) clearTimeout(timer);
  }
}

/**
 * cc 子进程实际会读的 `<config dir>/agents`。
 *
 * 必须按 **SDK spawn 的合并语义**来解:SDK 起 CLI 时用的是
 * `{ ...process.env, ...userEnv }`,所以子进程看到的 `CLAUDE_CONFIG_DIR` 是
 * 「host 递入的那份」优先、其次才是「host 自己 process.env 上的」。
 *
 * 两者都要看,漏一个就会扫错目录:
 *   - 只看 `process.env`:dev 多实例的重定向只存在于递入的 env 里(desktop boot 已把该键
 *     从 process.env 剥掉),会漏掉;
 *   - 只看递入的 env:没调过 stripSensitiveAnthropicEnv 的 host(CLI host、单测)其
 *     `process.env.CLAUDE_CONFIG_DIR` 照样会被 SDK 合并进子进程 —— 我们的字典副本里没有它
 *     (cleanProcessEnv 剥了),但 cc 读的就是它。
 *
 * 都没有则回落 `~/.claude` —— 与 cc 在子进程里自己的解析一致(local spawn 同一个用户)。
 */
function userAgentsDir(childEnv: NodeJS.ProcessEnv, hostEnv: NodeJS.ProcessEnv): string {
  const configDir = childEnv.CLAUDE_CONFIG_DIR?.trim() || hostEnv.CLAUDE_CONFIG_DIR?.trim();
  const base = configDir && configDir.length > 0 ? configDir : path.join(os.homedir(), '.claude');
  return path.join(base, 'agents');
}

async function isDirectory(p: string): Promise<boolean> {
  try {
    return (await fs.stat(p)).isDirectory();
  } catch {
    return false;
  }
}

/**
 * 流式读一个目录的条目,条目数超扫描预算立即抛。
 *
 * 打不开的目录(权限 / 竞态删除)当作空目录,只跳过它自己;但**条目过多要抛** —— 那种情况下
 * 结果不可信,静默截断会让上层以为「扫完了,没人声明 model」。
 * 每读一条都过一次时间预算:opendir 的异步迭代天然会让出事件循环,外层定时器也就有机会触发。
 */
async function readDirEntriesBounded(dir: string, budget: ScanBudget): Promise<Dirent[]> {
  let handle: Awaited<ReturnType<typeof fs.opendir>>;
  try {
    handle = await fs.opendir(dir);
  } catch {
    return [];
  }
  const entries: Dirent[] = [];
  // for-await 在 break / throw 时会自动关闭目录句柄。
  for await (const ent of handle) {
    if (entries.length >= budget.maxDirEntries) {
      throw new SubagentScanBudgetError(`dirEntries>${budget.maxDirEntries}`);
    }
    entries.push(ent);
    budget.checkTime();
  }
  return entries;
}

type EntryKind = 'directory' | 'file' | 'other';

/**
 * 把目录条目按跟随软链后的目标分类。
 *
 * `statEntry` 可注入是为了让 Windows 在未开启 Developer Mode、无法创建文件软链时,
 * 仍能真实覆盖 Dirent 的软链分支;目录 junction 则继续走端到端测试。
 */
export async function classifySubagentEntry(
  ent: Pick<Dirent, 'isDirectory' | 'isFile' | 'isSymbolicLink'>,
  fullPath: string,
  statEntry: (entryPath: string) => Promise<Pick<Stats, 'isDirectory' | 'isFile'>> = (entryPath) =>
    fs.stat(entryPath),
): Promise<EntryKind | undefined> {
  let isDir = ent.isDirectory();
  let isFile = ent.isFile();
  if (ent.isSymbolicLink()) {
    // follow: stat 走目标。悬空 / 无权限的链直接跳过这一条。
    try {
      const st = await statEntry(fullPath);
      isDir = st.isDirectory();
      isFile = st.isFile();
    } catch {
      return undefined;
    }
  }
  if (isDir) return 'directory';
  if (isFile) return 'file';
  return 'other';
}

/**
 * 递归收集目录下的 .md 文件。单个坏目录只跳过它自己,不影响其余扫描;超预算则整趟抛出。
 *
 * **软链必须跟随**:`readdir(withFileTypes)` 给软链的 Dirent 既不是 file 也不是 dir,
 * 只看 isFile()/isDirectory() 会把它整条漏掉。本仓在建 worktree 时是**刻意**保留
 * `.claude/agents` 里的软链的(WorktreeManager.copyDirIfExists 用 `dereference: false`,
 * 因为有人就是这么复用定义的)—— 漏掉一个软链定义,就等于误判「没人声明 model」,
 * 于是又把覆盖用的 env 设回去,正是本次要修的 bug。所以对软链补一次 follow-stat。
 *
 * 跟随软链就要防环:用 realpath 记账,同一真实目录只进一次(深度上限管不住 A→B→A)。
 *
 * **用 opendir 而不是 readdir**:readdir 会把整个目录一次性物化成数组,一个生成出来的十万
 * 条目录在任何计数预算生效**之前**就吃掉内存,随后的同步排序还会堵住事件循环 —— 那期间连外层
 * 定时器都触发不了。opendir 流式读能在超过 {@link MAX_DIR_ENTRIES} 时立刻抛出,不物化、不排序。
 */
async function collectMarkdownFiles(
  dir: string,
  budget: ScanBudget,
  visitedDirs: Set<string>,
  depth = 0,
): Promise<string[]> {
  // 深度上限也是预算的一部分,超了同样**抛**而不是返回空:深层目录里若有声明了 model 的定义,
  // 静默截断会让上层判成「没人声明」→ 又把覆盖用的 env 设回去(本 PR 要修的 bug)。
  if (depth > budget.maxDepth) {
    throw new SubagentScanBudgetError(`depth>${budget.maxDepth}`);
  }
  // 软链环兜底:按真实路径去重。realpath 失败(悬空链)就跳过这个目录。
  let real: string;
  try {
    real = await fs.realpath(dir);
  } catch {
    return [];
  }
  if (visitedDirs.has(real)) return [];
  visitedDirs.add(real);
  budget.countDir();
  const entries = await readDirEntriesBounded(dir, budget);
  const files: string[] = [];
  // 名字排序保证同一目录下的遍历顺序稳定(平台对同目录同名的取舍是文件系统序,
  // 我们至少让自己的结果可复现)。条目数已封顶,这次排序的规模是有界的。
  const sorted = entries.sort((a, b) => a.name.localeCompare(b.name));
  for (const ent of sorted) {
    // 隐藏条目与 .bak.N 备份跳过 —— 与本仓既有的 customization-scanner(同名过滤,
    // agents/shared/customization-scanner.ts)保持**同一份有效定义集**。
    // 这条的风险方向和其它几条相反:多认一份 cc 根本不加载的 `.reviewer.md` 备份,会让我们
    // 以为「有人声明了 model」从而删掉 env —— 用户配的默认值对真正的 agent 反而失效了。
    if (ent.name.startsWith('.') || /\.bak\.\d+$/.test(ent.name)) continue;
    const full = path.join(dir, ent.name);
    const kind = await classifySubagentEntry(ent, full);
    if (kind === undefined) continue;
    if (kind === 'directory') {
      files.push(...(await collectMarkdownFiles(full, budget, visitedDirs, depth + 1)));
      // 扩展名大小写不敏感:`reviewer.MD` 在大小写保留的文件系统上照样是一份定义,
      // 本仓既有的 customization-scanner 也是 `toLowerCase().endsWith('.md')`。
      // 大小写敏感地漏掉一份声明了 model 的定义 = 又把覆盖用的 env 设回去。
    } else if (kind === 'file' && ent.name.toLowerCase().endsWith('.md')) {
      budget.countFile();
      files.push(full);
    }
  }
  return files;
}

/**
 * 从 workingDir 向上逐级收集 `.claude/agents` 目录(近者在前)。
 * 平台对嵌套项目目录的规则是「离 workingDir 最近的同名定义生效」,顺序与此一致。
 *
 * **先 realpath 再向上走**:workingDir 本身可能是个软链(指向仓库的某个子目录)。子进程的
 * cwd 会被解析成物理路径,cc 于是能看到 `<真实仓库>/.claude/agents`;而按软链的字面父目录
 * 往上走查会走到完全另一支,漏掉那份定义 → 又误判「没人声明 model」。realpath 失败(不存在
 * 等)时回落字面路径,不因此放弃整个项目作用域。
 */
async function projectAgentsDirs(workingDir: string): Promise<string[]> {
  if (!workingDir || !path.isAbsolute(workingDir)) return [];
  const dirs: string[] = [];
  let cur = workingDir;
  try {
    cur = await fs.realpath(workingDir);
  } catch {
    /* 保持字面路径 */
  }
  for (;;) {
    const candidate = path.join(cur, '.claude', 'agents');
    if (await isDirectory(candidate)) dirs.push(candidate);
    const parent = path.dirname(cur);
    if (parent === cur) break;
    cur = parent;
  }
  return dirs;
}

/**
 * model id 的长度上限。真实 id 最长也就几十个字符;frontmatter 却能塞进整个前缀(32 KiB)。
 * 不封顶的话,这个串会一路流到诊断打分(suggestModelIds 逐词干比对整份可用清单)与日志里 ——
 * 前者是**同步**计算且发生在扫描 deadline 之外,拦不住,只能从源头限长。
 */
const MAX_DECLARED_MODEL_CHARS = 256;

function normalizeDeclaredModel(raw: unknown): string | undefined {
  if (typeof raw !== 'string') return undefined;
  // cc 对 model **会** trim,且把空白与 `inherit` 都当作「没指定」,继续沿解析链向下。
  const trimmed = raw.trim();
  if (trimmed.length === 0) return undefined;
  if (trimmed.toLowerCase() === 'inherit') return undefined;
  return trimmed.length > MAX_DECLARED_MODEL_CHARS
    ? trimmed.slice(0, MAX_DECLARED_MODEL_CHARS)
    : trimmed;
}

/**
 * 读文件开头的有界前缀 —— frontmatter 一定在这里,正文我们不需要(见 DiscoveredSubagent)。
 *
 * 这样「几 MB 的 md」既不占内存,也**不会被整条跳过**:按大小跳过看着安全,实则会漏掉一份
 * 可能声明了 model 的合法定义(长 system prompt 的 agent 完全正常),于是又误判「没人声明」
 * 并把覆盖用的 env 设回去 —— 正是本 PR 要修的 bug。
 *
 * 返回 null = 读不到(不存在 / 无权限),这一条不算。
 */
async function readFilePrefix(filePath: string): Promise<string | null> {
  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
  try {
    handle = await fs.open(filePath, 'r');
    const buf = Buffer.allocUnsafe(MAX_FRONTMATTER_BYTES);
    const { bytesRead } = await handle.read(buf, 0, MAX_FRONTMATTER_BYTES, 0);
    return buf.subarray(0, bytesRead).toString('utf8');
  } catch {
    return null;
  } finally {
    await handle?.close().catch(() => {});
  }
}

/** frontmatter 起始分隔符(允许 BOM 与前导空行,与 gray-matter 的宽容度对齐)。 */
const FRONTMATTER_OPEN = /^\uFEFF?\s*---\r?\n/;

async function readSubagentFile(
  filePath: string,
  scope: DiscoveredSubagent['scope'],
): Promise<DiscoveredSubagent | null> {
  const raw = await readFilePrefix(filePath);
  if (raw === null) return null;
  // 前缀里没读到 frontmatter 的**收尾**分隔符,但开头确实有起始分隔符 → 这份 frontmatter
  // 大到超出前缀,解析结果不可信。此时**抛**而不是跳过:跳过会让上层以为「没人声明 model」。
  if (FRONTMATTER_OPEN.test(raw) && !/\n---\s*(\r?\n|$)/.test(raw.replace(FRONTMATTER_OPEN, '\n'))) {
    throw new SubagentScanBudgetError(`frontmatter>${MAX_FRONTMATTER_BYTES}B`);
  }
  const parsed = parseFrontmatter(raw);
  if (parsed.parseError || !parsed.frontmatter) return null;
  const fm = parsed.frontmatter;
  // gray-matter 对「没有 frontmatter 的普通 md」返回空对象 —— 那不是 subagent 定义
  // (放在 agents 目录里的说明文件、笔记等)。空 frontmatter 一律跳过,否则会被当成
  // 一个匿名 agent 重发出去。
  if (Object.keys(fm).length === 0) return null;
  // 严格对齐 cc 的加载条件:`name` 与 `description` 都必须是非空字符串,缺任一 cc 就把整份
  // 定义**丢弃**(反编译自 bundled cli.js 的 agent 文件加载函数:
  //   `if (!name || typeof name !== 'string') return null;`
  //   `if (!description || typeof description !== 'string') { warn(...); return null; }`
  // 身份取 `frontmatter.name`;函数里的 basename(file,'.md') 只用于 memory 前缀与 filename
  // 字段,**不是** name 的回退)。
  //
  // 这里两个方向都会出错,所以必须照抄平台规则而不是往任一边偏:
  //   - 漏认一份 cc 会加载的定义 → 误判「没人声明 model」→ 又把覆盖用的 env 设回去;
  //   - 多认一份 cc 不加载的定义(例如只写了 model 没写 name 的草稿)→ 误判「有人声明」→
  //     删掉 env → 用户配的默认值对**所有**真实 agent 和内置 agent 静默失效。
  //
  // ⚠️ 三个字段的谓词**不对称**,必须逐个照抄,不能一刀切:
  //   - `name` / `description`:`!value || typeof value !== 'string'` —— 只排除空串,
  //     **不 trim**。所以 `description: "  "` 在 cc 眼里是合法的、会被加载;我们若额外 trim
  //     就比 cc 更严 → 漏认一份 cc 真会加载的定义 → 又把覆盖用的 env 设回去。
  //   - `model`:cc 自己会 `trim()` 并把空白与 `inherit` 视作未指定(见 normalizeDeclaredModel)。
  const name = typeof fm.name === 'string' && fm.name.length > 0 ? fm.name : '';
  const hasDescription = typeof fm.description === 'string' && fm.description.length > 0;
  if (name.length === 0 || !hasDescription) return null;
  return {
    name,
    filePath,
    scope,
    declaredModel: normalizeDeclaredModel(fm.model),
    frontmatter: fm,
  };
}

export interface DiscoverSubagentsOptions {
  workingDir: string;
  /**
   * **递给 SDK 的那份子进程 env**(`options.env`),用于取 `CLAUDE_CONFIG_DIR`。
   *
   * 刻意设成**必填**:dev 多实例的配置目录重定向只存在于这份 env 里(host boot 期已把该键
   * 从 `process.env` 剥掉),缺了它就会静默扫错目录。让类型强制调用方交出这份 env,
   * 比留个默认值再靠注释提醒可靠。解析规则见 {@link userAgentsDir}。
   */
  env: NodeJS.ProcessEnv;
  /** host 自己的 env;缺省 `process.env`。SDK spawn 会把它合并进子进程,故一并参与解析。 */
  hostEnv?: NodeJS.ProcessEnv;
  /** 整趟扫描的墙钟上限;缺省 {@link MAX_ELAPSED_MS}。测试注入小值验证超时分支。 */
  deadlineMs?: number;
  /** 测试注入起始时刻(避免依赖真实时钟)。 */
  now?: () => number;
  /**
   * 递归深度上限,有效范围 1..{@link MAX_DEPTH};非法值或超过缺省上限时回退缺省值。
   * 测试可注入较小值,避免为触发预算创建大量目录。
   */
  maxDepth?: number;
  /**
   * .md 文件数上限,有效范围 1..{@link MAX_FILES};非法值或超过缺省上限时回退缺省值。
   * 测试可注入较小值,避免为触发预算创建大量文件。
   */
  maxFiles?: number;
  /**
   * 单目录条目数上限,有效范围 1..{@link MAX_DIR_ENTRIES};非法值或超过缺省上限时回退缺省值。
   * 测试可注入较小值,避免为触发预算创建大量目录条目。
   */
  maxDirEntries?: number;
}

function resolveBudgetLimit(value: number | undefined, fallback: number): number {
  return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= fallback
    ? value
    : fallback;
}

/**
 * 扫出当前会话可见的用户手写 subagent 定义,按平台优先级去重(项目近者 > 项目远者 > 用户)。
 *
 * 单个文件/目录的 IO 异常都被吞成「这条不算」——本扫描只服务默认值与诊断,不能让它拖垮
 * 会话启动。但**预算超限会抛** {@link SubagentScanBudgetError}:那种情况下结果已不可信,
 * 必须由调用方显式降级,不能伪装成「扫完了,没人声明」。
 *
 * 超时有两道:计数式的 `budget.checkTime()`(便宜,覆盖「很多个都不慢」的累积)+ 外层
 * {@link withDeadline} 的真定时器(覆盖「某一个 fs 调用永远不返回」)。缺了后者,挂死的网络盘
 * 能让会话启动无限期卡住 —— 计数检查根本没机会执行。
 */
export async function discoverSubagentDefinitions(
  opts: DiscoverSubagentsOptions,
): Promise<DiscoveredSubagent[]> {
  const deadlineMs = opts.deadlineMs ?? MAX_ELAPSED_MS;
  return await withDeadline(scanSubagentDefinitions(opts, deadlineMs), deadlineMs);
}

async function scanSubagentDefinitions(
  opts: DiscoverSubagentsOptions,
  deadlineMs: number,
): Promise<DiscoveredSubagent[]> {
  const budget = new ScanBudget(
    (opts.now ?? Date.now)(),
    deadlineMs,
    resolveBudgetLimit(opts.maxDepth, MAX_DEPTH),
    resolveBudgetLimit(opts.maxFiles, MAX_FILES),
    resolveBudgetLimit(opts.maxDirEntries, MAX_DIR_ENTRIES),
  );
  const visitedDirs = new Set<string>();
  const scoped: Array<{ dir: string; scope: DiscoveredSubagent['scope'] }> = [
    // 顺序 = 跨作用域优先级从高到低(项目近者 > 项目远者 > 用户)。
    ...(await projectAgentsDirs(opts.workingDir)).map((dir) => ({ dir, scope: 'project' as const })),
    { dir: userAgentsDir(opts.env, opts.hostEnv ?? process.env), scope: 'user' as const },
  ];

  // 同名去重。分两种情况,因为「平台会选哪一个」的可知性完全不同:
  //
  // 1. **来自不同扫描根**(项目近者 / 项目远者 / 用户):优先级是平台文档确定的,近者、项目优先。
  //    `scoped` 已按该优先级排好,所以先到者胜、后来者一律不动。
  //    注意不能用 `scope` 字段判断这件事 —— 它只有 'project' / 'user' 两个值,嵌套项目的
  //    「近」与「远」两个根都是 'project',拿它当同源判据会把确定的优先级也一起打翻。
  // 2. **来自同一个扫描根**(比如 `agents/x.md` 与 `agents/review/x.md`):cc 在这个根里按文件
  //    系统枚举顺序任选其一 —— 那个顺序我们复现不了(ext4 与 APFS 不同,也不等于我们的名字
  //    排序)。与其赌顺序,不如让判定**与顺序无关**:声明了 model 的那个胜出。这样无论文件系统
  //    怎么枚举,结论都一样。
  //
  // 第 2 种的残留代价诚实说明:若 cc 实际加载的是没写 model 的那份,我们会多算一次「有人声明」
  // → 默认值不生效。选这个方向是因为本 PR 的不变量是「用户显式写下的 model 不被静默覆盖」,
  // 而同一个根里重名本身是配置错误(cc 自己也只是任选其一)。
  const byName = new Map<string, { def: DiscoveredSubagent; rootIndex: number }>();
  for (const [rootIndex, { dir, scope }] of scoped.entries()) {
    if (!(await isDirectory(dir))) continue;
    for (const filePath of await collectMarkdownFiles(dir, budget, visitedDirs)) {
      budget.checkTime();
      const found = await readSubagentFile(filePath, scope);
      if (!found) continue;
      const existing = byName.get(found.name);
      if (!existing) {
        byName.set(found.name, { def: found, rootIndex });
        continue;
      }
      // 不同扫描根 → 已存在的那个优先级更高,不动(情况 1)。
      if (existing.rootIndex !== rootIndex) continue;
      // 同一个扫描根 → 声明了 model 的胜出(情况 2)。
      if (existing.def.declaredModel === undefined && found.declaredModel !== undefined) {
        byName.set(found.name, { def: found, rootIndex });
      }
    }
  }
  return [...byName.values()].map((e) => e.def);
}