@furongjun1999/dsh-memory 0.4.11 → 0.5.0

package/md_cg/selfreport.py

@@ -1,151 +1,151 @@
-# -*- coding: utf-8 -*-
-"""常驻进程自报：把「我是谁 / 我从哪个 md_cg 包加载 / 我持哪一代 render 契约」
-落成**外部可读的事实**。
-
-# 生效条件：载体/位置：仓根 md_cg/selfreport.py（import 路径 md_cg.selfreport）；时间：常驻 md_cg MCP server 进程启动时由 mcp_server.main 调用 report()；方法：info() 采集进程事实（pid/ppid/cwd/argv/sys.path[0]），source_dir/source_file/render_version 由 codeindex 的实际加载位置与常量求出，report() 原子写 <tempdir>/md_cg_servers/<pid>.json；约束：**任何异常一律吞掉并返回 None/空**——自报是诊断设施，不得成为服务故障源；不记录环境变量值，只记录 MDCG_ROOT/MDCG_TOKEN 是否已设置。
-
-## 为什么需要它（根因，非猜测）
-
-判「一个常驻 md_cg 进程会不会用旧契约覆盖重建成果」，原先只能比「进程启动时间 vs
-md_cg/*.py 最新 mtime」。该判据有**活体盲区**：npm 副本内的进程启动于 11:37~11:39，
-而源码 mtime 为 09:24 —— `stale=False`，但它加载的是插件包 0.4.8 的
-`codeindex.render`（旧契约：合成 `# 生效条件：载体/位置：`），会把全量重建成果刷回
-`old_synth`（AGENTS.md §5 运维注记实证）。mtime 是**相对量**，每次须复算且天然滞后。
-
-自报给的是**绝对事实**：进程**自己**报出它实际加载的 `md_cg` 包目录与契约代际。
-外部脚本据此机械裁决，不再推断。旧包不含本模块，故**「无自报」本身即旧契约的证据**
-（唯一例外见 `scripts/mdcg_stale_servers.py` 的 cwd 兜底分支）。
-
-## 边界
-
-- 自报目录取 `tempfile.gettempdir()`（同用户跨端一致），不依赖 MDCG_ROOT——
-  库根未设时也要能判「进程持哪代契约」。
-- 只报事实，不做裁决：`render_version` 由消费方与本仓 `codeindex.RENDER_VERSION`
-  比对（同源，不写死版本号，避免两处漂移）。
-"""
-from __future__ import annotations
-
-import json
-import os
-import sys
-import tempfile
-import time
-
-# 自报目录：同用户、跨端一致（DSH 与 CodeBuddy 的 python 子进程共用同一 tempdir）。
-SELF_REPORT_DIR = os.path.join(tempfile.gettempdir(), "md_cg_servers")
-# 自报格式代际：本模块自身结构变化时才 +1（与 codeindex.RENDER_VERSION 无关，
-# 后者描述「节点正文由哪代 render 产出」，属索引契约，两者不可混用）。
-SELF_REPORT_SCHEMA = 1
-
-
-# 生效条件：无入参；返回 (source_dir, render_version, source_file)——均取自 codeindex 模块**实际加载位置**（而非本文件所在包），故包被 __path__ 重定向后报的是真源；import 失败时三项均 None，不抛。
-def _source():
-    try:
-        from . import codeindex
-        return (os.path.dirname(os.path.abspath(codeindex.__file__)),
-                getattr(codeindex, "RENDER_VERSION", None),
-                os.path.abspath(codeindex.__file__))
-    except Exception:                     # noqa: BLE001 —— 自报失败降级为 None
-        return None, None, None
-
-
-# 生效条件：tag 为任意字符串（缺省空串）；返回本进程自报字典，键固定为 schema/pid/ppid/ts/iso/tag/cwd/argv/sys_path0/python/source_dir/source_file/render_version/mdcg_root_set/mdcg_token_set；任何取值失败均降级为 None 而不抛。
-def info(tag: str = "") -> dict:
-    """采集本进程事实（纯读取，不写盘）。"""
-    sd, rv, sf = _source()
-    try:
-        cwd = os.getcwd()
-    except Exception:                     # noqa: BLE001
-        cwd = None
-    try:
-        ppid = os.getppid()
-    except Exception:                     # noqa: BLE001
-        ppid = None
-    try:
-        sp0 = sys.path[0] if sys.path else None
-    except Exception:                     # noqa: BLE001
-        sp0 = None
-    now = time.time()
-    return {
-        "schema": SELF_REPORT_SCHEMA,
-        "pid": os.getpid(),
-        "ppid": ppid,
-        "ts": now,
-        "iso": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now)),
-        "tag": str(tag or ""),
-        "cwd": cwd,
-        "argv": list(sys.argv),
-        "sys_path0": sp0,
-        "python": "%d.%d.%d" % sys.version_info[:3],
-        # 只报「是否设置」，不落值——避免令牌/库根出现在可被他人读取的临时文件里。
-        "mdcg_root_set": bool(os.environ.get("MDCG_ROOT")),
-        "mdcg_token_set": bool(os.environ.get("MDCG_TOKEN")),
-        "source_dir": sd,
-        "source_file": sf,
-        "render_version": rv,
-    }
-
-
-# 生效条件：tag 为任意字符串；成功时把 info(tag) 原子写入 <tempdir>/md_cg_servers/<pid>.json（先写 .tmp 再 os.replace），并追加 self_report_path 键后返回该字典；任何异常（目录不可建/不可写/序列化失败）一律吞掉并返回 None——自报故障绝不向上传播。
-def report(tag: str = "mcp_server"):
-    """写自报文件（fail-safe：失败返回 None，不抛）。"""
-    try:
-        data = info(tag)
-        os.makedirs(SELF_REPORT_DIR, exist_ok=True)
-        path = os.path.join(SELF_REPORT_DIR, "%d.json" % data["pid"])
-        tmp = path + ".tmp"
-        with open(tmp, "w", encoding="utf-8") as fh:
-            json.dump(data, fh, ensure_ascii=False, indent=2)
-        os.replace(tmp, path)
-        data["self_report_path"] = path
-        return data
-    except Exception:                     # noqa: BLE001
-        return None
-
-
-# 生效条件：无入参；返回 {pid(int): 自报字典}——读 SELF_REPORT_DIR 下全部 *.json，逐文件 json.loads 失败或 pid 键缺失/非整数者静默跳过（坏文件不使整体失败）；目录不存在时返回空字典。
-def read_all() -> dict:
-    """读全部自报（只读，无副作用）。"""
-    out = {}
-    try:
-        names = os.listdir(SELF_REPORT_DIR)
-    except OSError:
-        return out
-    for n in names:
-        if not n.endswith(".json"):
-            continue
-        try:
-            with open(os.path.join(SELF_REPORT_DIR, n), "r",
-                      encoding="utf-8", errors="replace") as fh:
-                d = json.load(fh)
-            pid = int(d.get("pid"))
-        except Exception:                 # noqa: BLE001
-            continue
-        out[pid] = d
-    return out
-
-
-# 生效条件：pids 为可迭代的 pid 集合（通常是「当前进程表中仍在的 md_cg 进程」）；删除自报目录中 pid 不在该集合内的 *.json 与遗留 *.tmp，返回删除条数；目录不存在或删除失败逐项吞掉，不抛。
-def purge(pids) -> int:
-    """清掉不属于「仍在的进程」的自报文件（防目录随重启次数膨胀）。"""
-    keep = {int(p) for p in (pids or ())}
-    n = 0
-    try:
-        names = os.listdir(SELF_REPORT_DIR)
-    except OSError:
-        return 0
-    for name in names:
-        try:
-            if name.endswith(".tmp"):
-                os.remove(os.path.join(SELF_REPORT_DIR, name))
-                n += 1
-                continue
-            if not name.endswith(".json"):
-                continue
-            if int(name[:-5]) in keep:
-                continue
-            os.remove(os.path.join(SELF_REPORT_DIR, name))
-            n += 1
-        except Exception:                 # noqa: BLE001
-            continue
-    return n
+# -*- coding: utf-8 -*-
+"""常驻进程自报：把「我是谁 / 我从哪个 md_cg 包加载 / 我持哪一代 render 契约」
+落成**外部可读的事实**。
+
+# 生效条件：载体/位置：仓根 md_cg/selfreport.py（import 路径 md_cg.selfreport）；时间：常驻 md_cg MCP server 进程启动时由 mcp_server.main 调用 report()；方法：info() 采集进程事实（pid/ppid/cwd/argv/sys.path[0]），source_dir/source_file/render_version 由 codeindex 的实际加载位置与常量求出，report() 原子写 <tempdir>/md_cg_servers/<pid>.json；约束：**任何异常一律吞掉并返回 None/空**——自报是诊断设施，不得成为服务故障源；不记录环境变量值，只记录 MDCG_ROOT/MDCG_TOKEN 是否已设置。
+
+## 为什么需要它（根因，非猜测）
+
+判「一个常驻 md_cg 进程会不会用旧契约覆盖重建成果」，原先只能比「进程启动时间 vs
+md_cg/*.py 最新 mtime」。该判据有**活体盲区**：npm 副本内的进程启动于 11:37~11:39，
+而源码 mtime 为 09:24 —— `stale=False`，但它加载的是插件包 0.4.8 的
+`codeindex.render`（旧契约：合成 `# 生效条件：载体/位置：`），会把全量重建成果刷回
+`old_synth`（AGENTS.md §5 运维注记实证）。mtime 是**相对量**，每次须复算且天然滞后。
+
+自报给的是**绝对事实**：进程**自己**报出它实际加载的 `md_cg` 包目录与契约代际。
+外部脚本据此机械裁决，不再推断。旧包不含本模块，故**「无自报」本身即旧契约的证据**
+（唯一例外见 `scripts/mdcg_stale_servers.py` 的 cwd 兜底分支）。
+
+## 边界
+
+- 自报目录取 `tempfile.gettempdir()`（同用户跨端一致），不依赖 MDCG_ROOT——
+  库根未设时也要能判「进程持哪代契约」。
+- 只报事实，不做裁决：`render_version` 由消费方与本仓 `codeindex.RENDER_VERSION`
+  比对（同源，不写死版本号，避免两处漂移）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+
+# 自报目录：同用户、跨端一致（DSH 与 CodeBuddy 的 python 子进程共用同一 tempdir）。
+SELF_REPORT_DIR = os.path.join(tempfile.gettempdir(), "md_cg_servers")
+# 自报格式代际：本模块自身结构变化时才 +1（与 codeindex.RENDER_VERSION 无关，
+# 后者描述「节点正文由哪代 render 产出」，属索引契约，两者不可混用）。
+SELF_REPORT_SCHEMA = 1
+
+
+# 生效条件：无入参；返回 (source_dir, render_version, source_file)——均取自 codeindex 模块**实际加载位置**（而非本文件所在包），故包被 __path__ 重定向后报的是真源；import 失败时三项均 None，不抛。
+def _source():
+    try:
+        from . import codeindex
+        return (os.path.dirname(os.path.abspath(codeindex.__file__)),
+                getattr(codeindex, "RENDER_VERSION", None),
+                os.path.abspath(codeindex.__file__))
+    except Exception:                     # noqa: BLE001 —— 自报失败降级为 None
+        return None, None, None
+
+
+# 生效条件：tag 为任意字符串（缺省空串）；返回本进程自报字典，键固定为 schema/pid/ppid/ts/iso/tag/cwd/argv/sys_path0/python/source_dir/source_file/render_version/mdcg_root_set/mdcg_token_set；任何取值失败均降级为 None 而不抛。
+def info(tag: str = "") -> dict:
+    """采集本进程事实（纯读取，不写盘）。"""
+    sd, rv, sf = _source()
+    try:
+        cwd = os.getcwd()
+    except Exception:                     # noqa: BLE001
+        cwd = None
+    try:
+        ppid = os.getppid()
+    except Exception:                     # noqa: BLE001
+        ppid = None
+    try:
+        sp0 = sys.path[0] if sys.path else None
+    except Exception:                     # noqa: BLE001
+        sp0 = None
+    now = time.time()
+    return {
+        "schema": SELF_REPORT_SCHEMA,
+        "pid": os.getpid(),
+        "ppid": ppid,
+        "ts": now,
+        "iso": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now)),
+        "tag": str(tag or ""),
+        "cwd": cwd,
+        "argv": list(sys.argv),
+        "sys_path0": sp0,
+        "python": "%d.%d.%d" % sys.version_info[:3],
+        # 只报「是否设置」，不落值——避免令牌/库根出现在可被他人读取的临时文件里。
+        "mdcg_root_set": bool(os.environ.get("MDCG_ROOT")),
+        "mdcg_token_set": bool(os.environ.get("MDCG_TOKEN")),
+        "source_dir": sd,
+        "source_file": sf,
+        "render_version": rv,
+    }
+
+
+# 生效条件：tag 为任意字符串；成功时把 info(tag) 原子写入 <tempdir>/md_cg_servers/<pid>.json（先写 .tmp 再 os.replace），并追加 self_report_path 键后返回该字典；任何异常（目录不可建/不可写/序列化失败）一律吞掉并返回 None——自报故障绝不向上传播。
+def report(tag: str = "mcp_server"):
+    """写自报文件（fail-safe：失败返回 None，不抛）。"""
+    try:
+        data = info(tag)
+        os.makedirs(SELF_REPORT_DIR, exist_ok=True)
+        path = os.path.join(SELF_REPORT_DIR, "%d.json" % data["pid"])
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, indent=2)
+        os.replace(tmp, path)
+        data["self_report_path"] = path
+        return data
+    except Exception:                     # noqa: BLE001
+        return None
+
+
+# 生效条件：无入参；返回 {pid(int): 自报字典}——读 SELF_REPORT_DIR 下全部 *.json，逐文件 json.loads 失败或 pid 键缺失/非整数者静默跳过（坏文件不使整体失败）；目录不存在时返回空字典。
+def read_all() -> dict:
+    """读全部自报（只读，无副作用）。"""
+    out = {}
+    try:
+        names = os.listdir(SELF_REPORT_DIR)
+    except OSError:
+        return out
+    for n in names:
+        if not n.endswith(".json"):
+            continue
+        try:
+            with open(os.path.join(SELF_REPORT_DIR, n), "r",
+                      encoding="utf-8", errors="replace") as fh:
+                d = json.load(fh)
+            pid = int(d.get("pid"))
+        except Exception:                 # noqa: BLE001
+            continue
+        out[pid] = d
+    return out
+
+
+# 生效条件：pids 为可迭代的 pid 集合（通常是「当前进程表中仍在的 md_cg 进程」）；删除自报目录中 pid 不在该集合内的 *.json 与遗留 *.tmp，返回删除条数；目录不存在或删除失败逐项吞掉，不抛。
+def purge(pids) -> int:
+    """清掉不属于「仍在的进程」的自报文件（防目录随重启次数膨胀）。"""
+    keep = {int(p) for p in (pids or ())}
+    n = 0
+    try:
+        names = os.listdir(SELF_REPORT_DIR)
+    except OSError:
+        return 0
+    for name in names:
+        try:
+            if name.endswith(".tmp"):
+                os.remove(os.path.join(SELF_REPORT_DIR, name))
+                n += 1
+                continue
+            if not name.endswith(".json"):
+                continue
+            if int(name[:-5]) in keep:
+                continue
+            os.remove(os.path.join(SELF_REPORT_DIR, name))
+            n += 1
+        except Exception:                 # noqa: BLE001
+            continue
+    return n

package/md_cg/semantic/__init__.py

@@ -1,10 +1,10 @@
-# -*- coding: utf-8 -*-
-"""灵枢语义层（semantic IR）· 原子级中英归一管线。
-
-模块：
-  - atoms.json        语义原子（815）
-  - zh_en_atoms.py    中文文本 → 标准英文原子序列
-  - en_normalizer.py  英文 query → 中文语素序列（检索归一）
-  - build_en_index.py 英文词 → 中文原子倒排索引构建
-  - SCHEMA.md         IR schema v0.1
-"""
+# -*- coding: utf-8 -*-
+"""灵枢语义层（semantic IR）· 原子级中英归一管线。
+
+模块：
+  - atoms.json        语义原子（815）
+  - zh_en_atoms.py    中文文本 → 标准英文原子序列
+  - en_normalizer.py  英文 query → 中文语素序列（检索归一）
+  - build_en_index.py 英文词 → 中文原子倒排索引构建
+  - SCHEMA.md         IR schema v0.1
+"""

package/md_cg/semantic/canonical.py

@@ -1,122 +1,122 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""灵枢 · 标准语义归一面（词表真源 + AI 写入侧归一 + 组合相遇判据）
-
-使用者设想（2026-09-14）四要素与代码边界：
-  ① 标准语义基准     = atoms.json（815 标准概念，词表唯一真源，本模块只读加载）；
-  ② 同义体按基准翻译 = 归一主体是 **AI 写入侧**（AI 自带翻译，add(semantic=...)
-    直接传标准原子序列；「荤油→猪油」类同义归一发生在 AI 理解里，
-    代码不维护同义表——系统职责收缩为词表+校验）；
-  ③ 归一产物作摘要   = fm.semantic 衍生层（可审查、可版本化）；
-  ④ 真源+原始双保留 = semantic 是 frontmatter 衍生层，正文原文无损——
-    归一错误传播仅限摘要层，词表更新后重归一可修复。
-
-代码职责（最小三件，全部纯函数）：
-  - atoms_zh()   词表加载（模块级缓存）；
-  - oov_of()     OOV 审计（警告不拒绝：词表覆盖有限，拒绝会堵死合法写入；
-                 OOV 列表落 fm.semantic_oov，同时是词表扩容的观测依据）；
-  - pair_hits()  检索面组合窗口共现判据。窗口语义来自 L3 探针实证
-                 （2026-09-14）：纯邻接只救 1/3（「羊 的 油」「鱼 里 提 取
-                 的 油」距离 2/4），win=6 全救 3/3 且受控池零误配；
-                 开放域「鱼和油分述」的误配风险由组合结构约束兜底
-                 （与 P1 compositions 汇合，b2_comp 臂为共同验收器）。
-"""
-import functools
-import json
-import os
-import re
-
-from . import zh_en_atoms
-
-WIN = 6          # 组合共现窗口（token 距离，探针实证口径）
-_ATOMS_ZH = None
-
-
-# 生效条件：模块级常量 `_ATOMS_ZH` 为 None 时按 `__file__` 所在目录的 atoms.json 取 `data.get("atoms", [])` 各项 `zh` 建集合并缓存，非 None 时直接返回 `_ATOMS_ZH`。
-def atoms_zh():
-    """标准语义基准词表（atoms.json 的 zh 概念集，模块级缓存）。"""
-    global _ATOMS_ZH
-    if _ATOMS_ZH is None:
-        p = os.path.join(os.path.dirname(os.path.abspath(__file__)),
-                         "atoms.json")
-        with open(p, encoding="utf-8") as f:
-            data = json.load(f)
-        _ATOMS_ZH = {a["zh"] for a in data.get("atoms", [])}
-    return _ATOMS_ZH
-
-
-# 生效条件：`text` 为 None 或空串时 `(text or "").split()` 得空序列、返回空列表 out；否则按空白切分后逐段经 `zh_en_atoms.segment` 展开 extend 进 out 并返回。
-def semantic_atoms(text):
-    """semantic 字段容错切分：按空格分段逐段贪心匹配。
-
-    兼容「鱼油」（AI 给了复合词）与「鱼 油」（AI 直接给原子序列）两种
-    写入形态——代码不二次加工 AI 产物，只在读取面做无损容错解析。
-    未映射字符原样保留（归一可逆可溯源）。
-    """
-    out = []
-    for part in (text or "").split():
-        out.extend(zh_en_atoms.segment(part))
-    return out
-
-
-# 生效条件：`text` 传入后，返回 `semantic_atoms(text)` 结果中不属于 `atoms_zh()` 词表集合的 token 列表（无匹配项时为空列表）。
-def oov_of(text):
-    """OOV 审计：切分产物中不在标准词表的 token 列表（空列表=全部合法）。"""
-    zh = atoms_zh()
-    return [a for a in semantic_atoms(text) if a not in zh]
-
-
-@functools.lru_cache(maxsize=256)
-# 生效条件：t = text or ""（text 为 None/空串时按 ""），仅当 t 含 [A-Za-z] 时经 normalize_en_query 归一——含字母的 term 原样保留、其余经 zh_en_atoms.segment 展开——返回 tuple(out)；归一抛异常或 t 无字母时返回 tuple(semantic_atoms(t))；
-def query_atoms(text):
-    """query 侧归一（同 semantic_atoms，缓存——每轮检索全 doc 复用）。
-
-    英文 query 汇入同一标准真源（2026-09-14）：含 [A-Za-z] 时先经
-    en_normalizer 归一为中文语素（复合概念整词映射，beef→牛肉），中文
-    语素再经 segment 展开为标准原子（「牛肉」→「牛 肉」，与 doc 侧
-    fm.semantic 的原子形态同构），英文保留词（专名/未登录词）原样
-    占位——是词表覆盖边界，非错误。纯中文 query 零变化（不触发英文
-    分支）。归一失败静默保持原文本（与 en_zh_terms 同降级风格）。
-    """
-    t = text or ""
-    if re.search(r"[A-Za-z]", t):
-        try:
-            from .en_normalizer import normalize_en_query
-            terms, _detail = normalize_en_query(t)
-            out = []
-            for term in terms:
-                if re.search(r"[A-Za-z]", term):
-                    out.append(term)                        # 英文保留词原样
-                else:
-                    out.extend(zh_en_atoms.segment(term))   # 中文语素→标准原子
-            return tuple(out)
-        except Exception:
-            pass
-    return tuple(semantic_atoms(t))
-
-
-# 生效条件：`doc_semantic` 经 `semantic_atoms` 切分后相邻原子对集合 pairs 为空（单原子或无原子）时返回 0.0；否则以 `query_atoms(qtext)` 建立 token→位置表，统计两原子位置差绝对值 ≤ `win`（默认形参 WIN）的命中对数 hit，返回 hit/len(pairs)。
-def pair_hits(doc_semantic, qtext, win=WIN):
-    """组合窗口共现命中率 ∈ [0,1]。
-
-    doc 侧：fm.semantic 的相邻原子对集合（标准语义基准上的组合结构）；
-    query 侧：query_atoms(qtext) 归一序列；
-    命中：对内两原子在 query 序列中窗口 win 内共现。
-    分数 = 命中对数 / doc 对数；doc 无相邻对（单原子摘要）→ 0.0（诚实）。
-    """
-    doc = semantic_atoms(doc_semantic)
-    pairs = {(doc[i], doc[i + 1]) for i in range(len(doc) - 1)}
-    if not pairs:
-        return 0.0
-    q = query_atoms(qtext)
-    qset = set(q)
-    idx = {}
-    for i, t in enumerate(q):
-        idx.setdefault(t, []).append(i)
-    hit = 0
-    for a, b in pairs:
-        if a not in qset or b not in qset:
-            continue
-        if any(abs(i - j) <= win for i in idx[a] for j in idx[b]):
-            hit += 1
-    return hit / len(pairs)
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""灵枢 · 标准语义归一面（词表真源 + AI 写入侧归一 + 组合相遇判据）
+
+使用者设想（2026-09-14）四要素与代码边界：
+  ① 标准语义基准     = atoms.json（815 标准概念，词表唯一真源，本模块只读加载）；
+  ② 同义体按基准翻译 = 归一主体是 **AI 写入侧**（AI 自带翻译，add(semantic=...)
+    直接传标准原子序列；「荤油→猪油」类同义归一发生在 AI 理解里，
+    代码不维护同义表——系统职责收缩为词表+校验）；
+  ③ 归一产物作摘要   = fm.semantic 衍生层（可审查、可版本化）；
+  ④ 真源+原始双保留 = semantic 是 frontmatter 衍生层，正文原文无损——
+    归一错误传播仅限摘要层，词表更新后重归一可修复。
+
+代码职责（最小三件，全部纯函数）：
+  - atoms_zh()   词表加载（模块级缓存）；
+  - oov_of()     OOV 审计（警告不拒绝：词表覆盖有限，拒绝会堵死合法写入；
+                 OOV 列表落 fm.semantic_oov，同时是词表扩容的观测依据）；
+  - pair_hits()  检索面组合窗口共现判据。窗口语义来自 L3 探针实证
+                 （2026-09-14）：纯邻接只救 1/3（「羊 的 油」「鱼 里 提 取
+                 的 油」距离 2/4），win=6 全救 3/3 且受控池零误配；
+                 开放域「鱼和油分述」的误配风险由组合结构约束兜底
+                 （与 P1 compositions 汇合，b2_comp 臂为共同验收器）。
+"""
+import functools
+import json
+import os
+import re
+
+from . import zh_en_atoms
+
+WIN = 6          # 组合共现窗口（token 距离，探针实证口径）
+_ATOMS_ZH = None
+
+
+# 生效条件：模块级常量 `_ATOMS_ZH` 为 None 时按 `__file__` 所在目录的 atoms.json 取 `data.get("atoms", [])` 各项 `zh` 建集合并缓存，非 None 时直接返回 `_ATOMS_ZH`。
+def atoms_zh():
+    """标准语义基准词表（atoms.json 的 zh 概念集，模块级缓存）。"""
+    global _ATOMS_ZH
+    if _ATOMS_ZH is None:
+        p = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                         "atoms.json")
+        with open(p, encoding="utf-8") as f:
+            data = json.load(f)
+        _ATOMS_ZH = {a["zh"] for a in data.get("atoms", [])}
+    return _ATOMS_ZH
+
+
+# 生效条件：`text` 为 None 或空串时 `(text or "").split()` 得空序列、返回空列表 out；否则按空白切分后逐段经 `zh_en_atoms.segment` 展开 extend 进 out 并返回。
+def semantic_atoms(text):
+    """semantic 字段容错切分：按空格分段逐段贪心匹配。
+
+    兼容「鱼油」（AI 给了复合词）与「鱼 油」（AI 直接给原子序列）两种
+    写入形态——代码不二次加工 AI 产物，只在读取面做无损容错解析。
+    未映射字符原样保留（归一可逆可溯源）。
+    """
+    out = []
+    for part in (text or "").split():
+        out.extend(zh_en_atoms.segment(part))
+    return out
+
+
+# 生效条件：`text` 传入后，返回 `semantic_atoms(text)` 结果中不属于 `atoms_zh()` 词表集合的 token 列表（无匹配项时为空列表）。
+def oov_of(text):
+    """OOV 审计：切分产物中不在标准词表的 token 列表（空列表=全部合法）。"""
+    zh = atoms_zh()
+    return [a for a in semantic_atoms(text) if a not in zh]
+
+
+@functools.lru_cache(maxsize=256)
+# 生效条件：t = text or ""（text 为 None/空串时按 ""），仅当 t 含 [A-Za-z] 时经 normalize_en_query 归一——含字母的 term 原样保留、其余经 zh_en_atoms.segment 展开——返回 tuple(out)；归一抛异常或 t 无字母时返回 tuple(semantic_atoms(t))；
+def query_atoms(text):
+    """query 侧归一（同 semantic_atoms，缓存——每轮检索全 doc 复用）。
+
+    英文 query 汇入同一标准真源（2026-09-14）：含 [A-Za-z] 时先经
+    en_normalizer 归一为中文语素（复合概念整词映射，beef→牛肉），中文
+    语素再经 segment 展开为标准原子（「牛肉」→「牛 肉」，与 doc 侧
+    fm.semantic 的原子形态同构），英文保留词（专名/未登录词）原样
+    占位——是词表覆盖边界，非错误。纯中文 query 零变化（不触发英文
+    分支）。归一失败静默保持原文本（与 en_zh_terms 同降级风格）。
+    """
+    t = text or ""
+    if re.search(r"[A-Za-z]", t):
+        try:
+            from .en_normalizer import normalize_en_query
+            terms, _detail = normalize_en_query(t)
+            out = []
+            for term in terms:
+                if re.search(r"[A-Za-z]", term):
+                    out.append(term)                        # 英文保留词原样
+                else:
+                    out.extend(zh_en_atoms.segment(term))   # 中文语素→标准原子
+            return tuple(out)
+        except Exception:
+            pass
+    return tuple(semantic_atoms(t))
+
+
+# 生效条件：`doc_semantic` 经 `semantic_atoms` 切分后相邻原子对集合 pairs 为空（单原子或无原子）时返回 0.0；否则以 `query_atoms(qtext)` 建立 token→位置表，统计两原子位置差绝对值 ≤ `win`（默认形参 WIN）的命中对数 hit，返回 hit/len(pairs)。
+def pair_hits(doc_semantic, qtext, win=WIN):
+    """组合窗口共现命中率 ∈ [0,1]。
+
+    doc 侧：fm.semantic 的相邻原子对集合（标准语义基准上的组合结构）；
+    query 侧：query_atoms(qtext) 归一序列；
+    命中：对内两原子在 query 序列中窗口 win 内共现。
+    分数 = 命中对数 / doc 对数；doc 无相邻对（单原子摘要）→ 0.0（诚实）。
+    """
+    doc = semantic_atoms(doc_semantic)
+    pairs = {(doc[i], doc[i + 1]) for i in range(len(doc) - 1)}
+    if not pairs:
+        return 0.0
+    q = query_atoms(qtext)
+    qset = set(q)
+    idx = {}
+    for i, t in enumerate(q):
+        idx.setdefault(t, []).append(i)
+    hit = 0
+    for a, b in pairs:
+        if a not in qset or b not in qset:
+            continue
+        if any(abs(i - j) <= win for i in idx[a] for j in idx[b]):
+            hit += 1
+    return hit / len(pairs)