beacon-mfg-mcp 1.4.2 → 1.5.1

package/RELEASE.md

@@ -1,4 +1,4 @@
-# Beacon-MFG 只读 MCP 服务 · v1.4.2
+# Beacon-MFG 只读 MCP 服务 · v1.5.1
 
 让任意支持 MCP 的主流 agent（Claude Desktop / Cline / Continue / WorkBuddy 等）能够
 **检索与调用**已发布到 Cloudflare Pages（或 GitHub）的灯塔工厂供应商数据，
@@ -21,7 +21,54 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 后三个构成「采购寻源」多轮会话链路 `start_sourcing → answer_sourcing → refine_sourcing`，
 依赖仓库平级的 `skills/rfq-kernel` 桥接模块。
 
-## 本次更新（v1.4.2）
+## 本次更新（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`）。
@@ -70,7 +117,7 @@ MCP 只做**只读检索**。后端数据采集、英文翻译、库维护等流
 ## 安装（三选一）
 
 ### 1. 从 GitHub Release 下载（推荐，零依赖）
-下载本 Release 的 `beacon-mfg-mcp-mcp-v1.4.2.tar.gz`，解压后：
+下载本 Release 的 `beacon-mfg-mcp-mcp-v1.5.1.tar.gz`，解压后：
 ```jsonc
 {
   "mcpServers": {

package/bin/beacon-mfg-mcp.js

@@ -1,54 +1,54 @@
-#!/usr/bin/env node
-'use strict';
-// beacon-mfg-mcp 启动器：本 MCP 服务是纯 Python 标准库实现，这里只负责
-// ① 在用户机器上找到 Python 解释器并拉起 server.py（stdio 协议）
-// ② 顺手踢一个**独立进程**去做节流的自更新检查
-const { spawnSync, spawn } = require('child_process');
-const path = require('path');
-
-const serverPy = path.join(__dirname, '..', 'server.py');
-const selfUpdateJs = path.join(__dirname, 'selfupdate.js');
-
-// 踢起自更新检查：detached + unref，主进程既不等它也不被它拖住。
-// 为什么必须是独立进程而不是本进程里的 async 函数：
-// 下面 spawnSync 是**同步阻塞**的，会冻结整个事件循环 —— async 的自更新
-// 在 server 运行期间推不动，等它能跑时本进程已经 process.exit() 了，
-// 更新逻辑永远跑不完（实测 stamp 根本不写）。独立进程不受此影响。
-// 失败、离线、没权限一律静默：它只影响「下次启动是不是最新版」。
-try {
-  const u = spawn(process.execPath, [selfUpdateJs], {
-    stdio: 'ignore',
-    detached: true,
-    windowsHide: true,
-  });
-  u.on('error', () => { /* 没有 node？不可能，自身就是 node 起的 */ });
-  u.unref();
-} catch (_) { /* 自更新是加分项，绝不能影响 MCP 启动 */ }
-
-// 探测可用的 Python 解释器（优先 python3，兼容 python / py）
-const candidates = ['python3', 'python', 'py'];
-let chosen = null;
-for (const c of candidates) {
-  const r = spawnSync(c, ['--version'], { stdio: 'ignore' });
-  if (r.status === 0) {
-    chosen = c;
-    break;
-  }
-}
-if (!chosen) {
-  process.stderr.write(
-    '[beacon-mfg-mcp] 未找到 Python 3。请先安装 Python 3.8+ 并加入 PATH，再重试。\n'
-  );
-  process.exit(1);
-}
-
-const child = spawnSync(chosen, [serverPy, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-  // 显式锁定 UTF-8：中文 Windows 上 python 默认按 GBK 写 stdout，
-  // MCP 客户端按 UTF-8 解码会乱码。从启动器层面保证子进程用 UTF-8 输出。
-  env: Object.assign({}, process.env, {
-    PYTHONUTF8: '1',
-    PYTHONIOENCODING: 'utf-8',
-  }),
-});
-process.exit(child.status === null ? 1 : child.status);
+#!/usr/bin/env node
+'use strict';
+// beacon-mfg-mcp 启动器：本 MCP 服务是纯 Python 标准库实现，这里只负责
+// ① 在用户机器上找到 Python 解释器并拉起 server.py（stdio 协议）
+// ② 顺手踢一个**独立进程**去做节流的自更新检查
+const { spawnSync, spawn } = require('child_process');
+const path = require('path');
+
+const serverPy = path.join(__dirname, '..', 'server.py');
+const selfUpdateJs = path.join(__dirname, 'selfupdate.js');
+
+// 踢起自更新检查：detached + unref，主进程既不等它也不被它拖住。
+// 为什么必须是独立进程而不是本进程里的 async 函数：
+// 下面 spawnSync 是**同步阻塞**的，会冻结整个事件循环 —— async 的自更新
+// 在 server 运行期间推不动，等它能跑时本进程已经 process.exit() 了，
+// 更新逻辑永远跑不完（实测 stamp 根本不写）。独立进程不受此影响。
+// 失败、离线、没权限一律静默：它只影响「下次启动是不是最新版」。
+try {
+  const u = spawn(process.execPath, [selfUpdateJs], {
+    stdio: 'ignore',
+    detached: true,
+    windowsHide: true,
+  });
+  u.on('error', () => { /* 没有 node？不可能，自身就是 node 起的 */ });
+  u.unref();
+} catch (_) { /* 自更新是加分项，绝不能影响 MCP 启动 */ }
+
+// 探测可用的 Python 解释器（优先 python3，兼容 python / py）
+const candidates = ['python3', 'python', 'py'];
+let chosen = null;
+for (const c of candidates) {
+  const r = spawnSync(c, ['--version'], { stdio: 'ignore' });
+  if (r.status === 0) {
+    chosen = c;
+    break;
+  }
+}
+if (!chosen) {
+  process.stderr.write(
+    '[beacon-mfg-mcp] 未找到 Python 3。请先安装 Python 3.8+ 并加入 PATH，再重试。\n'
+  );
+  process.exit(1);
+}
+
+const child = spawnSync(chosen, [serverPy, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  // 显式锁定 UTF-8：中文 Windows 上 python 默认按 GBK 写 stdout，
+  // MCP 客户端按 UTF-8 解码会乱码。从启动器层面保证子进程用 UTF-8 输出。
+  env: Object.assign({}, process.env, {
+    PYTHONUTF8: '1',
+    PYTHONIOENCODING: 'utf-8',
+  }),
+});
+process.exit(child.status === null ? 1 : child.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "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",
@@ -27,7 +27,6 @@
     "server.py",
     "http_server.py",
     "mcp_adapter.py",
-    "test_protocol.py",
     "bin/",
     "rfq-kernel/",
     "copy-rfk.js",

package/rfq-kernel/demo.py

@@ -9,6 +9,15 @@ from __future__ import annotations
 
 import json
 import sys
+# [utf8-guard] Windows 下 stdout/stderr 非 TTY 时按 locale 编码（中文 Windows = cp936/GBK），
+# 而本脚本输出的 ✗ ✓ ⚠ 等符号 GBK 码表里根本没有 → print 当场抛
+#   UnicodeEncodeError: 'gbk' codec can't encode character '\u2717'
+# 整条流水线会断在打印那一行。统一 UTF-8 + 兜底替换：宁可显示成 '?'，也绝不因打印而崩。
+for _s in (sys.stdout, sys.stderr):
+    try:
+        _s.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
 from datetime import datetime, timezone
 from pathlib import Path