beacon-mfg-mcp 1.5.1 → 1.5.4

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.4
 
 让任意支持 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,169 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
 依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
 
-## 本次更新（v1.5.1）
+## 本次更新（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 毫秒。**
+
+### 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 +281,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.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.1",
+  "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",