beacon-mfg-mcp 1.3.2 → 1.4.0

package/RELEASE.md

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

package/mcp_adapter.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+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 的「通知无回包」语义天然保留
+    （转发通知后不等待回包）。
+
+用法：
+  python mcp_adapter.py
+环境变量（可选）：BEACON_REPO / BEACON_MASK_PHONE / BEACON_SOURCE
+"""
+import json
+import os
+import sys
+import subprocess
+import threading
+import queue
+
+_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")
+
+
+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_stdin_framed():
+    """从父进程(stdio)读取一条标准 MCP 分帧消息，返回 dict；EOF 返回 None。"""
+    buf = b""
+    while True:
+        c = sys.stdin.buffer.read(1)
+        if not c:
+            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:"):
+            try:
+                clen = int(low.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
+
+
+def _write_stdout_framed(obj):
+    """向父进程(stdio)写一条标准 MCP 分帧消息。"""
+    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)
+    sys.stdout.buffer.flush()
+
+
+def main():
+    child = _spawn_server()
+    responses: "queue.Queue" = queue.Queue()
+    client_protocol = None  # 客户端在 initialize 里请求的协议版本
+
+    def reader():
+        # 子进程用换行分隔 JSON；逐行读、入队。
+        try:
+            for line in child.stdout:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except Exception:
+                    continue
+                responses.put(obj)
+        except Exception:
+            pass
+
+    threading.Thread(target=reader, daemon=True).start()
+
+    try:
+        while True:
+            msg = _read_stdin_framed()
+            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")
+
+            # 转发给子进程（换行分隔）
+            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)
+    finally:
+        try:
+            child.terminate()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beacon-mfg-mcp",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "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",
@@ -26,6 +26,8 @@
   "files": [
     "server.py",
     "http_server.py",
+    "mcp_adapter.py",
+    "test_protocol.py",
     "bin/",
     "rfq-kernel/",
     "copy-rfk.js",

package/server.py

@@ -208,14 +208,71 @@ _alias_cache: Optional[Dict[str, Any]] = None
 _gb_name_cache: Optional[Dict[str, str]] = None
 
 
+# ───────────────────────────────────────────────────────────────
+# 派生层缓存失效（让「后台上传 → 立刻可见」无需提交 / 无需重启）
+#
+# BEACON_WORKTREE=1（默认）下，postfetch 会把 fp / 倒排索引 / 清单等派生层重建到
+# 工作树。下面这组机制让 MCP 在不提交、不重启的前提下读到新版本：
+#   - 磁盘索引缓存（idx-*）按「HEAD sha + 工作树 mtime」判新（见 _index_text）
+#   - 进程内缓存（manifest/alias/cap/gb_name/fp_index/桶/分片）按文件 mtime 判新
+#     （见 _cache_stale），或按 BEACON_CACHE_TTL（秒）周期刷新。
+#   - 批量读（_read_many_text，被 _candidate_shards / _records_from_paths 使用）
+#     改为**工作树优先**、git archive HEAD 兜底 —— 否则这两条关键词 / 城市检索的
+#     关键路径会绕过上面的失效机制，永远读到已提交快照。
+# 非工作树模式（BEACON_WORKTREE=0）或 HTTP 模式：恢复旧的「提交后 / 重启后生效」。
+BEACON_CACHE_TTL = float(os.environ.get("BEACON_CACHE_TTL", "0") or "0")
+
+_mtime_cache: Dict[str, tuple] = {}  # relpath -> (checked_at, mtime)，2s 内复用避免热路径狂 stat
+
+
+def _wt_mtime(relpath: str) -> Optional[float]:
+    """工作树文件 mtime（秒）。非工作树模式或文件不存在 → None（不按 mtime 判新）。"""
+    if not REPO or os.environ.get("BEACON_WORKTREE", "1") == "0":
+        return None
+    now = time.time()
+    c = _mtime_cache.get(relpath)
+    if c is not None and (now - c[0]) < 2.0:
+        return c[1]
+    p = os.path.join(REPO, relpath)
+    try:
+        m = os.stat(p).st_mtime
+    except OSError:
+        m = None
+    _mtime_cache[relpath] = (now, m)
+    return m
+
+
+def _wt_mtime_any(relpaths) -> Optional[float]:
+    """多文件取最大 mtime（任一不存在则忽略），全不存在 → None。"""
+    mts = [m for m in (_wt_mtime(r) for r in relpaths) if m is not None]
+    return max(mts) if mts else None
+
+
+def _cache_stale(slot: tuple, relpath: Optional[str]) -> bool:
+    """进程内缓存是否该失效。slot = (value, loaded_at, sig_mtime)。
+    value 为空 / 超 BEACON_CACHE_TTL / 工作树 mtime 变化（postfetch 重建）→ 失效。
+    relpath 可为单路径或路径序列（取最大 mtime）。非工作树模式（mtime 为 None）则只受
+    TTL 与首次加载约束，即旧行为。
+    """
+    if slot is None or slot[0] is None:
+        return True
+    if BEACON_CACHE_TTL > 0 and (time.time() - slot[1]) > BEACON_CACHE_TTL:
+        return True
+    if relpath is not None:
+        m = _wt_mtime_any(relpath) if isinstance(relpath, (list, tuple, set)) else _wt_mtime(relpath)
+        if m is not None and slot[2] != m:
+            return True
+    return False
+
+
 # 版本号单一来源：直接读同目录 package.json，避免 MCP 内部版本与发布包版本漂移。
 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.3.2")
+            return json.load(f).get("version", "1.3.3")
     except Exception:
-        return "1.3.2"
+        return "1.3.3"
 
 
 # HTTP 基址列表（含兜底镜像）。默认部署 Cloudflare Pages 不可达时，自动回退到
@@ -505,12 +562,12 @@ def fetch_text(relpath: str) -> Optional[str]:
 # --------------------------------------------------------------------------- #
 def load_manifest() -> Dict[str, Any]:
     global _manifest_cache
-    if _manifest_cache is None:
+    if _cache_stale(_manifest_cache, "data/manifest.json"):
         txt = fetch_text("data/manifest.json")
         if not txt:
             raise RuntimeError("无法取得 manifest.json（检查 BEACON_SOURCE / BEACON_REPO / 网络）")
-        _manifest_cache = json.loads(txt)
-    return _manifest_cache
+        _manifest_cache = (json.loads(txt), time.time(), _wt_mtime("data/manifest.json"))
+    return _manifest_cache[0]
 
 
 def _shards_of_type(t: str) -> List[Dict[str, Any]]:
@@ -551,13 +608,14 @@ def _load_alias_file(rel: str) -> Dict[str, Any]:
 def load_gb_alias() -> Dict[str, Any]:
     """词 → 条目。两层表合并：gb-alias.json（数据推导）+ gb-alias-curated.json（人工策展）。"""
     global _alias_cache
-    if _alias_cache is None:
+    _alias_relpaths = ("data/gb-alias.json", "data/gb-alias-curated.json")
+    if _cache_stale(_alias_cache, _alias_relpaths):
         merged: Dict[str, Any] = {}
-        for rel in ("data/gb-alias.json", "data/gb-alias-curated.json"):
+        for rel in _alias_relpaths:
             for k, v in _load_alias_file(rel).items():
                 merged.setdefault(str(k).lower(), v)
-        _alias_cache = merged
-    return _alias_cache
+        _alias_cache = (merged, time.time(), _wt_mtime_any(_alias_relpaths))
+    return _alias_cache[0]
 
 
 def _alias_entries(v: Any) -> List[Dict[str, Any]]:
@@ -584,7 +642,7 @@ def _alias_entries(v: Any) -> List[Dict[str, Any]]:
 def _gb_names() -> Dict[str, str]:
     """国标码 → 中文名。取不到（离线/文件缺失）就返回空表，不影响主链路。"""
     global _gb_name_cache
-    if _gb_name_cache is None:
+    if _cache_stale(_gb_name_cache, "data/gb4754-full.json"):
         names: Dict[str, str] = {}
         txt = fetch_text("data/gb4754-full.json")
         if txt:
@@ -599,8 +657,8 @@ def _gb_names() -> Dict[str, str]:
                 if key in ("classes", "groups", "divisions") and isinstance(body, dict):
                     for k, v in body.items():
                         names[str(k)] = str(v.get("name", v)) if isinstance(v, dict) else str(v)
-        _gb_name_cache = names
-    return _gb_name_cache
+        _gb_name_cache = (names, time.time(), _wt_mtime("data/gb4754-full.json"))
+    return _gb_name_cache[0]
 
 
 def alias_codes(q: str, max_codes: int = 6) -> List[Dict[str, Any]]:
@@ -662,13 +720,14 @@ def _load_cap_index() -> Optional[Dict[str, Any]]:
     """skills/registry/index/cap.json —— 发布产物（与 city.json 同构）：
     {terms:{code:词面串}, shards:{code:{shard_name:count}}}。"""
     global _cap_index_cache
-    if _cap_index_cache is None:
+    if _cache_stale(_cap_index_cache, "skills/registry/index/cap.json"):
         txt = _index_text("skills/registry/index/cap.json")
         try:
-            _cap_index_cache = json.loads(txt) if txt else {}
+            _cap_index_cache = (json.loads(txt) if txt else {},
+                               time.time(), _wt_mtime("skills/registry/index/cap.json"))
         except Exception:
-            _cap_index_cache = {}
-    return _cap_index_cache
+            _cap_index_cache = ({}, time.time(), _wt_mtime("skills/registry/index/cap.json"))
+    return _cap_index_cache[0]
 
 
 def _cap_term_index() -> Dict[str, str]:
@@ -867,6 +926,11 @@ def _build_fp_index() -> List[Dict[str, Any]]:
     cp = _index_cache_path()
     wt = os.environ.get("BEACON_WORKTREE", "1") != "0"
     key = (cp or "mem") + ("|wt" if wt else "")
+    if wt:
+        # 工作树模式：manifest 由 postfetch 每次重建（mtime 随之变），把它并进键 →
+        # fp 分片被重建后 fp_index 自动翻新，无需提交 / 重启。
+        mm = _wt_mtime("data/manifest.json")
+        key += "|m%.0f" % (mm if mm is not None else 0)
     if _fp_index is not None and _fp_index_key == key:
         return _fp_index
     if cp and not wt and os.path.exists(cp):
@@ -926,7 +990,7 @@ def _build_fp_index() -> List[Dict[str, Any]]:
     return recs
 
 
-_CAP_TERMS_CACHE: Dict[str, Any] = {}
+_CAP_TERMS_SLOT: Optional[tuple] = None
 
 
 def _cap_term_of(code: str) -> str:
@@ -939,7 +1003,8 @@ def _cap_term_of(code: str) -> str:
     取不到时退回键本身：`caps_index` 允许出现码表之外的裸值（材料「不锈钢」、
     品类「正餐」），它们本身就是可检索词，丢掉等于让这类查询瞎掉。
     """
-    if "v" not in _CAP_TERMS_CACHE:
+    global _CAP_TERMS_SLOT
+    if _cache_stale(_CAP_TERMS_SLOT, "skills/registry/index/cap.json"):
         terms: Dict[str, Any] = {}
         try:
             txt = _index_text("skills/registry/index/cap.json")
@@ -947,8 +1012,8 @@ def _cap_term_of(code: str) -> str:
                 terms = (json.loads(txt).get("terms") or {})
         except Exception:
             terms = {}
-        _CAP_TERMS_CACHE["v"] = terms
-    return str(_CAP_TERMS_CACHE["v"].get(code) or code or "")
+        _CAP_TERMS_SLOT = (terms, time.time(), _wt_mtime("skills/registry/index/cap.json"))
+    return str(_CAP_TERMS_SLOT[0].get(code) or code or "")
 
 
 def _hay(rec: Dict[str, Any]) -> str:
@@ -992,8 +1057,8 @@ def _rec_summary(rec: Dict[str, Any]) -> Dict[str, Any]:
 INDEX_DIR = "skills/registry/index"
 INDEX_VERSION = 3          # 倒排 key 为分片路径；v2 用国标码会漏掉 gb=null 的记录
 _index_meta_cache: Optional[Dict[str, Any]] = None
-_bucket_cache: Dict[str, Dict[str, Any]] = {}
-_shard_rec_cache: Dict[str, List[Dict[str, Any]]] = {}
+_bucket_cache: Dict[str, tuple] = {}
+_shard_rec_cache: Dict[str, tuple] = {}
 
 _RE_CJK = re.compile("[\u4e00-\u9fff\u3400-\u4dbf]+")
 _RE_WORD = re.compile(r"[a-z0-9]+")
@@ -1036,13 +1101,18 @@ def _grams(text: str, query_mode: bool = False) -> List[str]:
 def _index_text(relpath: str) -> Optional[str]:
     """读索引文件。git 模式按 HEAD sha 落盘缓存（桶均 11KB），
     缓存后跨进程重复查询几乎零成本。
+
+    BEACON_WORKTREE=1（默认）：磁盘缓存额外按工作树文件 mtime 判新 —— postfetch
+    重建索引后 mtime 变化，下次查询即重读工作树版本，无需提交 HEAD 即可让关键词 /
+    城市检索看到新数据（修 DSH 发现的「不提交就永远看不到」坑）。非工作树模式保持
+    旧的「HEAD 变化才刷新」行为。
     """
     cp = None
     if REPO:
         h = _head_sha() or "nosha"
         cp = os.path.join(CACHE_DIR, "idx-" +
                           hashlib.sha1((h + "|" + relpath).encode("utf-8")).hexdigest() + ".json")
-        if os.path.exists(cp):
+        if os.path.exists(cp) and _index_sig_ok(cp, relpath):
             try:
                 with open(cp, "r", encoding="utf-8") as f:
                     return f.read()
@@ -1054,11 +1124,43 @@ def _index_text(relpath: str) -> Optional[str]:
             os.makedirs(CACHE_DIR, exist_ok=True)
             with open(cp, "w", encoding="utf-8") as f:
                 f.write(txt)
+            _write_index_sig(cp, relpath)
         except Exception:
             pass
     return txt
 
 
+def _index_sig_ok(cp: str, relpath: str) -> bool:
+    """工作树模式下，磁盘缓存里的 mtime 印记是否与当前工作树文件一致。
+
+    印记用 repr 精确往返（浮点不丢精度），避免 postfetch 在同一秒内重写索引文件时
+    截断判成「未变」而误服陈旧缓存。
+    """
+    sig = _wt_mtime(relpath)
+    if sig is None:
+        return True                      # 非工作树：不按 mtime 判新
+    sf = cp + ".sig"
+    try:
+        with open(sf, "r", encoding="utf-8") as f:
+            return float(f.read().strip()) == sig
+    except Exception:
+        return False                     # 缺印记 / 损坏 → 重建
+
+
+def _write_index_sig(cp: str, relpath: str) -> None:
+    sig = _wt_mtime(relpath)
+    sf = cp + ".sig"
+    try:
+        if sig is None:
+            if os.path.exists(sf):
+                os.remove(sf)
+            return
+        with open(sf, "w", encoding="utf-8") as f:
+            f.write(repr(sig))
+    except Exception:
+        pass
+
+
 def _git_read_many(paths: List[str]) -> Dict[str, str]:
     """git 模式：一次 `git archive` 批量取出多个文件。
 
@@ -1088,10 +1190,29 @@ def _git_read_many(paths: List[str]) -> Dict[str, str]:
 
 
 def _read_many_text(paths: List[str]) -> Dict[str, str]:
-    """批量取文本：git 模式 1 次 archive；HTTP 模式线程池并发。"""
+    """批量取文本：工作树优先 → git archive 兜底；HTTP 模式线程池并发。
+
+    BEACON_WORKTREE=1（默认）：**必须工作树优先**。`_candidate_shards`（索引桶）与
+    `_records_from_paths`（fp 分片）都走这里 —— 若沿用「git archive HEAD」就会永远
+    读到**已提交快照**，postfetch 刚重建、尚未提交的索引 / 分片完全看不见（DSH 实测
+    「关键词 / 城市检索不提交就搜不到」的真凶）。工作树缺的文件再走 archive 已提交
+    快照兜底，最后 HTTP。非工作树模式（BEACON_WORKTREE=0）保持旧行为。
+    """
     if not paths:
         return {}
     if REPO:
+        if os.environ.get("BEACON_WORKTREE", "1") != "0":
+            out: Dict[str, str] = {}
+            missing: List[str] = []
+            for p in paths:
+                w = _worktree_read(p)
+                if w is not None:
+                    out[p] = w
+                else:
+                    missing.append(p)
+            if missing:                       # 工作树缺失/半成品 → 已提交快照兜底
+                out.update(_git_read_many(missing))
+            return out
         got = _git_read_many(paths)
         if len(got) >= max(1, len(paths) // 2):   # archive 正常覆盖
             return got
@@ -1105,16 +1226,17 @@ def _read_many_text(paths: List[str]) -> Dict[str, str]:
 
 def _index_meta() -> Optional[Dict[str, Any]]:
     global _index_meta_cache
-    if _index_meta_cache is not None:
-        return _index_meta_cache
-    txt = _index_text(INDEX_DIR + "/meta.json")
-    if not txt:
-        return None
-    try:
-        _index_meta_cache = json.loads(txt)
-    except Exception:
-        return None
-    return _index_meta_cache
+    if _cache_stale(_index_meta_cache, INDEX_DIR + "/meta.json"):
+        txt = _index_text(INDEX_DIR + "/meta.json")
+        if not txt:
+            _index_meta_cache = (None, time.time(), _wt_mtime(INDEX_DIR + "/meta.json"))
+        else:
+            try:
+                _index_meta_cache = (json.loads(txt), time.time(),
+                                    _wt_mtime(INDEX_DIR + "/meta.json"))
+            except Exception:
+                _index_meta_cache = (None, time.time(), _wt_mtime(INDEX_DIR + "/meta.json"))
+    return _index_meta_cache[0]
 
 
 def _index_fresh() -> bool:
@@ -1155,17 +1277,16 @@ _city_names_cache: Optional[set] = None
 def _city_names() -> set:
     """倒排索引里出现过的城市名集合：地区词不作为相关性证据（只作筛选偏好）。"""
     global _city_names_cache
-    if _city_names_cache is not None:
-        return _city_names_cache
-    names: set = set()
-    txt = _index_text(INDEX_DIR + "/city.json")
-    if txt:
-        try:
-            names = set(json.loads(txt).keys())
-        except Exception:
-            names = set()
-    _city_names_cache = names
-    return names
+    if _cache_stale(_city_names_cache, INDEX_DIR + "/city.json"):
+        names: set = set()
+        txt = _index_text(INDEX_DIR + "/city.json")
+        if txt:
+            try:
+                names = set(json.loads(txt).keys())
+            except Exception:
+                names = set()
+        _city_names_cache = (names, time.time(), _wt_mtime(INDEX_DIR + "/city.json"))
+    return _city_names_cache[0]
 
 
 def _is_cjk(s: str) -> bool:
@@ -1202,16 +1323,23 @@ def _collapse_prefixes(toks: set) -> set:
 
 
 def _bucket_postings(gram: str, buckets: int) -> Dict[str, Any]:
-    """取倒排索引里某词的 postings {分片路径: 命中条数}；缺失/异常返回空 dict。"""
+    """取倒排索引里某词的 postings {分片路径: 命中条数}；缺失/异常返回空 dict。
+
+    桶缓存按工作树 mtime 判新（见 _wt_mtime）：postfetch 重建索引后，对应桶文件
+    mtime 变化即自动重读，无需重启。
+    """
     rel = _bucket_rel(gram, buckets)
-    b = _bucket_cache.get(rel)
-    if b is None:
+    m = _wt_mtime(rel)
+    slot = _bucket_cache.get(rel)
+    if slot is not None and (m is None or slot[0] == m):
+        b = slot[1]
+    else:
         txt = _index_text(rel)
         try:
             b = json.loads(txt) if txt else {}
         except Exception:
             b = {}
-        _bucket_cache[rel] = b
+        _bucket_cache[rel] = (m, b)
     post = b.get(gram) if isinstance(b, dict) else None
     return post if isinstance(post, dict) else {}
 
@@ -1354,13 +1482,22 @@ def _candidate_shards(tokens: List[str], city: str) -> Optional[List[str]]:
 
 
 def _records_from_paths(paths: List[str]) -> List[Dict[str, Any]]:
-    """批量读取若干 fp 分片的记录，并在进程内按路径缓存（重复查询近乎零成本）。"""
+    """批量读取若干 fp 分片的记录，并在进程内按路径缓存（重复查询近乎零成本）。
+
+    缓存按工作树 mtime 判新（见 _wt_mtime）：postfetch 重建 fp 分片后，对应分片 mtime
+    变化即重读，无需重启；非工作树模式保持旧行为（按路径存在性判新）。
+    """
     out: List[Dict[str, Any]] = []
     if not paths:
         return out
-    todo = [p for p in paths if p not in _shard_rec_cache]
-    for p in todo:
-        _shard_rec_cache[p] = []
+    todo: List[str] = []
+    for p in paths:
+        m = _wt_mtime(p)
+        slot = _shard_rec_cache.get(p)
+        if slot is not None and (m is None or slot[0] == m):
+            continue
+        todo.append(p)
+        _shard_rec_cache[p] = (m, [])
     for _path, txt in _read_many_text(todo).items():
         recs: List[Dict[str, Any]] = []
         for line in txt.splitlines():
@@ -1371,9 +1508,11 @@ def _records_from_paths(paths: List[str]) -> List[Dict[str, Any]]:
                 recs.append(json.loads(line))
             except Exception:
                 continue
-        _shard_rec_cache[_path] = recs
+        _shard_rec_cache[_path] = (_wt_mtime(_path), recs)
     for p in paths:
-        out.extend(_shard_rec_cache.get(p, []))
+        slot = _shard_rec_cache.get(p)
+        if slot:
+            out.extend(slot[1])
     return out
 
 

package/test_protocol.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+BeaconMFG MCP —— 发布前协议回归测试（pre-release smoke test）。
+
+为什么需要它
+------------
+`server.py` 同时服务两条链路：本地 stdio（npm / git 安装）与远程 Streamable HTTP
+（`http_server.py`）。业务逻辑一改，两条链路都可能悄悄坏掉，且**症状隐蔽**
+（能握手但查不出数据、或只有部分工具挂掉）。本脚本把「协议能握手 + 工具齐全 +
+真实检索有结果」三件事固化为一条命令，每次发版前跑一遍。
+
+用法
+----
+    python mcp/test_protocol.py                 # 自动起 HTTP 端点自测
+    python mcp/test_protocol.py --stdio         # 额外测 stdio(server.py)
+    python mcp/test_protocol.py --adapter       # 额外测标准分帧适配层
+    BEACON_REPO=/path/to/repo python mcp/test_protocol.py
+
+退出码：0 全部通过；1 有失败项。
+"""
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SERVER = os.path.join(HERE, "server.py")
+HTTP_SERVER = os.path.join(HERE, "http_server.py")
+ADAPTER = os.path.join(HERE, "mcp_adapter.py")
+
+EXPECT_TOOLS = {
+    "search_vendors", "get_vendor", "get_capability_card",
+    "start_sourcing", "answer_sourcing", "refine_sourcing",
+}
+
+# 三个城市各取一个高频词，覆盖不同行业与不同分片，避免「只测通一个分片」
+SMOKE_QUERIES = [("修车", "嘉兴"), ("面馆", "苏州"), ("米粉", "贵阳")]
+
+_results = []
+
+
+def _check(name, ok, detail=""):
+    _results.append((name, bool(ok), detail))
+    print("  %s %s%s" % ("PASS" if ok else "FAIL", name, ("  -> " + detail) if detail else ""))
+    return ok
+
+
+def _child_env():
+    env = dict(os.environ)
+    env.setdefault("BEACON_MASK_PHONE", "1")
+    env["PYTHONUTF8"] = "1"
+    env["PYTHONIOENCODING"] = "utf-8"
+    return env
+
+
+# --------------------------------------------------------------------------
+# 公共断言：拿到工具列表 + 跑真实检索
+# --------------------------------------------------------------------------
+def _assert_tools_and_search(call, label):
+    """call(method, params, session_id) -> result dict"""
+    r = call("initialize", {
+        "protocolVersion": "2024-11-05", "capabilities": {},
+        "clientInfo": {"name": "smoke", "version": "1"},
+    })
+    _check("%s initialize" % label, r is not None and "result" in r, "" if r else "无回包")
+
+    # 通知无回包（规范允许），不要等
+    try:
+        call("notifications/initialized", {}, r.get("__sid__") if isinstance(r, dict) else None)
+    except Exception:
+        pass
+
+    r2 = call("tools/list", {})
+    tools = set()
+    if r2 and "result" in r2:
+        tools = {t.get("name") for t in r2["result"].get("tools", [])}
+    missing = EXPECT_TOOLS - tools
+    _check("%s tools/list (6)" % label, not missing, ("缺: " + ",".join(missing)) if missing else "")
+
+    for q, city in SMOKE_QUERIES:
+        r3 = call("tools/call", {"name": "search_vendors",
+                                 "arguments": {"query": q, "city": city, "limit": 3}})
+        n, err = 0, ""
+        if r3 and "result" in r3:
+            try:
+                data = json.loads(r3["result"]["content"][0]["text"])
+                n = len(data.get("results", []))
+            except Exception as e:
+                err = "解析失败 %s" % e
+        else:
+            err = "无回包"
+        _check("%s search %s/%s" % (label, city, q), n > 0, err or "命中 %d" % n)
+
+
+# --------------------------------------------------------------------------
+# 1) Streamable HTTP（http_server.py）
+# --------------------------------------------------------------------------
+def test_http():
+    print("\n[1/3] Streamable HTTP  (mcp/http_server.py)")
+    port = int(os.environ.get("MCP_TEST_PORT", "8899"))
+    env = _child_env()
+    env["MCP_PORT"] = str(port)
+    proc = subprocess.Popen([sys.executable, "-u", HTTP_SERVER],
+                            env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    base = "http://127.0.0.1:%d/mcp" % port
+    try:
+        # 等端口起来
+        for _ in range(40):
+            try:
+                urllib.request.urlopen("http://127.0.0.1:%d/health" % port, timeout=1).read()
+                break
+            except Exception:
+                time.sleep(0.25)
+        else:
+            _check("HTTP 端点启动", False, "40 次探测仍未就绪")
+            return
+
+        def call(method, params, sid=None):
+            payload = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+            if method.startswith("notifications/"):
+                payload.pop("id")
+            data = json.dumps(payload).encode()
+            req = urllib.request.Request(base, data=data, method="POST")
+            req.add_header("Content-Type", "application/json")
+            req.add_header("Accept", "application/json, text/event-stream")
+            if sid:
+                req.add_header("Mcp-Session-Id", sid)
+            with urllib.request.urlopen(req, timeout=90) as resp:
+                new_sid = resp.headers.get("Mcp-Session-Id")
+                body = resp.read().decode()
+            if method.startswith("notifications/"):
+                return None
+            obj = json.loads(body)
+            if new_sid:
+                obj["__sid__"] = new_sid
+            return obj
+
+        _assert_tools_and_search(call, "http")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+# --------------------------------------------------------------------------
+# 2) 换行分隔 stdio（server.py）—— npm/git 安装走的默认链路
+# --------------------------------------------------------------------------
+def test_stdio():
+    print("\n[2/3] stdio 换行分隔  (mcp/server.py)")
+    proc = subprocess.Popen([sys.executable, "-u", SERVER], stdin=subprocess.PIPE,
+                            stdout=subprocess.PIPE, env=_child_env(),
+                            encoding="utf-8", bufsize=1)
+    try:
+        def send(method, params, notify=False):
+            msg = {"jsonrpc": "2.0", "method": method, "params": params}
+            if not notify:
+                msg["id"] = 1
+            proc.stdin.write(json.dumps(msg, ensure_ascii=False) + "\n")
+            proc.stdin.flush()
+            if notify:
+                return None
+            return json.loads(proc.stdout.readline())
+
+        def call(method, params, sid=None):
+            if method.startswith("notifications/"):
+                return send(method, params, notify=True)
+            return send(method, params)
+
+        _assert_tools_and_search(call, "stdio")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+# --------------------------------------------------------------------------
+# 3) 标准分帧适配层（mcp_adapter.py）—— 严格客户端走这条
+# --------------------------------------------------------------------------
+def test_adapter():
+    print("\n[3/3] 标准分帧适配层  (mcp/mcp_adapter.py)")
+    proc = subprocess.Popen([sys.executable, "-u", ADAPTER], stdin=subprocess.PIPE,
+                            stdout=subprocess.PIPE, env=_child_env(), bufsize=0)
+
+    def send(obj):
+        data = json.dumps(obj, ensure_ascii=False).encode()
+        proc.stdin.write(b"Content-Length: %d\r\n\r\n" % len(data) + data)
+        proc.stdin.flush()
+
+    def recv():
+        hdr = b""
+        while not hdr.endswith(b"\r\n\r\n"):
+            c = proc.stdout.read(1)
+            if not c:
+                return None
+            hdr += c
+        n = 0
+        for line in hdr.split(b"\r\n"):
+            if line.lower().startswith(b"content-length:"):
+                n = int(line.split(b":")[1].strip())
+        body = b""
+        while len(body) < n:
+            chunk = proc.stdout.read(n - len(body))
+            if not chunk:
+                return None
+            body += chunk
+        return json.loads(body.decode("utf-8"))
+
+    def call(method, params, sid=None):
+        msg = {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+        if method.startswith("notifications/"):
+            msg.pop("id")
+            send(msg)
+            return None
+        send(msg)
+        return recv()
+
+    try:
+        _assert_tools_and_search(call, "adapter")
+    finally:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except Exception:
+            proc.kill()
+
+
+def main():
+    print("=" * 60)
+    print("BeaconMFG MCP 协议回归测试")
+    print("数据源: BEACON_REPO=%s" % (os.environ.get("BEACON_REPO") or "(默认/联网)"))
+    print("=" * 60)
+
+    test_http()
+    if "--stdio" in sys.argv:
+        test_stdio()
+    if "--adapter" in sys.argv:
+        test_adapter()
+    else:
+        print("\n[2/3] stdio  (跳过，加 --stdio 启用)")
+        print("[3/3] adapter (跳过，加 --adapter 启用)")
+
+    passed = sum(1 for _, ok, _ in _results if ok)
+    failed = [(n, d) for n, ok, d in _results if not ok]
+    print("\n" + "=" * 60)
+    print("结果: %d 通过, %d 失败" % (passed, len(failed)))
+    for n, d in failed:
+        print("  FAIL %s  %s" % (n, d))
+    print("=" * 60)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())