@furongjun1999/dsh-memory 0.4.6 → 0.4.7

package/docs/discipline/templates/full.md.tmpl

@@ -0,0 +1,58 @@
+# 工作纪律（%%VERSION%%）· %%COUNT%% 条
+
+> 本文件由 `scripts/render_discipline.py` 从真源
+> `docs/工作纪律_认知图条目_v1.1.json` 渲染生成，**请勿手改**；改真源后重跑渲染。
+> 真源指纹（SHA256 前16位）：%%SOURCE_SHA%%
+
+## 概述
+
+%%OVERVIEW%%
+
+## 执行公约
+
+| 约定 | 内容 |
+|---|---|
+| **0.1 会话起始先查记忆** | 动手前先调认知图入口——工具名随端：MCP 端 = server「mdcg」的 `cg`；DSH 端 = 内建基元 `lingshu_cg`（即下文所有 `cg(...)`，同一服务勿因名字不同而猜测）。**`op` 是必填参数（route/read/write/verify/review…），任何调用都显式传、勿省略**。先 `cg(op=route, intent=<任务意图>)`；命中纪律/知识则按其 `execution.how` 执行。**禁止跳过此步直接改代码或跑命令。** |
+| **0.2 命中即声明** | 命中纪律须在回复中输出该条 `response.direct` 原文（「按工作纪律第 N 条：…」）。**这是「已执行」的唯一可观测证据；未声明即视为未执行。** |
+| **0.3 产出即证据** | 「动作」栏要求的产出（判定单／检索结果／验证结论／归档节点 id）必须实际给出，缺失即未执行。 |
+| **0.4 违规即归档** | 发现自己违反任一条 → 第 4 条归因 + 第 16 条写入灵枢记忆。**隐瞒违规本身是更严重的违规。** |
+| **0.5 例外不外溢** | 某条的「不适用」只豁免该条，不豁免其它条。 |
+
+## 纪律路由表
+
+%%ROUTING_TABLE_FULL%%
+
+## 声明出口（`response.direct` 原文 · 未输出即未执行）
+
+%%DECLARATION_TABLE%%
+
+## 记忆接口速查（`cg` / `stg`）
+
+工具名随端：MCP 端 = server「mdcg」的 `cg` / `stg`；DSH 端 = 内建基元 `lingshu_cg` / `lingshu_stg`（与 `cg` / `stg` 同一服务，仅注册名不同）。**`op` 一律必填。**
+
+| op | 用途 | 常用参数 |
+|---|---|---|
+| `route` | 任务开始路由记忆（返回知识 + 建议能力，不执行） | `intent`（任务意图） |
+| `read` | 召回/检索/按 id 取（`session`=只取该会话归属的记忆，缺省不过滤） | `query` / `node_id` / `k` / `layer` / `budget_tokens` / `context` / `session` |
+| `write` | 写入（先按 content_kind 审核 + 冲突检测，ACCEPT 落盘 / DEFER 入审核队列 / REJECT 入负记忆）。**自动归属**：frontmatter 带 `writer`/`session`/`harness`（服务端身份，不可伪造） | `content` / `content_kind`（text/code/…）/ `node_id`（同 id 即改写）/ `layer` / `tags` / `importance` / `verification_basis` / `condition_space` / `gated` / `consistency` / `on_conflict`（reject\|defer\|record） |
+| `verify` | 对节点做证据验证（confirmed/weakened/falsified）——**非队列裁决** | `node_id` / `verdict` / `evidence` |
+| `review` | 审核队列：`action=list/rounds/records` 查看；传 `pid`+`decision`+`reason` 即裁决落盘（accept/reject/edit/merge，**需 can_admin**；本机未配置外部验证器时写入恒 DEFER 入队，靠此裁决落盘） | `action` / `pid` / `decision` / `reason` / `edits` / `merge_into` |
+| `recent` | 近期事件窗口 | `action`（add/list/clear）/ `limit` |
+| `forget` / `protect` | 软删除/恢复 / 写保护 | `node_id` |
+
+三条调用铁律：
+1. **`op` 必填**——漏传会触发参数签名推导兜底（返回标记 `op_derived: true`），复杂任务中也必须显式传，防静默执行错误意图。
+2. **返回 `moved_to: "review_queue"` / `verdict: DEFER/REJECT` 时不要重试**——这是校验闸门的正常行为（返回自带 `hint` 说明），重试同样结果；落盘须由设计者权限（can_admin）经 `op=review` 裁决（decision=accept/reject/edit/merge，本机工具：`python scripts/review_cli.py list`），agent 端无裁决权是设计（写入者不得自裁自决），转告使用者即可。
+3. `stg` 同理经 `op` 分发（`timeline` / `relation` / `anchors` 等）。
+
+## 收尾强制流程（任务完成时不可跳过）
+
+1. **验证**（第 5 条）：未验证不固化——回放／断言／回归通过才收尾。
+2. **归档**（第 16 条）：提炼关键修改（内容／原因／位置／验证结论四要素，禁写中间过程）→ 写入灵枢记忆。
+3. **自检**（第 4 条）：本次是否有违规？有 → 按条件层归因，并补不适用条件。
+
+## 本文件维护（防漂移）
+
+- 真源唯一：`docs/工作纪律_认知图条目_v1.1.json`。
+- 本文件是**渲染产物**，不是手抄投影；任何端的手改都会被 `scripts/verify_discipline.py` 判为漂移。
+- 改纪律 → 改真源 → `render_discipline.py --write` → `verify_discipline.py` 通过 → 提交。

package/docs/discipline/templates/skill.md.tmpl

@@ -0,0 +1,23 @@
+---
+name: linglu-discipline
+description: 灵枢工作纪律与记忆操作规程（16 条）。会话开始或任何任务动手前使用；命中「查记忆 / 写记忆 / 命令执行 / 入库提交 / 根因分析 / 敏感信息 / 公开产物」等触发词时必须先加载本 skill。
+---
+
+你是挂载了灵枢（Lingshu）长期记忆的 Agent。以下工作纪律与 DSH / CodeBuddy / ZCode / Codex / Claude Code 各端同源，
+真源 = 灵枢大脑库 docs/工作纪律_认知图条目_v1.1.json（%%VERSION%%），共 %%COUNT%% 条。
+命中「触发」即执行该条「动作」，并在回复中原样输出该条「声明」；未声明视为未执行。
+
+【执行公约】
+0.1 会话起始先查记忆：动手前先调认知图入口（MCP server「mdcg」的 cg 工具；op 为必填参数，勿省略）cg(op=route, intent=<任务意图>)；命中纪律/知识则按其「动作」执行。
+0.2 命中即声明：输出该条 response.direct 原文——这是「已执行」的唯一可观测证据。
+0.3 产出即证据：动作栏要求的产出（判定单／检索结果／验证结论／归档节点 id）必须实际给出，缺失即未执行。
+0.4 违规即归档：发现违规 → 第 4 条归因 + 第 16 条写入灵枢记忆；隐瞒违规本身是更严重的违规。
+0.5 例外不外溢：某条的「不适用」只豁免该条，不豁免其它条。
+
+%%PREAMBLE%%【%%COUNT%% 条工作纪律 · 编号｜触发 → 动作 → 命中后必须输出的声明】
+%%ROUTING_TABLE%%
+
+【使用须知】
+- 「触发」命中即执行对应「动作」，并在回复中输出该条「声明」原文。
+- 逐条的完整「不适用」边界见真源 JSON 对应节点的 negative.reject；此处仅列关键项。
+- 本段为自动生成（真源指纹 SHA256 前16位：%%SOURCE_SHA%%），请勿手改；改真源后重跑 scripts/render_discipline.py。

package/docs/experiments/bench6-rust-rerun/bench_latency.py

@@ -0,0 +1,116 @@
+# -*- coding: utf-8 -*-
+"""bench6 rust 引擎检索计时：三口径 × 双语各 100 题，逐请求 perf_counter 计时。
+
+目的：补横评（docs/横评_六家100题中英双查_v1.0.md §8）中缺失的灵枢耗时行。
+口径：与竞品行同口径——「客户端端到端调用 100 题的总墙钟时间」；
+      rust 侧客户端开销 = stdin/stdout JSON 行 IPC 往返（serve 协议固有）。
+校验：计时用的同一批 hits 复算 bc.rows_from_hits + ec.summarize，
+      须与 py 基线 summary 一致——证明测的就是与横评对齐的口径。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(_HERE)))
+for _p in (_ROOT, os.path.join(_ROOT, "md_cg")):
+    if _p not in sys.path:
+        sys.path.insert(0, _p)
+
+from md_cg import bench6_common as bc      # noqa: E402
+from md_cg import eval_common as ec        # noqa: E402
+from run_rust import ARMS, BASELINE, K, ROOTS, Serve  # noqa: E402
+
+OUT_JSON = os.path.join(_HERE, "rust_latency.json")
+WARMUP = 10          # 预热请求数（页缓存/连接稳定），不计入统计
+
+
+def pct(values, q):
+    """线性插值百分位（ms）。"""
+    s = sorted(values)
+    if not s:
+        return 0.0
+    i = (len(s) - 1) * q
+    lo, hi = int(i), min(int(i) + 1, len(s) - 1)
+    return s[lo] + (s[hi] - s[lo]) * (i - lo)
+
+
+def time_arm(questions, root, paths):
+    """单臂计时：返回 (per-lang 计时统计, per-lang hits)。"""
+    stats, hits = {}, {"zh": {}, "en": {}}
+    with Serve(os.path.join(ROOTS, root), paths) as s:
+        for q in questions[: WARMUP // 2]:
+            s.search(q["question_zh"])
+            s.search(q["question_en"])
+        for lang, qkey in (("zh", "question_zh"), ("en", "question_en")):
+            ms, t0 = [], time.perf_counter()
+            for q in questions:
+                t1 = time.perf_counter()
+                hits[lang][q["qid"]] = s.search(q[qkey])
+                ms.append((time.perf_counter() - t1) * 1000.0)
+            total = time.perf_counter() - t0
+            stats[lang] = {
+                "total_s": round(total, 3), "n": len(ms),
+                "mean_ms": round(sum(ms) / len(ms), 3),
+                "p50_ms": round(pct(ms, 0.50), 3),
+                "p95_ms": round(pct(ms, 0.95), 3),
+                "max_ms": round(max(ms), 3),
+            }
+    return stats, hits
+
+
+def verify(hits, base_arm, base):
+    """同一批 hits 复算指标，与 py 基线 summary 比对。"""
+    ok = True
+    for lang in ("zh", "en"):
+        rows = bc.rows_from_hits(base["questions"], hits[lang], k=K)
+        got = ec.summarize(rows, k=K)
+        exp = base["arms"][base_arm]["langs"][lang]["summary"]
+        for m in ("hit@1", "hit@5", "mrr"):
+            if abs(got[m] - exp[m]) > 1e-9:
+                print("  [MISMATCH] %s %s: rust %.4f vs py %.4f"
+                      % (lang, m, got[m], exp[m]))
+                ok = False
+    return ok
+
+
+def main():
+    man = bc.prepare(verbose=False)
+    data = bc.load()
+    questions = data["questions"]
+    base = json.load(open(BASELINE, encoding="utf-8"))
+    # run_rust 用的 base 是裸 results json；此处兼容 dict 带 questions
+    base["questions"] = questions
+    print("[bench6-latency] 题 %d · 池 %d · 预热 %d 请求" %
+          (len(questions), man["pool"]["n"], WARMUP))
+
+    out = {"k": K, "warmup": WARMUP,
+           "engine": "rust mdcg-eval --serve (JSON 行 IPC)",
+           "arms": {}}
+    all_ok = True
+    for arm, root, paths, base_arm in ARMS:
+        print("\n== %s  (root=%s paths=%s ↔ %s)" % (arm, root, paths, base_arm))
+        stats, hits = time_arm(questions, root, paths)
+        ok = verify(hits, base_arm, base)
+        all_ok &= ok
+        for lang in ("zh", "en"):
+            st = stats[lang]
+            print("  [%s] %s  total %.3fs  mean %.3fms  p50 %.3fms  p95 %.3fms  max %.3fms"
+                  % ("OK " if ok else "BAD", lang, st["total_s"],
+                     st["mean_ms"], st["p50_ms"], st["p95_ms"], st["max_ms"]))
+        out["arms"][arm] = {"baseline_arm": base_arm,
+                            "metrics_match_baseline": ok, "latency": stats}
+
+    with open(OUT_JSON, "w", encoding="utf-8") as f:
+        json.dump(out, f, ensure_ascii=False, indent=2)
+    print("\n结果 → %s" % OUT_JSON)
+    print("口径校验：%s" % ("三组×双语指标与 py 基线一致（测的对齐口径）" if all_ok
+                           else "存在不一致——数字不可用，先排查"))
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/docs/experiments/bench6-rust-rerun/run_rust.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""bench6 rust 复跑驱动：mdcg-eval --serve 引擎重跑 100 题×双语，与 py 基线题级对比。
+
+口径（与 py 基线 results_v1.0.json 同源同判据）：
+  rust_lex        ↔ lingshu_lex          lex 库（无 meta）· 单词法路 · 无 context
+  rust_rrf4_noref ↔ lingshu_rrf4_noref   rrf4 库（有 meta）· 四路 · 无 context
+                                          （py 无 context 时 bucket 亦恒空，与 serve 天然同构）
+  rust_lex_meta   ↔ lingshu_lex_meta     rrf4 库（有 meta）· 单词法路 · 无 context
+  （lingshu_rrf4 带 context，serve 协议无 context 参数 → 不复刻，如实跳过）
+
+评分复用 bc.rows_from_hits + ec.summarize（与六家横评同一份判据），不重造。
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.dirname(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 bench6_common as bc      # noqa: E402
+from md_cg import eval_common as ec        # noqa: E402
+
+EXE = os.path.join(HERE, "rust", "target", "release", "mdcg-eval.exe")
+ROOTS = os.path.join(HERE, "_md_cg_eval_bench6")
+BASELINE = os.path.join(HERE, "data", "benchmarks", "bench6-100-zh-en", "results_v1.0.json")
+OUT_JSON = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rust_rerun_result.json")
+
+ARMS = [
+    # (rust 臂名, 库, 路清单, 基线臂名)
+    ("rust_lex", "lex", "lexical", "lingshu_lex"),
+    ("rust_rrf4_noref", "rrf4", "lexical,bucket,entity,graph", "lingshu_rrf4_noref"),
+    ("rust_lex_meta", "rrf4", "lexical", "lingshu_lex_meta"),
+]
+K = 5
+
+
+class Serve:
+    """mdcg-eval --serve 进程实例：一行请求一行响应（协议见 rust/src/serve.rs）。"""
+
+    def __init__(self, root: str, paths: str):
+        env = dict(os.environ, PYTHONUTF8="1")
+        self.p = subprocess.Popen(
+            [EXE, "--serve", "--root", root, "--paths", paths],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, encoding="utf-8", errors="replace",
+            shell=False, env=env, cwd=HERE)
+
+    def __enter__(self):
+        ready = self.p.stderr.readline()          # 阻塞等「[serve] 就绪 …」
+        if "就绪" not in ready:
+            raise RuntimeError("serve 启动失败: %s" % ready.strip())
+        print("    %s" % ready.strip())
+        return self
+
+    def search(self, query: str, k: int = K):
+        line = json.dumps({"op": "search", "query": query, "k": k}, ensure_ascii=False)
+        self.p.stdin.write(line + "\n")
+        self.p.stdin.flush()
+        resp = json.loads(self.p.stdout.readline())
+        if not resp.get("ok"):
+            raise RuntimeError("search 失败: %s" % resp.get("error"))
+        return [h["id"] for h in resp["hits"]]
+
+    def __exit__(self, *exc):
+        try:
+            self.p.stdin.write("quit\n")
+            self.p.stdin.flush()
+        except OSError:
+            pass
+        self.p.wait(timeout=10)
+        return False
+
+
+def run_arm(questions, root, paths):
+    hits = {"zh": {}, "en": {}}
+    with Serve(os.path.join(ROOTS, root), paths) as s:
+        for q in questions:
+            hits["zh"][q["qid"]] = s.search(q["question_zh"])
+            hits["en"][q["qid"]] = s.search(q["question_en"])
+    out = {}
+    for lang, by_qid in hits.items():
+        rows = bc.rows_from_hits(questions, by_qid, k=K)
+        out[lang] = {"summary": ec.summarize(rows, k=K), "rows": rows}
+    return out
+
+
+def compare(rust_lang, base_lang):
+    """题级 rank 对比。返回 (一致数, 差异明细)。"""
+    bi = {r["qid"]: r["rank"] for r in base_lang["rows"]}
+    diffs = []
+    for r in rust_lang["rows"]:
+        b = bi.get(r["qid"])
+        if b != r["rank"]:
+            diffs.append({"qid": r["qid"], "qtype": r["qtype"],
+                          "py_rank": b, "rust_rank": r["rank"]})
+    same = len(rust_lang["rows"]) - len(diffs)
+    return same, diffs
+
+
+def main():
+    man = bc.prepare(verbose=False)
+    data = bc.load()
+    questions = data["questions"]
+    base = json.load(open(BASELINE, encoding="utf-8"))
+    print("[bench6-rust] 题 %d · 池 %d · 引擎 %s" % (len(questions), man["pool"]["n"], EXE))
+
+    result = {"k": K, "engine": "rust (mdcg-eval --serve)",
+              "baseline": BASELINE, "arms": {}}
+    all_ok = True
+    for arm, root, paths, base_arm in ARMS:
+        print("\n== %s  (root=%s paths=%s ↔ %s)" % (arm, root, paths, base_arm))
+        out = run_arm(questions, root, paths)
+        result["arms"][arm] = {"baseline_arm": base_arm, "langs": out}
+        for lang in ("zh", "en"):
+            rs, bs = out[lang]["summary"], base["arms"][base_arm]["langs"][lang]["summary"]
+            same, diffs = compare(out[lang], base["arms"][base_arm]["langs"][lang])
+            flag = "OK " if not diffs else "DIFF"
+            if diffs:
+                all_ok = False
+            print("  [%s] %s  hit@1 %s→%s  hit@5 %s→%s  mrr %s→%s  题级一致 %d/%d"
+                  % (flag, lang, bs["hit@1"], rs["hit@1"], bs["hit@5"], rs["hit@5"],
+                     bs["mrr"], rs["mrr"], same, rs["n"]))
+            for d in diffs[:8]:
+                print("       %s  py=%s rust=%s (%s)" % (d["qid"], d["py_rank"], d["rust_rank"], d["qtype"]))
+            if len(diffs) > 8:
+                print("       …共 %d 题差异" % len(diffs))
+            out[lang]["compare"] = {"same": same, "diffs": diffs}
+
+    with open(OUT_JSON, "w", encoding="utf-8") as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
+    print("\n结果 → %s" % OUT_JSON)
+    print("结论：%s" % ("三组×双语题级 rank 与 py 基线逐位一致" if all_ok
+                        else "存在题级差异（见上）——须按第 4 条根因排查后再定性"))
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/docs/experiments/bench6-rust-rerun/rust_latency.json

@@ -0,0 +1,73 @@
+{
+  "k": 5,
+  "warmup": 10,
+  "engine": "rust mdcg-eval --serve (JSON 行 IPC)",
+  "arms": {
+    "rust_lex": {
+      "baseline_arm": "lingshu_lex",
+      "metrics_match_baseline": true,
+      "latency": {
+        "zh": {
+          "total_s": 0.007,
+          "n": 100,
+          "mean_ms": 0.074,
+          "p50_ms": 0.07,
+          "p95_ms": 0.099,
+          "max_ms": 0.149
+        },
+        "en": {
+          "total_s": 0.018,
+          "n": 100,
+          "mean_ms": 0.18,
+          "p50_ms": 0.186,
+          "p95_ms": 0.249,
+          "max_ms": 0.49
+        }
+      }
+    },
+    "rust_rrf4_noref": {
+      "baseline_arm": "lingshu_rrf4_noref",
+      "metrics_match_baseline": true,
+      "latency": {
+        "zh": {
+          "total_s": 0.012,
+          "n": 100,
+          "mean_ms": 0.12,
+          "p50_ms": 0.114,
+          "p95_ms": 0.179,
+          "max_ms": 0.203
+        },
+        "en": {
+          "total_s": 0.023,
+          "n": 100,
+          "mean_ms": 0.233,
+          "p50_ms": 0.231,
+          "p95_ms": 0.338,
+          "max_ms": 0.453
+        }
+      }
+    },
+    "rust_lex_meta": {
+      "baseline_arm": "lingshu_lex_meta",
+      "metrics_match_baseline": true,
+      "latency": {
+        "zh": {
+          "total_s": 0.009,
+          "n": 100,
+          "mean_ms": 0.094,
+          "p50_ms": 0.081,
+          "p95_ms": 0.162,
+          "max_ms": 0.288
+        },
+        "en": {
+          "total_s": 0.019,
+          "n": 100,
+          "mean_ms": 0.188,
+          "p50_ms": 0.192,
+          "p95_ms": 0.289,
+          "max_ms": 0.375
+        }
+      }
+    }
+  }
+}