beacon-mfg-mcp 1.5.1 → 1.5.3

package/README.md

@@ -7,7 +7,7 @@
 > 英文翻译（`en_backfill`）、库维护（`postfetch` / `gb_store` / `sync_assets`）等流水线**不进 MCP**、
 > 不暴露、不持密钥；MCP 也不会落在任何写路径上。
 
-## 提供的 tool（6 个，全部只读）
+## 提供的 tool（8 个，全部只读）
 
 | tool | 用途 | 关键参数 |
 |------|------|----------|
@@ -26,6 +26,8 @@
 >   千万量级下只需增大桶数（如 4096）并按城市对大分片二级切分，首次查询耗时仍与总量基本无关。
 | `get_vendor` | 按 id（+国标码）取完整中文档案 | `id`（必填） `gb`（可选，自动反查） |
 | `get_capability_card` | 按 id 取能力卡（工艺/设备/产能/认证等） | `id`（必填） |
+| `suggest_filters` | **用户原话 → 候选国标小类码**（拆词 + 别名 + 类名），供改用 `gb=` | `query`（必填） `city` `limit` |
+| `list_industries` | **国标小类货架**（只列有数据的类，附企业条数），供按语义自己挑码 | `keyword` `parent` `limit` `offset` |
 | `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购/询价意图 → 品类识别→宽召回→需求解析→生成 1~2 轮澄清问题，返回 `session_id` | `demand_text`（必填） `audience_id` |
 | `answer_sourcing` | 续接澄清轮次：写回客户答案，返回下一轮澄清问题或初选供应商列表 | `session_id`（必填） `answers` |
 | `refine_sourcing` | 推荐轮次交互：`details`(看详情与 RFQ 入口) / `more`(看更多) / `best`(看最匹配一家) | `session_id`（必填） `action` `value` |
@@ -35,6 +37,37 @@
 
 所有返回都是 JSON 文本。找不到时返回 `{ "error": ... }` 或 `has_card:false`，不会抛协议错。
 
+### 用户原话 → 国标码：给 agent 的调用协议（v1.5.3）
+
+**为什么需要**：`query` 是**字面子串**匹配，而名录按国标小类归档 —— 客户说「机加工」，
+库里写的是「机械零部件加工」，字面不通。实测（`city=嘉兴`）：
+
+| 调用 | 命中 |
+|---|---|
+| `query="机加工"` | 1 条 |
+| `gb="3484"`（机械零部件加工） | **350 条** |
+
+**不可能靠人工扩别名表覆盖所有说法**（精密件 / 手机壳 / 来料加工…），所以把
+「原话 → 国标码」这一步交给**客户端 LLM 自己**（服务端不调 LLM、不需要密钥）。
+
+推荐 agent 按这三步走：
+
+1. 先正常检索：`search_vendors(query=<用户原话>, city=<城市>)`。
+2. **命中 < 5 条（含 0）就换码**：返回体里的 `suggested_gb`（或 `hint`）已经给了候选码；
+   候选不够味就调 `suggest_filters(query, city)` 拿更多候选 —— 它按
+   `alias`（人工策展）> `gb_name`（类名被完整说出）> `substring` > `segmented`（拆词）
+   加权，并**优先「类名里含用户原话」的候选**（「轴承」→ 3451 滚动轴承制造）。
+3. 用 `search_vendors(gb=<码>, city=...)` 重试（只扫对应分片，更快）。多个码的结果
+   自行合并去重。**连候选都没有**（如「手机壳」）→ 调 `list_industries` 看货架
+   （287 个有数据的类，附条数）自己挑 1~3 个码。
+
+可直接放进 agent 系统提示词的一段：
+
+> 检索灯塔工厂名录时，`search_vendors` 的 `query` 是字面子串匹配。若命中数少于 5 条，
+> 说明用户说的是口语/采购词：先看返回的 `suggested_gb`，或调 `suggest_filters` 拿到
+> 候选国标小类码，再用 `gb=` 重试；仍无候选则调 `list_industries` 按语义挑码。
+> 不要因为命中少就回答「没有这类企业」。
+
 ## 安装 / 接入
 
 服务是**零第三方依赖**的单文件（`server.py`，仅用 Python 标准库），只需 Python 3.8+。

package/RELEASE.md

@@ -1,4 +1,4 @@
-# Beacon-MFG 只读 MCP 服务 · v1.5.1
+# Beacon-MFG 只读 MCP 服务 · v1.5.3
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
 **检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
@@ -8,12 +8,14 @@
 MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流水线**不进 MCP、不暴露、不持密钥**，
 也不会落在任何写路径上。对 Android App 与 cron/GUI 流水线**零影响**（详见 `mcp/README.md`）。
 
-## 六个只读 tool
+## 八个只读 tool
 | tool | 用途 | 关键参数 |
 |------|------|----------|
 | `search_vendors` | 按 关键词 / 城市 / 国标码 检索，返回精简档案 | `query` `city` `gb` `limit` `offset` |
 | `get_vendor` | 按 id（+国标码）取完整中文档案 | `id`（必填） `gb`（可选） |
 | `get_capability_card` | 按 id 取能力卡（工艺/设备/产能/认证） | `id`（必填） |
+| `suggest_filters` | **把用户原话映射成候选国标小类码**（拆词 + 别名 + 类名），供改用 `gb=` | `query`（必填） `city` `limit` |
+| `list_industries` | **国标小类货架**（只列有数据的类，附条数），供 LLM 按语义自己挑码 | `keyword` `parent` `limit` `offset` |
 | `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购意图 → 品类识别→宽召回→澄清，返回 `session_id` | `demand_text`（必填） `audience_id` |
 | `answer_sourcing` | 续接澄清轮次：写回客户答案，返回下一轮澄清或初选列表 | `session_id`（必填） `answers` |
 | `refine_sourcing` | 推荐轮次交互：`details`/`more`/`best` | `session_id`（必填） `action` `value` |
@@ -21,7 +23,102 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
 依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
 
-## 本次更新（v1.5.1）
+## 本次更新（v1.5.3）
+**用户说的话和名录里的写法对不上时，不再只回 1 条 —— 加了一层「语义路由」；
+顺带把 `get_capability_card` 从 42~65 秒压到 2 毫秒。**
+
+### 1. 问题：别名表不可能穷举
+
+拿「嘉兴 机加工」做用户侧压测（真 MCP stdio、非仓库 cwd 强制走 HTTP）：
+
+| 查询 | 命中 |
+|---|---|
+| `query="机加工"` + `city="嘉兴"` | **1 条** |
+| `query="机加工"`（全国） | 73 条 |
+| `gb="3484"`（机械零部件加工）+ `city="嘉兴"` | **350 条** |
+
+`search_vendors` 的关键词是**字面子串**匹配，而名录按国标小类归档：客户说的是
+「机加工」，库里写的是「机械零部件加工」，两者字面不通 → 召回率 0.3%。
+靠人工扩别名表补是走不通的 —— 说法千人千面（精密件 / 手机壳 / 来料加工…），
+表永远差一行，而且加得越多误召回越多。
+
+### 2. 解法：把「原话 → 国标码」这一步交给客户端 LLM
+
+**MCP 客户端本身就是一个 LLM**，所以服务端不需要调 LLM、不需要密钥、不引入延迟：
+把「货架」和「候选」交给它，让它现场做语义映射。别名表因此降级为
+**高频词加速器**（命中就直接省一次往返），不再是唯一入口。
+
+- 新增 **`suggest_filters(query, city)`**：三条来源按可信度加权给出候选码 ——
+  `alias`（人工策展 / 数据推导）> `gb_name`（类名被完整说出）> `substring`（类名子串）
+  > `segmented`（对原话做最长匹配拆出的词）。**名字里直接含用户原话的候选额外加权**
+  （「轴承」→ 3451 滚动轴承制造 必须压过 3399 其他未列明金属制品制造），
+  平票时按 `hits`（该词在该类下真实出现过的企业数）而不是类规模排序。
+  返回体自带 `next_call`，agent 可以直接照抄参数。
+- 新增 **`list_industries(keyword, parent)`**：国标货架（**只列已有企业的类**，287 个，
+  附条数）。一个 0 条的类摆上货架只会误导 LLM，所以刻意不列全 1382 个。
+  这是「没有字面候选时」的兜底：让 LLM 自己从类名里挑。
+- **`search_vendors` 命中 < 5 时内联 `hint` + `suggested_gb`**：省掉 agent 再调一次的
+  往返，看到就能改 `gb=` 重试。命中充足时**不打扰**（说明用户说的词本身就是库里的词）。
+- 顺手补了 4 条高价值策展别名（`机加工` `数控加工` `加工中心` `精密加工`）——
+  它们是**加速器**，不是这套机制的前提。
+
+### 3. `get_capability_card`：42~65 秒 → 2 毫秒
+
+能力卡只落在 `skills/registry/capability/`，既不进 git 也不在 CDN 静态站，**R2 是唯一供给**
+（由 Worker 反代）。对**没有卡**的供应商（大多数），`fetch_text` 会依次撞 3 个基址的 404，
+其中 jsDelivr / raw.githubusercontent 是**间歇性**慢 —— 同一条命令实测三次：**2.35 s / 42.68 s / 64.60 s**。
+
+- 清单新增 **`metadata.cap_cards`**：14587 个已发卡 id 的数字后缀（逗号串，清单 +114 KB）。
+- `get_capability_card` 先查这张表，**不在表里直接回 `has_card=false`，一次 HTTP 都不发**；
+  在表里的才真正去取。实测 **0.002 s**。
+- 清单里没有 `cap_cards` 时（旧快照）自动回落原路径 —— 向后兼容，不会因为数据没发而变哑。
+
+### 4. 发布闸门：补登记门类 E
+
+门类扩展时 E（建筑业）的记录已经进库，但 `skills/schema/gates/E.json` 没建 →
+`validate --strict` 报 `未知 category '建筑业'` → **r2/pages/git 全被闸门拦下，云端永远收不到新数据**。
+补上 E.json（`cap_domain` 故意留空：建筑业暂无能力码表，填一个没登记的域名会让
+`gate_schema` 静默取到空 label，看着像配了其实没配）。
+
+### 5. 实测（真 MCP stdio，发布后）
+
+| 步 | 耗时 |
+|---|---|
+| initialize / tools/list | 0.7~1.3 s / 0.00 s |
+| 首个检索（新进程冷缓存） | 1.8~3.7 s |
+| 同进程再检索 | 0.7~0.9 s |
+| `get_vendor`（热） | 0.2 s |
+| `get_capability_card`（无卡） | **0.002 s** |
+| 用户视角「找到一家并拿到档案」全程 | **2.9~7.1 s** |
+
+## 本次更新（v1.5.2，已发布）
+**搜索也走内容哈希缓存 —— 新进程首次检索 9.2 s → 3.8 s，同进程重复检索 1.2 s。**
+
+v1.5.0 给 `get_vendor` 加的「按清单 h 缓存分片」（`_shard_text`）**漏了搜索这条路**：
+`search_vendors` 走 `_records_from_paths` → `_read_many_text`，而 `_read_many_text` 的 HTTP
+分支直接调 `fetch_text` —— 只有 URL 级缓存，命中也要发条件请求等 304，且**不跨进程复用**。
+实测：同一个「模具」检索，冷启动与新进程热启动**都是 ~11 s、每次都重下 17.8 MB / 29 个请求**；
+缓存目录里 URL 哈希文件 33 个、`shard-*.json` **一个都没有**。
+
+- `_read_many_text` 的 HTTP 分支改走 `_shard_text`：内容没变就**完全不走网络**（连 304 都省）。
+  实测新进程热启动：**29 次 / 17.79 MB → 1 次 / 0.25 MB**（只剩 manifest）。
+- 两张别名表（`data/gb-alias.json` + `data/gb-alias-curated.json`）原来**逐个文件串行**取，
+  各付一次 CDN RTT（实测每个约 0.7 s）。改为一次 `_read_many_text` 并发取齐。
+- 清单新增 **`metadata.idxfiles`**：登记 512 个 terms 倒排桶 + 策展别名表的 `h`，
+  让它们也能命中内容缓存（否则每次检索都要为「关键词 → 分片」的解析表付一次 RTT）。
+  **刻意不放进 `shards`** —— App 会拉全部 `t=idx` 片（`RemoteSource.kt:419`），
+  512 个桶 / 约 35 MB 塞进去等于让手机每次同步多下 35 MB。代价只是清单 +26 KB。
+
+**用户侧实测**（`npx -y beacon-mfg-mcp` 真实路径、HTTP 模式、隔离缓存）：
+
+| 动作 | v1.5.1 | v1.5.2 |
+|---|---|---|
+| `get_vendor`（按 id 取详情） | 0.2 s 量级 | 0.2 s 量级（未变） |
+| 首次搜索（冷，全新安装） | 9.7 s | 5.0 s |
+| 首次搜索（新进程、缓存已在） | 9.2 s | 3.8 s |
+| 同进程第二次搜索 | 3.2 s | 1.2 s |
+
+## 本次更新（v1.5.1，已发布）
 **修「刚导入的企业在 MCP 上查不到」——idmap 新号守卫。**
 
 v1.5.0 的 idmap 有个致命假设：片存在但片里没这条 id ⇒ 判「不存在」（这样才能省掉
@@ -117,7 +214,7 @@ v1.5.0 的 idmap 有个致命假设：片存在但片里没这条 id ⇒ 判「
 ## 安装（三选一）
 
 ### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.1.tar.gz`，解压后：
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.3.tar.gz`，解压后：
 ```jsonc
 {
   "mcpServers": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Read-only MCP server exposing the BeaconMFG灯塔工厂 supplier directory (search vendors, get vendor detail, get capability card, multi-turn sourcing) to any MCP-compatible agent. No API key required.",
   "keywords": [
     "mcp",

package/server.py

@@ -271,9 +271,9 @@ def _pkg_version() -> str:
     try:
         p = os.path.join(os.path.dirname(os.path.abspath(__file__)), "package.json")
         with open(p, "r", encoding="utf-8") as f:
-            return json.load(f).get("version", "1.5.1")
+            return json.load(f).get("version", "1.5.3")
     except Exception:
-        return "1.5.1"
+        return "1.5.3"
 
 
 # HTTP 基址列表（含兜底镜像）。默认部署 Cloudflare Pages 不可达时，自动回退到
@@ -682,16 +682,31 @@ _shard_hash_slot: Optional[tuple] = None    # (rel -> sha1, 数据版本号)
 
 
 def _shard_hash_index() -> Dict[str, str]:
-    """分片路径 → 清单登记的 sha1（h）。随数据版本重建，进程内只建一次。"""
+    """分片路径 → 清单登记的 sha1（h）。随数据版本重建，进程内只建一次。
+
+    除 `shards` 外还合并 `metadata.idxfiles`：terms 倒排桶与策展别名表**刻意不在
+    shards 里** —— App 会拉全部 t=idx 片（RemoteSource.kt:419），把 512 个
+    terms 桶放进 shards 等于让手机每次同步多下 35 MB。
+    但 MCP 侧需要它们的 h 才能做内容哈希缓存，否则每次检索都各付一次 CDN RTT。
+    """
     global _shard_hash_slot
     ver = _data_version()
     if _shard_hash_slot is None or _shard_hash_slot[1] != ver:
         m: Dict[str, str] = {}
         try:
-            for s in load_manifest().get("shards", []):
+            man = load_manifest()
+            for s in man.get("shards", []):
                 p, h = s.get("p"), s.get("h")
                 if p and h:
                     m[str(p)] = str(h)
+            ix = (man.get("metadata") or {}).get("idxfiles") or {}
+            d = ix.get("dir")
+            for name, h in (ix.get("h") or {}).items():
+                if d and name and h:
+                    m["%s/%s" % (d, name)] = str(h)
+            for rel, h in (ix.get("files") or {}).items():
+                if rel and h:
+                    m[str(rel)] = str(h)
         except Exception:
             m = {}
         _shard_hash_slot = (m, ver)
@@ -778,9 +793,15 @@ def _zh_paths_for_gb(gb: str) -> List[str]:
 # 一个字都不出现，_hay 命中不了，于是返回 0 条 —— 而 App 同一句能出 3434。
 # 别名表把「口语词 → 国标码」补上，检索时按码直接定向对应分片。
 # --------------------------------------------------------------------------- #
-def _load_alias_file(rel: str) -> Dict[str, Any]:
-    """两种历史形态都兼容：[["metadata",..],["alias",{..}]] 和直接 {word: ...}。"""
-    txt = fetch_text(rel)
+def _load_alias_file(rel: str, txt: Optional[str] = None) -> Dict[str, Any]:
+    """两种历史形态都兼容：[["metadata",..],["alias",{..}]] 和直接 {word: ...}。
+
+    `txt` 可由调用方批量取好后传入（见 `load_gb_alias`）—— 免得逐文件各付一次 RTT。
+    未传入时走 `_shard_text`：`data/gb-alias.json` 登记在清单里 ⇒ 按内容哈希缓存，
+    跨进程也不重复下载。
+    """
+    if txt is None:
+        txt = _shard_text(rel)
     if not txt:
         return {}
     try:
@@ -802,9 +823,14 @@ def load_gb_alias() -> Dict[str, Any]:
     global _alias_cache
     _alias_relpaths = ("data/gb-alias.json", "data/gb-alias-curated.json")
     if _cache_stale(_alias_cache, _alias_relpaths):
+        # ⚡ 两张表互相独立 → 一次并发取齐。逐个 fetch 各付一次 CDN RTT
+        #    （实测每个约 0.7 s，串行 1.42 s —— 占「新进程首次检索」剩余耗时的一半）。
+        #    同时借 _read_many_text 落到 _shard_text：清单里登记了 h 的表按内容缓存，
+        #    内容没变就完全不走网络；没 h 的表（如 gb-alias-curated.json）自动退回 fetch。
+        raw = _read_many_text(list(_alias_relpaths))
         merged: Dict[str, Any] = {}
         for rel in _alias_relpaths:
-            for k, v in _load_alias_file(rel).items():
+            for k, v in _load_alias_file(rel, raw.get(rel)).items():
                 merged.setdefault(str(k).lower(), v)
         _alias_cache = (merged, time.time(), _wt_mtime_any(_alias_relpaths))
     return _alias_cache[0]
@@ -896,6 +922,244 @@ def _fp_paths_for_gbs(codes: List[str]) -> List[str]:
     return [s.get("p") for s in _shards_of_type("fp") if s.get("c") in set(codes)]
 
 
+# --------------------------------------------------------------------------- #
+# 语义路由层：不要求「服务端猜对用户的原话」，而是把**国标货架 + 候选码**交给
+# 客户端 LLM，让它现场做语义映射。
+#
+# 为什么这么做（2026-10-06 主人提的问题）：靠人工扩别名表覆盖「机加工 / 精密件 /
+# 手机壳…」是走不通的 —— 说法千人千面，表永远差一行，而且加得越多误召回越多。
+# 而 **MCP 客户端本身就是一个 LLM**。把「用户原话 → 国标码」这一步交给它：
+#   · 零额外基础设施：服务端不调 LLM、不需要密钥、不引入延迟和成本；
+#   · 天然覆盖长尾：LLM 的知识面就是那张「说法表」，不必我们枚举；
+#   · 可控可解释：LLM 挑码的依据是货架上的类名 + 真实条数，不是黑盒。
+# 别名表因此降级为**高频词加速器**（能命中就直接省一次往返），不再是唯一入口。
+#
+# 三个出口：
+#   list_industries()    → 国标货架（只列有数据的类，带条数）
+#   suggest_filters()    → 拆词 + 别名 + 类名子串，给出候选码与下一步调用
+#   search_vendors()     → 命中偏少时内联 hint，把这条链路推给 agent
+# --------------------------------------------------------------------------- #
+
+_GB_SHELF: Optional[List[Dict[str, Any]]] = None
+_SEG_PATTERNS: Optional[List[Tuple[str, str]]] = None
+
+
+def _gb_shelf() -> List[Dict[str, Any]]:
+    """国标小类货架：[{code, name, group, path, records}]。
+
+    数据源刻意选 `data/gb-index.json`（82 KB）而不是 `gb4754-full.json`（280 KB）：
+    前者**只含真正有数据的类**（269 个），并直接带每类条数。对「让 LLM 挑码」
+    这个用途，列一个 0 条的类只会误导它 —— 货架上摆不出来的东西没必要上架。
+    """
+    global _GB_SHELF
+    if _GB_SHELF is not None:
+        return _GB_SHELF
+    rows: List[Dict[str, Any]] = []
+    try:
+        txt = fetch_text("data/gb-index.json")
+        tree = (json.loads(txt) if txt else {}).get("tree") or {}
+    except Exception:
+        tree = {}
+    for dcode, dv in tree.items():
+        dname = str(dv.get("name") or "")
+        for gcode, gv in (dv.get("divisions") or {}).items():
+            gname = str(gv.get("name") or "")
+            for mcode, mv in (gv.get("groups") or {}).items():
+                mname = str(mv.get("name") or "")
+                for ccode, cv in (mv.get("classes") or {}).items():
+                    rows.append({
+                        "code": str(ccode),
+                        "name": str(cv.get("name") or ""),
+                        "group": str(mcode),
+                        "path": "%s/%s/%s" % (dname, gname, mname),
+                        "records": int(cv.get("count") or 0),
+                    })
+    _GB_SHELF = rows
+    return rows
+
+
+def _seg_patterns() -> List[Tuple[str, str]]:
+    """长词优先的匹配表 [(词, 来源)]，来源 ∈ alias / gb_name。"""
+    global _SEG_PATTERNS
+    if _SEG_PATTERNS is None:
+        pats: Dict[str, str] = {}
+        for w in load_gb_alias():
+            if len(w) >= 2:
+                pats.setdefault(w, "alias")
+        for r in _gb_shelf():
+            if len(r["name"]) >= 2:
+                pats.setdefault(r["name"], "gb_name")
+        _SEG_PATTERNS = sorted(pats.items(), key=lambda x: -len(x[0]))
+    return _SEG_PATTERNS
+
+
+def _segment_terms(text: str) -> List[Tuple[str, str]]:
+    """把一段人话按「最长优先、不重叠」切成已知词条。
+
+    这是「智能拆分需求」的确定性那一半：`不锈钢板激光切割折弯` →
+    `激光切割 / 折弯 / 不锈钢板` 三个候选，各自再去映射国标码。
+    剩下那一半（这几个词到底该挑哪个码、要不要并集）交给 LLM。
+    """
+    hay = (text or "").lower()
+    if not hay:
+        return []
+    hits: List[Tuple[str, str]] = []
+    i, n = 0, len(hay)
+    while i < n:
+        for w, src in _seg_patterns():
+            if hay.startswith(w.lower(), i):
+                hits.append((w, src))
+                i += len(w)
+                break
+        else:
+            i += 1
+    return hits
+
+
+def list_industries(keyword: str = "", parent: str = "", limit: int = 30,
+                    offset: int = 0) -> Dict[str, Any]:
+    """国标货架：给 LLM 一张「有哪些行业、各有多少家」的菜单。
+
+    用户原话与任何类名都不对字时（如「机加工」对不上「机械零部件加工」），
+    唯一靠谱的办法是让 LLM 看货架自己挑 —— 这正是本工具存在的理由。
+    """
+    limit = max(1, min(int(limit), 200))
+    offset = max(0, int(offset))
+    rows = _gb_shelf()
+    parent = (parent or "").strip()
+    if parent:
+        rows = [r for r in rows
+                if r["code"].startswith(parent) or r["group"].startswith(parent)
+                or r["path"].startswith(parent)]
+    keyword = (keyword or "").strip().lower()
+    if keyword:
+        rows = [r for r in rows
+                if keyword in r["name"].lower() or keyword in r["code"]
+                or keyword in r["path"].lower()]
+    rows = sorted(rows, key=lambda r: -r["records"])
+    return {
+        "total": len(rows),
+        "returned": len(rows[offset:offset + limit]),
+        "note": "只列**已有企业**的国标小类（带条数）。请按语义挑 1~3 个最接近的 code，"
+                "再调 search_vendors(gb=<code>, city=<城市>)。"
+                "传 parent 可缩小货架（门类字母如 C、或大类两位码如 35）。",
+        "industries": rows[offset:offset + limit],
+    }
+
+
+def suggest_filters(query: str, city: str = "", limit: int = 8) -> Dict[str, Any]:
+    """把用户原话映射成候选国标码（给 LLM 做决策依据，而不是替它做决定）。
+
+    三条来源按可信度排序：
+      1 alias      别名表精确命中（人工策展 / 数据推导）—— 最可信
+      2 gb_name    类名被完整说出（「机械零部件加工」）
+      3 substring  类名子串（「轴承」→ 轴承制造）
+      4 segmented  对原话做最长匹配拆出的词（覆盖「一句话多个诉求」）
+    全都没命中时**明确告诉 agent 去查货架**，而不是返回一个空数组让它瞎猜。
+    """
+    q = (query or "").strip()
+    if not q:
+        return {"error": "缺少必填参数 query"}
+    limit = max(1, min(int(limit), 30))
+    by_code = {r["code"]: r for r in _gb_shelf()}
+    cands: Dict[str, Dict[str, Any]] = {}
+
+    def _add(code: str, score: int, why: str, term: str = "", hits: int = 0) -> None:
+        row = by_code.get(code) or {}
+        name = row.get("name") or _gb_names().get(code, "")
+        # 名字里**直接含用户原话**是最强信号：「轴承」→ 3451 滚动轴承制造
+        # 一定比「3399 其他未列明金属制品制造」更可能是正解。没有这一步，
+        # 排序会被「类大 = 条数多」带偏（3399 有 4116 家，把正解压到第二名）。
+        if term and term.lower() in (name or "").lower():
+            score += 25
+        cur = cands.get(code)
+        item = {
+            "code": code,
+            "name": name,
+            "path": row.get("path", ""),
+            "records": row.get("records", 0),
+            "why": why,
+            "term": term or q,
+            "hits": int(hits or 0),
+            "_score": score,
+        }
+        if cur is None or score > cur["_score"]:
+            cands[code] = item
+
+    for h in alias_codes(q):
+        _add(h["code"], 100 if h["exact"] else 80, "alias", h["word"], h.get("hits", 0))
+    ql = q.lower()
+    for r in _gb_shelf():
+        nm = r["name"].lower()
+        if nm == ql:
+            _add(r["code"], 90, "gb_name", q)
+        elif ql in nm:
+            _add(r["code"], 60, "substring", q)
+    for term, src in _segment_terms(q):
+        if term.lower() == ql:
+            continue
+        if src == "alias":
+            for h in alias_codes(term):
+                _add(h["code"], 70 if h["exact"] else 55, "segmented", term,
+                     h.get("hits", 0))
+        for r in _gb_shelf():
+            if r["name"] == term:
+                _add(r["code"], 65, "segmented", term)
+
+    # 词条级证据（hits = 该词在该类下真实出现过的企业数）优先于类规模。
+    out = sorted(cands.values(), key=lambda x: (-x["_score"], -x["hits"], -x["records"]))
+    for x in out:
+        x.pop("_score", None)
+    out = out[:limit]
+
+    res: Dict[str, Any] = {
+        "query": q,
+        "city": city or "",
+        "candidates": out,
+        "how_to_use": "挑 1~3 个 code，逐个调 search_vendors(gb=<code>, city=<城市>)"
+                      "（给了 gb 只扫对应分片，最快）；多个码的结果自行合并去重。"
+                      "候选为空或都不对味时，调 list_industries 看货架自己挑。",
+    }
+    if out:
+        res["next_call"] = {"tool": "search_vendors",
+                            "arguments": {"gb": out[0]["code"], "city": city or "",
+                                          "limit": 20}}
+    else:
+        res["next_call"] = {"tool": "list_industries",
+                            "arguments": {"keyword": q, "limit": 30}}
+        res["note"] = ("没有字面/别名候选。请用你的语义理解先在货架上挑类："
+                       "先 list_industries(keyword=\"…\") 看有哪些类，"
+                       "必要时空 keyword 拉全货架（269 类）挑最贴近的 1~3 个 code。")
+    return res
+
+
+def _attach_routing_hint(out: Dict[str, Any], q: str, city: str) -> Dict[str, Any]:
+    """命中偏少时，把「怎么把口语词换成国标码」这条链路内联进结果。
+
+    只在 query 非空且命中 < 5 时触发 —— 命中充足说明用户说的词本身就是数据里的
+    词，不需要打扰 agent。内联（而不是让 agent 再调一次）是为了省一个 RTT：
+    agent 看到 hint 就能直接改参数重试。
+    """
+    if not q or out.get("total_matched", 0) >= 5:
+        return out
+    try:
+        s = suggest_filters(q, city, limit=5)
+    except Exception:
+        return out
+    cands = s.get("candidates") or []
+    if out.get("total_matched", 0) == 0 and not cands:
+        out["hint"] = ("关键词与名录里的写法对不上，且没有可推导的国标码。"
+                       "建议调 list_industries 用语义挑码后改传 gb=。")
+        return out
+    if cands:
+        out["hint"] = ("命中偏少：用户说的是口语/采购词，名录里按国标小类归档。"
+                       "改用 gb= 重试通常能召回几十~几百条（见 suggested_gb）。")
+        out["suggested_gb"] = [{"code": c["code"], "name": c["name"],
+                                "records": c["records"], "why": c["why"]}
+                               for c in cands]
+    return out
+
+
 # --------------------------------------------------------------------------- #
 # 能力（cap）别名召回：把「AI / 人工智能 / 机器学习 / 大模型 / 算法 …」映射到
 # 能力键（如 tech_ai），按能力键定向召回。与 GB 别名不同，cap 是跨门类能力、
@@ -1636,9 +1900,17 @@ def _read_many_text(paths: List[str]) -> Dict[str, str]:
         got = _git_read_many(paths)
         if len(got) >= max(1, len(paths) // 2):   # archive 正常覆盖
             return got
+    # ⚠ HTTP 分支必须走 _shard_text（按清单 h 做**内容哈希缓存**），不能裸调 fetch_text。
+    #   这里是 _candidate_shards（倒排桶）与 _records_from_paths（fp 分片）的**公共取数口**：
+    #   一次「模具」检索要拉约 17 MB 的 fp 分片（24 片）。裸 fetch_text 只有 URL 级缓存，
+    #   而 URL 缓存**不跨进程复用**（每次新进程都重下），于是热启动与冷启动同速
+    #   —— 实测两次都是 ~11 s，缓存目录里 URL 哈希文件 33 个、shard-*.json 一个都没有。
+    #   换 _shard_text 后，内容没变就完全不走网络（连 304 都省），且跨进程有效。
+    #   （没有 h 的路径——如倒排桶——_shard_text 内部自动退回 fetch_text，行为不变。）
+    _shard_hash_index()          # 预热：别让线程池里做首次构建
     out: Dict[str, str] = {}
     with concurrent.futures.ThreadPoolExecutor(max_workers=16) as ex:
-        for path, txt in zip(paths, ex.map(fetch_text, paths)):
+        for path, txt in zip(paths, ex.map(_shard_text, paths)):
             if txt:
                 out[path] = txt
     return out
@@ -1986,12 +2258,12 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
                 if gen_tokens and not all(tok in _hay(rec).lower() for tok in gen_tokens):
                     continue
                 matches.append(_rec_summary(rec))
-        return {
+        return _attach_routing_hint({
             "total_matched": len(matches),
             "returned": len(matches[offset:offset + limit]),
             "shards_scanned": scanned,
             "results": matches[offset:offset + limit],
-        }
+        }, q, city)
 
     # 未给国标码：优先走「预构建倒排索引 → 只拉命中分片」（O(命中量)）。
     # 索引缺失或陈旧时回退进程内全量索引（O(总量)，慢但结果等价）。
@@ -2000,13 +2272,13 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
 
     if via_index and not cands and not alias_paths and not cap_hits:
         # 索引明确判定无命中、别名也没给方向 —— 无需拉任何分片
-        return {
+        return _attach_routing_hint({
             "total_matched": 0,
             "returned": 0,
             "shards_scanned": 0,
             "via_index": True,
             "results": [],
-        }
+        }, q, city)
 
     matches: List[Dict[str, Any]] = []
     seen: set = set()
@@ -2102,7 +2374,7 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
         out["cap_expanded"] = [{"word": h["word"], "cap": h["cap"], "name": h["name"]}
                                for h in cap_hits]
         out["cap_records_seen"] = cap_scanned
-    return out
+    return _attach_routing_hint(out, q, city)
 
 
 def _pick(*vals: Any) -> Any:
@@ -2213,10 +2485,43 @@ def get_vendor(vid: str, gb: str = "") -> Dict[str, Any]:
     return {"error": f"找不到 id={vid} 对应的国标码，可能该记录尚未发布"}
 
 
+_CAP_CARD_IDS: Optional[set] = None
+
+
+def _card_count() -> int:
+    return int(((load_manifest().get("metadata") or {})
+                .get("cap_cards") or {}).get("count") or 0)
+
+
+def _cap_card_ids() -> Optional[set]:
+    """清单里登记的「已有能力卡的 id 集合」（None = 清单没这块，走原路径）。
+
+    2026-10-06 实测：能力卡只存在于本地 `skills/registry/capability/`，
+    既不进 git 也不在 CDN 静态站上 → 三个基址串行 404。对 majority 没有卡的
+    供应商，一次 `get_capability_card` 要 **42~65 秒**才肯回 has_card=false。
+    清单带上这张 id 表之后，没卡的直接短路，一次网络都不发。
+    """
+    global _CAP_CARD_IDS
+    if _CAP_CARD_IDS is None:
+        ids = ((load_manifest().get("metadata") or {}).get("cap_cards") or {}).get("ids")
+        _CAP_CARD_IDS = set(ids.split(",")) if ids else None
+    return _CAP_CARD_IDS
+
+
 def get_capability_card(vid: str) -> Dict[str, Any]:
     vid = (vid or "").strip()
     if not vid:
         return {"error": "缺少必填参数 id"}
+    # 短路：清单里查得到这张表时，没卡的 id 立刻回，别去撞三基址 404。
+    want = _cap_card_ids()
+    if want is not None:
+        num = vid.split("-")[-1]
+        if not num.isdigit() or num not in want:
+            return {
+                "id": vid, "has_card": False,
+                "note": "该供应商暂无已发布能力卡（全库仅 %d 家有卡）。"
+                        "需要档案请先调 get_vendor。" % _card_count(),
+            }
     rel = f"skills/registry/capability/{vid}.json"
     txt = fetch_text(rel)
     if not txt:
@@ -2301,7 +2606,11 @@ TOOLS = [
     {
         "name": "search_vendors",
         "description": "检索灯塔工厂供应商名录。可按关键词(企业名/工艺/材料/认证)、城市、国标码(GB/T 4754)过滤。"
-                       "返回精简档案(id/企业名/城市/国标码/认证等级/工艺/材料/认证/是否含电话)。",
+                       "返回精简档案(id/企业名/城市/国标码/认证等级/工艺/材料/认证/是否含电话)。"
+                       "⚠ 关键词是**字面子串**匹配：用户的口语词/采购词若与名录写法不同（如「机加工」"
+                       "vs 归档用的「机械零部件加工」），命中会极少。此时不要直接报「没有」——"
+                       "看返回体里的 hint / suggested_gb，或先调 suggest_filters 拿到候选码，"
+                       "再用 gb=<码> 重试（召回通常多几十倍，且只扫对应分片更快）。",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -2331,6 +2640,8 @@ TOOLS = [
     {
         "name": "get_capability_card",
         "description": "按供应商 id 取能力卡（工艺位/设备/产能/认证/起订量等）。"
+                       "全库仅少数供应商有已发布能力卡，无卡的会秒回 has_card=false"
+                       "（不必重试）。"
                        "无已发布卡片时返回 has_card=false 及原因说明。",
         "inputSchema": {
             "type": "object",
@@ -2384,6 +2695,36 @@ TOOLS = [
             "required": ["session_id"],
         },
     },
+    {
+        "name": "suggest_filters",
+        "description": "把用户原话（口语/采购词）映射成候选国标小类码，供你改用 search_vendors(gb=…)。"
+                       "用户说的是「机加工」，名录里按「机械零部件加工」归档——别名表覆盖不了所有说法，"
+                       "所以本工具把「拆词 + 别名 + 类名」的候选和每类条数给你，由你做最终语义选择。"
+                       "search_vendors 命中偏少时也会内联 suggested_gb。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "用户原话，如 机加工 / 不锈钢板激光切割折弯（必填）"},
+                "city": {"type": "string", "description": "可选，用于拼出下一步调用参数"},
+                "limit": {"type": "integer", "default": 8, "description": "候选码条数上限(1-30)"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "list_industries",
+        "description": "列出国标小类货架（只列已有企业的类，附企业条数），供你在没有字面候选时"
+                       "按语义自己挑码。可传 keyword 模糊筛、parent 按门类字母/大类码缩小范围。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "keyword": {"type": "string", "description": "可选，类名/码的子串"},
+                "parent": {"type": "string", "description": "可选，门类字母(C)或大类两位码(35)"},
+                "limit": {"type": "integer", "default": 30, "description": "返回条数(1-200)"},
+                "offset": {"type": "integer", "default": 0},
+            },
+        },
+    },
 ]
 
 
@@ -2505,6 +2846,13 @@ def _dispatch_inner(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
             return get_vendor(args.get("id", ""), args.get("gb", ""))
         if name == "get_capability_card":
             return get_capability_card(args.get("id", ""))
+        if name == "suggest_filters":
+            return suggest_filters(args.get("query", ""), args.get("city", ""),
+                                   int(args.get("limit") or 8))
+        if name == "list_industries":
+            return list_industries(args.get("keyword", ""), args.get("parent", ""),
+                                   int(args.get("limit") or 30),
+                                   int(args.get("offset") or 0))
         if name == "start_sourcing":
             return start_sourcing(args.get("demand_text", ""), args.get("audience_id", "domestic_downstream"))
         if name == "answer_sourcing":