让模型查分类树，而不是背它——然后发现整棵子树根本塞得下

/**
 * 让模型「查」分类树，而不是「背」它：三个只读 tool 的检索核心。
 *   listSystems()           → 一级系统及各自叶子数
 *   search(keywords[])      → 跨全树模糊检索，同名二三级跨系统折叠
 *   browse(system, level2?) → 展开子树全貌
 * 返回的每一条路径都直接取自树节点——模型编不出树上不存在的路径。
 */

export interface CategoryNode { title: string; children?: CategoryNode[] }
export interface LeafPath { titles: string[] }   // [一级, 二级, 三级]

export function flattenLeaves(tree: CategoryNode[], prefix: string[] = []): LeafPath[] {
  const out: LeafPath[] = [];
  for (const n of tree) {
    const titles = [...prefix, n.title];
    if (n.children?.length) out.push(...flattenLeaves(n.children, titles));
    else out.push({ titles });
  }
  return out;
}

/* ---------- 模糊匹配：2-gram + 完整包含，容忍错别字 ---------- */

export const normText = (s: string): string =>
  s.toLowerCase().replace(/[\s·/／()（）,，、.]+/g, '');

export function bigrams(s: string): Set<string> {
  const t = normText(s);
  const out = new Set<string>();
  for (let i = 0; i < t.length - 1; i++) out.add(t.slice(i, i + 2));
  return out;
}

/**
 * 标题 vs 检索词的相关度。
 * - 任一方完整包含另一方：强命中（full）
 * - 否则按 2-gram 重合比例给分 —— 错一个字仍能召回
 */
export function softMatch(title: string, kw: string): { s: number; full: boolean } {
  const t = normText(title);
  const k = normText(kw);
  if (!t || !k) return { s: 0, full: false };
  if (t.includes(k) || k.includes(t)) {
    return { s: 3 + Math.min(k.length, t.length) * 0.25, full: true };
  }
  const a = bigrams(t);
  const b = bigrams(k);
  if (!a.size || !b.size) return { s: 0, full: false };
  let common = 0;
  for (const g of b) if (a.has(g)) common++;
  const ratio = common / Math.min(a.size, b.size);
  if (ratio >= 0.5) return { s: 3 * ratio, full: false };

  // 第二档：字符覆盖率。短词里错一个字会毁掉大半 bigram
  // （「巡简任务」vs「巡检任务」只剩「任务」一个 bigram 相同），但字符仍有 3/4 重合。
  // 只对 ≥3 字的检索词启用，免得两个字的泛词到处命中。
  if (k.length >= 3) {
    const chars = new Set(t);
    let hit = 0;
    for (const c of k) if (chars.has(c)) hit++;
    const cov = hit / k.length;
    if (cov >= 0.75) return { s: 2 * cov, full: false };
  }
  return { s: 0, full: false };
}

/* ---------- search ---------- */

export interface CategoryHit {
  /** 同名跨系统时是「二级 / 三级」；只属于一个系统时是完整路径 */
  path: string;
  systems: string[];
  /** 各系统对应的完整路径（直填用） */
  pathsBySystem: Record<string, string[]>;
  score: number;
  why: string;
  /** 跨系统同名时，告诉模型怎么消歧 */
  note?: string;
}

/** 同一类产品的不同版本：它们之间的同名分类，可以靠「客户用的是哪个版本」这个事实消歧 */
export const isVersioned = (sys: string): boolean => sys.startsWith('借阅系统');

function disambiguationNote(systems: string[]): string | undefined {
  if (systems.length < 2) return undefined;
  return systems.every(isVersioned)
    ? `该分类在 ${systems.length} 个版本下同名；请按客户实际使用的版本选择。`
    : `该分类同时存在于 ${systems.join('、')}；这几个系统业务不同，请按问题内容判断。`;
}

export function search(tree: CategoryNode[], keywords: string[], limit = 12): CategoryHit[] {
  const kws = keywords.map(normText).filter((k) => k.length >= 2);
  if (!kws.length) return [];

  const groups = new Map<string, {
    score: number;
    reasons: Set<string>;
    pathsBySystem: Record<string, string[]>;
  }>();

  for (const leaf of flattenLeaves(tree)) {
    let total = 0;
    const reasons: string[] = [];
    for (const kw of kws) {
      // ★ 同一个关键词在一条路径里只计最高的一次。
      //   逐级累加会让「借还」在二级『借还管理』和三级『自助借还机接口』各拿一次分，
      //   整棵子树白得同样的底分，真正的区分词反而被淹没。
      let best = 0;
      let bestWhy = '';
      leaf.titles.forEach((title, i) => {
        const isLeaf = i === leaf.titles.length - 1;
        const weight = isLeaf ? 1.6 : i === 0 ? 0.8 : 1.2;   // 三级最重
        const hit = softMatch(title, kw);
        const pts = hit.s * weight;
        if (pts > best) {
          best = pts;
          bestWhy = hit.full ? `『${title}』与「${kw}」完整重合` : '';
        }
      });
      if (best > 0) {
        total += best;
        if (bestWhy) reasons.push(bestWhy);
      }
    }
    if (total <= 0) continue;

    const [system, ...sub] = leaf.titles;
    const key = sub.join(' / ');
    const g = groups.get(key) ?? { score: 0, reasons: new Set<string>(), pathsBySystem: {} };
    // ★ 同名组取最高分而不是累加：「在越多系统下同名」不代表越相关
    g.score = Math.max(g.score, total);
    reasons.forEach((r) => g.reasons.add(r));
    g.pathsBySystem[system!] = leaf.titles;
    groups.set(key, g);
  }

  return [...groups.entries()]
    .map(([key, g]) => {
      const systems = Object.keys(g.pathsBySystem);
      return {
        path: systems.length === 1 ? `${systems[0]} / ${key}` : key,
        systems,
        pathsBySystem: g.pathsBySystem,
        score: Math.round(g.score * 10) / 10,
        why: [...g.reasons].slice(0, 2).join('；') || '模糊相关',
        note: disambiguationNote(systems),
      };
    })
    .sort((a, b) => b.score - a.score)
    .slice(0, limit);
}

/* ---------- listSystems / browse ---------- */

export function listSystems(tree: CategoryNode[]): Array<{ system: string; leaves: number }> {
  return tree.map((n) => ({ system: n.title, leaves: flattenLeaves([n]).length }));
}

export function browse(tree: CategoryNode[], system: string, level2?: string, limit = 120) {
  const root = tree.find((n) => n.title === system)
    ?? tree.find((n) => softMatch(n.title, system).s > 0);   // 容忍写法差异
  if (!root) {
    return { ok: false as const, error: `没有叫「${system}」的系统；先调 listSystems() 看看有哪些` };
  }
  let paths = flattenLeaves([root]).map((l) => l.titles);
  if (level2) paths = paths.filter((p) => p[1] === level2);
  return {
    ok: true as const,
    system: root.title,
    paths: paths.slice(0, limit).map((p) => p.join(' / ')),
    truncated: paths.length > limit,
  };
}