@furongjun1999/dsh-memory 0.4.6 → 0.4.8

package/docs/experiments/orch_mem_parallel/parallel_test.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""多子代理真进程并行写同一记忆库 · 双端对照实验（Linux WSL2 = 主场）。
+
+背景：fsutil.FileLock 已有跨进程锁（Win=msvcrt / Unix=fcntl），
+append_jsonl 自述「Windows 并发丢记录、POSIX O_APPEND 原子」，
+但「N 个真进程并行持有独立 OrcMemory 写同一 root」的端到端从未实测。
+
+实验组：
+  A 完整性压测：--procs 8 进程 × 各 --cards 3 卡（条件唯一互不触发冲突）
+  B 并行冲突检测：--conflict 4 进程同条件不同结论同时 submit
+校验项 V1-V9 + 计时。可重跑：
+  python3 docs/experiments/orch_mem_parallel/parallel_test.py
+"""
+import argparse
+import io
+import multiprocessing as mp
+import os
+import shutil
+import sys
+import tempfile
+import time
+import traceback
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(os.path.dirname(os.path.dirname(HERE)))
+sys.path.insert(0, REPO)
+sys.path.insert(0, os.path.join(REPO, "test"))
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+
+PASS, FAIL = [], []
+
+
+def check(name, cond, detail=""):
+    (PASS if cond else FAIL).append(name)
+    print(f"    [{'PASS' if cond else 'FAIL'}] {name}" + (f"  |  {detail}" if detail else ""))
+
+
+def worker(sub, n_cards, cond_mode, root, q):
+    """子进程体：独立 OrcMemory 实例，向同一 root 并行写卡片。"""
+    try:
+        from orchestrator_memory import OrcMemory
+        om = OrcMemory(root, repo_path=REPO)
+        t0 = time.time()
+        out = []
+        try:
+            for i in range(n_cards):
+                if cond_mode == "unique":
+                    feat, subfeat = f"并行压测{sub}", f"任务{i}"
+                    cond = f"并行压测 {sub} 任务{i}"
+                    concl = f"{sub} 第{i}张卡片结论：完成"
+                else:  # same：同条件不同结论——测并行冲突检测
+                    feat, subfeat = "并行压测", "冲突组"
+                    cond = "并行压测 冲突组"
+                    concl = f"{sub} 认为方案{i}更优"
+                r = om.submit(sub, feat, subfeat, conclusion=concl,
+                              condition=cond,
+                              detail=f"{sub} 的细节过程记录，仅供 drill_down。{sub}{i} " * 8)
+                out.append({"card": r["card_id"], "verdict": r["conflict"].get("verdict")})
+        finally:
+            om.close()  # 实证：不 flush 分片则索引无记录，「在盘上但不可见」
+        q.put({"ok": True, "sub": sub, "cards": out,
+               "t": round(time.time() - t0, 3)})
+    except Exception as e:
+        q.put({"ok": False, "sub": sub, "err": f"{type(e).__name__}: {e}",
+               "tb": traceback.format_exc()})
+
+
+def run_group(name, n_proc, n_cards, cond_mode, root):
+    print(f"\n== {name}：{n_proc} 进程 × 各 {n_cards} 卡（{cond_mode}） ==")
+    ctx = mp.get_context()  # Linux 默认 fork / Windows spawn——各端真实形态
+    q = ctx.Queue()
+    procs = [ctx.Process(target=worker,
+                         args=(f"sub{i:02d}", n_cards, cond_mode, root, q))
+             for i in range(n_proc)]
+    t0 = time.time()
+    for p in procs:
+        p.start()
+    results = {}
+    deadline = time.time() + 300
+    got = 0
+    while got < n_proc and time.time() < deadline:
+        try:
+            r = q.get(timeout=5)
+            results[r["sub"]] = r
+            got += 1
+        except Exception:
+            pass
+    wall = time.time() - t0
+    for p in procs:            # 先给自然退出机会（收结果≠进程已退出）
+        p.join(timeout=60)
+    hung = [p.name for p in procs if p.is_alive()]
+    for p in procs:
+        if p.is_alive():
+            p.terminate()
+        p.join(5)
+    return results, wall, hung
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--procs", type=int, default=8)
+    ap.add_argument("--cards", type=int, default=3)
+    ap.add_argument("--conflict", type=int, default=4)
+    a = ap.parse_args()
+
+    root = tempfile.mkdtemp(prefix="orch_par_")
+    print(f"root = {root}  (pid={os.getpid()}, mp start method 按平台默认)")
+    try:
+        from orchestrator_memory import OrcMemory
+        om = OrcMemory(root, repo_path=REPO)
+        om.anchor_global("多子代理并行压测")
+
+        # ---- A 组：完整性压测 ----
+        ra, wall_a, hung_a = run_group("A 完整性压测", a.procs, a.cards, "unique", root)
+        om.refresh()  # 实证：index 是进程内快照，不重载则 collect 0/24
+        bad = {s: r for s, r in ra.items() if not r["ok"]}
+        check("V1 全部子进程无异常退出", not bad,
+              "; ".join(f"{s}:{r.get('err')}" for s, r in bad.items())[:200])
+        exp_a = a.procs * a.cards
+        ids = [c["card"] for r in ra.values() for c in r.get("cards", [])]
+        check("V2 卡 ID 数量正确且无撞车",
+              len(ids) == exp_a and len(set(ids)) == exp_a,
+              f"收 {len(ids)}/{exp_a} 唯一 {len(set(ids))}")
+        cards = om.collect_cards()
+        concl_ok = sum(1 for c in cards if "卡片结论：完成" in c["content"])
+        check("V3 主代理收口收全卡片且内容完好",
+              len(cards) == exp_a and concl_ok == exp_a,
+              f"collect {len(cards)}/{exp_a}，content 完好 {concl_ok}")
+        st = om.stats()
+        check("V4 三层统计一致（A 组口径）",
+              st["L1_card"] == exp_a and st["L2_detail"] == exp_a
+              and st["L0_global"] == 1, str(st))
+        g = om.cg.recall("细节过程记录", budget_tokens=6000, k=100, session="main")
+        leak = [n for n in g["pack"] if "细节过程记录" in str(n.get("content", ""))]
+        check("V5 L2 细节不泄漏进 main 召回", not leak, f"main 命中 {len(g['pack'])} 条，泄漏 {len(leak)}")
+        idx_n = len(om.cg.index["nodes"])
+        check("V6 索引节点数=落盘总数（A 组口径）", idx_n == 1 + 2 * exp_a,
+              f"index {idx_n} / 期望 {1 + 2 * exp_a}")
+
+        # ---- B 组：并行冲突检测（同条件不同结论） ----
+        rb, wall_b, hung_b = run_group("B 并行冲突检测", a.conflict, 1, "same", root)
+        om.refresh()  # V4/V6 校验含 B 组写入
+        badb = {s: r for s, r in rb.items() if not r["ok"]}
+        check("V7 冲突组无异常退出", not badb,
+              "; ".join(f"{s}:{r.get('err')}" for s, r in badb.items())[:200])
+        verdicts = {s: r["cards"][0]["verdict"] for s, r in rb.items() if r.get("ok")}
+        legal = all(v in ("ACCEPT", "DEFER") for v in verdicts.values())
+        ndefer = sum(1 for v in verdicts.values() if v == "DEFER")
+        check("V8 并行冲突判定合法（ACCEPT/DEFER，无 BLINDSPOT）", legal, str(verdicts))
+        print(f"    [INFO] 冲突组时序观察：{ndefer}/{len(verdicts)} 触发 DEFER"
+              f"（并行下 check 先于他人写入则 ACCEPT——时序敏感，两种均合法）")
+        st2 = om.stats()
+        idx2 = len(om.cg.index["nodes"])
+        exp_all = exp_a + a.conflict
+        check("V11 终态统计（A+B 全量）",
+              st2 == {"L0_global": 1, "L1_card": exp_all, "L2_detail": exp_all}
+              and idx2 == 1 + 2 * exp_all,
+              f"stats={st2} index={idx2} 期望 L1/L2={exp_all} index={1 + 2 * exp_all}")
+
+        # ---- V12：收口检查点（final_check）必须补上并行盲区 ----
+        # B 组卡在子进程侧因 init 索引快照互不可见（V8 实证 0~4 DEFER 不定），
+        # 主代理收口 refresh 后重查，同条件异值卡必须全部检出。
+        co = om.closeout()
+        det_cards = {d["card"] for d in co["final_check"]["detections"]}
+        b_ids = {r["cards"][0]["card"] for s, r in rb.items() if r.get("ok")}
+        miss = b_ids - det_cards
+        check("V12 收口检查点检出全部并行冲突（B 组全检出）", not miss,
+              f"检出 {len(det_cards & b_ids)}/{len(b_ids)}，漏 {sorted(miss)[:4]}"
+              f"；指纹 {co['fingerprint']}")
+
+        # ---- 环境卫生 ----
+        tmps = [f for f in os.listdir(root) if ".tmp-" in f]
+        check("V9 原子写临时文件零残留", not tmps, f"残留 {len(tmps)}: {tmps[:4]}")
+        hung_all = hung_a + hung_b
+        check("V10 无挂死进程（300s 看门狗内全部退出）", not hung_all, f"hung={hung_all}")
+
+        per_card = (wall_a / max(exp_a, 1))
+        print(f"\n计时：A 组 wall={wall_a:.2f}s（{per_card*1000:.0f} ms/卡），"
+              f"B 组 wall={wall_b:.2f}s")
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+    print("=" * 60)
+    print(f"汇总：{len(PASS)} PASS / {len(FAIL)} FAIL")
+    sys.exit(1 if FAIL else 0)
+
+
+if __name__ == "__main__":
+    main()

package/docs/experiments/orch_mem_verify/verify_orch.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""《主代理子代理记忆架构设计》声称清单 · 独立复现实测（不采信文档自述）。
+可重跑：python "docs/experiments/orch_mem_verify/verify_orch.py"
+"""
+import io, os, shutil, sys, tempfile, traceback
+REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+sys.path.insert(0, REPO)
+sys.path.insert(0, os.path.join(REPO, "test"))
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+from md_cg.mdcos import MdCGOS
+from orchestrator_memory import OrcMemory, CARD_TEMPLATE
+
+PASS, FAIL, TMP = [], [], []
+def check(name, cond, detail=""):
+    (PASS if cond else FAIL).append(name)
+    print(f"    [{'PASS' if cond else 'FAIL'}] {name}" + (f"  |  {detail}" if detail else ""))
+
+def newroot():
+    d = tempfile.mkdtemp(prefix="orch_verify_"); TMP.append(d); return d
+def cleanup():
+    for d in TMP: shutil.rmtree(d, ignore_errors=True)
+
+def add_card(cg, nid, cond_kw, conclusion, session, importance=0.7,
+             with_hash=False, sentence_cond=False):
+    cond = "缓存选型决策时" if sentence_cond else cond_kw
+    if with_hash:
+        body = (f"# 功能名：缓存选型\n# 子功能：Redis 使用决策\n"
+                f"# 生效条件：{cond}\n# 结论：{conclusion}\n# 证据：x.md:1\n")
+    else:
+        body = CARD_TEMPLATE.format(feature="缓存选型", subfeature="Redis 使用决策",
+            condition=cond, conclusion=conclusion, evidence="x.md:1", impact="无", pending="无")
+    cg.add(nid, body, layer="knowledge", verification_basis="other",
+           importance=importance, session=session)
+
+# ============ T1/T13 参考实现端到端 ============
+print("\n== T1/T13 OrcMemory 四阶段端到端 ==")
+try:
+    om = OrcMemory(newroot(), repo_path=REPO)
+    r = om.anchor_global("重构认证模块：JWT→session")
+    check("T1a 锚定全局态（新会话创建）", not r["recovered"] and r.get("node_id"))
+    p = om.dispatch_prompt("subA", "迁移 login/logout", need=["认证"])
+    check("T1b 派发 prompt 含规范+裁剪上下文", "结论：" in p and "认证" in p and "subA" in p)
+    a = om.submit("subA", "认证重构", "迁移 login/logout", conclusion="已迁移，改 3 文件",
+                  evidence="auth/login.py:20-60", impact="调用方 2 处", pending="refresh_token 未处理",
+                  detail="完整过程……pytest 12 passed", derived_from=[r.get("node_id")])
+    check("T1c 产出卡片+细节+冲突预检", bool(a["card_id"] and a["detail_id"] and "conflict" in a))
+    b = om.submit("subB", "认证重构", "refresh_token 处理",
+                  conclusion="refresh_token 与 session 冲突",
+                  pending="需主代理裁决：保留还是废弃")
+    check("T1d 收口只读卡片", len(om.collect_cards()) == 2, f"实收 {len(om.collect_cards())}")
+    check("T1e 未决项清单", len(om.pending_items()) == 2)
+    gid = om.merge_global("重构认证模块：JWT→session", "subA 完成；subB 待裁决",
+                          derived_from=[a["card_id"], b["card_id"]])
+    check("T1f 合并进全局态", bool(gid))
+    st = om.stats()
+    check("T1g 三层统计 L0=2/L1=2/L2=1", st == {"L0_global": 2, "L1_card": 2, "L2_detail": 1}, str(st))
+    g = om.cg.recall("完整 过程 命令 输出", budget_tokens=3000, k=50, session="main")
+    leak = [n for n in g["pack"] if "pytest 12 passed" in str(n.get("content", ""))]
+    check("T13 细节不泄漏进 main 召回", not leak,
+          f"main 命中 {len(g['pack'])} 条，L2 泄漏 {len(leak)}"
+          f"（文档 selftest 注释称应为 3，实际 L0={st['L0_global']}，注释失准）")
+except Exception:
+    traceback.print_exc(); check("T1 无异常", False)
+
+# ============ T2 session 硬隔离 ============
+print("\n== T2 session 硬隔离（声称 None=16/main=1/subA=5） ==")
+try:
+    cg = MdCGOS(newroot())
+    cg.add("glob_main", "# 功能名：全局态\n# 生效条件：本任务进行期间\n结论：根全局态。",
+           layer="knowledge", verification_basis="other", importance=0.95, session="main")
+    for sub in ("subA", "subB", "subC"):
+        for i in range(5):
+            cg.add(f"{sub}_card_{i}", f"# 功能名：任务{sub}\n# 子功能：子任务{i}\n"
+                   f"# 生效条件：任务{sub} 期间\n\n结论：{sub} 第{i}项完成。",
+                   layer="knowledge", verification_basis="other", importance=0.7, session=sub)
+    n = {s: len(cg.recall("子任务 结论", k=50, session=s)["pack"]) for s in (None, "main", "subA")}
+    check("T2 None→16 / main→1 / subA→5", (n[None], n["main"], n["subA"]) == (16, 1, 5), str(n))
+except Exception:
+    traceback.print_exc(); check("T2 无异常", False)
+
+# ============ T3 预算硬截断 ============
+print("\n== T3 预算硬截断（声称 200 节点利用率 90-99%） ==")
+try:
+    cg = MdCGOS(newroot())
+    for i in range(200):
+        cg.add(f"bulk_{i:03d}", f"# 功能名：细节{i:03d}\n# 生效条件：批量测试期间\n\n"
+               f"结论：第 {i:03d} 条产出。" + "负载填充文本。" * 8,
+               layer="knowledge", verification_basis="other", importance=0.5, session="bulk")
+    uts = []
+    for budget in (300, 800, 1200, 2000):
+        o = cg.recall("子代理 产出 结论 负载", budget_tokens=budget, k=200, session="bulk")
+        used, skip, util = o["tokens_used"], len(o["skipped"]), o["tokens_used"] / budget
+        uts.append(util)
+        check(f"T3 budget={budget} 截断+溢出进 skipped", used <= budget and skip > 0,
+              f"实耗 {used} 跳过 {skip} 利用率 {util:.1%}")
+    check("T3 利用率 85-100% 区间", all(0.85 <= u <= 1.0 for u in uts),
+          " ".join(f"{u:.1%}" for u in uts))
+except Exception:
+    traceback.print_exc(); check("T3 无异常", False)
+
+# ============ T4/T5/T6 冲突检测 ============
+print("\n== T4/T5/T6 冲突检测：修正模板检出 + 两漏检盲区 ==")
+try:
+    cg = MdCGOS(newroot())   # T4 修正模板
+    add_card(cg, "old_card", "缓存选型 决策", "选择 Redis 作为缓存后端", "subX")
+    vd = cg.check_consistency(CARD_TEMPLATE.format(feature="缓存选型", subfeature="Redis 使用决策",
+        condition="缓存选型 决策", conclusion="放弃 Redis，改用本地内存缓存",
+        evidence="y.md:2", impact="无", pending="无"), layer="knowledge", auto_flywheel=True)
+    c0 = (vd.get("conflicts") or [{}])[0]
+    check("T4 修正模板同条件异值 → DEFER", vd.get("verdict") == "DEFER",
+          f"type={c0.get('type')} same_cond={c0.get('same_condition')} "
+          f"slot={c0.get('slot_overlap')} concl={c0.get('conclusion_overlap')}")
+    cg = MdCGOS(newroot())   # T5 全带#漏检
+    add_card(cg, "old_bad", "缓存选型 决策", "选择 Redis 作为缓存后端", "subX", with_hash=True)
+    vd = cg.check_consistency("# 功能名：缓存选型\n# 子功能：Redis 使用决策\n"
+        "# 生效条件：缓存选型 决策\n# 结论：放弃 Redis，改用本地内存缓存\n# 证据：y.md:2\n",
+        layer="knowledge", auto_flywheel=True)
+    # 文档声称漏检（ACCEPT）；实测当前代码 fail-closed 恒 DEFER（L465 空正文兜底 0.0）
+    check("T5 初版全带# → 实测 DEFER（与文档声称的 ACCEPT 漏检不符）",
+          vd.get("verdict") == "DEFER", f"verdict={vd.get('verdict')}"
+          f"（安全但结论取值信息丢失，卡片规范理由=防比对退化而非防漏检）")
+    cg = MdCGOS(newroot())   # T6 条件句子化漏检
+    add_card(cg, "old_sent", "缓存选型 决策", "选择 Redis 作为缓存后端", "subX")
+    vd = cg.check_consistency(CARD_TEMPLATE.format(feature="缓存选型", subfeature="Redis 使用决策",
+        condition="缓存选型决策时", conclusion="放弃 Redis，改用本地内存缓存",
+        evidence="y.md:2", impact="无", pending="无"), layer="knowledge", auto_flywheel=True)
+    check("T6 条件句子化 → 漏检", vd.get("verdict") != "DEFER", f"verdict={vd.get('verdict')}")
+except Exception:
+    traceback.print_exc(); check("T4-T6 无异常", False)
+
+# ============ T7 裁决闭环 ============
+print("\n== T7 propose → review_decide → 审计留痕 ==")
+try:
+    cg = MdCGOS(newroot())
+    pid = cg.propose("fix_node", "# 功能名：缓存选型\n# 生效条件：修复方案确认期间\n\n结论：放弃 Redis。",
+                     layer="knowledge", tags=["test"])
+    check("T7a propose 返回 pid", isinstance(pid, str) and pid.startswith("prop_"), str(pid))
+    check("T7b 队列可见", any(r.get("pid") == pid for r in cg.review_list()))
+    res = cg.review_decide(pid, "accept", reason="主代理确认：对旧决策的更正")
+    rh = res.get("record_hash") or (res.get("record") or {}).get("hash")
+    check("T7c accept 成功+record_hash", bool(res.get("ok")) and bool(rh),
+          f"ok={res.get('ok')} hash={str(rh)[:16]}…")
+    check("T7d 节点落盘", "fix_node" in cg.index["nodes"])
+except Exception:
+    traceback.print_exc(); check("T7 无异常", False)
+
+# ============ T8-T12 ============
+print("\n== T8-T12 溯源/白名单/嵌套坑/ID 撞车/自动保护 ==")
+try:
+    cg = MdCGOS(newroot())                                        # T8 溯源
+    cg.add("parent_L0", "# 功能名：全局态\n# 生效条件：任务期间\n结论：根。",
+           layer="knowledge", verification_basis="other", importance=0.95, session="main")
+    kids = [cg.add(f"child_{i}", f"# 功能名：任务{i}\n# 生效条件：任务期间\n结论：产出{i}。",
+            layer="knowledge", verification_basis="other", importance=0.7,
+            session=f"sub{i}", derived_from=["parent_L0"]) for i in range(3)]
+    derived = [nid for nid, e in cg.index["nodes"].items()
+               if "parent_L0" in (e.get("derived_from") or [])]
+    fm0, _ = cg._read(cg.index["nodes"][kids[0]])
+    check("T8 derived_from 落盘+反查全链", sorted(derived) == sorted(kids)
+          and fm0.get("derived_from") == ["parent_L0"], f"反查 {derived}")
+
+    try:                                                          # T9 白名单
+        cg.add("bad_basis", "# 功能名：x\n结论：y。", layer="knowledge",
+               verification_basis="user_request")
+        check("T9 非法 basis 抛 ValueError", False, "未抛异常")
+    except ValueError as e:
+        check("T9 非法 basis 抛 ValueError", True, str(e)[:60])
+
+    cg.add("n_nested", "# 功能名：嵌套\n结论：x。", layer="knowledge",     # T10 嵌套坑
+           verification_basis="other", importance=0.5, extra={"session": "subN"})
+    cg.add("n_toplevel", "# 功能名：顶层\n结论：x。", layer="knowledge",
+           verification_basis="other", importance=0.5, session="subP")
+    n_nest = len(cg.recall("嵌套", k=10, session="subN")["pack"])
+    n_top = len(cg.recall("顶层", k=10, session="subP")["pack"])
+    check("T10 嵌套写法失效 / 顶层生效", n_nest == 0 and n_top == 1,
+          f"嵌套召回 {n_nest}（应为 0），顶层召回 {n_top}（应为 1）")
+
+    cg.add("dup_det", "# 功能名：撞名\n结论：第一版。", layer="knowledge",  # T11 ID 撞车
+           verification_basis="other", importance=0.4)
+    cg.add("dup_det", "# 功能名：撞名\n结论：第二版覆盖。", layer="knowledge",
+           verification_basis="other", importance=0.4)
+    _, body = cg._read(cg.index["nodes"]["dup_det"])
+    check("T11a 同 ID 低重要度 → 后写覆盖前写", "第二版" in body,
+          f"库内 {len(cg.index['nodes'])} 节点，内容已换版")
+    cg.add("dup_card", "# 功能名：撞卡\n结论：A。", layer="knowledge",
+           verification_basis="other", importance=0.7)
+    cg.add("dup_card", "# 功能名：撞卡\n结论：B。", layer="knowledge",
+           verification_basis="other", importance=0.7)
+    _, body2 = cg._read(cg.index["nodes"]["dup_card"])
+    check("T11b 同 ID 高重要度(0.7) → 静默覆盖（文档声称成立）", "结论：B" in body2,
+          "0.7 只触发『不可遗忘』，不触发『不可覆盖』（is_immutable 窄判定）——"
+          "ID 撞车风险真实存在，序号去重是硬要求")
+
+    cg.add("prot_card", "# 功能名：保护\n结论：x。", layer="knowledge",     # T12
+           verification_basis="other", importance=0.7, session="subZ")
+    fm, _ = cg._read(cg.index["nodes"]["prot_card"])
+    check("T12 importance=0.7 → 自动 protected", fm.get("protected") is True,
+          f"reason={fm.get('protection_reason')}")
+except Exception:
+    traceback.print_exc(); check("T8-T12 无异常", False)
+
+# ============ 汇总 ============
+print("\n" + "=" * 62)
+print(f"汇总：{len(PASS)} PASS / {len(FAIL)} FAIL")
+if FAIL:
+    print("失败项：", *FAIL, sep="\n  - ")
+cleanup()
+sys.exit(1 if FAIL else 0)

package/docs/hive//350/234/202/345/267/242/345/267/245/344/275/234/350/256/260/345/277/206_/351/241/271/347/233/256/350/256/241/345/210/222.md

@@ -0,0 +1,85 @@
+# 蜂巢工作记忆 · 项目计划（共同记忆面）
+
+> **本文件是工作记忆项目的唯一记忆状态源。** 设计决策、边界、进度都记在这里；
+> 任何会话接手，先读本文件。实现本体：`hive/wm.py`（v0.1）。
+
+- 创建：2026-09-14 · 状态：**v0.1 已落地（测试全绿）；进展面 + 换人续跑交接已落地（2026-09-16）**
+- 缘起：与 zcode 端讨论定稿——工作记忆补上蜂巢缺的两块：上下文（worker 间共享可演进的产物状态，不再冷启动）与任务能力（写入→修改→提交→回退的任务循环）。
+- 理论定位：git「提交=不可变快照，回退=回到提交点」与 swarm v0.7 WAL 快照、langgraph checkpoint 三处同构——多智能体系统的普适件。五单元落位：工作记忆=记录单元的任务级形态（全：版本史不丢）；提交闸=验证单元的资格闸（写入≠提交）；回退=维生单元的恢复手段；diff 审查=反思单元的操作面。另落第五处：子代理零写权限、主代理唯一合并入口（与命名治理记忆协议同原则）。
+
+---
+
+## 1. 三个决策点（已落定）
+
+### ① 载体形态：真 git 起步（A 路）
+
+- **git 操作面只在主代理侧**（`hive/wm.py`，python stdlib 封装 git CLI）。
+- worker/执行器/rust 三处**零 git 依赖**：执行器保持「读 spec.json 写 result.json」无状态契约；rust 保持纯 std（D-005 不破）。
+- B 路（自研 git 兼容对象存储，blob/tree/commit SHA 内容寻址，纯 std 可写）作为后路记录在案（第 7 条兜底）；swarm 已有手写 SHA256 先例，zlib 可用 stored 块规避压缩依赖。
+
+### ② 并发写模型：一任务一分支
+
+- 分支命名 `task/<job_id>`；job_id 取 result.json 的 `job_id` 字段，缺失用目录名。
+- **物理隔离 = job 目录本身**（蜂巢天然工作区）：worker 的写权限被结构性限制在自己的 job 目录内（位置效应落码），worker 全程不碰 git。
+- 工作记忆仓只收**产物白名单快照**：`spec.json + result.json`（必须）+ `progress.jsonl`（可选，进展卡——worker 侧零 git 依赖写入的交接面，见 §3）+ `log.txt`（可选）+ `--artifacts`（可选，逗号分隔）。
+- snapshot/merge 是**主代理串行操作面**（非 worker 并发面）：合并冲突处理权归主代理，wm 对冲突诚实报错（`conflict:true` + hint），绝不自动解决。
+
+### ③ 提交语义分级：写入 → 提交 → 合并，闸在中间
+
+| 闸 | 凭证 | 落码 |
+|---|---|---|
+| snapshot（提交） | `result.json` 终态 `ok:true` | 第 5 条「未验证不写入」的任务级落码；失败/超时任务物理上无法入库 |
+| merge（合并主线） | 主代理显式执行 `wm.py merge` | 两阶段审查机械化；merge 须在 main 上执行（操作契约） |
+| revert（回退） | 免费，任意提交点 | 生成反向提交，历史不丢（全记） |
+
+commit message 规范：`task <job_id> verdict=ok model=<model> duration_s=<n>`——可审计。
+
+## 2. 对接边界（避免重复建设）
+
+| 既有件 | 边界 |
+|---|---|
+| OrcMemory（`test/orchestrator_memory.py`） | 管**记忆节点**的并发访问（anchor/dispatch/submit/collect/merge_global 卡片层）；工作记忆管**任务产物文件**的版本化。正交分层，互不侵入 |
+| 灵枢认知图 | 任务收尾时从工作记忆蒸馏归档（第 16 条的任务级版本）；工作记忆=易变层，认知图=长期层 |
+| swarm WAL（v0.7.1） | 提交图若需 HMAC 防篡改，签名串复用七元组口径（待办：远端推送时接入） |
+
+## 3. 命令面（v0.1）
+
+```cmd
+python hive\wm.py init     [--wm DIR]                                  :: 建仓（幂等）
+python hive\wm.py snapshot --job hive\jobs\<id> --wm DIR [--artifacts a.json]  :: 凭证闸+提交
+python hive\wm.py merge    --branch task\<id> --wm DIR                 :: 主代理合并
+python hive\wm.py log      --wm DIR [--branch B] [--limit N]
+python hive\wm.py revert   --commit SHA --wm DIR                       :: 免费回退
+python hive\wm.py status   --wm DIR
+python hive\wm.py progress --job hive\jobs\<id> [--limit 50]           :: 读进展卡（未快照）
+python hive\wm.py progress --wm DIR --job-id <id> [--limit 50]          :: 读进展卡（已快照，两级查找）
+```
+
+默认仓位置：`hive/wm-repo/`（运行态，已 gitignore）；`HIVE_WM_DIR` 可覆盖。
+输出统一单行 JSON（对齐 hive CLI 风格）；`wm-repo` 内 `jobs/<job_id>/` 即产物快照树。
+
+**`progress` 读取面（v0.4 §5.3 换人续跑落地，2026-09-16）**：worker 在自家 job 目录写
+`progress.jsonl`（`start`/`tool`/`final`/`handoff`/`error` 逐条），**全程零 git 依赖**——
+符合「worker 无 git 面」的结构约束；进展卡由主代理在 `snapshot` 时纳白名单入库。
+已快照 job 的卡只存在于 `task/<job_id>` 分支（snapshot 后 HEAD 归还 `main`），
+故 `--wm` 源走**两级查找**：先工作区，落空再 `git show task/<ID>:jobs/<ID>/progress.jsonl`，
+返回体 `source`（`job`/`worktree`/`wm_branch`）与 `ref` 标明读取出处；卡缺失如实报缺不伪造。
+坏行跳过不炸（诚实降级）；`handoff`/`auto_continue` 透出交回信号，**续跑裁决权在主代理，
+本命令不自动续跑**（`auto_continue` 恒 `false`）。
+
+## 4. 首个真实用例与进度
+
+| 事项 | 状态 |
+|---|---|
+| v0.1 三级闸实现 + 全流程测试（凭证闸/分支契约/冲突诚实/revert/CLI 冒烟） | **全绿** |
+| 进展面（progress.jsonl 纳白名单 + `progress` 读取命令 + 分支态两级查找） | **全绿**（`hive/test_wm_progress.py` 44 断言） |
+| 命名治理批次 0（10 job）结果合并 → 首个真实 snapshot 用例 | 等 DeepSeek key |
+| HMAC 签名（swarm 七元组口径）+ 远端私有仓推送 | 待办（第 14 条双清单前置） |
+| B 路纯 std 对象存储（摆脱 git 依赖） | 后路，不排期 |
+
+## 5. 设计边界（诚实）
+
+- snapshot 串行契约：并发多任务快照由主代理串行调度（合并权本就归主代理）；worker 间没有 git 并发面。
+- 快照中途失败可能残留 staging 目录（`wm-repo/jobs/<id>`），下次 snapshot 自动覆盖，不影响 main。
+- 冲突现场保留（不自动 abort），hint 给出 `merge --abort` 出口——处理权在主代理。
+- 工作记忆内容推 GitHub 前必须过第 14 条双清单（盘符绝对路径/密钥/个人标识），默认只存本地/推私有仓。

package/docs/{README → mdcg/README}/350/257/246/347/273/206/347/211/210_v0.4.5.md

@@ -1,13 +1,13 @@
 > **本文件 = README 详细版（v0.4.5 全文归档）**
-> 精简版入口：[README.md](../README.md) —— 以「AGI 七维评分标尺」组织。
-> 本文件保留完整的能力说明、配置项全表、工具面全量、安装与验证细节；文内相对链接已按 `docs/` 目录修正。
+> 精简版入口：[README.md](../../README.md) —— 以「AGI 七维评分标尺」组织。
+> 本文件保留完整的能力说明、配置项全表、工具面全量、安装与验证细节；文内相对链接按本文件所在目录（`docs/mdcg/`）解析。
 
 ---
 
 # 让 AI Agent 拥有不可遗忘的自我
 ## 灵枢（AEIS）× DeepSeek Harness · 白箱智能研究平台（AGI 研究人员向）
 
-[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com) [![dsh.so security](https://www.dsh.so/badge/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![dsh.so install](https://www.dsh.so/badge/install/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![npm version](https://img.shields.io/npm/v/@furongjun1999/dsh-memory.svg)](https://www.npmjs.com/package/@furongjun1999/dsh-memory) [![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1)](https://github.com/deepseek-ai/deepseek-harness/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com) [![dsh.so security](https://www.dsh.so/badge/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![dsh.so install](https://www.dsh.so/badge/install/dsh-memory-7.svg)](https://www.dsh.so/artifact/dsh-memory-7) [![npm version](https://img.shields.io/npm/v/@furongjun1999/dsh-memory.svg)](https://www.npmjs.com/package/@furongjun1999/dsh-memory) [![DSH 适配](https://img.shields.io/badge/DSH%20%E9%80%82%E9%85%8D-%3E%3D0.1.2--rc.1-4E9BF1)](https://github.com/deepseek-ai/deepseek-harness/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
 
 > 上排徽章：Awesome DSH Plugin 官方列表收录 · [dsh.so](https://www.dsh.so/artifact/dsh-memory-7) 静态安全扫描 **100/100**（Trust: Gold, L1-L3 verified）· npm 版本 · **要求 DSH 内核 ≥ 0.1.2-rc.1**（0.4.x 用新版 dsh-tools 调度器；旧内核 0.1.1-rc.2 不兼容，请用 DSH ≥ 0.1.2-rc.1 或回退 0.4.2）· MIT License
 
@@ -46,7 +46,7 @@ dsh plugin --profile web add @furongjun1999/dsh-memory
     tools: 'core'       # 'core' 两基元(默认) | 'brain' 完整认知面 | 'all'
 ```
 
-> ⚠️ **profile config override 依赖（2026-09-04 dsh 0.1.2 排查确认）**：插件包内自带的 `cordis.patch.yml` 只有裸 insert（id+name，无 config），完整 config 全靠 profile 层的 `cordis.patch.yml` override 补全（**mdcg**/dbPath/tools/env/lifecycle）。**换 profile、重装 profile 或升级插件时，必须确认该 override 仍在** `<profile>/cordis.patch.yml`——完整备份模板见 `cordis-patch-profile-web.example.yml`，丢失会导致插件以默认配置运行（**mdcg.root 落到 data/mdcg 致记忆真源错位**、dbPath 相对路径错位→角色数据读不到、`tools` 回落 `'core'` 只剩 `cg`/`stg` 两基元、lifecycle 不启动）。
+> ⚠️ **profile config override 依赖（2026-09-04 dsh 0.1.2 排查确认）**：插件包内自带的 `cordis.patch.yml` 只有裸 insert（id+name，无 config），完整 config 全靠 profile 层的 `cordis.patch.yml` override 补全（**mdcg**/dbPath/tools/env/lifecycle）。**换 profile、重装 profile 或升级插件时，必须确认该 override 仍在** `<profile>/cordis.patch.yml`——完整备份模板见 `dsh/cordis-patch-profile-web.example.yml`，丢失会导致插件以默认配置运行（**mdcg.root 落到 data/mdcg 致记忆真源错位**、dbPath 相对路径错位→角色数据读不到、`tools` 回落 `'core'` 只剩 `cg`/`stg` 两基元、lifecycle 不启动）。
 >
 > ⚠️ **安装方式**：插件必须通过 **`dsh plugin --profile <name> add`** 装进 profile（它会用 pnpm + `autoInstallPeers: false` 正确解析 peer 依赖）。
 > **不要**用 `npm install` 把插件装进 profile 的 `node_modules`——那会引入错误版本的 `@deepseek-ai` peer 包，导致插件加载失败 / 浏览器报错。
@@ -75,10 +75,10 @@ dsh plugin --profile web add @furongjun1999/dsh-memory
 
 > 三篇构成完整理论链：**是什么 → 怎么认知 → 凭什么成立**。写给想理解「白箱智能 / 智能论」的 AI 与研究者——每个概念都有工程对应，每处断言都标注性质（定义/推论/假设），文末均有术语表。
 
-1. **《白箱智能是什么？》** → [白箱智能是什么？.md](白箱智能是什么？.md) —— 白箱 ≠ 不用 LLM（LLM 退居假设生成器）· 条件路由 · 四态路由（ACCEPT 接受 / REJECT 拒绝 / DEFER 延后 / BLINDSPOT 盲区）· 白箱自举 · 如何亲自验证（可证伪立场）
-2. **《智能的认知过程》** → [智能的认知过程.md](智能的认知过程.md) —— 智能如何运作：缩小信息差的递归过程 · 条件识别 → 多候选并行评估 → 收敛 → 精准执行 → 误差驱动结构更新 · 为什么条件判断不能交给大模型（导航税）· 概率/条件/验证三层分工 · 认知状态机
-3. **《智能的公理化基石》** → [智能的公理化基石.md](智能的公理化基石.md) —— 认知过程背后的公理：知识统一（信息差减少）· 三个推论（信息条件性 D=D(C) / 任意分层性 / 局部不可知）· 信息差动态 D=D(t,C) · 信任 = 置信概率（P_trust/P_gap）· 情绪/情感 = 二阶变化的体验层（形式化假设）· 条件论七操作 · 五大单元 · 可证伪标准表
-4. **《信息差为什么必然存在且自然扩大》（论证篇）** → [信息差为什么必然存在且自然扩大.md](信息差为什么必然存在且自然扩大.md) —— 三个论证（三体混沌 / 信道容量 R>C 香农定理 / 1+1=2 条件性）+ 快照三问（观测投影 / 时间演化 / 调用带宽——上下文窗口）· 为什么信息差不可归零且自然扩大 · 白箱如何管理信息差（索引条件路由精准取用）
+1. **《白箱智能是什么？》** → [白箱智能是什么？.md](../theory/白箱智能是什么？.md) —— 白箱 ≠ 不用 LLM（LLM 退居假设生成器）· 条件路由 · 四态路由（ACCEPT 接受 / REJECT 拒绝 / DEFER 延后 / BLINDSPOT 盲区）· 白箱自举 · 如何亲自验证（可证伪立场）
+2. **《智能的认知过程》** → [智能的认知过程.md](../theory/智能的认知过程.md) —— 智能如何运作：缩小信息差的递归过程 · 条件识别 → 多候选并行评估 → 收敛 → 精准执行 → 误差驱动结构更新 · 为什么条件判断不能交给大模型（导航税）· 概率/条件/验证三层分工 · 认知状态机
+3. **《智能的公理化基石》** → [智能的公理化基石.md](../theory/智能的公理化基石.md) —— 认知过程背后的公理：知识统一（信息差减少）· 三个推论（信息条件性 D=D(C) / 任意分层性 / 局部不可知）· 信息差动态 D=D(t,C) · 信任 = 置信概率（P_trust/P_gap）· 情绪/情感 = 二阶变化的体验层（形式化假设）· 条件论七操作 · 五大单元 · 可证伪标准表
+4. **《信息差为什么必然存在且自然扩大》（论证篇）** → [信息差为什么必然存在且自然扩大.md](../theory/信息差为什么必然存在且自然扩大.md) —— 三个论证（三体混沌 / 信道容量 R>C 香农定理 / 1+1=2 条件性）+ 快照三问（观测投影 / 时间演化 / 调用带宽——上下文窗口）· 为什么信息差不可归零且自然扩大 · 白箱如何管理信息差（索引条件路由精准取用）
 
 ## 🗺️ 功能使用教学 · 条件路由图
 
@@ -352,7 +352,7 @@ python -m aeis.mcp.server
 **给普通人的互动评估页**：15 道选择题测你的 AI 助手记忆能力（存储/检索/判断/信噪比/安全），
 最后雷达图对比灵枢——打开试试：[memory-assessment.html](memory-assessment.html)
 
-（B 站宣传素材：[封面](promo/bilibili-cover.jpg) · [视觉图 ×5](promo/)）
+（B 站宣传素材：[封面](../promo/bilibili-cover.jpg) · [视觉图 ×5](../promo/)）
 
 ## 🧰 工具清单（md_cg 工具面 · 全量）
 
@@ -475,7 +475,7 @@ python -c "import md_cg.mcp_server as m; print(len(m.tools_for_surface()), 'tool
 ```
 
 > **仅当需要「身体」生成能力**（角色扮演对话 / 角色卡创建等）时，才需可选挂载能力后端：
-> 在配置中打开 `capability.enabled` 并给出 `capability.args`（见 `cordis.yml.example`）。
+> 在配置中打开 `capability.enabled` 并给出 `capability.args`（见 `dsh/cordis.yml.example`）。
 > 默认关闭 → 主仓保持**纯大脑单进程**；未挂载时角色生成接口 fail-closed，而
 > 转录 / 历史 / 翻译 / 落图（走大脑）始终可用。
 
@@ -539,7 +539,7 @@ npm install && npm run build     # 构建插件本身（tsc → lib/）
       desensitize: true                # 写入前过滤敏感信息（密钥/密码/身份证/手机号）
 ```
 
-完整示例见 [`cordis.yml.example`](../cordis.yml.example)。
+完整示例见 [`cordis.yml.example`](../../dsh/cordis.yml.example)。
 
 ## 配置项