@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/md_cg/bench_unified_en.py

@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+"""locomo-zh-500 英文侧统一标准真源路复测（2026-09-14）。
+
+背景：统一标准真源语义路（MDCG_SEMANTIC=1，semantic/canonical.py）已在受控
+盲测（bench_blind_comp b3_unified 臂）实证「英文原题经 query_atoms 内部归一
+（en_normalizer→中文语素→标准原子）直查 fm.semantic 摘要，L2 hit@1=100%」。
+本脚本回答开放域问题：真实 locomo 语料 + 500 道英文原题上，统一真源路净效应
+多大？en→zh 归一词表覆盖瓶颈多大？
+
+三臂（同题同池，只变 doc 侧正文形态与开关）：
+
+* u0_en_lex  ：doc=英文原文正文（text+[date]），默认词法路——英文 char-bigram
+  对英文正文的词法基线（现状跨语答案所在层的对照组）；
+* u1_unified ：doc=英文原文正文 + fm.semantic=segment(中文摘要)（AI 写入侧
+  归一的规则近似下界），MDCG_SEMANTIC=1，英文原题直查——语义增量 = u1-u0；
+* u2_pure_zh ：doc=中文五槽正文（zh）+ fm.semantic 同上，英文原题直查——
+  英文 query 对中文正文词法零交集，唯一通路就是归一原子与语义资格层——
+  「英文检索路径归一化到统一标准真源」的最强形态。
+
+诚实边界（报告须原样引用）：
+
+* fm.semantic 为规则切分（segment）非 AI 真实归一——下界口径；
+* en→zh 归一词表（EN_ZH 手工表）远小于中文原子空间，英文专名/域词保留原文
+  → 对中文 doc 零命中——词表覆盖瓶颈按题级 OOV 统计报告；
+* 池全为 gold 证据语料（bench6 同源口径）→ 指标是上界而非端到端记忆能力；
+* question_en 是英文自然语言问句，中文侧 questions500.question 是关键词串
+  → 本测只与自身三臂对照，不与中文口径 94.6/99.2 直接比（题面形态不同）。
+
+跑法：python -m md_cg.bench_unified_en
+"""
+import json
+import os
+import shutil
+import sys
+import time
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+for _p in (HERE, os.path.join(HERE, "md_cg")):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from md_cg import eval_common as ec            # noqa: E402
+from md_cg import bench6_common as b6          # noqa: E402  口径/数据源复用
+from md_cg.mdcos import MdCGOS                 # noqa: E402
+from md_cg.semantic.canonical import semantic_atoms, query_atoms  # noqa: E402
+
+ARM_ROOT = os.path.join(HERE, "_md_cg_eval_unified_en")  # gitignore 已覆盖
+K = 10
+
+
+def build(root, corpus, semantic_of=None, zh_body=False):
+    """单库构建：正文形态与 fm.semantic 摘要层是仅有的两个自由度。"""
+    if os.path.isdir(root):
+        shutil.rmtree(root, ignore_errors=True)
+    cg = MdCGOS(root, autoflush=500)
+    for c in corpus:
+        kw = {}
+        if semantic_of is not None:
+            sem = semantic_of(c)
+            if sem:
+                kw["semantic"] = sem
+        body = c.get("zh") if zh_body else b6.ingest_text_en(c)
+        cg.add(c["id"], body, layer="knowledge",
+               eval_src="unified_en", verification_basis="data", **kw)
+    cg.flush()
+    ec.install_read_cache(cg)
+    return cg
+
+
+def run_arm(cg, questions, tag, semantic=False):
+    if semantic:
+        os.environ["MDCG_SEMANTIC"] = "1"
+    else:
+        os.environ.pop("MDCG_SEMANTIC", None)
+    rows = ec.evaluate_group(cg, questions, k=K, paths=("lexical",),
+                             judge=False, verbose=False)
+    summ = ec.summarize(rows, k=K)
+    by_type = {"ALL": summ}
+    for qt in sorted({r["qtype"] for r in rows}):
+        sub = [r for r in rows if r["qtype"] == qt]
+        by_type[qt] = ec.summarize(sub, k=K)
+    return rows, by_type
+
+
+def oov_stats(questions):
+    """题级 en→zh 归一覆盖统计：英文保留词占比 = 词表覆盖瓶颈的直接量化。"""
+    n_tok = n_keep = n_q_with_keep = 0
+    for q in questions:
+        atoms = query_atoms(q["question"])
+        keeps = [a for a in atoms if any("A" <= ch <= "z" for ch in a)]
+        n_tok += len(atoms)
+        n_keep += len(keeps)
+        if keeps:
+            n_q_with_keep += 1
+    return {"n_questions": len(questions),
+            "n_atoms": n_tok,
+            "n_en_keep": n_keep,
+            "keep_ratio": round(n_keep / n_tok, 4) if n_tok else 0.0,
+            "q_with_keep_ratio": round(n_q_with_keep / len(questions), 4)
+            if questions else 0.0}
+
+
+def main():
+    t0 = time.time()
+    rows500 = list(ec.iter_jsonl(b6.QUESTIONS500))
+    corpus = list(ec.iter_jsonl(b6.CORPUS567))
+    en_by_qid = {r["qid"]: r for r in ec.iter_jsonl(b6.EN_QUESTIONS)}
+    # 全量 500 题（不抽样），中英 qrels 逐字一致断言复用 bench6 口径
+    questions = b6.align_queries(rows500, en_by_qid)
+    for q in questions:
+        q["question"] = q["question_en"]        # 英文原题直查
+    print("[unified_en] 题 %d（英文原题全量）/ 语料 %d / k=%d"
+          % (len(questions), len(corpus), K))
+
+    ec.unlock_global_cap()
+    ec.use_jaccard()
+
+    def sem_of(c):
+        s = str((c.get("zh_fields") or {}).get("summary") or "").strip()
+        if not s:
+            s = str(c.get("zh") or "").strip()
+        return " ".join(semantic_atoms(s)) if s else ""
+
+    out = {"n_q": len(questions), "n_corpus": len(corpus), "k": K,
+           "arms": {}, "oov": oov_stats(questions),
+           "semantic_rule": "segment(zh_fields.summary)，OOV 保留——规则近似下界"}
+
+    cg0 = build(os.path.join(ARM_ROOT, "u0"), corpus)               # 英文正文
+    cg1 = build(os.path.join(ARM_ROOT, "u1"), corpus, sem_of)       # +semantic
+    cg2 = build(os.path.join(ARM_ROOT, "u2"), corpus, sem_of,
+                zh_body=True)                                        # 纯中文库
+    arms = ((cg0, "u0_en_lex", False),
+            (cg1, "u1_unified", True),
+            (cg2, "u2_pure_zh", True))
+    # CLI：--arms u2,u2c 只跑指定臂（归因探针用）；--out 改结果文件名
+    argv = sys.argv[1:]
+    only = None
+    out_name = "unified_en_baseline.json"
+    if "--arms" in argv:
+        only = set(argv[argv.index("--arms") + 1].split(","))
+        arms = tuple((cg, tag, sem) for cg, tag, sem in arms if tag in only)
+    if "--out" in argv:
+        out_name = argv[argv.index("--out") + 1]
+    if not arms:
+        print("[arms] 无匹配臂")
+        return
+    for cg, tag, sem in arms:
+        _rows, by_type = run_arm(cg, questions, tag, semantic=sem)
+        out["arms"][tag] = by_type
+        mode = ("MDCG_SEMANTIC=1" if sem else "词法默认") + \
+               (" + fm.semantic 摘要层" if sem else "")
+        print("\n== 臂 %s（%s）==" % (tag, mode))
+        for name, s in by_type.items():
+            print("  %-18s hit@1=%6.1f%%  hit@%d=%6.1f%%  MRR=%.4f  (n=%d)"
+                  % (name, s["hit@1"] * 100, K, s["hit@%d" % K] * 100,
+                     s["mrr"], s["n"]))
+        if tag == "u2_pure_zh":
+            # 归因臂 u2c：中文关键词原题 × 同一纯中文库 × 同一语义路——
+            # 钉「语义路机制 + doc 侧摘要」上界。u2c 远高于 u2 → 瓶颈纯在
+            # query 侧 en→zh 归一（扩表有效）；u2c 亦低 → 瓶颈在 win6 共现
+            # 机制或 doc 侧，扩表无效。
+            zh_q = [dict(q, question=q["question_zh"]) for q in questions]
+            _rc, by_c = run_arm(cg, zh_q, "u2c", semantic=True)
+            out["arms"]["u2c_zh_sem_attribution"] = by_c
+            print("== 臂 u2c_zh_sem_attribution（中文题面 × 同库同语义路，归因上界）==")
+            for name, s in by_c.items():
+                print("  %-18s hit@1=%6.1f%%  hit@%d=%6.1f%%  MRR=%.4f  (n=%d)"
+                      % (name, s["hit@1"] * 100, K, s["hit@%d" % K] * 100,
+                         s["mrr"], s["n"]))
+        cg.close()
+
+    a0, a1, a2 = ((out["arms"].get(t) or {}).get("ALL") for t in
+                  ("u0_en_lex", "u1_unified", "u2_pure_zh"))
+    if not all((a0, a1, a2)):
+        print("[arms] 单臂探针模式，跳过 deltas")
+        ec.save_result(out_name, out)
+        print("\n[unified_en] 完成（%.1fs），结果已存 %s"
+              % (time.time() - t0, out_name))
+        return
+    out["deltas"] = {
+        "u1_minus_u0_hit@1": round(a1["hit@1"] - a0["hit@1"], 4),
+        "u1_minus_u0_hit@10": round(a1["hit@%d" % K] - a0["hit@%d" % K], 4),
+    }
+    out["elapsed_s"] = round(time.time() - t0, 1)
+    out["boundaries"] = [
+        "池全为 gold 证据语料 → 指标是上界而非端到端记忆能力",
+        "fm.semantic=规则切分（segment），非 AI 真实归一 → 下界口径",
+        "英文题面为自然问句，中文口径 94.6/99.2 的题面是关键词串——"
+        "两口径题面形态不同，不可直接比较",
+        "en→zh 归一词表覆盖瓶颈见 out.oov（英文保留词占比）——扩表是明确路径",
+        "u2 纯中文库上英文词法零交集 → 该臂成绩全部来自统一真源语义路",
+        "u2c 归因臂=中文题面×同库×同语义路 → u2c−u2 差值即 query 侧归一缺口，"
+        "u2c 自身即机制+doc 侧上界",
+    ]
+    ec.save_result(out_name, out)
+    print("\n[unified_en] 完成（%.1fs），结果已存 %s" % (out["elapsed_s"], out_name))
+
+
+if __name__ == "__main__":
+    main()

package/md_cg/branches.py

@@ -0,0 +1,275 @@
+# -*- coding: utf-8 -*-
+"""记忆演化分支（Pi 机制移植④，交接文档 §3④「记忆演化 fork」，P0）。
+
+pi：会话 = entry 树，任意历史节点可 fork；被放弃旁支由 branch_summary
+归档定长摘要。灵枢映射（单一演化线 → 假设分支实验场）：
+
+- fork：把主支节点复制成分支实验副本（fm.branch_id / branched_from），
+  副本 derived_from=[主支]、relation="split_from"——血缘单向可回溯；
+- 分支节点默认从主支检索隐身（_candidates 按 branch 过滤，一处生效
+  全链路穿透）——实验不污染主支（验收：召回主支时分支节点零命中）；
+- merge：按 branched_from 溯源回写主支（derived_from=[分支 nid] 追加进
+  主支原链、relation="merged_from"），override 走快照——合并后链完整；
+- discard：校验 BRANCH_MARKS 必填 → 写教训节点（knowledge 层、可检索）
+  → 分支文件移入冷区 _branches/<id>/（物理保留、索引摘除、永不删除）。
+
+与 writepipe 同哲学：库层函数收 cg，权限闸保持库层强制——
+fork/merge 走 add 的 require_layer_write 自动覆盖；
+discard 改变库可见性，需 can_admin（principal.require_admin）。
+生命周期事件走 _audit.jsonl（③ 两段式载体，零新日志格式）。
+"""
+
+import os
+import re
+import uuid
+
+#: discard 的 branch_summary 必填标记（复用 NEG_MEMORY_MARKS 的必填防呆模式：
+#: 「假设 + 结果 + 教训」缺一不收——放弃分支必须留下可复用的教训）。
+BRANCH_MARKS = ("分支假设", "实验结果", "教训")
+
+#: 分支文件冷区（LAYERS 之外，_scan_nodes 不扫——天然不进索引与检索）。
+COLD_DIR = "_branches"
+
+_BRANCH_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+
+def branch_tag(branch_id: str) -> str:
+    """分支节点的标注 tag（fork 时写入；branch_summary 也带它以便反查）。"""
+    return "branch:" + str(branch_id or "").strip().lower()
+
+
+def branch_node_id(orig: str, branch_id: str) -> str:
+    """分支副本 id：`<主支nid>@<branch_id>`（@ 文件名合法、撞名不可能）。"""
+    return "%s@%s" % (orig, str(branch_id or "").strip().lower())
+
+
+def _audit(cg, op: str, **meta) -> None:
+    """生命周期留痕；审计失败绝不阻断主流程（G8 同哲学）。"""
+    a = getattr(cg, "_audit", None)
+    if a is None:
+        return
+    try:
+        a(op, None, **meta)
+    except Exception:
+        pass
+
+
+def _iter_branch_nodes(cg, branch_id: str):
+    bid = str(branch_id or "").strip().lower()
+    return [(k, v) for k, v in (cg.index.get("nodes") or {}).items()
+            if v.get("branch_id") == bid]
+
+
+def _fm_of(rec):
+    """get 返回形态兼容：{'frontmatter': fm, 'content': c} 或平铺 fm。"""
+    if not rec:
+        return {}
+    return rec.get("frontmatter") or rec
+
+
+def fork(cg, node_ids, branch_id=None, note=None) -> dict:
+    """把主支节点复制成分支实验副本。
+
+    返回 {ok, branch_id, tag, forked:[{from,to}], skipped:[{id,why}]}。
+    幂等：同 (主支节点, branch_id) 的副本已存在则 skipped，不重复复制。
+    """
+    ids = [str(x).strip() for x in (node_ids or []) if str(x).strip()]
+    if not ids:
+        return {"ok": False, "error": "node_ids 为空（至少指定一个主支节点）"}
+    if branch_id is None:
+        branch_id = "br_" + uuid.uuid4().hex[:8]
+    branch_id = str(branch_id).strip().lower()
+    if not _BRANCH_RE.match(branch_id):
+        return {"ok": False, "error": "branch_id 非法（%s）：%r"
+                % (_BRANCH_RE.pattern, branch_id)}
+    forked, skipped = [], []
+    for nid in ids:
+        if "@" in nid:
+            skipped.append({"id": nid, "why": "已是分支节点，不支持再 fork"})
+            continue
+        rec = cg.get(nid)
+        if not rec:
+            skipped.append({"id": nid, "why": "主支节点不存在或不可见"})
+            continue
+        fm = _fm_of(rec)
+        bid = branch_node_id(nid, branch_id)
+        if cg.get(bid):
+            skipped.append({"id": nid, "why": "副本已存在：%s" % bid})
+            continue
+        cg.add(bid, rec.get("content") or "",
+               layer=fm.get("layer") or "knowledge",
+               role=fm.get("role"),
+               tags=list(fm.get("tags") or []),
+               condition_space=fm.get("condition_space"),
+               importance=float(fm.get("importance", 0.5)),
+               verification_basis=fm.get("verification_basis") or "test",
+               non_applicable_conditions=fm.get("non_applicable_conditions"),
+               consistency=False,
+               derived_from=[nid], relation="split_from",
+               branch_id=branch_id, branched_from=nid, branch_note=note,
+               actor="branch_fork")
+        forked.append({"from": nid, "to": bid})
+    _audit(cg, "branch_fork", branch_id=branch_id,
+           forked=[f["to"] for f in forked])
+    return {"ok": bool(forked), "branch_id": branch_id,
+            "tag": branch_tag(branch_id), "forked": forked, "skipped": skipped}
+
+
+def search(cg, query: str, branch_id: str, **kw):
+    """分支内检索：主支 + 本分支可见、其他分支隐身（_candidates branch 过滤）。"""
+    return cg.search(query, branch=str(branch_id or "").strip().lower(), **kw)
+
+
+def rewrite(cg, node_id, content, tags=None, importance=None,
+            actor="branch_rewrite", **extra) -> dict:
+    """分支实验改写的**唯一正路**（防裸 add 丢分支归属）。
+
+    背景：add 是全量重建 fm——裸 add 改写分支节点而不重传 branch_id，
+    节点会在索引里退化成主支（实验内容直接泄漏进主支检索）。本帮手：
+    - 只接受在册分支节点（含 @ 且 entry.branch_id 在册）；
+    - 归属与血缘（branch_id / branched_from / branch_note / derived_from /
+      derived_relation）一律从旧 fm 继承，调用方**不可改**（extra 里
+      同名键静默剥离）——「分支上怎么改内容都行，改不了它是谁的实验」；
+    - 层/条件空间/验证基底默认继承旧 fm（tags/importance 可显式覆盖）；
+    - override=True → 旧内容自动快照留痕（③ 快照机制，零新日志）。
+    写权限由 add 的 require_layer_write 库层强制，不在此重复设闸。
+    """
+    nid = str(node_id or "").strip()
+    if "@" not in nid:
+        return {"ok": False,
+                "error": "非分支节点（须为 <主支>@<branch_id> 形态）：%s" % nid}
+    e = (cg.index.get("nodes") or {}).get(nid)
+    if not e or not e.get("branch_id"):
+        return {"ok": False, "error": "分支节点不存在或无分支归属：%s" % nid}
+    rec = cg.get(nid)
+    fm = _fm_of(rec)
+    if isinstance(content, dict) or content is None:
+        return {"ok": False, "error": "content 须为字符串"}
+    for k in ("branch_id", "branched_from", "branch_note", "derived_from",
+              "relation", "merged_from_branch", "override", "consistency"):
+        extra.pop(k, None)   # 归属/血缘/写法闸不可经 extra 篡改
+    cg.add(nid, str(content or ""),
+           layer=fm.get("layer") or e.get("layer") or "knowledge",
+           tags=list(tags if tags is not None else (fm.get("tags") or [])),
+           importance=float(importance if importance is not None
+                            else (fm.get("importance") or 0.5)),
+           condition_space=fm.get("condition_space"),
+           verification_basis=fm.get("verification_basis") or "test",
+           non_applicable_conditions=fm.get("non_applicable_conditions"),
+           override=True, consistency=False,
+           derived_from=list(fm.get("derived_from") or []),
+           relation=fm.get("derived_relation") or "split_from",
+           branch_id=fm.get("branch_id") or e.get("branch_id"),
+           branched_from=fm.get("branched_from") or e.get("branched_from"),
+           branch_note=fm.get("branch_note"),
+           actor=actor, **extra)
+    _audit(cg, "branch_rewrite", branch_id=e.get("branch_id"), node=nid)
+    return {"ok": True, "node": nid, "branch_id": e.get("branch_id")}
+
+
+def merge(cg, branch_id, reason=None) -> dict:
+    """把分支上的改写按 branched_from 溯源回写主支。
+
+    - 主支内容 = 分支内容；层/tags/重要性继承主支（实验元数据不带回去）；
+    - 主支 derived_from 追加分支 nid（原链保留）、relation="merged_from"；
+    - override=True → 主支旧内容自动快照留痕；
+    - 分支节点保留（merge 不自动删——显式两步、可逆、诚实）。
+    """
+    bid = str(branch_id or "").strip().lower()
+    ents = _iter_branch_nodes(cg, bid)
+    if not ents:
+        return {"ok": False, "error": "分支不存在或无节点：%s" % bid}
+    merged, skipped = [], []
+    for nid, e in ents:
+        orig = e.get("branched_from")
+        rec = cg.get(orig) if orig else None
+        if not rec:
+            skipped.append({"id": nid, "why": "主支节点不存在：%s" % orig})
+            continue
+        src = cg.get(nid)
+        old_fm = _fm_of(rec)
+        src_fm = _fm_of(src)
+        chain = list(old_fm.get("derived_from") or [])
+        if nid not in chain:
+            chain.append(nid)
+        cg.add(orig, (src or {}).get("content") or "",
+               layer=old_fm.get("layer") or e.get("layer") or "knowledge",
+               tags=list(old_fm.get("tags") or e.get("tags") or []),
+               condition_space=src_fm.get("condition_space"),
+               importance=float(old_fm.get("importance", 0.5)),
+               verification_basis=old_fm.get("verification_basis") or "test",
+               non_applicable_conditions=old_fm.get("non_applicable_conditions"),
+               override=True, consistency=False,
+               derived_from=chain, relation="merged_from",
+               merged_from_branch=bid, actor="branch_merge")
+        merged.append({"branch_node": nid, "target": orig})
+    _audit(cg, "branch_merge", branch_id=bid,
+           merged=[m["target"] for m in merged], reason=reason)
+    return {"ok": bool(merged), "branch_id": bid, "merged": merged,
+            "skipped": skipped,
+            "hint": "分支节点保留：可 branch_search 继续实验，或 discard 冷归档"}
+
+
+def discard(cg, branch_id, summary: str) -> dict:
+    """放弃分支：校验教训必填 → 写 branch_summary 教训节点 → 分支冷归档。
+
+    - summary 必须含 BRANCH_MARKS 三标记（缺一不收，防「无声放弃」）；
+    - 教训节点进 knowledge 层、tags 带 branch:<id>——可被正常检索召回；
+    - 分支节点文件移入 _branches/<id>/（物理保留不违背永不删除，
+      LAYERS 之外故 _scan_nodes 不再扫到——索引与主支检索天然干净）；
+    - 需 can_admin（改变库可见性属高危操作）。
+    """
+    p = getattr(cg, "principal", None)
+    if p is not None:
+        p.require_admin("branch_discard")
+    bid = str(branch_id or "").strip().lower()
+    missing = [m for m in BRANCH_MARKS if m not in (summary or "")]
+    if missing:
+        return {"ok": False, "error": "branch_summary 缺必填标记",
+                "missing": missing, "required": list(BRANCH_MARKS)}
+    ents = _iter_branch_nodes(cg, bid)
+    if not ents:
+        return {"ok": False, "error": "分支不存在或无节点：%s" % bid}
+    body = summary if summary.lstrip().startswith("#") else \
+        "# branch_summary：%s\n\n%s" % (bid, summary)
+    sid = cg.add("branch_summary_%s" % bid, body, layer="knowledge",
+                 tags=["branch_summary", branch_tag(bid)],
+                 verification_basis="test", consistency=False,
+                 actor="branch_discard")
+    cold = os.path.join(cg.root, COLD_DIR, bid)
+    os.makedirs(cold, exist_ok=True)
+    moved = 0
+    for nid, e in ents:
+        path = e.get("path")
+        if path:
+            src = os.path.join(cg.root, str(path).replace("/", os.sep))
+            if os.path.exists(src):
+                os.replace(src, os.path.join(cold, os.path.basename(src)))
+                moved += 1
+        (cg.index.get("nodes") or {}).pop(nid, None)
+    fl = getattr(cg, "flush", None)
+    if fl is not None:
+        try:
+            fl()
+        except Exception:
+            pass
+    _audit(cg, "branch_discard", branch_id=bid, moved=moved, summary_node=sid)
+    return {"ok": True, "branch_id": bid, "moved": moved,
+            "summary_node": sid, "cold_dir": "%s/%s" % (COLD_DIR, bid)}
+
+
+def list_branches(cg) -> dict:
+    """按 branch_id 聚合现存分支（节点清单 + 溯源主支）。"""
+    groups = {}
+    for nid, e in (cg.index.get("nodes") or {}).items():
+        bid = e.get("branch_id")
+        if not bid:
+            continue
+        g = groups.setdefault(bid, {"branch_id": bid, "tag": branch_tag(bid),
+                                    "nodes": [], "branched_from": []})
+        g["nodes"].append(nid)
+        bf = e.get("branched_from")
+        if bf and bf not in g["branched_from"]:
+            g["branched_from"].append(bf)
+    return {"ok": True,
+            "branches": sorted(groups.values(), key=lambda g: g["branch_id"])}