beacon-mfg-mcp 1.5.0 → 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,143 +1,259 @@
-# Beacon-MFG 只读 MCP 服务 · v1.5.0
-
-让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
-**检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
-**无需 clone 整个仓库、无需任何密钥**。
-
-## 设计边界
-MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流水线**不进 MCP、不暴露、不持密钥**，
-也不会落在任何写路径上。对 Android App 与 cron/GUI 流水线**零影响**（详见 `mcp/README.md`）。
-
-## 六个只读 tool
-| tool | 用途 | 关键参数 |
-|------|------|----------|
-| `search_vendors` | 按 关键词 / 城市 / 国标码 检索，返回精简档案 | `query` `city` `gb` `limit` `offset` |
-| `get_vendor` | 按 id（+国标码）取完整中文档案 | `id`（必填） `gb`（可选） |
-| `get_capability_card` | 按 id 取能力卡（工艺/设备/产能/认证） | `id`（必填） |
-| `start_sourcing` | 【客户 agent 自动触发】识别找厂/代工/采购意图 → 品类识别→宽召回→澄清，返回 `session_id` | `demand_text`（必填） `audience_id` |
-| `answer_sourcing` | 续接澄清轮次：写回客户答案，返回下一轮澄清或初选列表 | `session_id`（必填） `answers` |
-| `refine_sourcing` | 推荐轮次交互：`details`/`more`/`best` | `session_id`（必填） `action` `value` |
-
-后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
-依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
-
-## 本次更新（v1.5.0）
-**`get_vendor` 从 4.5 分钟降到 6 秒（45×）。** 起因是外部实测反馈「HTTP 模式比本地 git 模式慢约 100 倍，
-按 id 取一家企业要 270 秒」。定位结论：慢不在计算，而在**为了找一个 id 而下载整张 18.4 MB 的
-`name-index.jsonl`**——id 只是其中一行。
-
-- **idmap 定址分片**：新增 `skills/registry/index/idmap/`，`id → 国标码` 按 id 千位切片（183 片 × 1000 id，
-  命中那片约 20 KB）。片名由 id 直接算出（`CN-MFG-0093680` → `93680 // 1000` → `093.jsonl`），
-  **不需要目录表、不需要额外请求**。
-- **零 404 的开关设计**：idmap 的元信息放在 `manifest.metadata.idmap` 里——清单本来就要拉，所以是零额外请求。
-  清单里**没有**这个块 = 该快照尚未发布 idmap → 整体走老路径。这样「MCP 先升级、数据后发布」的窗口期
-  不会变成满屏 404（实测过：一次 404 的冷启动兜底要 44 秒）。
-- **按内容哈希缓存分片**：清单里每片都登记了内容 sha1，用它当缓存键——内容不变则**完全不走网络**，
-  取到后顺手校验，不符就不写缓存。
-- **zh 详情分片改并发取**；**HTTP 超时 15→30 s**；**显式声明 gzip 并手动解压**
-  （urllib 不会自动解压，JSON 压缩 6~20×，此前一直是裸传）。
-- **实测**（`scripts/bench_get_vendor.py`，缓存目录强制隔离）：
-
-  | 场景 | 冷启动 | 复用缓存 |
-  |------|--------|----------|
-  | 线上 CDN（本次前） | 270.6 s | — |
-  | 线上 CDN（本次后） | **5.95 s** | **1.22 s** |
-  | 本地快照 | 1.77 s | 0.80 s |
-
-- **恢复 `mcp/test_protocol.py`**：上一个提交误删了发布前必跑的协议回归测试，本次还原（313 行）。
-  发布前实测三条链路 **16/16 通过**（HTTP / stdio / 标准分帧适配层 + 死代理容错）。
-- 数据侧（`skills/registry/index/idmap/**` 与含 `metadata.idmap` 的 `data/manifest.json`）已同步发布到 Pages，
-  旧版 MCP 不受影响（读不到 idmap 块就走老路径）。
-
-## 本次更新（v1.4.2，已发布）
-- **自动升级（自更新）**：新增 `bin/selfupdate.js`，MCP 启动时以**独立 detached 子进程**拉起（绝不阻塞 MCP 启动），
-  节流查 npm registry `latest`（默认 24h 一次，可用 `BEACON_MCP_UPDATE_INTERVAL_H` 调），发现新版本即执行
-  `npm i -g beacon-mfg-mcp@<新版本>`（Windows 上正确走 `npm.cmd + shell`）。
-- **跳过条件**：设 `BEACON_MCP_NO_UPDATE=1`、或已设 `BEACON_SOURCE` / `BEACON_REPO`（离线 / 本地仓库用户）时**不联网升级**，避免对本地仓库用户添乱。
-- **并发保护**：原子目录锁 + 残留锁 10 分钟过期自愈（踩过死锁坑——残留锁会让之后所有启动永久跳过自更新）。
-- **测试**：`test_update.js` 单元测试 23/23 通过，并以 fake-npm 拦截验证安装命令形态正确（`npm.cmd i -g beacon-mfg-mcp@1.4.2`）。
-- **前向生效说明**：自更新是「向前生效」的——已装的 ≤1.4.1 旧版代码里没有 `selfupdate.js`，需**一次性手动** `npm i -g beacon-mfg-mcp@latest` 进入自动升级基线；之后永久自动。`npx beacon-mfg-mcp` 用户天然永远最新。
-
-## 本次更新（v1.4.1，已发布）
-- **直连优先 + 死代理容错**：修复「失效代理导致检索归零」——默认源不可达时直连兜底镜像，且报错信息直指真因（是代理挂了而非数据问题），`npm i -g` 装一次即享受（无需重启客户端）。
-
-## 本次更新（v1.4.0，已发布）
-- **标准分帧适配层 `mcp_adapter.py`**：补齐「严格分帧」客户端接入路径，与「换行 stdio」「Streamable HTTP」三条传输链路统一。
-- **协议回归测试 `test_protocol.py`**：一条命令覆盖三条链路（握手 + 6 工具齐全 + 三城市真实检索 `via_index`），发版前必跑。
-
-## 本次更新（v1.3.3，已发布）
-- **本地检索免提交、免重启即时可见**：这是 v1.3.1「worktree 兜底」的收尾。v1.3.1 只让**单文件读**走了工作树，
-  但关键词/城市检索的**召回**走的是**批量读** `_read_many_text()`——它在 git 模式下恒走 `git archive HEAD`
-  （已提交快照），于是**改完数据、重建索引后，关键词检索仍读旧索引、必须 commit 才可见**。
-  本次把批量读也改为「**工作树优先 → `git archive HEAD` 兜底 → HTTP**」。
-- **进程内 + 磁盘缓存按文件新鲜度失效**：新增 `_wt_mtime` / `_cache_stale`，各 loader
-  （manifest / 别名 / 国标名表 / cap 索引 / city / 索引桶 / fp 分片 / 能力词）改为
-  **按工作树文件 mtime 判新**——派生层一重建，MCP 立刻重读，**无需重启进程**；
-  磁盘索引缓存（`idx-*`）加 **mtime 印记**（`repr` 精确往返），同秒重写也能识别。
-- **可选 TTL**：`BEACON_CACHE_TTL`（秒，默认 `0`=关闭）可让进程内缓存周期性刷新；
-  非工作树模式（`BEACON_WORKTREE=0`）保持旧的「提交后 / 重启后生效」行为不变。
-- 已用**真实注入实验**验证：单进程、不 commit、只 sleep，`data/gb` 新记录经本地重建后
-  关键词检索由 `0` 命中变 `1` 命中。
-
-## 本次更新（v1.3.2，已发布）
-- **npm 启动器锁定 UTF-8**：`bin/beacon-mfg-mcp.js` 拉起 python 时注入 `PYTHONUTF8=1` / `PYTHONIOENCODING=utf-8`，
-  修复中文 Windows 上 python 按 GBK 写 stdout、被客户端按 UTF-8 解码导致的工具描述/结果乱码。
-- **HTTP 兜底镜像**：默认源 `beacon-mfg.pages.dev` 不可达时，自动回退到 GitHub 镜像
-  `cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main` 与 `raw.githubusercontent.com/eiry16/beacon-mfg/main`
-  （与 Android App 同策略），保证「免 clone 检索」在单一 CDN 失效时仍可工作；可用 `BEACON_MIRRORS` 追加。
-- **serverInfo 版本对齐**：服务端自报版本改为读 `package.json`，不再硬编码，消除与 npm 包版本漂移。
-
-## 本次更新（v1.3.1，已发布）
-- **npm 包自带 rfq-kernel**：`prepack` 会把 `skills/rfq-kernel` 打进包内，因此 `npm i -g beacon-mfg-mcp`
-  安装后 6 个 tool 全部可用（早于此版本的 npm 包不含该桥接，3 个寻源 tool 会降级）。
-  GitHub Release tarball 同步包含 `rfq-kernel/`。
-- **闭合检索缺口**：本地 git 模式默认 `BEACON_WORKTREE=1`，优先读工作树文件（含未提交/刚修改的数据），
-  仅在文件缺失或单对象 JSON 解析失败（半成品）时退回 `git show HEAD`，再否则走 HTTP。
-  设 `BEACON_WORKTREE=0` 可恢复「只读已提交快照」的严格行为。
-
-## 安装（三选一）
-
-### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.0.tar.gz`，解压后：
-```jsonc
-{
-  "mcpServers": {
-    "beacon-mfg": {
-      "command": "python",
-      "args": ["/解压目录/server.py"],
-      "env": { "BEACON_REPO": "/你的/beacon-mfg仓库路径" }   // 可选：离线 + 隐私安全
-    }
-  }
-}
-```
-
-### 2. npm（需先 `npm login`，仓库已配 `NPM_TOKEN` 后自动发布）
-```bash
-npm install -g beacon-mfg-mcp
-# 或一次性运行：
-npx beacon-mfg-mcp
-```
-装好后客户端配置：
-```jsonc
-{
-  "mcpServers": {
-    "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [], "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" } }
-  }
-}
-```
-
-### 3. 从源码（git clone）
-```bash
-git clone https://github.com/eiry16/beacon-mfg.git
-# 客户端 command 指向 beacon-mfg/mcp/server.py
-```
-
-## 环境变量
-- `BEACON_REPO`：本地 git 仓库路径；设了就用 `git show HEAD:` + 工作树 读（推荐：离线 + 掩码态隐私安全）。
-- `BEACON_SOURCE`：HTTP 基址，默认 `https://beacon-mfg.pages.dev`（可改自定义域名）。
-- `BEACON_WORKTREE`：本地模式是否优先读工作树（默认 `1`；设 `0` 恢复「只读已提交快照」）。
-- `BEACON_MIRRORS`：HTTP 模式追加的兜底镜像基址（逗号分隔）；默认源不可达时除内置的 jsDelivr/raw 外，可在此追加自有镜像。
-- `HTTPS_PROXY` / `HTTP_PROXY`：python 子进程的代理；在中国大陆等直连 GitHub 困难的网络，设 `HTTPS_PROXY=http://127.0.0.1:7890` 可让镜像链路走代理。
-
-## 许可
-MIT
+# Beacon-MFG 只读 MCP 服务 · v1.5.3
+
+让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
+**检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
+**无需 clone 整个仓库、无需任何密钥**。
+
+## 设计边界
+MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流水线**不进 MCP、不暴露、不持密钥**，
+也不会落在任何写路径上。对 Android App 与 cron/GUI 流水线**零影响**（详见 `mcp/README.md`）。
+
+## 八个只读 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` |
+
+后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
+依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
+
+## 本次更新（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 ⇒ 判「不存在」（这样才能省掉
+18.4 MB 的 name-index 兜底）。但**抓取流水线与政府信源导入每天都在发新号**，
+而 idmap 只在 manifest 步重算、只在 pages 步上云 —— 于是「刚导入、还没发布」的新 id
+天然不在已发布快照里，会被这条判定**静默误杀**（政府名录一次能进上千家，症状是查不到、不报错）。
+
+- `idmap/meta.json` 与 `manifest.metadata.idmap` 新增 **`max_id`**（已发布的最大 id 数字）。
+  客户端据此区分：`id <= max_id` 且片里没有 ⇒ 真不存在（照样省掉兜底）；
+  `id > max_id` ⇒ 尚未发布的新号，老老实实走兜底。**正确性优先于那点延迟。**
+- 两个守卫的**顺序不能反**：`max_id` 比 `buckets` 精确（后者只到千位）。
+  实测踩过：buckets=183 / max_id=182302 时，id=0187302 的 bucket=187 已越界，
+  但它只是「比最大号大 5000」的新号 —— 先走 buckets 守卫就被误杀了。
+- 生成器侧加了**条数对账**（`n_rec + other != len(rows)` 直接抛错）——
+  少一条就是一个 id 永远查不到，这种丢失是静默的，必须在生成时拦住。
+- 顺带加了 idmap 残留片清理（dedup 真删实体 id 时，旧的高位片会被 manifest 哈希并上传，
+  白占流量与仓库体积）。
+
+## 本次更新（v1.5.0，已发布）
+**`get_vendor` 从 4.5 分钟降到 6 秒（45×）。** 起因是外部实测反馈「HTTP 模式比本地 git 模式慢约 100 倍，
+按 id 取一家企业要 270 秒」。定位结论：慢不在计算，而在**为了找一个 id 而下载整张 18.4 MB 的
+`name-index.jsonl`**——id 只是其中一行。
+
+- **idmap 定址分片**：新增 `skills/registry/index/idmap/`，`id → 国标码` 按 id 千位切片（183 片 × 1000 id，
+  命中那片约 20 KB）。片名由 id 直接算出（`CN-MFG-0093680` → `93680 // 1000` → `093.jsonl`），
+  **不需要目录表、不需要额外请求**。
+- **零 404 的开关设计**：idmap 的元信息放在 `manifest.metadata.idmap` 里——清单本来就要拉，所以是零额外请求。
+  清单里**没有**这个块 = 该快照尚未发布 idmap → 整体走老路径。这样「MCP 先升级、数据后发布」的窗口期
+  不会变成满屏 404（实测过：一次 404 的冷启动兜底要 44 秒）。
+- **按内容哈希缓存分片**：清单里每片都登记了内容 sha1，用它当缓存键——内容不变则**完全不走网络**，
+  取到后顺手校验，不符就不写缓存。
+- **zh 详情分片改并发取**；**HTTP 超时 15→30 s**；**显式声明 gzip 并手动解压**
+  （urllib 不会自动解压，JSON 压缩 6~20×，此前一直是裸传）。
+- **实测**（`scripts/bench_get_vendor.py`，缓存目录强制隔离）：
+
+  | 场景 | 冷启动 | 复用缓存 |
+  |------|--------|----------|
+  | 线上 CDN（本次前） | 270.6 s | — |
+  | 线上 CDN（本次后） | **5.95 s** | **1.22 s** |
+  | 本地快照 | 1.77 s | 0.80 s |
+
+- **恢复 `mcp/test_protocol.py`**：上一个提交误删了发布前必跑的协议回归测试，本次还原（313 行）。
+  发布前实测三条链路 **16/16 通过**（HTTP / stdio / 标准分帧适配层 + 死代理容错）。
+- 数据侧（`skills/registry/index/idmap/**` 与含 `metadata.idmap` 的 `data/manifest.json`）已同步发布到 Pages，
+  旧版 MCP 不受影响（读不到 idmap 块就走老路径）。
+
+## 本次更新（v1.4.2，已发布）
+- **自动升级（自更新）**：新增 `bin/selfupdate.js`，MCP 启动时以**独立 detached 子进程**拉起（绝不阻塞 MCP 启动），
+  节流查 npm registry `latest`（默认 24h 一次，可用 `BEACON_MCP_UPDATE_INTERVAL_H` 调），发现新版本即执行
+  `npm i -g beacon-mfg-mcp@<新版本>`（Windows 上正确走 `npm.cmd + shell`）。
+- **跳过条件**：设 `BEACON_MCP_NO_UPDATE=1`、或已设 `BEACON_SOURCE` / `BEACON_REPO`（离线 / 本地仓库用户）时**不联网升级**，避免对本地仓库用户添乱。
+- **并发保护**：原子目录锁 + 残留锁 10 分钟过期自愈（踩过死锁坑——残留锁会让之后所有启动永久跳过自更新）。
+- **测试**：`test_update.js` 单元测试 23/23 通过，并以 fake-npm 拦截验证安装命令形态正确（`npm.cmd i -g beacon-mfg-mcp@1.4.2`）。
+- **前向生效说明**：自更新是「向前生效」的——已装的 ≤1.4.1 旧版代码里没有 `selfupdate.js`，需**一次性手动** `npm i -g beacon-mfg-mcp@latest` 进入自动升级基线；之后永久自动。`npx beacon-mfg-mcp` 用户天然永远最新。
+
+## 本次更新（v1.4.1，已发布）
+- **直连优先 + 死代理容错**：修复「失效代理导致检索归零」——默认源不可达时直连兜底镜像，且报错信息直指真因（是代理挂了而非数据问题），`npm i -g` 装一次即享受（无需重启客户端）。
+
+## 本次更新（v1.4.0，已发布）
+- **标准分帧适配层 `mcp_adapter.py`**：补齐「严格分帧」客户端接入路径，与「换行 stdio」「Streamable HTTP」三条传输链路统一。
+- **协议回归测试 `test_protocol.py`**：一条命令覆盖三条链路（握手 + 6 工具齐全 + 三城市真实检索 `via_index`），发版前必跑。
+
+## 本次更新（v1.3.3，已发布）
+- **本地检索免提交、免重启即时可见**：这是 v1.3.1「worktree 兜底」的收尾。v1.3.1 只让**单文件读**走了工作树，
+  但关键词/城市检索的**召回**走的是**批量读** `_read_many_text()`——它在 git 模式下恒走 `git archive HEAD`
+  （已提交快照），于是**改完数据、重建索引后，关键词检索仍读旧索引、必须 commit 才可见**。
+  本次把批量读也改为「**工作树优先 → `git archive HEAD` 兜底 → HTTP**」。
+- **进程内 + 磁盘缓存按文件新鲜度失效**：新增 `_wt_mtime` / `_cache_stale`，各 loader
+  （manifest / 别名 / 国标名表 / cap 索引 / city / 索引桶 / fp 分片 / 能力词）改为
+  **按工作树文件 mtime 判新**——派生层一重建，MCP 立刻重读，**无需重启进程**；
+  磁盘索引缓存（`idx-*`）加 **mtime 印记**（`repr` 精确往返），同秒重写也能识别。
+- **可选 TTL**：`BEACON_CACHE_TTL`（秒，默认 `0`=关闭）可让进程内缓存周期性刷新；
+  非工作树模式（`BEACON_WORKTREE=0`）保持旧的「提交后 / 重启后生效」行为不变。
+- 已用**真实注入实验**验证：单进程、不 commit、只 sleep，`data/gb` 新记录经本地重建后
+  关键词检索由 `0` 命中变 `1` 命中。
+
+## 本次更新（v1.3.2，已发布）
+- **npm 启动器锁定 UTF-8**：`bin/beacon-mfg-mcp.js` 拉起 python 时注入 `PYTHONUTF8=1` / `PYTHONIOENCODING=utf-8`，
+  修复中文 Windows 上 python 按 GBK 写 stdout、被客户端按 UTF-8 解码导致的工具描述/结果乱码。
+- **HTTP 兜底镜像**：默认源 `beacon-mfg.pages.dev` 不可达时，自动回退到 GitHub 镜像
+  `cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main` 与 `raw.githubusercontent.com/eiry16/beacon-mfg/main`
+  （与 Android App 同策略），保证「免 clone 检索」在单一 CDN 失效时仍可工作；可用 `BEACON_MIRRORS` 追加。
+- **serverInfo 版本对齐**：服务端自报版本改为读 `package.json`，不再硬编码，消除与 npm 包版本漂移。
+
+## 本次更新（v1.3.1，已发布）
+- **npm 包自带 rfq-kernel**：`prepack` 会把 `skills/rfq-kernel` 打进包内，因此 `npm i -g beacon-mfg-mcp`
+  安装后 6 个 tool 全部可用（早于此版本的 npm 包不含该桥接，3 个寻源 tool 会降级）。
+  GitHub Release tarball 同步包含 `rfq-kernel/`。
+- **闭合检索缺口**：本地 git 模式默认 `BEACON_WORKTREE=1`，优先读工作树文件（含未提交/刚修改的数据），
+  仅在文件缺失或单对象 JSON 解析失败（半成品）时退回 `git show HEAD`，再否则走 HTTP。
+  设 `BEACON_WORKTREE=0` 可恢复「只读已提交快照」的严格行为。
+
+## 安装（三选一）
+
+### 1. 从 GitHub Release 下载（推荐，零依赖）
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.3.tar.gz`，解压后：
+```jsonc
+{
+  "mcpServers": {
+    "beacon-mfg": {
+      "command": "python",
+      "args": ["/解压目录/server.py"],
+      "env": { "BEACON_REPO": "/你的/beacon-mfg仓库路径" }   // 可选：离线 + 隐私安全
+    }
+  }
+}
+```
+
+### 2. npm（需先 `npm login`，仓库已配 `NPM_TOKEN` 后自动发布）
+```bash
+npm install -g beacon-mfg-mcp
+# 或一次性运行：
+npx beacon-mfg-mcp
+```
+装好后客户端配置：
+```jsonc
+{
+  "mcpServers": {
+    "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [], "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" } }
+  }
+}
+```
+
+### 3. 从源码（git clone）
+```bash
+git clone https://github.com/eiry16/beacon-mfg.git
+# 客户端 command 指向 beacon-mfg/mcp/server.py
+```
+
+## 环境变量
+- `BEACON_REPO`：本地 git 仓库路径；设了就用 `git show HEAD:` + 工作树 读（推荐：离线 + 掩码态隐私安全）。
+- `BEACON_SOURCE`：HTTP 基址，默认 `https://beacon-mfg.pages.dev`（可改自定义域名）。
+- `BEACON_WORKTREE`：本地模式是否优先读工作树（默认 `1`；设 `0` 恢复「只读已提交快照」）。
+- `BEACON_MIRRORS`：HTTP 模式追加的兜底镜像基址（逗号分隔）；默认源不可达时除内置的 jsDelivr/raw 外，可在此追加自有镜像。
+- `HTTPS_PROXY` / `HTTP_PROXY`：python 子进程的代理；在中国大陆等直连 GitHub 困难的网络，设 `HTTPS_PROXY=http://127.0.0.1:7890` 可让镜像链路走代理。
+
+## 许可
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.5.0",
+  "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.0")
+            return json.load(f).get("version", "1.5.3")
     except Exception:
-        return "1.5.0"
+        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 是跨门类能力、
@@ -1137,13 +1401,35 @@ def _idmap_lookup(vid: str) -> Tuple[Optional[str], bool]:
     客户端必须照样按空串走 _unclassified 那条路，而不是当成「没找到」）。
     shard_ok = 该片的**范围已被覆盖** → 此时 id 缺席可判定为「不存在」，
     调用方不必再去付 18.4 MB / 320 个分片的兜底代价。
+
+    ⚠ 「片里没有」要**先过 max_id 这道闸**才能判不存在。抓取流水线与政府信源
+    导入每天都在发新号，而 idmap 只在 manifest 步重算、只在 pages 步上云 ——
+    于是「刚导入、还没发布」的新 id 天然不在已发布的 idmap 里。
+    若只看「片存在但片里没这条」就判不存在，等于**把新导入的企业全部误杀**
+    （政府名录一次能进上千家，症状还是静默的：查不到，不报错）。
+    判据：id 数字 <= meta.max_id 才敢判「真不存在」；超过就退回慢路径兜底。
     """
     meta = _idmap_meta()
     nb = meta.get("buckets")
     if not isinstance(nb, int) or nb <= 0:
         return None, False          # 快照里没有 idmap（尚未发布）→ 调用方按老路径走
 
-    # 范围守卫：超出范围 = 这条 id 不在已发布快照里，直接判定，
+    # 已发布的最大 id 数字。老版本快照没有这个字段 → 退化成「只能靠 buckets 守卫」，
+    # 此时新 id 会被误判，所以**取不到就整体不走 idmap**（宁可慢，不可错）。
+    mx = meta.get("max_id")
+    if not isinstance(mx, int) or mx < 0:
+        return None, False
+
+    # ⚠ 两个守卫的**顺序不能反**。
+    #   max_id 是比 buckets 更精确的上界（buckets 只精确到千位）：
+    #   例如 buckets=183 / max_id=182302 时，id=0187302 的 bucket=187 已越界，
+    #   但它其实只是「比已发布最大号大 5000」的新号 —— 若先走 buckets 守卫就会
+    #   被判成不存在（误杀）。所以先用 max_id 收口，再谈 buckets。
+    m_vid = _VENDOR_ID_RE.match(vid or "")
+    if m_vid is not None and int(m_vid.group(1)) > mx:
+        return None, False      # 尚未发布的新号 → 交回调用方走兜底
+
+    # 范围守卫：连千位片都还没生成 = 远在未来的号，直接判定，
     # 不去请求那个必定 404 的分片。
     b = _idmap_bucket(vid)
     if b is not None and b >= nb:
@@ -1614,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
@@ -1964,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(总量)，慢但结果等价）。
@@ -1978,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()
@@ -2080,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:
@@ -2191,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:
@@ -2279,7 +2606,11 @@ TOOLS = [
     {
         "name": "search_vendors",
         "description": "检索灯塔工厂供应商名录。可按关键词(企业名/工艺/材料/认证)、城市、国标码(GB/T 4754)过滤。"
-                       "返回精简档案(id/企业名/城市/国标码/认证等级/工艺/材料/认证/是否含电话)。",
+                       "返回精简档案(id/企业名/城市/国标码/认证等级/工艺/材料/认证/是否含电话)。"
+                       "⚠ 关键词是**字面子串**匹配：用户的口语词/采购词若与名录写法不同（如「机加工」"
+                       "vs 归档用的「机械零部件加工」），命中会极少。此时不要直接报「没有」——"
+                       "看返回体里的 hint / suggested_gb，或先调 suggest_filters 拿到候选码，"
+                       "再用 gb=<码> 重试（召回通常多几十倍，且只扫对应分片更快）。",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -2309,6 +2640,8 @@ TOOLS = [
     {
         "name": "get_capability_card",
         "description": "按供应商 id 取能力卡（工艺位/设备/产能/认证/起订量等）。"
+                       "全库仅少数供应商有已发布能力卡，无卡的会秒回 has_card=false"
+                       "（不必重试）。"
                        "无已发布卡片时返回 has_card=false 及原因说明。",
         "inputSchema": {
             "type": "object",
@@ -2362,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},
+            },
+        },
+    },
 ]
 
 
@@ -2483,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":