mcp-multi-bridge 2.2.0 → 2.3.1

package/README.md

@@ -52,7 +52,7 @@ bridge 拉取工具列表的规则：
 
 1. 按 `path` 去重，同一 path 只查一次（不是按组织逐个查）
 2. 多个 path 并行查询
-3. 按**工具名**合并：同名工具只出现一次，`orgKey` 的可选值是提供该工具的所有组织
+3. 按**工具名**合并，同名是否合并看参数结构（见下）
 4. 单个 path 失败不阻断整体，能拿到多少给多少，失败的写进 `login` 工具的告警里
 
 ### `orgKey` 只能选同后端的组织
@@ -60,36 +60,245 @@ bridge 拉取工具列表的规则：
 这是为了避免一种必然失败的情况：工具来自 A 后端，`orgKey` 却指向 B 后端的组织，
 请求发过去那边不认识这个工具。bridge 会在调用前校验，跨后端直接拒绝并列出可用选项。
 
-### 工具数量上限
+### 同名工具怎么合并
 
-默认上限 40 个。超过后会在 `login` 工具的描述里告警——工具过多会挤占模型上下文，
-也会降低工具选择的准确率。真到这一步，说明该拆 server 了。
+不同 path 下出现同名工具时，按 `inputSchema` 的指纹判断：
+
+| 情况 | 处理 | 例子 |
+|---|---|---|
+| 结构相同 | **合并**成一个工具，`orgKey` 取并集 | sz / tc / vn 三个 MES 环境共用一套 API |
+| 结构不同 | **拆开**，加 `<系统>__` 前缀 | MES 的 `search(rid)` 与 ERP 的 `search(keyword)` |
+
+结构相同说明是同一套后端的不同部署环境，靠 `orgKey` 就能区分，加前缀反而让模型困惑。
+结构不同则是真的两个工具，必须区分，否则模型会拿着 A 系统的参数去调 B 系统。
+
+系统名从 path 末段提取并去掉 `-mcp-server` / `-api` 后缀：
+`/mcp-servers/sz-mes-mcp-server` → `sz-mes`，冲突时暴露为 `sz-mes__search`。
+
+**例外**：如果一个实例只连一个后端（一套系统一个 `--name`），系统名直接取
+`--name` 的值，不再从 path 推导。部署者写什么就是什么，比从 path 猜更准：
+
+```
+--name warehouse，path 是 /mcp-servers/erp-api
+  → 系统名取 warehouse，不取 erp
+```
+
+因为这时 `--name` 和系统是一一对应的，没有歧义。多后端聚合时
+`--name` 代表的是配置目录、下面挂着好几套系统，只能按 path 区分。
+
+## 三个容易混淆的 name
+
+| 名称 | 在哪 | 作用 |
+|---|---|---|
+| `--name` | 命令行 | **只用来算配置目录** `~/.<name>-mcp-login`，不参与路由 |
+| `orgs[].path` | config.json | **决定调用哪个 MCP server**，唯一的路由依据 |
+| mcp.json 的 key | 客户端配置 | 客户端侧 server 名，工具前缀 `mcp__<key>__` 来自它 |
+
+`--name` 不决定调用哪个后端。一个 `--name` 可以聚合多个 path
+（当前 `--name mes` 下有 5 个 path、10 个组织），这种情况必须靠 path 区分系统。
+
+## 工具很多时：按需检索
+
+工具定义要常驻模型上下文。按中等复杂度工具约 350 tokens 估算：
+
+| 工具数 | 常驻开销 | 能否直接用 |
+|---|---|---|
+| 20 | 7K | ✅ |
+| 100 | 35K | ✅ 但选择准确率开始下降 |
+| 500 | 175K | ⚠ 接近上限 |
+| 1000 | 350K | ❌ 超过多数模型整个窗口 |
+
+所以工具多了不能全塞。bridge 有三种模式：
+
+```
+MCP_BRIDGE_TOOL_MODE=auto      默认。工具数超过 40 自动切 layered
+MCP_BRIDGE_TOOL_MODE=layered   强制分层
+MCP_BRIDGE_TOOL_MODE=flat      强制全量
+```
+
+**默认 auto 而不是一直分层**：工具少时分层反而多一层间接，模型要先 `search_tools`
+才能调，纯属负担。只有当全量塞不下时才值得这个代价。
+
+### 分层时模型看到什么
+
+```
+login                     状态查询
+search_tools              按关键词检索工具（描述里带系统目录摘要）
+describe_tool             看某个工具的完整参数定义
+call_tool                 调用任意工具
++ 常驻的 N 个高频工具      默认 20 个
+```
+
+`search_tools` 的返回只给「名称 + 一句话 + 前几个参数名」，不给完整 schema——
+一个完整 schema 就几百 token，一次返回 10 个就等于回到全量暴露。需要细节时走 `describe_tool`。
+
+**命中多个时不自动挑一个。** bridge 不知道上下文：用户说「物料」可能是查也可能是建，
+猜错会调错工具、产生副作用（误删数据是最坏情况）。所以按分数排好后交给模型选。
+
+返回条数默认 5，可传 `limit`，**上限 10**。上限卡在 10 是因为：
+一次返回太多，模型的选择准确率会下降，而且每条结果都占上下文。
+需要看更多时应该收窄查询词，而不是调大 limit。
+
+排序依据三层：
+
+1. 文本相关度 —— 名称命中 > 参数名命中 > 描述命中
+2. 意图加权 —— 「料号」偏向读操作，「创建料号」偏向写操作
+3. 名称字典序 —— 完全平票时的兜底，保证同样查询返回同样顺序
+
+实测 1200 个工具（6 套系统 × 200）：
+
+```
+flat    : 604 KB ≈ 177K tokens
+layered :  12 KB ≈   4K tokens     降幅 98%
+检索延迟: 10-40ms
+```
+
+### 常驻哪些工具
+
+默认按组织覆盖数排序取前 N 个——被多套部署共用的工具更可能是每次都用的。
+但真实频次只有日志知道，所以应该按调用统计把名单固化下来：
+
+```bash
+MCP_BRIDGE_RESIDENT_COUNT=20
+MCP_BRIDGE_RESIDENT=searchRidReport,captchaGet
+```
+
+> **这两个只对分层模式生效。** 工具没超过 40 个时走 flat（全量暴露），
+> 它们会被忽略。为免误以为配置写错，这种情况会在 stderr 和 `login` 工具的描述里
+> 各提示一次——`login` 那条是给客户端界面看的，因为多数客户端不显示 stderr。
+
+统计方法（如果接了 Loki，`request_body` 里有工具名）：
+
+```logql
+sum by (tool) (count_over_time({filename=~".+"} | json | line_format "{{.request_body}}" |= "tools/call" [7d]))
+```
+
+### 客户端最终看到几个工具
+
+分层模式下是 `1 + 3 + N`：
+
+| 组成 | 数量 | 能否配置 |
+|---|---|---|
+| `login` | 1 | 不能，本包提供的状态查询 |
+| `search_tools` / `describe_tool` / `call_tool` | 3 | 不能，分层机制本身 |
+| 常驻业务工具 | 默认 20（上限 200） | `MCP_BRIDGE_RESIDENT_COUNT` / `MCP_BRIDGE_RESIDENT` |
+
+所以默认是 24 个。但这是「工具数超过 40」之后才会出现的情况——
+工具少的时候走 flat，看到的就是 `1 + 全部业务工具`。
+
+### 聚合几十上百套 MCP 时
+
+一个 bridge 可以聚合任意多个 path。数量上去之后有两个成本要处理：
+
+**1. 全量拉取很贵**
+
+启动时要对每个后端发一次 `tools/list`。实测（单后端 30ms 延迟）：
+
+| 后端数 | 首次拉取 |
+|---|---|
+| 5 | 约 1 秒 |
+| 50 | 约 6 秒 |
+| 200 | 约 20 秒 |
+
+所以工具清单**按 TTL 缓存**，默认 5 分钟：
+
+```bash
+MCP_BRIDGE_TOOLS_TTL_MS=300000
+```
+
+缓存期必须远大于拉取耗时，否则客户端每次刷新都要重来一遍——实测 200 个后端时，
+缓存让重复的 `tools/list` 从 19 秒降到 0.1 秒。
+
+**新增的工具怎么被发现？** 不需要把 TTL 调小。`tools/call` 进来时如果索引里
+查不到该工具，会自动强制刷新一次再判断。所以「网关刚加了工具、模型马上要用」
+这个场景是通的，代价只有那一次调用多花一轮拉取。
+
+**2. 并发要限**
+
+不设上限时 200 个后端会在同一瞬间建立 200 个连接，网关和本地 socket 都吃不住，
+而且失败会一起失败。
+
+```bash
+MCP_BRIDGE_FETCH_CONCURRENCY=16
+```
+
+默认 16。实测 200 个后端下，8 并发约 28 秒、16 并发约 18 秒，再往上收益不明显
+（压测环境是单进程 mock，序列化大 JSON 会成为新瓶颈，真实网关下最优值可能不同）。
+
+### 检索是怎么打分的
+
+不是向量检索，是加权关键词命中。1000 个工具用倒排就够，上 embedding 反而多一个服务要维护。
+
+**匹配依据只有三处**：工具名、描述、参数名。全部来自工具定义本身，
+bridge 侧**不维护任何业务词对照表**。
+
+早期版本内置过一份约 30 条的「料号 → material/item」别名表，后来删掉了，因为实测有两个问题：
+
+| 问题 | 说明 |
+|---|---|
+| 对写全中文描述的工具零贡献 | 真实 MES 的描述里本来就有「料号、批次、仓库、库位」，别名表一条都没用上 |
+| 会误匹配 | 「料号」被映射到 `item`，而别的系统里 `item` 可能是电商商品，`queryItem` 就被错误命中 |
+
+所以规则很简单：**工具名或描述里有这个词，就能搜到；没有就搜不到。**
+这是可预期的，也不会出现「bridge 猜错了领域」这种难以排查的情况。
+
+**新增工具不需要改代码**：
+
+```
+新增 queryCustomsDeclaration，描述「查询报关单」
+  「报关单」→ 命中（中文来自 description）
+  「customs」→ 命中（英文来自 name）
+  「declNo」→ 命中（参数名）
+```
+
+搜不到时，问题在工具定义，不在 bridge。正确的修法是**在网关侧补描述**：
+
+```
+❌ doZzz / "Process ZZZ"           「质量追溯」搜不到
+✅ doZzz / "质量追溯 · Process ZZZ"  「质量追溯」直接命中
+```
+
+描述里带上用户可能说的中文说法（含同义词），比维护一份注定对不齐的词表更省事，
+也不会漏掉长尾——业务词根本不可能靠人工枚举穷尽。
+
+**2. 意图分级**。业务 API 的工具名几乎都是 `queryXxx` / `createXxx` / `updateXxx` /
+`deleteXxx` 四件套，光看业务对象四个分数完全一样。用户说「料号」时想要的是查不是创建，
+所以按动作词加权重：
+
+```
+「料号」    → queryMaterial    只说业务对象，偏向读操作
+「创建物料」 → createMaterial   明说动作，导向写操作
+「导出物料」 → exportMaterial   导出和查询都是读，靠动作词再分一层
+```
+
+只想业务对象时不会优先给出「删除批次」这类写操作——读操作选错代价小，写操作有数据风险。
 
 ### 拆成多个客户端条目
 
-不想把所有后端压在一个 bridge 里，可以用环境变量限定本实例负责的 path：
+另一种办法是不分层，而是用环境变量限定本实例负责的 path：
 
 ```json
 {
   "mcpServers": {
     "mes-test": {
       "command": "mcp-multi-bridge",
-      "args": [],
-      "env": { "MES_MCP_PATHS": "mes-mcp-server" }
+      "args": ["--name", "mes-test"],
+      "env": { "MCP_BRIDGE_PATHS": "mes-mcp-server" }
     },
     "mes-prod": {
       "command": "mcp-multi-bridge",
-      "args": [],
-      "env": { "MES_MCP_PATHS": "tc-mes-mcp-server" }
+      "args": ["--name", "mes-prod"],
+      "env": { "MCP_BRIDGE_PATHS": "tc-mes-mcp-server" }
     }
   }
 }
 ```
 
-`MES_MCP_PATHS` 用逗号分隔，可以写完整 path（`/mcp-servers/xxx`），
-也可以只写末段（`xxx`），两种都识别。
+`MCP_BRIDGE_PATHS` 用逗号分隔，可以写完整 path（`/mcp-servers/xxx`），
+也可以只写末段（`xxx`），两种都识别。旧名 `MES_MCP_PATHS` 仍兼容。
 
-这样客户端列表里会出现两个独立条目，各自的工具集和 `orgKey` 范围互不干扰。
+两种做法的取舍：拆 server 简单但要维护多套配置和凭证；分层只维护一套，
+代价是每次找工具多一跳。系统数量不多时，拆 server 更省事。
 
 ## 检查安装的版本
 
@@ -322,6 +531,8 @@ mcp-multi-login --home "C:/Users/你/.mes-mcp-login" --org tc
 ## 提供的工具
 
 工具列表由网关返回，本包原样透传。`login` 会被本包替换成本地状态查询工具。
+分层模式下还会额外提供 `search_tools` / `describe_tool` / `call_tool` 三个元工具，
+用于按需发现工具，避免把上千个定义全塞进上下文。
 
 工具本身（有哪些、叫什么、什么参数）完全取决于网关侧配置，本包不做增删。
 当前 MES 网关提供的是：

package/bin.js

@@ -32,7 +32,7 @@
  *   - 只读 token.json / config.json，永不写入或删除
  *   - 不监听任何端口，不弹浏览器
  *   - 凭据每次调用重新读文件（所以登录后立即生效，无需重启）
- *   - 工具列表短暂缓存（TOOLS_TTL_MS），避免一次会话内反复打网关
+ *   - 工具列表按 TTL 缓存（默认 5 分钟），避免一次会话内反复打网关
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -48,11 +48,13 @@ import {
     CONFIG_FILE,
     CONFIG_DIR,
     CONFIG_DIR_ERROR,
+    CONFIG_NAME,
     NAME_DIR_SUFFIX
 } from './lib/config.js';
 import { getOrgAuth, getCurrentOrgKey, listLoggedInOrgs } from './lib/token.js';
 import { rpc, extractPayload } from './lib/higress.js';
 import { settings, DEFAULT_SETTINGS } from './lib/settings.js';
+import { buildIndex, searchTools, summarize } from './lib/toolindex.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -61,11 +63,59 @@ const PKG = require('./package.json');
 // 由 bridge 自己提供、不从 Higress 透传的工具
 const LOCAL_TOOL = 'login';
 
+// 分层模式下由 bridge 提供、用来按需发现和调用工具的三个元工具。
+// 名字用下划线前缀风格，和业务工具区分开，避免撞名。
+const META_SEARCH = 'search_tools';
+const META_DESCRIBE = 'describe_tool';
+const META_CALL = 'call_tool';
+const META_TOOLS = new Set([META_SEARCH, META_DESCRIBE, META_CALL]);
+
 // 工具数量上限：超过则告警，建议拆分 server 或缩小合并范围
 const MAX_TOOLS = 40;
 
-// 工具列表缓存时长：客户端本来只在启动时拉一次，这里仅避免同一会话内重复打网关
-const TOOLS_TTL_MS = 5000;
+/**
+ * 工具暴露模式
+ *
+ * flat    全量塞给模型。工具少时最优：少一次往返，模型能看见全部选项
+ * layered 只给常驻集 + 三个元工具，其余按需检索
+ * auto    工具数超过阈值自动切 layered（默认）
+ *
+ * 为什么默认 auto 而不是永远 layered：当前 MES 只有 4 个工具，
+ * 加三个元工具反而多一层间接，模型要先 search 才能调，纯属负担。
+ */
+function toolMode() {
+    const m = String(process.env.MCP_BRIDGE_TOOL_MODE || 'auto').toLowerCase();
+    return ['flat', 'layered', 'auto'].includes(m) ? m : 'auto';
+}
+
+/** 常驻工具数量：layered 模式下直接暴露给模型的工具个数 */
+function residentCount() {
+    const n = Number(process.env.MCP_BRIDGE_RESIDENT_COUNT || 20);
+    return Number.isFinite(n) && n > 0 ? Math.min(200, Math.floor(n)) : 20;
+}
+
+/** 手动指定的常驻工具名单，优先级高于按名字排序 */
+function residentList() {
+    const raw = String(process.env.MCP_BRIDGE_RESIDENT || '').trim();
+    if (!raw) return [];
+    return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * 工具列表缓存时长
+ *
+ * 定这个值的依据是「重拉一次有多贵」：聚合几十上百个后端时，
+ * 全量拉取要十几秒（实测 200 个后端在 30ms 延迟下约 20 秒）。
+ * 缓存期比拉取时间还短就毫无意义，客户端每次刷新都要重来。
+ *
+ * 工具清单只在网关侧改配置时变，不需要秒级感知；
+ * 真需要立刻用上新工具时，tools/call 查不到会强制刷新一次。
+ * 所以默认给 5 分钟，可用 MCP_BRIDGE_TOOLS_TTL_MS 调整。
+ */
+function toolsTtl() {
+    const n = Number(process.env.MCP_BRIDGE_TOOLS_TTL_MS || 300000);
+    return Number.isFinite(n) && n >= 0 ? n : 300000;
+}
 
 /**
  * 按 path 归组组织
@@ -152,6 +202,36 @@ async function handleCli(argv) {
     MCP_BRIDGE_PATHS=/mcp-servers/tc-mes-mcp-server
   然后在 mcp.json 里配多个带不同 env 的条目。
 
+工具暴露模式（工具多时必看）:
+  工具定义会常驻模型上下文。按中等复杂度工具约 350 tokens 估算，
+  1000 个工具就是 35 万 tokens，超过多数模型的整个窗口。
+  这时应改为按需检索：
+
+    MCP_BRIDGE_TOOL_MODE=auto      默认。工具数超过 ${MAX_TOOLS} 自动分层
+    MCP_BRIDGE_TOOL_MODE=layered   强制分层：常驻集 + search/describe/call 三个元工具
+    MCP_BRIDGE_TOOL_MODE=flat      强制全量，工具少时最优（少一次往返）
+
+    MCP_BRIDGE_RESIDENT_COUNT=20   分层时常驻几个工具
+    MCP_BRIDGE_RESIDENT=queryXxx,queryYyy
+                                   手动指定常驻名单。频次只有日志知道，
+                                   建议按真实调用统计后把名单固化下来。
+
+  同名工具的处理：参数结构相同的视为同一套后端的不同部署环境，会合并；
+  结构不同的视为不同系统的冲突，自动加 <系统>__ 前缀区分。
+
+聚合很多后端时（几十上百套 MCP）:
+    MCP_BRIDGE_TOOLS_TTL_MS=300000
+                                   工具清单缓存时长，默认 5 分钟。
+                                   全量拉取很贵：200 个后端 30ms 延迟下约 20 秒，
+                                   所以缓存期要远大于拉取耗时。
+                                   新增工具靠 tools/call 的强制刷新兜底，
+                                   不需要把 TTL 调很小。
+
+    MCP_BRIDGE_FETCH_CONCURRENCY=16
+                                   拉清单时的并发上限，默认 16。
+                                   不设上限会在同一瞬间建立上百个连接，
+                                   网关和本地 socket 都吃不住。
+
 配置目录（二选一，必须指定）:
   MCP_MULTI_HOME=<绝对路径>      旧名 MCP_BRIDGE_HOME 仍兼容
   --name <系统名>                目录为 ~/.<系统名>${NAME_DIR_SUFFIX}
@@ -185,7 +265,9 @@ async function handleCli(argv) {
         console.log(`${PKG.name} ${PKG.version}`);
         console.log(`安装位置: ${__dirname}`);
         console.log(`网关地址: ${cfg.baseUrl}`);
-        console.log(`工具上限: ${MAX_TOOLS}`);
+        const mode = toolMode();
+        const modeLabel = mode === 'auto' ? `auto（超过 ${MAX_TOOLS} 个自动分层）` : mode;
+        console.log(`工具暴露: ${modeLabel}`);
         if (allow) console.log(`限定 path: ${allow.join(', ')}`);
         console.log();
 
@@ -485,65 +567,258 @@ function localLoginTool(cfg, orgKeys, warning) {
     };
 }
 
+/**
+ * 挑选常驻工具（layered 模式下直接暴露给模型的那批）
+ *
+ * 排序依据：组织覆盖数降序，再按名字。
+ * 被多套部署环境共用的工具（通用查询这类）更可能是每次对话都要用的，
+ * 放进常驻集能省掉最常见的几次往回搜索。
+ *
+ * 环境变量 MCP_BRIDGE_RESIDENT 可手动指定名单，优先级最高——
+ * 真实调用频次只有日志能统计出来，bridge 自己不知道，
+ * 所以最终应该由运维按日志数据把名单固化下来。
+ */
+function pickResident(items, limit) {
+    const picked = [];
+    const seen = new Set();
+
+    for (const n of residentList()) {
+        const it = items.get(n) || [...items.values()].find((x) => x.originalName === n);
+        if (it && !seen.has(it.name)) {
+            picked.push(it.name);
+            seen.add(it.name);
+        }
+    }
+
+    if (picked.length >= limit) return picked.slice(0, limit);
+
+    const rest = [...items.values()]
+        .filter((it) => !seen.has(it.name))
+        .sort((a, b) => {
+            const pa = a.orgKeys.length * 1000 + a.paths.length * 100;
+            const pb = b.orgKeys.length * 1000 + b.paths.length * 100;
+            return pb - pa || a.name.localeCompare(b.name);
+        });
+
+    for (const it of rest) {
+        if (picked.length >= limit) break;
+        picked.push(it.name);
+    }
+    return picked;
+}
+
+/**
+ * 三个元工具：把「发现工具」这件事本身变成工具
+ *
+ * 为什么不把完整工具清单塞进 search_tools 的 description：
+ * 那样每轮都要为整份目录付 token，而模型多数时候只查一两个工具。
+ * 目录只以「系统 + 数量 + 少量样例」的缩略形式给出，够它判断该搜哪套系统。
+ */
+function metaTools(items, bySystem, tenantLabel) {
+    const dir = summarize(bySystem, items, 4)
+        .map((r) => `  - ${r.text}`)
+        .join('\n');
+
+    return [
+        {
+            name: META_SEARCH,
+            description: `按关键词检索可用的工具。当前共 ${items.size} 个工具，分属下列系统：\n${dir}\n\n参数 query 支持中英文，例如「料号」「批次」「创建订单」。返回命中的工具名与简短说明，然后用 ${META_CALL} 调用。`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: '检索词。中英文都可以，描述你要做的事或涉及的业务对象' },
+                    system: { type: 'string', description: '可选，只在某套系统内搜索。留空则搜全部' },
+                    limit: { type: 'number', description: '返回条数，默认 5，最多 10' }
+                },
+                required: ['query']
+            }
+        },
+        {
+            name: META_DESCRIBE,
+            description: `查看某个工具的完整参数定义。先用 ${META_SEARCH} 找到工具名，不确定参数格式时再调用这里。`,
+            inputSchema: {
+                type: 'object',
+                properties: { name: { type: 'string', description: '工具名，来自检索结果' } },
+                required: ['name']
+            }
+        },
+        {
+            name: META_CALL,
+            description: `调用一个工具。工具名可以是检索结果里的任意工具。凭据与${tenantLabel}信息由本服务注入，不需要自己传。`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: '要调用的工具名' },
+                    arguments: { type: 'object', description: '传给该工具的参数对象' }
+                },
+                required: ['name']
+            }
+        }
+    ];
+}
+
+/**
+ * 生成系统标签
+ *
+ * 聚合几十套同构系统时（比如 50 个 MES 部署环境共用一套 API），
+ * 把系统名全列出来会占掉整条检索结果 15% 的体积，而且对模型没有信息量——
+ * 它只需要知道「这个工具能用」，具体用哪套由 orgKey 决定。
+ * 所以超过 3 个就折叠成数量。
+ */
+function systemLabel(it) {
+    const list = it.systemList && it.systemList.length ? it.systemList : [it.system];
+    if (list.length <= 1) return `[${list[0]}]`;
+    if (list.length <= 3) return `[${list.join('/')}]`;
+    return `[${list[0]} 等 ${list.length} 套系统]`;
+}
+
+/**
+ * 生成 search 返回给模型的文本
+ *
+ * 只给名称 + 一句话 + 前几个参数名，不给完整 JSON Schema：
+ * 一个工具的完整 schema 就几百 token，一次返回 5 个等于回到全量暴露。
+ * 需要细节时让模型再走 describe。
+ */
+function formatFound(list) {
+    if (!list.length) {
+        // 搜不到说明工具自带的名称与描述里没有这些词。提示去补描述而不是加映射表：
+        // 桥接层不维护业务词对照，缺中文就该在网关侧把描述写全。
+        return (
+            '没有匹配的工具。\n' +
+            '可以换用工具名里的英文词（search / query / report / create）再试；\n' +
+            '若仍然搜不到，说明该工具的描述里没有这些说法，需要在网关侧补上中文描述。'
+        );
+    }
+    return list
+        .map((it) => {
+            const props = Object.keys(it.tool?.inputSchema?.properties || {});
+            const shown = props.slice(0, 6).join(', ');
+            const more = props.length > 6 ? ` …共 ${props.length} 个参数` : '';
+            const desc = String(it.tool?.description || '').split('\n')[0].slice(0, 90);
+            return `- ${it.name} ${systemLabel(it)}\n  ${desc}\n  参数：${shown || '无'}${more}`;
+        })
+        .join('\n');
+}
+
+/**
+ * 限并发执行
+ *
+ * 一个实例可能聚合几十上百个后端。无限制地打出去会同时建立上百个连接，
+ * 网关侧和本地的 socket 都吃不住，而且失败时是一起失败。
+ * 实测 200 个后端并发拉取时峰值 200 个连接，网关压力不可控。
+ *
+ * @param {T[]} list
+ * @param {number} limit
+ * @param {(item:T)=>Promise<R>} fn
+ * @returns {Promise<PromiseSettledResult<R>[]>} 与 Promise.allSettled 结构一致
+ */
+async function mapSettled(list, limit, fn) {
+    const out = new Array(list.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (true) {
+            const i = cursor++;
+            if (i >= list.length) return;
+            try {
+                out[i] = { status: 'fulfilled', value: await fn(list[i]) };
+            } catch (e) {
+                out[i] = { status: 'rejected', reason: e };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, list.length) }, worker));
+    return out;
+}
+
+/**
+ * 拉工具清单的并发上限
+ *
+ * 不设上限时，200 个后端会在同一瞬间建立 200 个连接——
+ * 网关和本地 socket 都吃不住，且失败会一起失败。
+ *
+ * 默认 16 是折中：实测 200 个后端 30ms 延迟下，
+ * 8 并发约 28 秒、16 并发约 18 秒；再往上收益不明显
+ * （压测环境是单进程 mock，序列化大 JSON 会成为新瓶颈，
+ * 真实网关下最优值可能不同，所以留了环境变量可调）。
+ */
+function fetchConcurrency() {
+    const n = Number(process.env.MCP_BRIDGE_FETCH_CONCURRENCY || 16);
+    return Number.isFinite(n) && n > 0 ? Math.min(64, Math.floor(n)) : 16;
+}
+
 /**
  * 按 path 去重拉取工具清单，并按工具名合并
  *
  * 并行的目的是：后端多时不要串行等 N 次网络往返。
  * 单个后端失败不阻断整体——能拿到多少给多少，失败的记在 errors 里。
  *
- * @returns {{tools:object[], index:Map<string,{orgKeys:string[],paths:string[]}>, errors:string[], warnings:string[]}}
+ * 同名工具的合并规则交给 toolindex.buildIndex：
+ * 参数结构相同视为同一套后端的不同部署环境（合并），
+ * 结构不同则是不同系统的真冲突（加系统前缀拆开）。
+ *
+ * @returns {{tools:object[], index:Map<string,{orgKeys:string[],paths:string[],system:string}>,
+ *            items:Map, bySystem:Map, conflicts:string[], errors:string[], warnings:string[]}}
  */
 async function collectTools(cfg) {
     const allow = allowedPaths();
     const groups = groupByPath(cfg).filter((g) => pathAllowed(g.path, allow));
 
-    const settled = await Promise.allSettled(
-        groups.map(async (g) => {
-            const r = await rpc(cfg, g.rep, 'tools/list', {});
-            return { group: g, tools: (r.result || r).tools || [] };
-        })
-    );
+    const conc = fetchConcurrency();
+    const settled = await mapSettled(groups, conc, async (g) => {
+        const r = await rpc(cfg, g.rep, 'tools/list', {});
+        return { group: g, tools: (r.result || r).tools || [] };
+    });
 
     const errors = [];
     const warnings = [];
-    const merged = new Map(); // name -> { tool, orgKeys:Set, paths:Set }
 
+    // 拉成功的后端，交给 buildIndex 统一处理命名冲突
+    const byPath = [];
+    const orgKeysByPath = new Map();
     settled.forEach((s, i) => {
         const g = groups[i];
         if (s.status === 'rejected') {
             errors.push(`${g.path}: ${s.reason?.message || s.reason}`);
             return;
         }
-        for (const t of s.value.tools) {
-            if (t.name === LOCAL_TOOL) continue; // 用本地状态工具替换远端登录
-            let e = merged.get(t.name);
-            if (!e) {
-                e = { tool: t, orgKeys: new Set(), paths: new Set() };
-                merged.set(t.name, e);
-            }
-            for (const o of g.orgs) e.orgKeys.add(o.key);
-            e.paths.add(g.path);
-        }
+        const usable = s.value.tools.filter((t) => t && t.name !== LOCAL_TOOL);
+        byPath.push({ path: g.path, tools: usable });
+        orgKeysByPath.set(g.path, g.orgs.map((o) => o.key));
     });
 
-    // 同名工具出现在多个后端时提示一次——语义可能不同，但通常是一致的
-    for (const [name, e] of merged) {
-        if (e.paths.size > 1) {
-            warnings.push(
-                `工具 ${name} 同时存在于 ${e.paths.size} 个后端，已合并（orgKey 为各后端${settings(cfg).tenantLabel}的并集）`
-            );
-        }
+    const built = buildIndex(byPath, orgKeysByPath, { defaultSystem: CONFIG_NAME });
+
+    if (built.conflicts.length) {
+        warnings.push(
+            `${built.conflicts.length} 个工具名在多套系统里定义不同，已加系统前缀区分：` +
+                built.conflicts.slice(0, 8).join('、') +
+                (built.conflicts.length > 8 ? ' 等' : '')
+        );
     }
 
     const tools = [];
     const index = new Map();
-    for (const [name, e] of merged) {
-        const orgKeys = [...e.orgKeys];
-        tools.push(augmentTool(e.tool, orgKeys, cfg));
-        index.set(name, { orgKeys, paths: [...e.paths] });
+    for (const item of built.items.values()) {
+        tools.push(augmentTool(item.tool, item.orgKeys, cfg));
+        index.set(item.name, {
+            orgKeys: item.orgKeys,
+            paths: item.paths,
+            system: item.system,
+            originalName: item.originalName,
+            prefixed: item.prefixed
+        });
     }
 
-    return { tools, index, errors, warnings, groupCount: groups.length };
+    return {
+        tools,
+        index,
+        items: built.items,
+        bySystem: built.bySystem,
+        conflicts: built.conflicts,
+        errors,
+        warnings,
+        groupCount: groups.length
+    };
 }
 
 async function main() {
@@ -556,7 +831,7 @@ async function main() {
     let cache = { at: 0, index: new Map(), tools: [], errors: [], warnings: [], groupCount: 0 };
 
     async function getTools(force = false) {
-        if (!force && Date.now() - cache.at < TOOLS_TTL_MS && cache.index.size) return cache;
+        if (!force && Date.now() - cache.at < toolsTtl() && cache.index.size) return cache;
         const cfg = loadConfig();
         if (!cfg) {
             cache = { at: Date.now(), index: new Map(), tools: [], errors: ['未找到配置'], warnings: [], groupCount: 0 };
@@ -575,31 +850,131 @@ async function main() {
             return { tools: [localLoginTool(null, [])] };
         }
 
+        const L = settings(cfg);
         const allKeys = cfg.orgs.map((o) => o.key);
-        const r = await getTools(true);
+
+        // 走缓存，不再每次强制重拉。
+        // 聚合几十上百个后端时，一次全量拉取要十几秒——实测 200 个后端
+        // 在 30ms 延迟下约 20 秒。如果客户端每次刷新工具列表都重来一遍，
+        // 界面会一直转圈。工具清单变化本来就不频繁，用 TTL 缓存足够。
+        // 真正需要「立刻看到新工具」的场景由 tools/call 兜底：
+        // 索引里查不到该工具时会强制刷新一次。
+        const r = await getTools(false);
 
         for (const e of r.errors) console.error(`[bridge] 后端拉取失败 ${e}`);
         for (const w of r.warnings) console.error(`[bridge] ${w}`);
 
+        // 模式判定：flat 全量、layered 分层、auto 按数量切换。
+        // 阈值用 MAX_TOOLS：超过它时模型的选择准确率已经明显下滑，
+        // 这时才值得付出「多一次搜索」的代价。
+        const mode = toolMode();
+        const layered = mode === 'layered' || (mode === 'auto' && r.tools.length > MAX_TOOLS);
+
         let warning;
-        if (r.tools.length + 1 > MAX_TOOLS) {
-            warning = `当前合并了 ${r.tools.length + 1} 个工具，超过建议上限 ${MAX_TOOLS}。` +
-                `工具过多会挤占模型上下文并降低选择准确率，建议用 MCP_BRIDGE_PATHS 拆分到多个 server 条目。`;
-            console.error(`[bridge] ${warning}`);
-        } else if (r.errors.length) {
+        if (r.errors.length) {
             warning = `${r.errors.length} 个后端拉取失败，工具列表可能不完整：${r.errors.join('；')}`;
         }
 
-        return { tools: [localLoginTool(cfg, allKeys, warning), ...r.tools] };
+        if (!layered) {
+            if (r.tools.length + 1 > MAX_TOOLS) {
+                const note = `当前合并了 ${r.tools.length + 1} 个工具，超过建议上限 ${MAX_TOOLS}。` +
+                    `工具过多会挤占模型上下文并降低选择准确率。` +
+                    `可用 MCP_BRIDGE_TOOL_MODE=layered 改为按需检索，或调整 MCP_BRIDGE_RESIDENT 指定常驻工具。`;
+                console.error(`[bridge] ${note}`);
+                warning = warning ? `${warning}；${note}` : note;
+            }
+            // 常驻相关配置只对 layered 生效。扁平模式下被静默忽略会让人以为配置没写对，
+            // 所以显式说一句——排查这类「配了没反应」最费时间。
+            const ignored = [];
+            if (process.env.MCP_BRIDGE_RESIDENT_COUNT) ignored.push('MCP_BRIDGE_RESIDENT_COUNT');
+            if (process.env.MCP_BRIDGE_RESIDENT) ignored.push('MCP_BRIDGE_RESIDENT');
+            let ignoredNote;
+            if (ignored.length) {
+                ignoredNote =
+                    `注意：当前是全量暴露（flat），${ignored.join(' 与 ')} 被忽略——` +
+                    `它们只对分层模式生效。要启用请设 MCP_BRIDGE_TOOL_MODE=layered。`;
+                console.error(`[bridge] ${ignoredNote}`);
+            }
+            console.error(`[bridge] 工具 ${r.tools.length} 个，全量暴露（flat）`);
+            warning = [warning, ignoredNote].filter(Boolean).join('；') || undefined;
+            return { tools: [localLoginTool(cfg, allKeys, warning), ...r.tools] };
+        }
+
+        // 分层模式：login + 三个元工具 + 常驻集
+        const limit = residentCount();
+        const residentNames = pickResident(r.items, limit);
+        const resident = residentNames.map((n) => r.items.get(n)).filter(Boolean);
+
+        console.error(
+            `[bridge] 工具 ${r.tools.length} 个，分层暴露（layered）：` +
+                `常驻 ${resident.length} 个 + 元工具 ${META_TOOLS.size} 个，其余按需检索`
+        );
+
+        const metaNote =
+            `工具较多（共 ${r.tools.length} 个），已改为按需检索：` +
+            `先用 ${META_SEARCH} 找到工具，再用 ${META_CALL} 调用。`;
+
+        return {
+            tools: [
+                localLoginTool(cfg, allKeys, warning ? `${warning}；${metaNote}` : metaNote),
+                ...metaTools(r.items, r.bySystem, L.tenantLabel),
+                ...resident.map((it) => augmentTool(it.tool, it.orgKeys, cfg))
+            ]
+        };
     });
 
     // tools/call：按 orgKey 选中组织，注入该组织的 token 后转发
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args = {} } = request.params;
+        let { name, arguments: args = {} } = request.params;
 
         try {
             const cfg = loadConfig();
 
+            // ── 元工具：工具检索与描述 ──
+            // 这两个不碰后端，只查本地索引，所以放在最前面，不需要 token
+            if (name === META_SEARCH) {
+                if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);
+                const r = await getTools(false);
+                const hits = searchTools(r.items, args.query, {
+                    system: args.system || undefined,
+                    limit: Number(args.limit) || 5
+                });
+                return textResult(
+                    `${formatFound(hits)}\n\n—— 共 ${r.items.size} 个工具，用 ${META_DESCRIBE} 看完整参数，用 ${META_CALL} 调用。`
+                );
+            }
+
+            if (name === META_DESCRIBE) {
+                if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);
+                const r = await getTools(false);
+                const it = r.items.get(args.name);
+                if (!it) {
+                    const hint = searchTools(r.items, args.name, { limit: 5 });
+                    return textResult(
+                        `没有名为 \`${args.name}\` 的工具。` +
+                            (hint.length ? `\n\n相近的有：\n${formatFound(hint)}` : `\n\n用 ${META_SEARCH} 检索。`),
+                        true
+                    );
+                }
+                return textResult(
+                    `工具：${it.name}\n` +
+                        `系统：${it.systemList.join(', ')}\n` +
+                        `可用${settings(cfg).tenantLabel}：${it.orgKeys.join(', ') || '（无）'}\n` +
+                        `说明：${it.tool?.description || '（无）'}\n\n` +
+                        `参数定义：\n${JSON.stringify(it.tool?.inputSchema || {}, null, 2)}`
+                );
+            }
+
+            // 元工具转发：把 name/arguments 换成真实工具，后续流程完全复用。
+            // 不另写一套转发逻辑，避免凭据注入、失效判定、组织选择三处各维护一份。
+            if (name === META_CALL) {
+                if (!args || !args.name) {
+                    return textResult(`缺少参数 name。用 ${META_SEARCH} 找到工具名后传入。`, true);
+                }
+                name = String(args.name);
+                args = (args.arguments && typeof args.arguments === 'object') ? args.arguments : {};
+            }
+
             // login 已改造成状态查询，不走网关
             if (name === LOCAL_TOOL) {
                 if (!cfg) return textResult(loginGuide('尚未初始化配置'), true);

package/lib/config.js

@@ -53,13 +53,14 @@ function expand(raw) {
  * 优先级：MCP_MULTI_HOME > MCP_BRIDGE_HOME（旧名） > --name 推导
  * 用环境变量而不是 config.json 里的字段——要读配置就得先知道目录，写进配置里是循环依赖。
  *
- * @returns {{dir:string, error:string|null}} dir 为空表示未配置
+ * @returns {{dir:string, name:string, error:string|null}} dir 为空表示未配置
+ *   name 是 --name 传入的系统名（用环境变量指定目录时为空），供工具分组使用
  */
 function resolveDir() {
     const pick = (v) => (typeof v === 'string' && v.trim() ? v.trim() : '');
 
     const custom = pick(process.env.MCP_MULTI_HOME) || pick(process.env.MCP_BRIDGE_HOME);
-    if (custom) return { dir: expand(custom), error: null };
+    if (custom) return { dir: expand(custom), name: '', error: null };
 
     const name = pick(nameFromArgv());
     if (name) {
@@ -67,14 +68,16 @@ function resolveDir() {
         if (!/^[A-Za-z0-9._-]+$/.test(name) || name === '.' || name === '..') {
             return {
                 dir: '',
+                name: '',
                 error: `--name 的值不合法：「${name}」。只允许字母、数字、点、下划线、连字符。`
             };
         }
-        return { dir: path.join(os.homedir(), `.${name}${NAME_DIR_SUFFIX}`), error: null };
+        return { dir: path.join(os.homedir(), `.${name}${NAME_DIR_SUFFIX}`), name, error: null };
     }
 
     return {
         dir: '',
+        name: '',
         error:
             '未指定配置目录。启动时加其中之一：\n' +
             '  1) 环境变量 MCP_MULTI_HOME=<配置目录绝对路径>\n' +
@@ -89,6 +92,14 @@ const RESOLVED = resolveDir();
 export const CONFIG_DIR = RESOLVED.dir;
 /** 未配置时的说明文字；已配置为 null */
 export const CONFIG_DIR_ERROR = RESOLVED.error;
+/**
+ * --name 传入的系统名；用 MCP_MULTI_HOME 指定目录或未配置时为空字符串。
+ *
+ * 用途：工具分组时若本实例只连一个后端，直接用它做系统名，
+ * 比从 path 末段猜（sz-mes / tc-mes）更准——部署者写什么就是什么。
+ * 注意它和 CONFIG_DIR 是两回事：--name 只决定目录，不参与路由选择。
+ */
+export const CONFIG_NAME = RESOLVED.name;
 export const CONFIG_FILE = CONFIG_DIR ? path.join(CONFIG_DIR, 'config.json') : '';
 export const TOKEN_FILE = CONFIG_DIR ? path.join(CONFIG_DIR, 'token.json') : '';
 

package/lib/toolindex.js

@@ -0,0 +1,432 @@
+/**
+ * toolindex.js —— 工具索引与检索
+ *
+ * 为什么需要这一层：
+ * 工具定义要占模型上下文。按中等复杂度工具约 350 tokens 估算，
+ * 1000 个工具就是 350K tokens，超过多数模型的整个窗口。
+ * 所以不能全量塞给模型，得让它按需查。
+ *
+ * 但「全量塞」在工具少时是更好的——少一次往返，模型看得见全部选项。
+ * 因此这里只提供索引能力，什么时候切换由调用方（bin.js）按数量决定。
+ */
+
+/**
+ * 从 MCP path 提取系统标识
+ *
+ * /mcp-servers/sz-mes-mcp-server  →  sz-mes
+ * /mcp-servers/erp-api            →  erp
+ * /foo                            →  foo
+ */
+export function systemFromPath(p) {
+    const segs = String(p || '').split('/').filter(Boolean);
+    let seg = segs.pop() || '';
+
+    // 末段只是容器名（/sap/mcp 这种），真正标识在上一层
+    if (/^(mcp|api|sse|v1|v2|server|srv)$/i.test(seg) && segs.length) seg = segs.pop();
+
+    return seg
+        .replace(/[-_](mcp|api)([-_](server|srv))?$/i, '')
+        .replace(/[-_](server|srv)$/i, '')
+        .toLowerCase() || 'default';
+}
+
+/**
+ * 工具定义的指纹，用于判断「同名工具是否真的同一个」
+ *
+ * 只取参数结构，不含 description——同一套后端的多个部署环境，
+ * 描述里可能带环境相关的字眼（如「深圳正式环境」），但参数是一样的。
+ */
+export function schemaFingerprint(tool) {
+    const s = tool?.inputSchema || {};
+    const norm = (v) => {
+        if (Array.isArray(v)) return v.map(norm);
+        if (v && typeof v === 'object') {
+            const out = {};
+            for (const k of Object.keys(v).sort()) out[k] = norm(v[k]);
+            return out;
+        }
+        return v;
+    };
+    try {
+        return JSON.stringify(norm(s));
+    } catch (e) {
+        return '{}';
+    }
+}
+
+/**
+ * 把分词结果规范化：英文小写拆驼峰与下划线，中文按二元组切
+ *
+ * 驼峰必须在转小写之前拆，否则 searchRidReport 会变成一个整词，
+ * rid / report 都拿不到——那样按「RID」搜就完全搜不到本该首位的结果。
+ */
+export function tokenize(text) {
+    const raw = String(text || '');
+    const out = new Set();
+
+    // 驼峰、下划线、连字符统一拆成空格，再小写
+    const flat = raw
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/[_-]/g, ' ')
+        .toLowerCase();
+
+    for (const w of flat.match(/[a-z][a-z0-9]*/g) || []) out.add(w);
+
+    // 中文：完整词 + 二元组，短词精确命中权重更高
+    const cjk = raw.match(/[\u4e00-\u9fa5]+/g) || [];
+    for (const run of cjk) {
+        if (run.length === 1) out.add(run);
+        for (let i = 0; i + 1 < run.length; i++) out.add(run.slice(i, i + 2));
+        if (run.length <= 6) out.add(run);
+    }
+
+    return out;
+}
+
+/**
+ * 给单个工具建检索字段
+ *
+ * 只返回索引相关的词集合，不碰 tool/name/system——
+ * 早先版本在这里返回了 system，结果把调用方算好的合并系统覆盖成占位符，
+ * 分类目录里出现一个无名的 `*` 组。
+ */
+function entryOf(tool) {
+    const props = Object.keys(tool?.inputSchema?.properties || {});
+    const desc = String(tool?.description || '');
+    const name = String(tool?.name || '');
+
+    // 名称权重最高，其次是描述，参数名再次。
+    // 名称里带动作词（query/create/update），描述里多是业务对象，两者互补。
+    const basis = [name, desc, props.join(' ')].join(' ');
+
+    return {
+        tokens: tokenize(basis),
+        nameTokens: tokenize(name),
+        propTokens: tokenize(props.join(' ')),
+        text: (name + ' ' + desc).toLowerCase()
+    };
+}
+
+/**
+ * 构建索引并解决同名冲突
+ *
+ * 冲突判定：同一工具名在多套系统里出现，且参数指纹不同 → 真冲突。
+ * 指纹相同说明是同一套后端的不同部署环境（如 sz / tc 两个 MES），应当合并，
+ * 「组织」维度已经能区分它们，加前缀反而会让模型困惑。
+ *
+ * 系统名的来源按优先级：
+ *   1. opts.defaultSystem —— 调用方给的（一般来自 --name），仅在本实例
+ *      只连一个后端时使用。一套系统一个 --name 是更自然的部署方式，
+ *      这时 --name 就是最准的系统标识，不用从 path 末段猜。
+ *   2. path 末段推导 —— 一个实例连多套系统时只能这样，
+ *      因为 --name 代表的是配置目录，下面挂着好几套后端。
+ *
+ * @param {{path:string, tools:object[]}[]} byPath 每个后端的工具列表
+ * @param {Map<string,string[]>} orgKeysByPath path → 该 path 下的组织 key
+ * @param {{defaultSystem?:string}} [opts]
+ * @returns {{items:Map<string,object>, bySystem:Map<string,object>, conflicts:string[]}}
+ */
+export function buildIndex(byPath, orgKeysByPath, opts = {}) {
+    // 只连一个后端且给了 defaultSystem 时，用这个名字，别去猜 path
+    const forced = byPath.length === 1 ? String(opts.defaultSystem || '').trim() : '';
+
+    // 先把所有 (系统, 工具) 摊平
+    const flat = [];
+    for (const g of byPath) {
+        const system = forced || systemFromPath(g.path);
+        const orgKeys = orgKeysByPath.get(g.path) || [];
+        for (const t of g.tools || []) {
+            if (!t || !t.name) continue;
+            flat.push({ tool: t, system, path: g.path, orgKeys, fp: schemaFingerprint(t) });
+        }
+    }
+
+    // 按工具名归组，看每个名字跨了几套系统、指纹是否一致
+    const byName = new Map();
+    for (const f of flat) {
+        if (!byName.has(f.tool.name)) byName.set(f.tool.name, []);
+        byName.get(f.tool.name).push(f);
+    }
+
+    const items = new Map();
+    const bySystem = new Map();
+    const conflicts = [];
+
+    for (const [name, list] of byName) {
+        const fps = new Set(list.map((x) => x.fp));
+        const systems = new Set(list.map((x) => x.system));
+        // 同名 + 多系统 + 指纹不一致 = 真冲突，必须区分
+        const needPrefix = systems.size > 1 && fps.size > 1;
+
+        if (needPrefix) conflicts.push(name);
+
+        // 冲突时按系统拆成多条；否则合并成一条
+        const buckets = needPrefix
+            ? groupBy(list, (x) => x.system)
+            : new Map([['*', list]]);
+
+        for (const [sys, group] of buckets) {
+            const exposed = needPrefix ? `${sys}__${name}` : name;
+            const orgKeys = new Set();
+            const paths = new Set();
+            const systems = new Set();
+            for (const x of group) {
+                for (const k of x.orgKeys) orgKeys.add(k);
+                paths.add(x.path);
+                systems.add(x.system);
+            }
+
+            const realName = exposed;
+            const realTool = { ...group[0].tool, name: realName };
+
+            items.set(exposed, {
+                name: realName,
+                originalName: name,
+                // 合并时可能是多套环境共用一套工具，记成列表；过滤时按包含判断
+                system: [...systems].sort().join(','),
+                systemList: [...systems].sort(),
+                prefixed: needPrefix,
+                tool: realTool,
+                orgKeys: [...orgKeys].sort(),
+                paths: [...paths].sort(),
+                ...entryOf(realTool)
+            });
+
+            // 目录按系统建索引。合并掉的工具要登记到它涉及的每个系统下——
+            // 否则 sz-mes / tc-mes 共用的工具只会挂在一个占位名下，目录就成了空的。
+            for (const s of systems) {
+                if (!bySystem.has(s)) bySystem.set(s, []);
+                bySystem.get(s).push(exposed);
+            }
+        }
+    }
+
+    return { items, bySystem, conflicts: [...new Set(conflicts)] };
+}
+
+function groupBy(arr, keyFn) {
+    const m = new Map();
+    for (const x of arr) {
+        const k = keyFn(x);
+        if (!m.has(k)) m.set(k, []);
+        m.get(k).push(x);
+    }
+    return m;
+}
+
+/**
+ * 动作词分级
+ *
+ * 同为只读，query 和 export 也不是一回事：用户说「料号」是要看数据，
+ * 不是要导出一份文件。不分级的话 exportMaterial 会靠字母序排到 queryMaterial 前面。
+ * 主级是日常查询，次级是导出/统计这类更重或更少用的操作。
+ */
+const READ_PRIMARY = ['query', 'search', 'get', 'list', 'find', 'select', 'fetch', 'detail', 'page', 'read'];
+const READ_SECONDARY = ['export', 'report', 'count', 'view', 'check', 'exists', 'summary', 'stat'];
+
+const WRITE_PRIMARY = ['create', 'add', 'insert', 'update', 'modify', 'edit', 'delete', 'remove', 'save', 'submit'];
+const WRITE_SECONDARY = ['import', 'cancel', 'approve', 'reject', 'batch', 'sync'];
+
+/**
+ * 判定查询意图
+ *
+ * 业务 API 的工具名几乎都是 queryXxx / createXxx / updateXxx / deleteXxx 四件套，
+ * 光看业务对象（material、customer）四个分数完全一样。
+ * 用户说「料号」时想要的是查，不是创建——不区分意图就会随机选中 createMaterial。
+ *
+ * 返回 read / write / unknown。unknown 在打分时按 read 处理：
+ * 读操作无副作用，选错代价小；写操作选错有数据风险。
+ */
+export function detectIntent(query) {
+    const q = String(query || '');
+    if (/创建|新增|添加|新建|修改|更新|编辑|删除|移除|保存|提交|导入|作废|审核|撤销/.test(q)) return 'write';
+    if (/\b(create|add|insert|update|modify|delete|remove|save|submit|cancel)\w*/i.test(q)) return 'write';
+    if (/查询|搜索|查找|获取|列出|查看|导出|统计|报表|明细|列表|详情|有多少/.test(q)) return 'read';
+    if (/\b(query|search|get|list|find|fetch|export|count)\w*/i.test(q)) return 'read';
+    return 'unknown';
+}
+
+/**
+ * 工具名开头的动作词等级
+ * @returns {'read'|'read2'|'write'|'write2'|''}
+ */
+function verbOf(name) {
+    const s = String(name || '');
+    // 带系统前缀时（erp__queryOrder）只看前缀后的部分
+    const tail = s.includes('__') ? s.split('__').slice(1).join('__') : s;
+    const w = (String(tail).match(/^[A-Za-z]+/) || [''])[0].toLowerCase();
+    if (!w) return '';
+
+    for (const v of READ_PRIMARY) if (w.startsWith(v)) return 'read';
+    for (const v of WRITE_PRIMARY) if (w.startsWith(v)) return 'write';
+    for (const v of READ_SECONDARY) if (w.startsWith(v)) return 'read2';
+    for (const v of WRITE_SECONDARY) if (w.startsWith(v)) return 'write2';
+    return '';
+}
+
+/** 意图与动作词的加权 */
+function verbBonus(intent, kind) {
+    if (!kind) return 0;
+    if (intent === 'write') {
+        return kind === 'write' ? 20 : kind === 'write2' ? 10 : kind === 'read' ? -4 : -2;
+    }
+    // read 与 unknown 都偏向读操作
+    return kind === 'read' ? 20 : kind === 'read2' ? 8 : kind === 'write' ? -12 : -6;
+}
+
+/**
+ * 查询里明说的动作词 → 工具名动词
+ *
+ * 「导出物料」和「查询物料」都算 read，只按读/写分级的话 exportMaterial
+ * 会被 queryMaterial 挤到后面。用户既然说了「导出」，就该给 export 额外加权。
+ */
+const ACTION_HINTS = {
+    导出: ['export'],
+    下载: ['export', 'download'],
+    统计: ['stat', 'count', 'summary'],
+    计数: ['count'],
+    列表: ['list', 'page'],
+    分页: ['page', 'list'],
+    详情: ['detail', 'get'],
+    明细: ['detail', 'report'],
+    创建: ['create', 'add'],
+    新增: ['create', 'add'],
+    添加: ['add', 'create'],
+    新建: ['create', 'add'],
+    修改: ['update', 'modify', 'edit'],
+    更新: ['update'],
+    编辑: ['edit', 'update'],
+    删除: ['delete', 'remove'],
+    移除: ['remove', 'delete'],
+    审批: ['approve'],
+    作废: ['cancel', 'void'],
+    查询: ['query'],
+    搜索: ['search'],
+    查找: ['find', 'search'],
+    获取: ['get', 'fetch']
+};
+
+/** 工具名的首个英文词（去掉系统前缀） */
+function leadingWord(name) {
+    const s = String(name || '');
+    const tail = s.includes('__') ? s.split('__').slice(1).join('__') : s;
+    return ((String(tail).match(/^[A-Za-z]+/) || [''])[0] || '').toLowerCase();
+}
+
+/** 查询里明说的动作词命中时额外加权 */
+function actionBonus(query, name) {
+    const w = leadingWord(name);
+    if (!w) return 0;
+    let bonus = 0;
+    for (const [cn, ens] of Object.entries(ACTION_HINTS)) {
+        if (!query.includes(cn)) continue;
+        for (const en of ens) if (w.startsWith(en)) { bonus += 25; break; }
+    }
+    return bonus;
+}
+
+/**
+ * 检索工具
+ *
+ * 打分是手写的加权命中，没有引入 BM25：工具描述普遍很短，
+ * 文档长度差异对相关性的影响远小于「名称是否命中」，
+ * IDF 那套在这种语料上收益有限，反而多一层不好调的参数。
+ *
+ * 刻意不做「业务词别名表」。曾经有一份约 30 条的「料号→material/item」
+ * 对照表，实测有两个问题：
+ *   1. 对描述写全中文的工具零贡献——「料号、批次、仓库」本来就出现在描述里
+ *   2. 会误匹配——把 item 当成物料，但别的系统里 item 可能是电商商品
+ * 匹配依据只认三处：工具名、描述、参数名。缺中文就去补描述，
+ * 不在桥接层维护一张注定对不齐的词表。
+ *
+ * 命中多个时按分数排序取前 N 个，不自动挑一个——bridge 不知道上下文，
+ * 用户说「物料」可能是查也可能是建，猜错会调错工具、产生副作用。
+ * 选择权留给模型。
+ *
+ * 上限 10：一次返回太多，模型的选择准确率会下降，
+ * 而且每条结果都占上下文。需要更多时应该收窄查询词。
+ *
+ * @param {Map} items buildIndex 返回的 items
+ * @param {string} query 检索词
+ * @param {{system?:string, limit?:number}} opts
+ */
+export function searchTools(items, query, opts = {}) {
+    const q = String(query || '').trim();
+    const limit = Math.max(1, Math.min(10, opts.limit || 5));
+    if (!q) return [];
+
+    const qTokens = tokenize(q);
+    const qLower = q.toLowerCase();
+    const intent = detectIntent(q);
+    const scored = [];
+
+    for (const item of items.values()) {
+        if (opts.system && !(item.systemList || []).includes(opts.system)) continue;
+
+        // 先算「文本是否相关」。意图与动作加权只在相关的前提下生效——
+        // 否则任何 queryXxx 对任何查询词都能靠动作词白得 20 分，
+        // 「完全无关的词」也会搜出结果。
+        let base = 0;
+
+        const nm = item.name.toLowerCase();
+        if (nm === qLower) base += 200;
+        else if (nm.includes(qLower)) base += 80;
+        else if (item.originalName && item.originalName.toLowerCase().includes(qLower)) base += 70;
+
+        // 分词命中：名称权重高，参数名次之，描述再次
+        for (const t of qTokens) {
+            if (item.nameTokens.has(t)) base += 25;
+            else if (item.propTokens.has(t)) base += 10;
+            else if (item.tokens.has(t)) base += 4;
+        }
+
+        // 查询串整体出现在描述里，说明是业务对象层面的匹配
+        if (qLower.length >= 2 && item.text.includes(qLower)) base += 20;
+
+        if (base <= 0) continue;
+
+        // 业务对象打平时，用动作词分出读/写、主次
+        let score = base + verbBonus(intent, verbOf(item.name));
+
+        // 用户明说了动作词（导出、统计、创建…）时，匹配该动作的工具再抬高
+        score += actionBonus(q, item.name);
+
+        scored.push({ item, score });
+    }
+
+    scored.sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name));
+    return scored.slice(0, limit).map((x) => x.item);
+}
+
+/**
+ * 生成按系统分组的目录
+ *
+ * 工具集完全相同的系统合并成一行。
+ * 这不只是排版问题：MES 的 sz/tc/vn/hn/qc 是同一套 API 的五个部署环境，
+ * 逐行列出会让模型以为有 5 倍的工具量，进而更倾向于放弃检索、直接猜名字。
+ * 合并后写作「sz-mes / tc-mes（共用 3 个）」，既准确又短。
+ */
+export function summarize(bySystem, items, perSystemSample = 4) {
+    const groups = new Map();
+    for (const [system, names] of bySystem) {
+        const key = [...names].sort().join('\u0000');
+        if (!groups.has(key)) groups.set(key, { systems: [], names });
+        groups.get(key).systems.push(system);
+    }
+
+    return [...groups.values()]
+        .map(({ systems, names }) => {
+            systems.sort();
+            const sample = names.slice(0, perSystemSample).join('、');
+            const more = names.length > perSystemSample ? ` 等 ${names.length} 个` : '';
+            const label = systems.length > 1 ? `${systems.join(' / ')}（共用 ${names.length} 个）` : `${systems[0]}（${names.length} 个）`;
+            return {
+                system: systems.join(','),
+                systems,
+                count: names.length,
+                text: `${label}：${sample}${more}`
+            };
+        })
+        .sort((a, b) => b.count - a.count || a.system.localeCompare(b.system));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-multi-bridge",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "多后端 MCP 桥接：把网关后多个后端、多个租户的工具集合并成一个 MCP 服务，凭据由登录 CLI 提供",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
   },
   "scripts": {
     "start": "node bin.js",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "test": "node test/toolindex.test.mjs"
   },
   "keywords": [
     "mcp",