beacon-mfg-mcp 1.5.3 → 1.5.4

package/RELEASE.md

@@ -1,4 +1,4 @@
-# Beacon-MFG 只读 MCP 服务 · v1.5.3
+# Beacon-MFG 只读 MCP 服务 · v1.5.4
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
 **检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
@@ -23,7 +23,74 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
 依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
 
-## 本次更新（v1.5.3）
+## 本次更新（v1.5.4）
+**把「宿主根本连不上」和「连上了但结果会误导 agent」这两类问题一次收干净。
+无破坏性变更：八个 tool 的入参、三种接入方式、返回体既有字段全部不变（只增不减）。**
+
+### 1. stdio 适配层：宿主是**换行分帧**，旧 adapter 只认 `Content-Length`
+
+症状：MCP 在宿主里**永远起不来** —— 探测日志连续 249 次 `initialize/tools/list timed out`，
+工具列表里从头到尾没有 beacon-mfg。而手工喂同样三行 JSON 却是好的。
+
+根因（三层，缺一层都还是坏的）：
+
+| 层 | 问题 | 修法 |
+|---|---|---|
+| 1 | `_read_msg()` 只认 LSP 的 `Content-Length` 分帧；宿主发的是**换行分隔 JSON** → 首条即当垃圾丢弃，回包 0 字节 | 按首条报文自动判分帧；单条坏报文不再当 EOF 结束会话 |
+| 2 | 拉起子进程时没注入 `PYTHONUTF8` → 中文 Windows 的 cp936 使 `tools/list` 里那条带 `⚠` 的工具描述抛 `UnicodeEncodeError`，**进程直接崩** | adapter 注入 `PYTHONUTF8=1`/`PYTHONIOENCODING=utf-8`；`server.py` 另加 stdout/stderr reconfigure 兜底 |
+| 3 | 严格「请求↔响应」配对：宿主若发来**带 id 的通知**（server 按协议不回），配对挂住 → 死锁 | 改成**纯双向透传桥**，不解析、不配对，只转字节 |
+
+外加收尾 drain：stdin 到 EOF 后先关子进程 stdin、等回包吐完再 terminate，否则最后几帧响应会被连坐丢掉。
+
+修复后宿主探测一次到位：`state=ready`，`tools/list` 5578 字节，**579 ms**。
+
+### 2. `suggest_filters` 补 `cap_candidates`：能力域命中不再被当成「无候选」
+
+「找苏州做 AI 的企业」这类需求，国标小类里**本来就没有**对应的类，
+但名录里有跨门类的**能力域**（如 `tech_ai` 人工智能与算法）。旧版只给
+`candidates: []` + 一句「去 `list_industries` 自己挑」，agent 等于被推去空手翻货架。
+
+现在单独给一个字段（和 `candidates` 分开，避免 agent 拿能力键去当 `gb=` 用）：
+
+```json
+"cap_candidates": [{"cap": "tech_ai", "name": "人工智能与算法", "word": "人工智能", "records": 1}],
+"cap_note": "这些是**能力域**（跨门类的工艺/技术标签），不是国标码，别拿去当 gb= 用。……",
+"next_call": {"tool": "search_vendors", "arguments": {"query": "人工智能", "city": "苏州", "limit": 20}}
+```
+
+### 3. `via` 标签如实化：新增 `cap_text` / `city`
+
+`_hay`（检索面）把**厂名/工艺**和**能力键的中文词面**混在一起 ——
+于是「query 词出现在 `_hay` 里」分不清是「厂名真写了这个词」还是「只是撞上了能力词面」。
+实测：问「苏州做人工智能的企业」，赤兔智能（能力键 `tech_ai`，厂名/工艺里**一个「人工智能」都没有**）
+被判成 `via=text`，agent 会误读成「这家厂自己写了 AI」。
+
+现在按**字面检索面**（`_hay_lit`，不含 cap 词面）判定：
+`text`（真的字面命中）/ `cap_text`（只是撞上能力词面）/ `alias` / `cap` / `city`（纯城市筛选）。
+结果按 `text → cap_text → alias → cap` 稳定分档排序，并附 `order_note` 写明
+**`score` 是能力画像分（有已发布能力卡才有分、无卡为 0），不是相关度** ——
+防止「一家餐厅 sc=0 排在持卡 L2 企业 sc=40 前面」这类误判。
+
+### 4. `get_vendor`：按分片归属回填 `gb`，消除自相矛盾
+
+zh 记录自身常常**不写 `gb`**（只留 `industry`），但它就归档在那个 gb 分片里。
+结果同一家企业：`search_vendors(gb=6531)` 报 `gb:"6531"`，`get_vendor` 却报
+`gb:null` + `gb_unclassified:true`。现在按分片归属回填并标 `gb_source:"shard"`。
+
+### 5. 命中 1~4 条时也补 `hint`
+
+`total_matched` 落在 1~4 时旧版**不给任何提示**（只覆盖了 0 条和有候选两种情况），
+agent 容易把「数据薄」读成「没有这家厂」。
+
+### 验收（发版前实测）
+
+- 协议回归 `mcp/test_protocol.py --stdio --adapter`：**16/16 通过**（HTTP / 换行 stdio / 标准分帧三链路 × 握手 + 8 工具 + 三城市检索）。
+- 语义路由验收 `scripts/check_semantic_routing.py`：**14/14 通过**。
+- 检索哨兵「机加工@嘉兴」：**643 条**（修复前 1 条）；城市正确性 10/10；关键词 0 条无关。
+- 体感：冷启动首查 4.55 s、同进程热查 0.77 s、`get_capability_card` 0.01 s；
+  「找到一个嘉兴机加工厂并拿到联系方式」全程 **6.48 s**。
+
+## 本次更新（v1.5.3），已发布
 **用户说的话和名录里的写法对不上时，不再只回 1 条 —— 加了一层「语义路由」；
 顺带把 `get_capability_card` 从 42~65 秒压到 2 毫秒。**
 
@@ -214,7 +281,7 @@ v1.5.0 的 idmap 有个致命假设：片存在但片里没这条 id ⇒ 判「
 ## 安装（三选一）
 
 ### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.3.tar.gz`，解压后：
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.4.tar.gz`，解压后：
 ```jsonc
 {
   "mcpServers": {

package/mcp_adapter.py

@@ -3,93 +3,211 @@
 """
 BeaconMFG MCP —— 标准协议适配层（adapter / shim）。
 
-为什么需要它：
-  beacon-mfg 的 mcp/server.py 用「换行分隔 JSON-RPC 子集」做传输
-  （`for raw in sys.stdin` + `json + "\n"`），并不是标准 MCP 的
-  `Content-Length` 分帧。标准 MCP 客户端（WorkBuddy 连接器、Claude Desktop
-  等）按 LSP 分帧跟它握手会解析失败。
-
-本适配层做什么：
-  - 对外（父进程 = MCP host）：讲标准 MCP stdio（Content-Length 分帧）。
-  - 对内（子进程 = server.py）：把请求转成换行分隔 JSON 转发，并把 server.py
-    的换行回包重新分帧后返回。
-  - 不修改 server.py 任何代码；server.py 的「通知无回包」语义天然保留
-    （转发通知后不等待回包）。
+【为什么存在】
+  mcp/server.py 用**换行分隔 JSON-RPC**（`for raw in sys.stdin` + `json + "\n"`），
+  这正是 **MCP stdio 规范**的分帧方式。但有一类宿主用 LSP 式的
+  `Content-Length: N\\r\\n\\r\\n{...}` 分帧。本适配层让同一个 server 同时吃两种帧。
+
+【2026-10-06 两处致命缺陷（实测代价：WorkBuddy 里 249 轮探测全部超时，0 个工具）】
+
+  ① **只认 Content-Length**。旧版断言「标准 MCP 客户端用 Content-Length 分帧」，
+     于是收到换行的 `{...}\\n` 时不认为一条消息结束，一直阻塞等一个永远不来的空行；
+     宿主 15s 判 `initialize timed out`，杀进程重试。实测两端分歧：
+       printf '{...}\\n'  | python server.py       → 正常回包  ✅
+       printf '{...}\\n'  | python mcp_adapter.py  → stdout 0 字节、静默退出 ❌
+       Content-Length 分帧 | 两者都正常                       ✅
+
+  ② **「一请求等一响应」的严格配对会死锁**。旧版每转发一个带 id 的请求，就阻塞等子进程
+     回一条；而 server.py 里 `notifications/initialized` 是**不回包**的。宿主只要把这条
+     通知带上 id 发出来（部分宿主确实这么干），adapter 就永久卡在等待上，
+     之后所有请求（含 tools/list）都拿不到响应 → 宿主报 `tools/list timed out`。
+     现象与 ① 极像（都是超时），但根因完全不同，只修 ① 会停在 tools/list 上原地打转。
+
+【现在的设计：纯分帧桥】
+  不再做请求/响应的配对，**双向直通**：
+    主线程   客户端 → 子进程（自动识别帧，统一转成换行分隔）
+    读线程   子进程 → 客户端（按客户端用的那一种帧回写，逐条即时转发）
+  唯一的状态是「客户端请求的 protocolVersion」——server.py 回的是固定版本号，
+  严格客户端会因版本不一致卡住握手，所以回包时按 id 认领并改写。
+  这样无论宿主发通知带不带 id、发不发未知方法，都不可能死锁。
 
 用法：
   python mcp_adapter.py
 环境变量（可选）：BEACON_REPO / BEACON_MASK_PHONE / BEACON_SOURCE
+诊断（可选）：BEACON_ADAPTER_TRACE=1 把收发实录写进 %TEMP%/beacon_adapter_trace.log
 """
 import json
 import os
 import sys
 import subprocess
+import tempfile
 import threading
-import queue
+import time
 
 _HERE = os.path.dirname(os.path.abspath(__file__))
 REPO = os.environ.get("BEACON_REPO") or os.path.dirname(_HERE)
 SERVER = os.path.join(_HERE, "server.py")
 MASK = os.environ.get("BEACON_MASK_PHONE", "1")
 
+# 输入缓冲（字节级，跨次 read 保留）
+_BUF = b""
+# 客户端用的帧格式：None=未知，'lsp'=Content-Length，'lines'=换行分隔
+_FRAMING = {"kind": None}
+# initialize 的 id 与客户端请求的协议版本（回包时按 id 认领并改写）
+_INIT = {"id": None, "proto": None}
+# 诊断开关：默认**关**（排查「宿主不吭声」时设 BEACON_ADAPTER_TRACE=1 打开，
+# 收发实录会写进 %TEMP%/beacon_adapter_trace.log）。2026-10-06 定位 tools/list 超时
+# 就是靠它一眼看出「子进程吐到一半就死了」。
+_TRACE_ON = os.environ.get("BEACON_ADAPTER_TRACE") == "1"
+
+
+def _trace(msg: str) -> None:
+    if not _TRACE_ON:
+        return
+    try:
+        p = os.path.join(tempfile.gettempdir(), "beacon_adapter_trace.log")
+        with open(p, "a", encoding="utf-8") as f:
+            f.write("%.3f %d %s\n" % (time.time(), os.getpid(), msg[:400]))
+    except Exception:
+        pass
 
-def _spawn_server():
-    return subprocess.Popen(
-        [sys.executable, "-u", SERVER],
-        stdin=subprocess.PIPE,
-        stdout=subprocess.PIPE,
-        env={**os.environ, "BEACON_REPO": REPO, "BEACON_MASK_PHONE": MASK},
-        bufsize=0, text=True, encoding="utf-8",
-    )
 
+# --------------------------------------------------------------------------- #
+# 读：客户端 → 我们（自动识别两种帧）
+# --------------------------------------------------------------------------- #
+def _read_some() -> bytes:
+    """非阻塞语义地取一块可用字节（单次 os.read，有多少拿多少）。EOF 返回 b''。"""
+    try:
+        return sys.stdin.buffer.raw.read(65536)
+    except Exception:
+        return b""
+
+
+def _read_line() -> bytes | None:
+    """读到 \\n 为止，返回不含换行的 bytes；EOF 且无残留返回 None。"""
+    global _BUF
+    while b"\n" not in _BUF:
+        chunk = _read_some()
+        if not chunk:
+            if _BUF:
+                line, _BUF = _BUF, b""
+                return line
+            return None
+        _BUF += chunk
+    line, _, _BUF = _BUF.partition(b"\n")
+    return line
 
-def _read_stdin_framed():
-    """从父进程(stdio)读取一条标准 MCP 分帧消息，返回 dict；EOF 返回 None。"""
-    buf = b""
+
+def _read_exact(n: int) -> bytes | None:
+    global _BUF
+    while len(_BUF) < n:
+        chunk = _read_some()
+        if not chunk:
+            return None
+        _BUF += chunk
+    body, _BUF = _BUF[:n], _BUF[n:]
+    return body
+
+
+def _read_msg() -> dict | None:
+    """读一条客户端消息，自动识别 Content-Length 分帧 / 换行分隔。真 EOF → None。
+
+    单条脏数据**不终止会话**（旧版把它当 EOF 直接退，宿主只会看到超时）。
+    """
     while True:
-        c = sys.stdin.buffer.read(1)
-        if not c:
+        line = _read_line()
+        while line is not None and not line.strip():
+            line = _read_line()          # 跳过空行
+        if line is None:
+            _trace("RECV eof")
             return None
-        buf += c
-        if buf.endswith(b"\r\n\r\n") or buf.endswith(b"\n\n"):
-            break
-    clen = None
-    for line in buf.split(b"\n"):
-        low = line.strip().lower()
-        if low.startswith(b"content-length:"):
+        head = line.strip()
+
+        if head.lower().startswith(b"content-length:"):
+            _FRAMING["kind"] = "lsp"
+            clen = None
             try:
-                clen = int(low.split(b":", 1)[1].strip())
+                clen = int(head.split(b":", 1)[1].strip())
             except ValueError:
                 pass
-    if clen is None:
-        return None
-    body = b""
-    while len(body) < clen:
-        chunk = sys.stdin.buffer.read(clen - len(body))
-        if not chunk:
-            return None
-        body += chunk
-    try:
-        return json.loads(body.decode("utf-8"))
-    except Exception:
-        return None
+            while True:                  # 吃掉剩余头直到空行
+                h = _read_line()
+                if h is None:
+                    _trace("RECV eof(header)")
+                    return None
+                hs = h.strip()
+                if not hs:
+                    break
+                if clen is None and hs.lower().startswith(b"content-length:"):
+                    try:
+                        clen = int(hs.split(b":", 1)[1].strip())
+                    except ValueError:
+                        pass
+            if clen is None:
+                _trace("DROP lsp 头里没有 Content-Length")
+                continue
+            body = _read_exact(clen)
+            if body is None:
+                _trace("RECV eof(body) 期待 %d 字节" % clen)
+                return None
+            try:
+                obj = json.loads(body.decode("utf-8"))
+            except Exception as e:
+                _trace("DROP lsp body 解析失败 %s raw=%r" % (e, body[:200]))
+                continue
+            _trace("RECV lsp method=%s id=%s" % (obj.get("method"), obj.get("id")))
+            return obj
+
+        # MCP stdio 规范：一条消息 = 一行 JSON（不带 Content-Length）
+        if _FRAMING["kind"] is None:
+            _FRAMING["kind"] = "lines"
+        try:
+            obj = json.loads(head.decode("utf-8"))
+        except Exception as e:
+            _trace("DROP lines 解析失败 %s raw=%r" % (e, head[:200]))
+            continue
+        _trace("RECV lines method=%s id=%s" % (obj.get("method"), obj.get("id")))
+        return obj
+
 
+# --------------------------------------------------------------------------- #
+# 写：我们 → 客户端（按客户端进来的那一种帧回写）
+# --------------------------------------------------------------------------- #
+def _write_msg(obj: dict) -> None:
+    """两种帧**不能混**，且 LSP 帧的 body 一个字节都不能少。
 
-def _write_stdout_framed(obj):
-    """向父进程(stdio)写一条标准 MCP 分帧消息。"""
+    只写 `Content-Length` 头、漏掉 body，客户端会一直等那 N 个字节，
+    表现同样是「timed out」——极难从现成日志里看出来，务必别手滑。
+    """
     data = json.dumps(obj, ensure_ascii=False).encode("utf-8")
-    sys.stdout.buffer.write(b"Content-Length: %d\r\n\r\n" % len(data))
-    sys.stdout.buffer.write(data)
+    if _FRAMING["kind"] == "lsp":
+        sys.stdout.buffer.write(b"Content-Length: %d\r\n\r\n" % len(data) + data)
+    else:
+        sys.stdout.buffer.write(data + b"\n")
     sys.stdout.buffer.flush()
+    _trace("SEND framing=%s id=%s bytes=%d" % (_FRAMING["kind"], obj.get("id"), len(data)))
+
+
+def _spawn_server():
+    return subprocess.Popen(
+        [sys.executable, "-u", SERVER],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        # ⚠ 必须显式注入 UTF-8（npm 启动器 bin/beacon-mfg-mcp.js 就是这么干的，本适配层
+        #   曾漏掉）：中文 Windows 上 python 默认按 cp936 写 stdout，而 tool 描述里含
+        #   `⚠`(U+26A0) 这类 GBK 编不出的字符 —— initialize 能过，`tools/list` 必崩，
+        #   宿主只看到「tools/list timed out」。2026-10-06 实测：WorkBuddy 249 轮探测全废。
+        env={**os.environ, "BEACON_REPO": REPO, "BEACON_MASK_PHONE": MASK,
+             "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"},
+        bufsize=0, text=True, encoding="utf-8",
+    )
 
 
 def main():
     child = _spawn_server()
-    responses: "queue.Queue" = queue.Queue()
-    client_protocol = None  # 客户端在 initialize 里请求的协议版本
 
-    def reader():
-        # 子进程用换行分隔 JSON；逐行读、入队。
+    def pump_down():
+        """子进程 → 客户端。逐条即时转发，不做任何配对判断。"""
         try:
             for line in child.stdout:
                 line = line.strip()
@@ -97,54 +215,49 @@ def main():
                     continue
                 try:
                     obj = json.loads(line)
-                except Exception:
+                except Exception as e:
+                    _trace("DROP child 输出解析失败 %s raw=%r" % (e, line[:200]))
                     continue
-                responses.put(obj)
-        except Exception:
-            pass
+                # 按 id 认领 initialize 回包，改写回客户端请求的协议版本
+                if (_INIT["proto"] and obj.get("id") is not None
+                        and obj.get("id") == _INIT["id"]
+                        and isinstance(obj.get("result"), dict)):
+                    obj["result"]["protocolVersion"] = _INIT["proto"]
+                _write_msg(obj)
+        except Exception as e:
+            _trace("child 读线程异常 %s" % e)
+        finally:
+            _trace("child stdout 关闭")
 
-    threading.Thread(target=reader, daemon=True).start()
+    pump = threading.Thread(target=pump_down, daemon=True)
+    pump.start()
 
     try:
         while True:
-            msg = _read_stdin_framed()
+            msg = _read_msg()
             if msg is None:
                 break
-            method = msg.get("method")
-            mid = msg.get("id")
-            is_notification = (mid is None) or (isinstance(method, str) and method.startswith("notifications/"))
-
-            if method == "initialize":
-                # 记下客户端请求版本，用于回包时回写（兼容严格客户端）
-                client_protocol = (msg.get("params") or {}).get("protocolVersion")
-
-            # 转发给子进程（换行分隔）
+            if msg.get("method") == "initialize":
+                _INIT["id"] = msg.get("id")
+                _INIT["proto"] = (msg.get("params") or {}).get("protocolVersion")
             child.stdin.write(json.dumps(msg, ensure_ascii=False) + "\n")
             child.stdin.flush()
-
-            if is_notification:
-                continue  # 通知无需回包，server.py 自身也是 continue
-
-            # 请求：等子进程回包（按到达顺序，server.py 严格顺序响应）
-            try:
-                resp = responses.get(timeout=60)
-            except queue.Empty:
-                if mid is not None:
-                    _write_stdout_framed({
-                        "jsonrpc": "2.0", "id": mid,
-                        "error": {"code": -32000, "message": "no response from server.py"},
-                    })
-                continue
-
-            # 兼容严格客户端：server.py 回的是固定 protocolVersion，
-            # 改写回客户端在 initialize 里请求的版本，避免握手因版本不一致卡住。
-            if method == "initialize" and client_protocol and isinstance(resp.get("result"), dict):
-                resp["result"]["protocolVersion"] = client_protocol
-
-            _write_stdout_framed(resp)
+    except Exception as e:
+        _trace("主循环异常 %s" % e)
     finally:
+        # ⚠ 别急着 terminate：客户端 stdin 一关就可能还有回包在子进程/管道里，
+        #   直接杀进程会把最后几条响应丢掉（宿主侧表现还是「超时」，白折腾）。
+        #   正确顺序：关子进程 stdin（它读完就自然退）→ 等读线程吐完 → 再收尾。
+        _trace("客户端 stdin 结束，等待子进程吐完剩余回包")
+        try:
+            child.stdin.close()
+        except Exception:
+            pass
+        pump.join(timeout=60)
+        _trace("读线程结束，收尾")
         try:
-            child.terminate()
+            if child.poll() is None:
+                child.terminate()
         except Exception:
             pass
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "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

@@ -43,6 +43,18 @@ import time
 import hmac
 import urllib.request
 import urllib.error
+
+# [utf8-guard] 中文 Windows 上，宿主若没注入 PYTHONUTF8/PYTHONIOENCODING，stdout 会落回
+# cp936；而 TOOLS 的 tool 描述里含 `⚠`(U+26A0) 这类 GBK 根本编不出的字符 ——
+# initialize 全是 ASCII 能过，一到 `tools/list` 就 UnicodeEncodeError **当场崩进程**。
+# 宿主侧只能看到「tools/list timed out」，日志里毫无线索。
+# 2026-10-06 实测：WorkBuddy 里连续 249 轮探测全部卡死于此。
+# 强制 UTF-8 + 出错降级替换：宁可显示成 '?'，也绝不因为一次打印而断开协议。
+for _s in (sys.stdout, sys.stderr):
+    try:
+        _s.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
 import socket
 from typing import Any, Dict, List, Optional, Tuple
 import sys as _sys
@@ -271,9 +283,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.3")
+            return json.load(f).get("version", "1.5.4")
     except Exception:
-        return "1.5.3"
+        return "1.5.4"
 
 
 # HTTP 基址列表（含兜底镜像）。默认部署 Cloudflare Pages 不可达时，自动回退到
@@ -1112,6 +1124,19 @@ def suggest_filters(query: str, city: str = "", limit: int = 8) -> Dict[str, Any
         x.pop("_score", None)
     out = out[:limit]
 
+    # 能力域候选（跨门类的工艺/技术标签，如 tech_ai=人工智能与算法）。
+    # **绝不能混进 candidates**：那串是国标码，agent 会照着拿去调 search_vendors(gb=…)；
+    # 把「tech_ai」塞进去就会被当成一个国标码用，必然 0 条。所以单独字段 + 单独说明。
+    # 2026-10-06 补：在此之前 suggest_filters 完全不看能力维，于是「人工智能」这种词
+    # 国标侧没类、能力侧不问 —— 两边都空，agent 只能拿到 candidates:[] 瞎猜。
+    cap_cands: List[Dict[str, Any]] = []
+    try:
+        for c in cap_alias_codes(q):
+            cap_cands.append({"cap": c["cap"], "name": c["name"], "word": c["word"],
+                              "records": _cap_count(c["cap"])})
+    except Exception:
+        cap_cands = []
+
     res: Dict[str, Any] = {
         "query": q,
         "city": city or "",
@@ -1120,10 +1145,24 @@ def suggest_filters(query: str, city: str = "", limit: int = 8) -> Dict[str, Any
                       "（给了 gb 只扫对应分片，最快）；多个码的结果自行合并去重。"
                       "候选为空或都不对味时，调 list_industries 看货架自己挑。",
     }
+    if cap_cands:
+        res["cap_candidates"] = cap_cands
+        res["cap_note"] = ("这些是**能力域**（跨门类的工艺/技术标签），不是国标码，"
+                           "别拿去当 gb= 用。search_vendors(query=…) 已自动按它们展开并计数；"
+                           "这里的用处是告诉你「该能力在名录里有多厚」——records 很小就是很薄。")
     if out:
         res["next_call"] = {"tool": "search_vendors",
                             "arguments": {"gb": out[0]["code"], "city": city or "",
                                           "limit": 20}}
+    elif cap_cands:
+        # 国标侧没候选、但能力域命中了 —— 别让 agent 空着手去翻货架
+        res["next_call"] = {"tool": "search_vendors",
+                            "arguments": {"query": q, "city": city or "", "limit": 20}}
+        res["note"] = ("国标小类里没有这个词（GB/T 4754 本来就不保证有「%s」这一类），"
+                       "但它命中能力域 %s。直接调 search_vendors(query=\"%s\") 即可，"
+                       "能力域会被自动展开；结果偏少属正常 —— 那是数据厚度问题，"
+                       "不是查询写法问题。"
+                       % (q, "、".join(c["name"] for c in cap_cands), q))
     else:
         res["next_call"] = {"tool": "list_industries",
                             "arguments": {"keyword": q, "limit": 30}}
@@ -1157,6 +1196,28 @@ def _attach_routing_hint(out: Dict[str, Any], q: str, city: str) -> Dict[str, An
         out["suggested_gb"] = [{"code": c["code"], "name": c["name"],
                                 "records": c["records"], "why": c["why"]}
                                for c in cands]
+        return out
+    # 命中 1~4 条、别名与类名一条候选都推不出来 —— 最糟的一档，也是最容易被漏掉的一档：
+    # 既有几条噪音（agent 会以为「就这些」直接交付），又没有任何可执行的下一步。
+    # 2026-10-06 实测：查「苏州做AI的企业」只回 2 条（其中一条是名字里带「人工智能」的
+    # 餐厅），hint 全程不出现 —— 因为旧逻辑只有「0 条且无候选」和「有候选」两个分支，
+    # 1~4 条无候选直接掉进空档 return。必须补上。
+    try:
+        caps = cap_alias_codes(q)
+    except Exception:
+        caps = []
+    if caps:
+        out["cap_expanded"] = [{"cap": c["cap"], "name": c["name"], "word": c["word"],
+                                "records": _cap_count(c["cap"])} for c in caps]
+        out["hint"] = ("这个词命中能力域 %s（跨门类的工艺/技术标签，不是国标小类），"
+                       "search_vendors(query=…) 已自动展开并计入结果。命中偏少说明该能力"
+                       "在名录里确实很薄，**不要理解成「没这家厂」**。放宽可调 "
+                       "list_industries(keyword=…) 换近义类目再传 gb=。"
+                       % "、".join("%s %d 家" % (c["name"], _cap_count(c["cap"])) for c in caps))
+        return out
+    out["hint"] = ("命中偏少且推不出国标码：这几条多半只是**字面撞词**，未必真是你要的行业。"
+                   "建议调 list_industries(keyword=\"…\") 用语义挑 1~3 个国标小类，"
+                   "再改传 gb= 重试；这样召回和精度都会好很多。")
     return out
 
 
@@ -1218,6 +1279,12 @@ def _cap_name(code: str) -> str:
     return str(t).split()[0] if t else code
 
 
+def _cap_count(code: str) -> int:
+    """能力键 → 全库企业数（cap.json 的 shards[code] 是一堆「分片名 → 条数」，求和）。"""
+    cap = _load_cap_index() or {}
+    return sum((((cap.get("shards") or {}).get(code) or {})).values())
+
+
 def _cap_shard_paths(cap_code: str) -> List[str]:
     """能力键 → 指纹分片路径（一个逻辑桶可能拆成多个物理分片，必须全收）。
 
@@ -1696,14 +1763,7 @@ def _cap_term_of(code: str) -> str:
     return str(_CAP_TERMS_SLOT[0].get(code) or code or "")
 
 
-def _hay(rec: Dict[str, Any]) -> str:
-    """检索面：query 的每个词都必须出现在这里（AND 全命中）。
-
-    2026-09-23 加入 `cap`（跨门类能力键）—— 在此之前的六个字段
-    （co/city/dist/gb/proc/mat/cert/products）全都表达不了「能力」：
-    赤兔智能的键是 `tech_ai`，而它的厂名/工艺/材料里一个「人工智能」都没有，
-    客户问「苏州做人工智能的企业」就永远 0 条。键必须摊成中文词面才能被中文命中。
-    """
+def _hay_parts(rec: Dict[str, Any], with_cap: bool) -> str:
     parts = [
         # `or ""` 不是多余：gb 为 None（未归类）时 str() 会产出字面量 "None"，
         # 2271 条 gb=null 的记录于是每条都带一个 "None" 词面 —— 查 "none" 能命中
@@ -1713,11 +1773,35 @@ def _hay(rec: Dict[str, Any]) -> str:
         " ".join(rec.get("mat", []) or []),
         " ".join(rec.get("cert", []) or []),
         " ".join(rec.get("products", []) or []),
-        " ".join(_cap_term_of(c) for c in (rec.get("cap") or [])),
     ]
+    if with_cap:
+        parts.append(" ".join(_cap_term_of(c) for c in (rec.get("cap") or [])))
     return " ".join(p for p in parts if p)
 
 
+def _hay(rec: Dict[str, Any]) -> str:
+    """检索面：query 的每个词都必须出现在这里（AND 全命中）。
+
+    2026-09-23 加入 `cap`（跨门类能力键）—— 在此之前的六个字段
+    （co/city/dist/gb/proc/mat/cert/products）全都表达不了「能力」：
+    赤兔智能的键是 `tech_ai`，而它的厂名/工艺/材料里一个「人工智能」都没有，
+    客户问「苏州做人工智能的企业」就永远 0 条。键必须摊成中文词面才能被中文命中。
+    """
+    return _hay_parts(rec, True)
+
+
+def _hay_lit(rec: Dict[str, Any]) -> str:
+    """**字面**检索面 = `_hay` 去掉 cap 词面。
+
+    存在的理由：`_hay` 把厂名/工艺与 cap 词面混在一起，于是「query 词出现在
+    `_hay` 里」这一条**分不清**是「厂名/工艺真写了这个词」还是「只是能力键的中文
+    词面撞上了」。2026-10-06 实测：问「苏州做人工智能的企业」，赤兔智能（键
+    tech_ai）被判成 `via=text`，而它厂名/工艺里一个「人工智能」都没有 —— agent
+    读到 text 会误以为「这家厂自己写了 AI」。所以 text 的判定改走这里。
+    """
+    return _hay_parts(rec, False)
+
+
 def _rec_summary(rec: Dict[str, Any]) -> Dict[str, Any]:
     return {
         "id": rec.get("id"),
@@ -2257,7 +2341,9 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
                     continue
                 if gen_tokens and not all(tok in _hay(rec).lower() for tok in gen_tokens):
                     continue
-                matches.append(_rec_summary(rec))
+                s = _rec_summary(rec)
+                s["via"] = "gb"
+                matches.append(s)
         return _attach_routing_hint({
             "total_matched": len(matches),
             "returned": len(matches[offset:offset + limit]),
@@ -2287,13 +2373,23 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
         for rec in recs:
             if not _city_ok(rec, city):
                 continue
-            if not relax_tokens and gen_tokens and not all(tok in _hay(rec).lower() for tok in gen_tokens):
+            # 只在有关键词时才算检索面（纯城市查询不需要，省一次 join/条）。
+            hay = _hay(rec).lower() if gen_tokens else ""
+            if not relax_tokens and gen_tokens and not all(tok in hay for tok in gen_tokens):
                 continue
             rid = rec.get("id")
             if rid in seen:      # 别名召回与文本召回的并集要去重
                 continue
             seen.add(rid)
             s = _rec_summary(rec)
+            # 只有落在**字面**检索面（厂名/城市/工艺/材料/认证/产品）上才算 text；
+            # 全靠 cap 词面撞上的如实标 cap_text —— 见 `_hay_lit` 的说明。
+            # 没挂 cap 键的记录两张面完全等价（绝大多数），直接复用 hay 不额外算。
+            if gen_tokens:
+                lit = hay if not rec.get("cap") else _hay_lit(rec).lower()
+                s["via"] = "text" if all(tok in lit for tok in gen_tokens) else "cap_text"
+            else:
+                s["via"] = "city"      # 没给关键词，纯城市筛选
             if relax_tokens:
                 a = alias_by_code.get(rec.get("gb") or "")
                 if a:
@@ -2328,6 +2424,7 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
                 continue
             seen.add(rid)
             s = _rec_summary(rec)
+            s["via"] = "alias"         # 别名定向召回（企业自己没写过这个词）
             a = alias_by_code.get(rec.get("gb") or "")
             if a:
                 s["alias_match"] = {"word": a["word"], "gb": a["code"], "name": a["name"]}
@@ -2354,16 +2451,31 @@ def search_vendors(query: str = "", city: str = "", gb: str = "",
                     continue
                 seen.add(rid)
                 s = _rec_summary(rec)
+                s["via"] = "cap"       # 能力定向召回（跨门类能力键，如 tech_ai）
                 s["alias_match"] = {"word": h["word"], "cap": h["cap"],
                                     "name": h["name"], "type": "cap"}
                 matches.append(s)
 
+    # 分档排序（稳定）：text → cap_text → alias → cap。
+    # 为什么必须显式排：cap_text 与 text 是**同一趟**文本召回里 append 进去的，
+    # 不重排两档会交错，order_note 里「按召回来源分档排列」就成了假承诺。
+    _RANK = {"text": 0, "city": 0, "cap_text": 1, "alias": 2, "cap": 3}
+    matches.sort(key=lambda x: _RANK.get(x.get("via"), 9))
+
     out = {
         "total_matched": len(matches),
         "returned": len(matches[offset:offset + limit]),
         "shards_scanned": scanned,
         "via_index": via_index,
         "results": matches[offset:offset + limit],
+        # 结果顺序是**有意设计的分档**，不是随机的：按召回纯度递减排列。
+        # 而 `score` 是**能力画像分**（有已发布能力卡才有分，无卡为 0），**不是相关度**。
+        # 两者一起看极易误判（实测：一家餐厅 sc=0 排在持卡 L2 企业 sc=40 前面），
+        # 所以在这里把口径写死，让 agent 自己能分辨「谁更值得先看」。
+        "order_note": ("results 按召回来源分档排列：via=text(厂名/工艺/材料等**字面**命中) → "
+                       "via=cap_text(厂名里其实没这个词，只是撞上了能力键的中文词面) → "
+                       "via=alias(别名定向) → via=cap(能力定向)；score 是**能力画像分**"
+                       "（有已发布能力卡才有分，无卡为 0），**不是相关度**，不要拿它反推排序。"),
     }
     if alias_hits:
         out["alias_expanded"] = [{"word": a["word"], "gb": a["code"], "name": a["name"]}
@@ -2462,7 +2574,16 @@ def get_vendor(vid: str, gb: str = "") -> Dict[str, Any]:
                 return {"error": f"分片 {zh_path} 解析失败: {e}"}
             for rec in arr:
                 if rec.get("id") == vid:
-                    return {"vendor": normalize_vendor(rec)}
+                    v = normalize_vendor(rec)
+                    # zh 记录自身常常**不写 gb**（只留 industry.code），但它就归档在
+                    # 这个 gb 分片里。不按分片归属回填的话会出现自相矛盾：
+                    # search_vendors(gb=6531) 能搜到它、get_vendor 却说
+                    # gb=null + gb_unclassified=true（2026-10-06 实测 CN-I-0000001）。
+                    if not v.get("gb"):
+                        v["gb"] = gb
+                        v["gb_source"] = "shard"   # 记录没写，取自分片归属
+                        v.pop("gb_unclassified", None)
+                    return {"vendor": v}
         return {"error": f"国标码 {gb} 的全部 zh 分片(共{len(zh_paths)}个)中均未找到 id={vid}"}
 
     # 兜底：gb 为 null（未归类）—— 这些记录躺在 c=='' 的 zh 分片里