@furongjun1999/dsh-memory 0.4.8 → 0.4.9

package/md_cg/test_retr_s1b.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""S1b 细口径桶收敛探针（脚本式，exit code 定成败）。
+
+用法：python -X utf8 -m md_cg.test_retr_s1b
+覆盖：
+- bucket_key_readable：'cond_感知系统_d94e90d2' → '感知系统'；orphan/空 → ''；无哈希段保持
+- 默认关：无 gates 键；关→开→关 结果一致；子开关未设不生效
+- S1b 开：query 侧推断出候选桶 → 候选收敛（out < in）、**orphan/无桶恒留兜底**、不引入任何新节点
+- 命中不到任何桶 → no_key_match 且不收敛（回退）
+- topk / min_sim 可配（topk=0 关闭；min_sim=1.0 只认完全同名键）
+- 幂等：重复检索 / 索引重建后同口径
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg import routing  # noqa: E402
+from md_cg.mdcg import MdCG  # noqa: E402
+
+passed = 0
+failed = 0
+QUERY = "感知系统 记忆 检索"
+
+
+def check(name, cond, detail=""):
+    global passed, failed
+    if cond:
+        passed += 1
+        print("  [PASS] " + name)
+    else:
+        failed += 1
+        print("  [FAIL] " + name + "  " + detail)
+
+
+def _setenv(**kv):
+    old = {}
+    for k, v in kv.items():
+        old[k] = os.environ.get(k)
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+    return old
+
+
+def _restore(old):
+    for k, v in old.items():
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+
+
+def _ids(results):
+    return sorted(r[0]["id"] for r in results)
+
+
+def _build(root):
+    cg = MdCG(root)
+    cg.add("s1", "感知系统 记忆 节点 检索", "knowledge", tags=["domain:感知系统"])
+    cg.add("s2", "感知系统 缓存 命中", "knowledge", tags=["domain:感知系统"])
+    cg.add("g1", "图数据库 遍历 邻接", "knowledge", tags=["domain:图数据库"])
+    cg.add("o1", "感知系统 但无域标签（落 orphan）", "knowledge")
+    cg.add("c1", "感知系统 情境层（不参与分桶）", "contextual")
+    cg.flush()
+    return cg
+
+
+def main():
+    # ---- 1) key 解析 ----
+    check("bucket_key_readable 剥离哈希",
+          routing.bucket_key_readable("cond_感知系统_d94e90d2") == "感知系统")
+    check("bucket_key_readable orphan/空 → ''",
+          routing.bucket_key_readable("orphan") == ""
+          and routing.bucket_key_readable("") == ""
+          and routing.bucket_key_readable(None) == "")
+    check("bucket_key_readable 无哈希段保持",
+          routing.bucket_key_readable("cond_letta-code") == "letta-code")
+
+    root = tempfile.mkdtemp(prefix="retr_s1b_")
+    cg = _build(root)
+    b_sense = [e.get("bucket") for e in cg.index["nodes"].values()
+               if e.get("path", "").endswith("s1.md")][0]
+    check("写入侧确实落了桶", bool(b_sense) and b_sense != "orphan", str(b_sense))
+
+    # ---- 2) 默认关 ----
+    old = _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S1B_BUCKET=None,
+                  MDCG_GATE_S1_DOMAIN=None, MDCG_GATE_S2_COND=None,
+                  MDCG_BUCKET_TOPK=None, MDCG_BUCKET_MIN_SIM=None)
+    r_off, m_off = cg.search(QUERY, k=10, judge=False, record=False)
+    base = _ids(r_off)
+    check("默认关：meta 不含 gates 键", "gates" not in m_off,
+          str(sorted(m_off.keys())))
+
+    # ---- 3) 子开关未设 → 不生效 ----
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0", MDCG_GATE_S1B_BUCKET=None)
+    r_x, m_x = cg.search(QUERY, k=10, judge=False, record=False)
+    check("子开关未设：S1b 不生效",
+          "s1b" not in (m_x.get("gates") or {}) and _ids(r_x) == base,
+          str(m_x.get("gates")))
+
+    # ---- 4) S1b 开：桶收敛 + orphan 兜底 + 不引入新节点 ----
+    _setenv(MDCG_GATE_S1B_BUCKET="1", MDCG_BUCKET_TOPK="1", MDCG_BUCKET_MIN_SIM="0.34")
+    r1, m1 = cg.search(QUERY, k=10, judge=False, record=False)
+    g1 = (m1.get("gates") or {}).get("s1b") or {}
+    ids1 = _ids(r1)
+    check("S1b 推断出感知系统桶",
+          g1.get("keys") == [b_sense], str(g1))
+    check("S1b 收敛：out < in", g1.get("out", 99) < g1.get("in", 0), str(g1))
+    check("S1b 收敛后不引入任何新节点（⊆ 默认关结果集）",
+          set(ids1) <= set(base), str(ids1) + " vs " + str(base))
+    check("S1b 保留 orphan 兜底节点", "o1" in ids1, str(ids1))
+    check("S1b 丢弃异桶节点", "g1" not in ids1, str(ids1))
+
+    # ---- 5) 命中不到桶 → 回退不收敛（与「S1b 关」的同查询结果逐条比较，避免自证）----
+    _setenv(MDCG_GATE_S1B_BUCKET=None)
+    r2c, _m2c = cg.search("完全无关的词 词组", k=10, judge=False, record=False)
+    _setenv(MDCG_GATE_S1B_BUCKET="1")
+    r2, m2 = cg.search("完全无关的词 词组", k=10, judge=False, record=False)
+    g2 = (m2.get("gates") or {}).get("s1b") or {}
+    check("无键命中：no_key_match 且结果与关闭时一致",
+          g2.get("reason") == "no_key_match" and "out" not in g2
+          and _ids(r2) == _ids(r2c),
+          str(g2) + " " + str(_ids(r2)) + " vs " + str(_ids(r2c)))
+    # 5b) S4 显式关闭时 S1b 仍生效（证明门控未与 S4 耦合）
+    _setenv(MDCG_GATE_S4_LAYER="0")
+    r2d, m2d = cg.search(QUERY, k=10, judge=False, record=False)
+    g2d = (m2d.get("gates") or {}).get("s1b") or {}
+    check("S4 显式关闭时 S1b 仍生效",
+          g2d.get("keys") == [b_sense] and "s4" not in (m2d.get("gates") or {}),
+          str(g2d) + " gates=" + str(sorted((m2d.get("gates") or {}).keys())))
+    _setenv(MDCG_GATE_S4_LAYER=None)
+
+    # 5c) 候选不足 → 回退全量（专属小库：两个分桶各 1 节点、无 orphan；min_results=3）
+    root_ins = tempfile.mkdtemp(prefix="retr_s1bins_")
+    cgi = MdCG(root_ins)
+    cgi.add("a1", "感知系统 记忆", "knowledge", tags=["domain:感知系统"])
+    cgi.add("b1", "图数据库 邻接", "knowledge", tags=["domain:图数据库"])
+    cgi.flush()
+    bi = [e.get("bucket") for e in cgi.index["nodes"].values()
+          if e.get("path", "").endswith("a1.md")][0]
+    # 对照组必须用**同一个 min_results**（否则比的是两次不同检索，不是回退等价）
+    _setenv(MDCG_GATE_S1B_BUCKET=None)
+    r_ioff, _m = cgi.search(QUERY, k=10, judge=False, record=False, min_results=3)
+    _setenv(MDCG_GATE_S1B_BUCKET="1")
+    r_ins, m_ins = cgi.search(QUERY, k=10, judge=False, record=False, min_results=3)
+    gi = (m_ins.get("gates") or {}).get("s1b") or {}
+    check("候选不足 → fallback=insufficient",
+          gi.get("fallback") == "insufficient" and gi.get("keys") == [bi], str(gi))
+    check("回退时审计 out 记真实输出（= in，不回退口径误导）",
+          gi.get("out") == gi.get("in") == 2 and gi.get("would_keep") == 1, str(gi))
+    check("回退后结果与 S1b 关闭时一致（含异桶节点）",
+          _ids(r_ins) == _ids(r_ioff) and "b1" in _ids(r_ins),
+          str(_ids(r_ins)) + " vs " + str(_ids(r_ioff)))
+
+    # ---- 6) topk / min_sim 可配 ----
+    _setenv(MDCG_BUCKET_TOPK="0")
+    r3, m3 = cg.search(QUERY, k=10, judge=False, record=False)
+    g3 = (m3.get("gates") or {}).get("s1b") or {}
+    check("topk=0：关闭且候选不变",
+          g3.get("reason") == "disabled_by_topk" and _ids(r3) == base, str(g3))
+    _setenv(MDCG_BUCKET_TOPK="2", MDCG_BUCKET_MIN_SIM="0.0")
+    r4, m4 = cg.search(QUERY, k=10, judge=False, record=False)
+    g4 = (m4.get("gates") or {}).get("s1b") or {}
+    check("topk=2 + min_sim=0：取到 2 个桶",
+          len(g4.get("keys") or []) == 2, str(g4))
+    _setenv(MDCG_BUCKET_TOPK="1", MDCG_BUCKET_MIN_SIM="1.0")
+    r5, m5 = cg.search("感知", k=10, judge=False, record=False)
+    g5 = (m5.get("gates") or {}).get("s1b") or {}
+    check("min_sim=1.0：部分匹配不入选", g5.get("reason") == "no_key_match", str(g5))
+    _setenv(MDCG_BUCKET_MIN_SIM="0.34")
+    r6, m6 = cg.search("感知", k=10, judge=False, record=False)
+    g6 = (m6.get("gates") or {}).get("s1b") or {}
+    check("min_sim=0.34：部分匹配（感知→感知系统 0.5）入选",
+          g6.get("keys") == [b_sense], str(g6))
+
+    # ---- 7) 幂等 ----
+    _setenv(MDCG_BUCKET_TOPK="1", MDCG_BUCKET_MIN_SIM="0.34")
+    ra, ma = cg.search(QUERY, k=10, judge=False, record=False)
+    rb, mb = cg.search(QUERY, k=10, judge=False, record=False)
+    check("S1b 幂等：重复检索同口径",
+          _ids(ra) == _ids(rb)
+          and (ma.get("gates") or {}).get("s1b") == (mb.get("gates") or {}).get("s1b"))
+    cg.rebuild_index()
+    rc, mc = cg.search(QUERY, k=10, judge=False, record=False)
+    check("S1b 幂等：索引重建后同口径",
+          _ids(rc) == _ids(ra)
+          and (mc.get("gates") or {}).get("s1b") == (ma.get("gates") or {}).get("s1b"))
+
+    # ---- 8) 默认口径等价 ----
+    _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S1B_BUCKET=None,
+            MDCG_GATE_S1_DOMAIN=None, MDCG_GATE_S2_COND=None,
+            MDCG_BUCKET_TOPK=None, MDCG_BUCKET_MIN_SIM=None)
+    r9, m9 = cg.search(QUERY, k=10, judge=False, record=False)
+    check("默认口径等价：关→开→关 首末一致",
+          _ids(r9) == base and "gates" not in m9, str(_ids(r9)))
+    _restore(old)
+
+    print("\ntest_retr_s1b: %d 通过 / %d 失败" % (passed, failed))
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())

package/md_cg/test_retr_s3.py

@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""S3 图扩散激活探针（脚本式，exit code 定成败）。
+
+用法：python -X utf8 -m md_cg.test_retr_s3
+覆盖：
+- 默认关：不落 gates 键、结果与开启前后（关→开→关）一致
+- S3 开：沿 edges 双向扩散出候选（TIER_SPREAD），seeds/expanded 审计计数正确
+- hops 控制扩散半径；decay 控制跳数衰减（A > B > C 分数序）
+- 未过 S2 门控的邻居不得被扩散引入
+- 无 edges → expanded=0/reason=no_edges，并落回原 T2/T3 路径（召回不丢）
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg.mdcg import MdCG, TIER_SPREAD  # noqa: E402
+
+passed = 0
+failed = 0
+
+
+def check(name, cond, detail=""):
+    global passed, failed
+    if cond:
+        passed += 1
+        print("  [PASS] " + name)
+    else:
+        failed += 1
+        print("  [FAIL] " + name + "  " + detail)
+
+
+def _setenv(**kv):
+    old = {}
+    for k, v in kv.items():
+        old[k] = os.environ.get(k)
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+    return old
+
+
+def _restore(old):
+    for k, v in old.items():
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+
+
+def _build(root, edges=True, pos_b=None):
+    cg = MdCG(root)
+    cg.add("A", "工程 结构 应力 梁 截面", "knowledge", importance=0.5,
+           condition_space={"observation_position": "工程 结构"})
+    cg.add("B", "qxzq 与检索词无交集", "knowledge", importance=0.5,
+           condition_space={"observation_position": pos_b or "工程 结构"})
+    cg.add("C", "ppyx 另一段无交集文本", "knowledge", importance=0.5,
+           condition_space={"observation_position": "工程 结构"})
+    cg.add("D", "孤立节点 无任何边", "knowledge", importance=0.5,
+           condition_space={"observation_position": "工程 结构"})
+    if edges:
+        cg.append_edge("A", {"target": "B", "relation_type": "related"})
+        cg.append_edge("B", {"target": "C", "relation_type": "related"})
+    cg.flush()
+    return cg
+
+
+def _score_of(results, nid):
+    for r in results:
+        if r[0]["id"] == nid:
+            return r[1]
+    return None
+
+
+def main():
+    root = tempfile.mkdtemp(prefix="retr_s3_")
+    cg = _build(root)
+
+    # ---- 1) 默认关 ----
+    old = _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S1_DOMAIN=None,
+                  MDCG_GATE_S2_COND=None, MDCG_GATE_S3_SPREAD=None)
+    r_off, meta_off = cg.search("工程 应力", k=5, judge=False, record=False)
+    check("默认关：meta 不含 gates 键", "gates" not in meta_off,
+          str(sorted(meta_off.keys())))
+    snap_off = [(r[0]["id"], round(float(r[1]), 6)) for r in r_off]
+
+    # 1b 总开关开、S1/S2 显式关、S3 子开关未设 → S3 必须仍为关（显式 =1 才生效）
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0", MDCG_GATE_S3_SPREAD=None)
+    r_m, m_m = cg.search("工程 应力", k=5, judge=False, record=False)
+    check("S3 子开关未设：不生效（无 gates / 结果不变）",
+          "gates" not in m_m
+          and [(r[0]["id"], round(float(r[1]), 6)) for r in r_m] == snap_off,
+          str(m_m.get("gates")) + " " + str([r[0]["id"] for r in r_m]))
+
+    # ---- 2) S3 开（S1/S2 关），hops=1 ----
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0", MDCG_GATE_S3_SPREAD="1",
+            MDCG_SPREAD_HOPS="1", MDCG_SPREAD_DECAY="0.5",
+            MDCG_SPREAD_GAIN="0.2")
+    r1, m1 = cg.search("工程 应力", k=5, judge=False, record=False)
+    s3 = (m1.get("gates") or {}).get("s3") or {}
+    check("S3 命中种子=1", s3.get("seeds") == 1, str(s3))
+    check("S3 hops=1 扩散出 1 个邻居", s3.get("expanded") == 1, str(s3))
+    check("S3 tier 为扩散层", m1.get("tier") == TIER_SPREAD, str(m1.get("tier")))
+    check("S3 邻居 B 进入结果", _score_of(r1, "B") is not None,
+          str([r[0]["id"] for r in r1]))
+    check("S3 未连通的 D 不进入", _score_of(r1, "D") is None,
+          str([r[0]["id"] for r in r1]))
+
+    # ---- 3) hops=2 扩散到 C，且衰减有序 A > B > C ----
+    _setenv(MDCG_SPREAD_HOPS="2")
+    r2, m2 = cg.search("工程 应力", k=5, judge=False, record=False)
+    s3 = (m2.get("gates") or {}).get("s3") or {}
+    check("S3 hops=2 扩散出 2 个", s3.get("expanded") == 2, str(s3))
+    sa, sb, sc = _score_of(r2, "A"), _score_of(r2, "B"), _score_of(r2, "C")
+    check("S3 衰减有序 A>B>C",
+          sa is not None and sb is not None and sc is not None
+          and sa > sb > sc, "A=%s B=%s C=%s" % (sa, sb, sc))
+
+    # ---- 4) 未过 S2 门控的邻居不得被扩散引入（部分被拦，避免全滤回退掩盖不变量）----
+    rroot = tempfile.mkdtemp(prefix="retr_s3g_")
+    rg = MdCG(rroot)
+    rg.add("A", "工程 结构 应力", "knowledge",
+           condition_space={"observation_position": "工程 结构"})
+    rg.add("B", "qxzq 无交集", "knowledge",
+           condition_space={"observation_position": "医学 疾病"})
+    rg.append_edge("A", {"target": "B", "relation_type": "related"})
+    rg.flush()
+    _setenv(MDCG_GATE_S2_COND="1")
+    r3, m3 = rg.search("工程 应力", k=5, judge=False, record=False,
+                       context={"observation_position": "工程 结构"})
+    g3 = m3.get("gates") or {}
+    ids3 = [r[0]["id"] for r in r3]
+    check("S2 确实拦掉了 B", (g3.get("s2") or {}).get("dropped") == 1,
+          str(g3.get("s2")))
+    check("扩散不得引入被 S2 拦掉的邻居 B",
+          "B" not in ids3 and (g3.get("s3") or {}).get("expanded", 0) == 0,
+          str(ids3) + " " + str(g3.get("s3")))
+    _setenv(MDCG_GATE_S2_COND="0")
+
+    # ---- 5) 无 edges → 不扩散且落回原路径 ----
+    root2 = tempfile.mkdtemp(prefix="retr_s3n_")
+    cg2 = _build(root2, edges=False)
+    r4, m4 = cg2.search("工程 应力", k=5, judge=False, record=False)
+    s3 = (m4.get("gates") or {}).get("s3") or {}
+    check("无 edges：expanded=0 且 reason=no_edges",
+          s3.get("expanded") == 0 and s3.get("reason") == "no_edges", str(s3))
+    check("无 edges：落回原路径且召回不丢",
+          _score_of(r4, "A") is not None and m4.get("tier") != TIER_SPREAD,
+          str(m4.get("tier")))
+
+    # ---- 5b) 幂等：重复检索 / 索引重建后同口径 ----
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0", MDCG_GATE_S3_SPREAD="1",
+            MDCG_SPREAD_HOPS="2", MDCG_SPREAD_DECAY="0.5",
+            MDCG_SPREAD_GAIN="0.2")
+    _snap = lambda rs: [(r[0]["id"], round(float(r[1]), 6)) for r in rs]
+    ra, ma = cg.search("工程 应力", k=5, judge=False, record=False)
+    rb, mb = cg.search("工程 应力", k=5, judge=False, record=False)
+    check("S3 幂等：重复检索同口径",
+          _snap(ra) == _snap(rb)
+          and (ma.get("gates") or {}) == (mb.get("gates") or {}),
+          str(_snap(ra)) + " vs " + str(_snap(rb)))
+    cg.rebuild_index()
+    rc, mc = cg.search("工程 应力", k=5, judge=False, record=False)
+    check("S3 幂等：索引重建后同口径",
+          _snap(rc) == _snap(ra)
+          and (mc.get("gates") or {}) == (ma.get("gates") or {}),
+          str(_snap(rc)) + " vs " + str(_snap(ra)))
+
+    # ---- 6) 默认口径等价（关→开→关）----
+    _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S1_DOMAIN=None,
+            MDCG_GATE_S2_COND=None, MDCG_GATE_S3_SPREAD=None,
+            MDCG_SPREAD_HOPS=None, MDCG_SPREAD_DECAY=None,
+            MDCG_SPREAD_GAIN=None)
+    r_off2, meta_off2 = cg.search("工程 应力", k=5, judge=False, record=False)
+    snap_off2 = [(r[0]["id"], round(float(r[1]), 6)) for r in r_off2]
+    check("默认口径等价：关→开→关 首末一致", snap_off == snap_off2,
+          str(snap_off) + " vs " + str(snap_off2))
+    check("默认关：meta 仍不含 gates 键", "gates" not in meta_off2,
+          str(sorted(meta_off2.keys())))
+    _restore(old)
+
+    print("\ntest_retr_s3: %d 通过 / %d 失败" % (passed, failed))
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())

package/md_cg/test_retr_s4.py

@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""S4 层级激活优先级探针（脚本式，exit code 定成败）。
+
+用法：python -X utf8 -m md_cg.test_retr_s4
+覆盖：
+- layer_boosts 解析（默认副本 / 部分覆盖 / 非法项忽略 / 负值夹 0）
+- 默认关：无 gates 键；关→开→关 结果一致
+- 子开关未设（总开关开）→ S4 不生效
+- 层级加成生效：同内容不同层 → anchor/self > structural > knowledge > contextual
+- 自定义 MDCG_LAYER_BOOST 改变次序；分数上限仍 1.0
+- 只改排序不拉回被门控剔除的节点；幂等（重复检索 / 索引重建）
+"""
+import os
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from md_cg.mdcg import MdCG, layer_boosts, LAYER_BOOST_DEFAULT  # noqa: E402
+
+passed = 0
+failed = 0
+TEXT = "阿尔法 贝塔 伽马 德尔塔"
+# 查询只与正文部分重叠（sim≈0.5），否则精确匹配会把分数顶到 1.0、层级加成看不出来
+QUERY = "阿尔法 泽塔"
+
+
+def check(name, cond, detail=""):
+    global passed, failed
+    if cond:
+        passed += 1
+        print("  [PASS] " + name)
+    else:
+        failed += 1
+        print("  [FAIL] " + name + "  " + detail)
+
+
+def _setenv(**kv):
+    old = {}
+    for k, v in kv.items():
+        old[k] = os.environ.get(k)
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+    return old
+
+
+def _restore(old):
+    for k, v in old.items():
+        if v is None:
+            os.environ.pop(k, None)
+        else:
+            os.environ[k] = v
+
+
+def _scores(results):
+    return {r[0]["id"]: round(float(r[1]), 6) for r in results}
+
+
+def main():
+    # ---- 1) 解析器 ----
+    check("默认表副本（不共享引用）",
+          layer_boosts("") == LAYER_BOOST_DEFAULT
+          and layer_boosts("") is not LAYER_BOOST_DEFAULT)
+    bo = layer_boosts("anchor=0.3,zzz=1,contextual=abc,knowledge=-5")
+    check("部分覆盖 + 非法项忽略 + 负值夹 0",
+          bo["anchor"] == 0.3 and bo["contextual"] == LAYER_BOOST_DEFAULT["contextual"]
+          and bo["knowledge"] == 0.0 and "zzz" in bo, str(bo))
+
+    # ---- 2) 建库：同内容、不同层 ----
+    root = tempfile.mkdtemp(prefix="retr_s4_")
+    cg = MdCG(root)
+    for layer in ("anchor", "self", "structural", "knowledge", "contextual"):
+        cg.add("n_" + layer, TEXT, layer)
+    cg.flush()
+
+    old = _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S4_LAYER=None,
+                  MDCG_LAYER_BOOST=None)
+    r_off, m_off = cg.search(QUERY, k=10, judge=False, record=False)
+    snap_off = _scores(r_off)
+    check("默认关：meta 不含 gates 键", "gates" not in m_off,
+          str(sorted(m_off.keys())))
+    check("默认关：同内容各层分数相同（无加成）",
+          len(set(snap_off.values())) == 1 and 0 < max(snap_off.values()) < 1.0,
+          str(snap_off))
+
+    # 2b 子开关未设（总开关开、S1/S2 显式关）→ S4 不生效
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S4_LAYER=None,
+            MDCG_LAYER_BOOST=None, MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0")
+    r_x, m_x = cg.search(QUERY, k=10, judge=False, record=False)
+    check("子开关未设：S4 不生效",
+          "s4" not in (m_x.get("gates") or {}) and _scores(r_x) == snap_off,
+          str(m_x.get("gates")))
+
+    # ---- 3) S4 开：层级次序 ----
+    _setenv(MDCG_RETRIEVAL_PIPELINE="1", MDCG_GATE_S4_LAYER="1",
+            MDCG_LAYER_BOOST=None, MDCG_GATE_S1_DOMAIN="0",
+            MDCG_GATE_S2_COND="0")
+    r4, m4 = cg.search(QUERY, k=10, judge=False, record=False)
+    sc = _scores(r4)
+    g4 = (m4.get("gates") or {}).get("s4") or {}
+    check("S4 审计含 boosts/layers", bool(g4.get("boosts")) and bool(g4.get("layers")),
+          str(g4)[:160])
+    check("anchor/self > structural > knowledge > contextual",
+          sc["n_anchor"] > sc["n_structural"] > sc["n_knowledge"] > sc["n_contextual"]
+          and sc["n_self"] == sc["n_anchor"],
+          str(sc))
+    check("加成上限：分数不超过 1.0", max(sc.values()) <= 1.0 + 1e-9, str(sc))
+
+    # ---- 4) 自定义加成表改变次序 ----
+    _setenv(MDCG_LAYER_BOOST="contextual=0.5,knowledge=0.0,anchor=0.0,self=0.0,structural=0.0")
+    r5, _m5 = cg.search(QUERY, k=10, judge=False, record=False)
+    sc5 = _scores(r5)
+    check("自定义加成：contextual 升到首位",
+          sc5["n_contextual"] > sc5["n_anchor"], str(sc5))
+
+    # ---- 5) 只改排序，不拉回被门控剔除的节点 ----
+    _setenv(MDCG_LAYER_BOOST=None, MDCG_GATE_S2_COND="1",
+            MDCG_GATE_S1_DOMAIN="0")
+    # 注意：本段临时改了 S1/S2，出段后必须还原，否则幂等段的 gates 不可比
+    root2 = tempfile.mkdtemp(prefix="retr_s4g_")
+    cgg = MdCG(root2)
+    cgg.add("g_ok", TEXT, "knowledge",
+            condition_space={"observation_position": "工程 结构"})
+    cgg.add("g_no", TEXT, "anchor",
+            condition_space={"observation_position": "医学 疾病"})
+    cgg.flush()
+    r6, m6 = cgg.search("阿尔法", k=10, judge=False, record=False,
+                        context={"observation_position": "工程 结构"})
+    ids6 = [r[0]["id"] for r in r6]
+    check("S2 拦掉的节点不因 S4 加成回归",
+          "g_no" not in ids6 and "g_ok" in ids6, str(ids6) + " " + str(m6.get("gates")))
+    _setenv(MDCG_GATE_S2_COND=None, MDCG_GATE_S1_DOMAIN="0")
+
+    # ---- 6) 幂等：重复检索 / 索引重建 ----
+    r7, m7 = cg.search(QUERY, k=10, judge=False, record=False)
+    check("S4 幂等：重复检索同口径",
+          _scores(r7) == sc and (m7.get("gates") or {}) == (m4.get("gates") or {}),
+          str(_scores(r7)))
+    cg.rebuild_index()
+    r8, m8 = cg.search(QUERY, k=10, judge=False, record=False)
+    check("S4 幂等：索引重建后同口径",
+          _scores(r8) == sc and (m8.get("gates") or {}) == (m4.get("gates") or {}),
+          str(_scores(r8)))
+
+    # ---- 7) 默认口径等价（关→开→关）----
+    _setenv(MDCG_RETRIEVAL_PIPELINE=None, MDCG_GATE_S4_LAYER=None,
+            MDCG_LAYER_BOOST=None, MDCG_GATE_S2_COND=None, MDCG_GATE_S1_DOMAIN=None)
+    r9, m9 = cg.search(QUERY, k=10, judge=False, record=False)
+    check("默认口径等价：关→开→关 首末一致",
+          _scores(r9) == snap_off and "gates" not in m9, str(_scores(r9)))
+    _restore(old)
+
+    print("\ntest_retr_s4: %d 通过 / %d 失败" % (passed, failed))
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())