beacon-mfg-mcp 1.3.1 → 1.3.3

package/README.md

@@ -46,8 +46,18 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 ```
 
 ```jsonc
-{ "mcpServers": { "beacon-mfg": { "command": "beacon-mfg-mcp", "args": [] } } }
+{
+  "mcpServers": {
+    "beacon-mfg": {
+      "command": "beacon-mfg-mcp",
+      "args": [],
+      "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" }
+    }
+  }
+}
 ```
+> 启动器（`bin/beacon-mfg-mcp.js`）已默认注入上述两个变量；此处写出仅为显式/可覆盖。
+> 二者保证 python 子进程以 UTF-8 输出，否则中文 Windows 上工具描述/结果会乱码。
 
 不填 `BEACON_REPO` 时默认走 `https://beacon-mfg.pages.dev`，即开即用。
 
@@ -92,6 +102,13 @@ npm i -g beacon-mfg-mcp      # 或不安装直接用 npx beacon-mfg-mcp
 HTTP 模式带正确 `User-Agent` 与 `ETag` 304 缓存（与 App 同款策略），并落盘 `~/.cache/beacon-mcp-cache`，
 重复查询零传输。CF 部署版手机号可能是全号——隐私敏感场景请用方式 A。
 
+> **CDN 兜底镜像（v1.3.2 新增）**：默认源 `beacon-mfg.pages.dev` 不可达（抖动/被墙）时，
+> MCP 会**自动回退**到 GitHub 兜底镜像拉 `manifest.json` 与分片——`cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main`
+> 与 `raw.githubusercontent.com/eiry16/beacon-mfg/main`（与 Android App 同策略）。因此「免 clone 检索」
+> 在单一 CDN 失效时仍可工作。如需自定义/追加镜像，设 `BEACON_MIRRORS`（逗号分隔的基址列表）。
+> 注意：能力卡（`get_capability_card`）不在 git 内、仅存于 CF/R2，镜像兜底覆盖的是 manifest + 分片 + 档案这类主数据；
+> 在中国大陆等直连 GitHub 困难的网络，给 MCP 进程设 `HTTPS_PROXY=http://127.0.0.1:7890`（或你的代理）可让镜像链路走代理。
+
 ## 远程 HTTP 端点（Streamable HTTP）
 
 `server.py` 本体是 **stdio**；`http_server.py` 是它的 **HTTP 传输适配层**（复用同一份 `_dispatch`/`TOOLS`，
@@ -169,7 +186,7 @@ MCP 服务有两种发布渠道（详见 `mcp/RELEASE.md`）：
 
 - **GitHub Release（已配 CI）**：推送 `mcp-v*` 标签即由 `.github/workflows/mcp-release.yml`
   自动打包 `mcp/` 目录为 `beacon-mfg-mcp-mcp-vX.Y.Z.tar.gz` 并创建 Release。
-- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已发布到 npm 公共仓库，当前版本 **`1.3.1`**
+- **npm 包（已发布 ✅）**：`beacon-mfg-mcp` 已发布到 npm 公共仓库，当前版本 **`1.3.2`**
   （<https://www.npmjs.com/package/beacon-mfg-mcp>）。第三方可直接 `npm i -g beacon-mfg-mcp`
   或 `npx beacon-mfg-mcp`，客户端配置 `"command": "beacon-mfg-mcp"` 即可，无需 clone、无需填路径。
   **1.3.0 起 npm 包自带 rfq-kernel**，安装 → MCP 握手 → `tools/list` 暴露 6 个 tool 且全部可用

package/RELEASE.md

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

@@ -26,5 +26,11 @@ if (!chosen) {
 
 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.3.1",
+  "version": "1.3.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

@@ -208,6 +208,90 @@ _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.3")
+    except Exception:
+        return "1.3.3"
+
+
+# HTTP 基址列表（含兜底镜像）。默认部署 Cloudflare Pages 不可达时，自动回退到
+# GitHub 兜底镜像（与 Android App 同策略：pages.dev 主源 + jsDelivr / raw 镜像），
+# 保证「免 clone 检索」在单一 CDN 抖动/被墙时仍可工作。可用 BEACON_MIRRORS 追加自定义镜像。
+def _http_bases() -> List[str]:
+    bases = [BEACON_SOURCE]
+    if BEACON_SOURCE == DEFAULT_SOURCE:
+        bases.append("https://cdn.jsdelivr.net/gh/eiry16/beacon-mfg@main")
+        bases.append("https://raw.githubusercontent.com/eiry16/beacon-mfg/main")
+    m = os.environ.get("BEACON_MIRRORS")
+    if m:
+        for x in m.split(","):
+            x = x.strip().rstrip("/")
+            if x:
+                bases.append(x)
+    return bases
+
+
 # --------------------------------------------------------------------------- #
 # 使用量埋点（设计见 docs/MCP_USAGE_AUDIT.md §3.4 / §4 / §14）
 # --------------------------------------------------------------------------- #
@@ -362,48 +446,59 @@ def _git_show(relpath: str) -> Optional[str]:
     return None
 
 
+# 单基址 HTTP 超时（秒）。多镜像回退时每个基址各自计时，避免单一 CDN 卡死拖垮整体。
+_HTTP_TIMEOUT = 15
+
+
 def _http_get(relpath: str) -> Tuple[Optional[str], Optional[str]]:
-    url = BEACON_SOURCE + "/" + relpath
-    cap = _cache_path(url)
-    etag = None
-    if os.path.exists(cap):
+    """统一的 HTTP 读取：依次尝试 _http_bases() 中的基址（主源 + 兜底镜像），
+    任一成功即返回；全部失败则用本地缓存兜底（保证离线可用）。"""
+    cached_body = None
+    cached_etag = None
+    for base in _http_bases():
+        url = base + "/" + relpath
+        cap = _cache_path(url)
+        etag = None
+        if os.path.exists(cap):
+            try:
+                with open(cap, "r", encoding="utf-8") as f:
+                    blob = json.load(f)
+                etag = blob.get("etag")
+                cached_body = blob.get("body")
+                cached_etag = etag
+            except Exception:
+                etag = None
+        headers = {"User-Agent": UA, "Accept": "*/*"}
+        # 埋点头：服务端据此填 tool / tokens / hits 列。收不到也没关系 ——
+        # worker 那边**照样计数**，只是这三列为空（文档 §3.4）。
         try:
-            with open(cap, "r", encoding="utf-8") as f:
-                blob = json.load(f)
-            etag = blob.get("etag")
+            headers.update(_beacon_headers())
         except Exception:
-            etag = None
-    headers = {"User-Agent": UA, "Accept": "*/*"}
-    # 埋点头：服务端据此填 tool / tokens / hits 列。收不到也没关系 ——
-    # worker 那边**照样计数**，只是这三列为空（文档 §3.4）。
-    try:
-        headers.update(_beacon_headers())
-    except Exception:
-        pass
-    req = urllib.request.Request(url, headers=headers)
-    if etag:
-        req.add_header("If-None-Match", etag)
-    try:
-        resp = urllib.request.urlopen(req, timeout=30)
-        body = resp.read().decode("utf-8")
-        new_etag = resp.headers.get("ETag")
+            pass
+        req = urllib.request.Request(url, headers=headers)
+        if etag:
+            req.add_header("If-None-Match", etag)
         try:
-            with open(cap, "w", encoding="utf-8") as f:
-                json.dump({"etag": new_etag, "body": body}, f)
+            resp = urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT)
+            body = resp.read().decode("utf-8")
+            new_etag = resp.headers.get("ETag")
+            try:
+                with open(cap, "w", encoding="utf-8") as f:
+                    json.dump({"etag": new_etag, "body": body}, f)
+            except Exception:
+                pass
+            return body, new_etag
+        except urllib.error.HTTPError as e:
+            if e.code == 304 and cached_body is not None:
+                return cached_body, etag
+            continue
         except Exception:
-            pass
-        return body, new_etag
-    except urllib.error.HTTPError as e:
-        if e.code == 304 and os.path.exists(cap):
-            with open(cap, "r", encoding="utf-8") as f:
-                return json.load(f).get("body"), etag
-        return None, None
-    except Exception:
-        # 网络不通时若本地有缓存也返回，保证离线可用
-        if os.path.exists(cap):
-            with open(cap, "r", encoding="utf-8") as f:
-                return json.load(f).get("body"), etag
-        return None, None
+            # 当前基址不可达：尝试下一个兜底镜像；全部失败后在末尾用本地缓存兜底
+            continue
+    # 全部基址失败：若有任何本地缓存也返回，保证离线可用
+    if cached_body is not None:
+        return cached_body, cached_etag
+    return None, None
 
 
 def _worktree_read(relpath: str) -> Optional[str]:
@@ -467,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]]:
@@ -513,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]]:
@@ -546,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:
@@ -561,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]]:
@@ -624,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]:
@@ -829,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):
@@ -888,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:
@@ -901,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")
@@ -909,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:
@@ -954,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]+")
@@ -998,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()
@@ -1016,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` 批量取出多个文件。
 
@@ -1050,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
@@ -1067,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:
@@ -1117,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:
@@ -1164,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 {}
 
@@ -1316,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():
@@ -1333,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
 
 
@@ -1935,7 +2112,7 @@ def main() -> None:
                 "result": {
                     "protocolVersion": "2024-11-05",
                     "capabilities": {"tools": {}},
-                    "serverInfo": {"name": "beacon-mfg-readonly", "version": "1.3.0"},
+                    "serverInfo": {"name": "beacon-mfg-readonly", "version": _pkg_version()},
                 },
             })
         elif method == "notifications/initialized":