@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/migrate_aeis.py

@@ -1,213 +1,221 @@
-# -*- coding: utf-8 -*-
-"""md_cg · 本地记忆迁移（AEIS sqlite → md 认知图）
-
-把 `AEIS/data/aeis_memory.db` 的认知图（nodes + edges）迁到 md_cg 目录，
-供 dsh / zcode 共同读写。**这是本地私有记忆**：默认 sensitivity=private。
-
-用法：
-    python -m md_cg.migrate_aeis --db <sqlite> --root <md_root> [选项]
-
-选项：
-    --layers knowledge,anchor,self   只迁这些层（默认全部）
-    --limit N                        只迁前 N 条（调试）
-    --dry-run                        只统计不写
-    --clearance private              调用方密级（默认 private）
-
-校验（全量，非抽样）：节点数等价 + content/tags/importance/confidence/
-condition_space/edges/access_count/modality/created_at 逐字段等价。
-
-层映射：context→contextual；knowledge/anchor/self/structural 同名。
-幂等：按 id 原子覆盖写，可反复执行。
-"""
-from __future__ import annotations
-
-import collections
-import io
-import json
-import os
-import sqlite3
-import sys
-import time
-
-from . import subgraph
-from .mdcos import MdCGSecure
-from .security import Principal, DEFAULT_SENSITIVITY
-
-# AEIS layer → md_cg layer
-LAYER_MAP = {
-    "anchor": "anchor",
-    "structural": "structural",
-    "knowledge": "knowledge",
-    "context": "contextual",
-    "contextual": "contextual",
-    "self": "self",
-    "rejected": "rejected",
-    "unresolved": "unresolved",
-}
-MDCG_LAYERS = ("anchor", "structural", "knowledge", "contextual", "self",
-               "rejected", "unresolved")
-
-
-def _norm_text(s: str) -> str:
-    """统一换行：md 是 LF 文本格式，把 CRLF/CR 规范化为 LF。
-
-    源 sqlite 里的内容常含 \\r\\n（Windows 剪贴板/网页抓取），而 md 文件按 LF 存；
-    不规范化会让「content 全量等价」校验出现假失败（实测 24/4523）。
-    """
-    if not s:
-        return s or ""
-    return s.replace("\r\n", "\n").replace("\r", "\n")
-
-
-def _j(v, default):
-    if v is None or v == "":
-        return default
-    if isinstance(v, (dict, list)):
-        return v
-    try:
-        return json.loads(v)
-    except (ValueError, TypeError):
-        return default
-
-
-def _f(v, default=0.0):
-    try:
-        return float(v)
-    except (TypeError, ValueError):
-        return default
-
-
-def load_nodes(db: str, layers=None, limit=None):
-    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
-    con.row_factory = sqlite3.Row
-    sql, params = "SELECT * FROM nodes", []
-    if layers:
-        sql += " WHERE layer IN (%s)" % ",".join("?" * len(layers))
-        params = list(layers)
-    sql += " ORDER BY created_at"
-    if limit:
-        sql += f" LIMIT {int(limit)}"
-    rows = [dict(r) for r in con.execute(sql, params)]
-    con.close()
-    return rows
-
-
-def load_edges(db: str):
-    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
-    out = collections.defaultdict(list)
-    for src, tgt, rel, conf, ver in con.execute(
-            "SELECT source_id, target_id, relation_type, confidence, verified FROM edges"):
-        out[src].append(subgraph.normalize_edge(tgt, rel, _f(conf, 0.7), int(ver or 0)))
-    con.close()
-    return out
-
-
-def migrate(db: str, root: str, layers=None, limit=None, dry_run=False,
-            clearance: str = "private", verbose=True):
-    rows = load_nodes(db, layers, limit)
-    edges = load_edges(db)
-    principal = Principal(tenant="aeis-local", actor="migrate",
-                          clearance=clearance, can_write=True, can_admin=True)
-    cg = MdCGSecure(root, principal=principal, autoflush=500)
-
-    unknown_layers, written = set(), 0
-    t0 = time.time()
-    if not dry_run:
-        for i, r in enumerate(rows, 1):
-            raw_layer = (r.get("layer") or "knowledge")
-            layer = LAYER_MAP.get(raw_layer)
-            if layer is None:
-                unknown_layers.add(raw_layer)
-                layer = "knowledge"
-            cg.add(
-                r["id"], _norm_text(r["content"] or ""), layer=layer,
-                override=True,     # 迁移是受控整库写入：按 id 幂等覆盖，显式越权
-                sensitivity=DEFAULT_SENSITIVITY if clearance != "private" else "private",
-                tags=_j(r.get("tags"), []),
-                condition_space=_j(r.get("condition_space"), {}),
-                importance=_f(r.get("importance"), 0.5),
-                confidence=_f(r.get("confidence"), 0.6),
-                edges=edges.get(r["id"], []),
-                created_at=_f(r.get("created_at"), 0),
-                modality=r.get("modality") or "text",
-                temporal=r.get("temporal_coordinate"),
-                spatial=_j(r.get("spatial_coordinates"), {}),
-                semantic_coordinates=_j(r.get("semantic_coordinates"), {}),
-                state_attributes=_j(r.get("state_attributes"), {}),
-                entity_id=r.get("entity_id"),
-                access_count=int(r.get("access_count") or 0),
-                last_access=_f(r.get("last_access"), 0),
-                # legacy 标记：迁移进来的历史记忆无 CCG 5 要素，
-                # 资格判定据此判 DEFER（可检索、待补条件）而非 BLINDSPOT。
-                ccg_exempt=True,
-                migrated_from="aeis_memory.db",
-            )
-            written += 1
-            if verbose and i % 2000 == 0:
-                print(f"    …已写入 {i}/{len(rows)}（{time.time()-t0:.0f}s）", flush=True)
-        cg.flush()
-
-    # ---------- 全量等价校验 ----------
-    bad = []
-    if not dry_run:
-        for r in rows:
-            got = cg.get(r["id"])
-            if not got:
-                bad.append((r["id"], "missing"))
-                continue
-            fm = got["frontmatter"]
-            checks = [
-                ("content", (got["content"] or "").rstrip("\n") != _norm_text(r["content"] or "").rstrip("\n")),
-                ("tags", _j(fm.get("tags"), []) != _j(r.get("tags"), [])),
-                ("importance", abs(_f(fm.get("importance")) - _f(r.get("importance"))) > 1e-9),
-                ("confidence", abs(_f(fm.get("confidence")) - _f(r.get("confidence"))) > 1e-9),
-                ("condition_space", _j(fm.get("condition_space"), {}) != _j(r.get("condition_space"), {})),
-                ("edges", len(fm.get("edges") or []) != len(edges.get(r["id"], []))),
-                ("access_count", int(fm.get("access_count") or 0) != int(r.get("access_count") or 0)),
-                ("modality", (fm.get("modality") or "text") != (r.get("modality") or "text")),
-                ("created_at", abs(_f(fm.get("created_at")) - _f(r.get("created_at"))) > 1e-6),
-                ("entity_id", (fm.get("entity_id") or None) != (r.get("entity_id") or None)),
-            ]
-            for name, is_bad in checks:
-                if is_bad:
-                    bad.append((r["id"], name))
-                    break
-
-    report = {
-        "db": db, "root": root, "dry_run": dry_run,
-        "layers_filter": layers,
-        "sqlite_nodes": len(rows),
-        "md_nodes_total": len(cg.index["nodes"]),
-        "written": written,
-        "count_equal": (dry_run or len(rows) == written),
-        "field_mismatches": len(bad),
-        "samples": bad[:5],
-        "edges_total": sum(len(v) for v in edges.values()),
-        "unknown_layers": sorted(unknown_layers),
-        "elapsed_sec": round(time.time() - t0, 1),
-        "health": cg.health() if not dry_run else None,
-    }
-    if verbose:
-        print(json.dumps(report, ensure_ascii=False, indent=2))
-    cg.close()
-    return report
-
-
-def main(argv):
-    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
-    def opt(name, default=None):
-        return argv[argv.index(name) + 1] if name in argv else default
-    db = opt("--db")
-    root = opt("--root")
-    if not db or not root:
-        print(__doc__)
-        return 1
-    layers = opt("--layers")
-    layers = [x.strip() for x in layers.split(",")] if layers else None
-    return 0 if migrate(db, root, layers=layers, limit=opt("--limit"),
-                        dry_run="--dry-run" in argv,
-                        clearance=opt("--clearance", "private")) else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv))
+# -*- coding: utf-8 -*-
+"""md_cg · 本地记忆迁移（AEIS sqlite → md 认知图）
+
+把 `AEIS/data/aeis_memory.db` 的认知图（nodes + edges）迁到 md_cg 目录，
+供 dsh / zcode 共同读写。**这是本地私有记忆**：默认 sensitivity=private。
+
+用法：
+    python -m md_cg.migrate_aeis --db <sqlite> --root <md_root> [选项]
+
+选项：
+    --layers knowledge,anchor,self   只迁这些层（默认全部）
+    --limit N                        只迁前 N 条（调试）
+    --dry-run                        只统计不写
+    --clearance private              调用方密级（默认 private）
+
+校验（全量，非抽样）：节点数等价 + content/tags/importance/confidence/
+condition_space/edges/access_count/modality/created_at 逐字段等价。
+
+层映射：context→contextual；knowledge/anchor/self/structural 同名。
+幂等：按 id 原子覆盖写，可反复执行。
+"""
+from __future__ import annotations
+
+import collections
+import io
+import json
+import os
+import sqlite3
+import sys
+import time
+
+from . import subgraph
+from .mdcos import MdCGSecure
+from .security import Principal, DEFAULT_SENSITIVITY
+
+# AEIS layer → md_cg layer
+LAYER_MAP = {
+    "anchor": "anchor",
+    "structural": "structural",
+    "knowledge": "knowledge",
+    "context": "contextual",
+    "contextual": "contextual",
+    "self": "self",
+    "rejected": "rejected",
+    "unresolved": "unresolved",
+}
+MDCG_LAYERS = ("anchor", "structural", "knowledge", "contextual", "self",
+               "rejected", "unresolved")
+
+
+# 生效条件：s 为假值（None/空串）时返回 s or ""（即空串），否则返回把 "\r\n" 与 "\r" 依次替换为 "\n" 后的字符串。
+def _norm_text(s: str) -> str:
+    """统一换行：md 是 LF 文本格式，把 CRLF/CR 规范化为 LF。
+
+    源 sqlite 里的内容常含 \\r\\n（Windows 剪贴板/网页抓取），而 md 文件按 LF 存；
+    不规范化会让「content 全量等价」校验出现假失败（实测 24/4523）。
+    """
+    if not s:
+        return s or ""
+    return s.replace("\r\n", "\n").replace("\r", "\n")
+
+
+# 生效条件：v 为 None 或 v == "" 时返回 default；v 是 dict/list 时原样返回 v；其余值经 json.loads(v) 解析成功则返回解析结果，抛 ValueError/TypeError 时返回 default。
+def _j(v, default):
+    if v is None or v == "":
+        return default
+    if isinstance(v, (dict, list)):
+        return v
+    try:
+        return json.loads(v)
+    except (ValueError, TypeError):
+        return default
+
+
+# 生效条件：float(v) 转换成功时返回该浮点值，抛 TypeError/ValueError 时返回 default（未传则取默认实参 0.0）。
+def _f(v, default=0.0):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return default
+
+
+# 生效条件：db 以只读 URI 打开 nodes 表；layers 为真值时加 "layer IN (...)" 过滤（None 或空列表不过滤），limit 为真值时拼接 LIMIT int(limit)（None/0/"" 等假值不加 LIMIT），返回按 created_at 排序的行转成的 dict 列表 rows。
+def load_nodes(db: str, layers=None, limit=None):
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    con.row_factory = sqlite3.Row
+    sql, params = "SELECT * FROM nodes", []
+    if layers:
+        sql += " WHERE layer IN (%s)" % ",".join("?" * len(layers))
+        params = list(layers)
+    sql += " ORDER BY created_at"
+    if limit:
+        sql += f" LIMIT {int(limit)}"
+    rows = [dict(r) for r in con.execute(sql, params)]
+    con.close()
+    return rows
+
+
+# 生效条件：db 以只读 URI 打开，遍历 edges 表全部行，按 source_id 聚合为 defaultdict(list)，每项取 normalize_edge(target_id, relation_type, _f(confidence, 0.7), int(verified or 0))，返回该 out。
+def load_edges(db: str):
+    con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+    out = collections.defaultdict(list)
+    for src, tgt, rel, conf, ver in con.execute(
+            "SELECT source_id, target_id, relation_type, confidence, verified FROM edges"):
+        out[src].append(subgraph.normalize_edge(tgt, rel, _f(conf, 0.7), int(ver or 0)))
+    con.close()
+    return out
+
+
+# 生效条件：以 db、root 建库后，dry_run 为真则跳过写入与回读校验（written=0、count_equal 恒为真、health 为 None），为假则按 rows 逐条 override 写入并做 10 项字段回读比对累计 field_mismatches；clearance 非 "private" 时 sensitivity 取 DEFAULT_SENSITIVITY、否则为 "private"；layer 不在 LAYER_MAP 的记入 unknown_layers 并按 knowledge 写入；verbose 为真时打印 report；最终返回该 report。
+def migrate(db: str, root: str, layers=None, limit=None, dry_run=False,
+            clearance: str = "private", verbose=True):
+    rows = load_nodes(db, layers, limit)
+    edges = load_edges(db)
+    principal = Principal(tenant="aeis-local", actor="migrate",
+                          clearance=clearance, can_write=True, can_admin=True)
+    cg = MdCGSecure(root, principal=principal, autoflush=500)
+
+    unknown_layers, written = set(), 0
+    t0 = time.time()
+    if not dry_run:
+        for i, r in enumerate(rows, 1):
+            raw_layer = (r.get("layer") or "knowledge")
+            layer = LAYER_MAP.get(raw_layer)
+            if layer is None:
+                unknown_layers.add(raw_layer)
+                layer = "knowledge"
+            cg.add(
+                r["id"], _norm_text(r["content"] or ""), layer=layer,
+                override=True,     # 迁移是受控整库写入：按 id 幂等覆盖，显式越权
+                sensitivity=DEFAULT_SENSITIVITY if clearance != "private" else "private",
+                tags=_j(r.get("tags"), []),
+                condition_space=_j(r.get("condition_space"), {}),
+                importance=_f(r.get("importance"), 0.5),
+                confidence=_f(r.get("confidence"), 0.6),
+                edges=edges.get(r["id"], []),
+                created_at=_f(r.get("created_at"), 0),
+                modality=r.get("modality") or "text",
+                temporal=r.get("temporal_coordinate"),
+                spatial=_j(r.get("spatial_coordinates"), {}),
+                semantic_coordinates=_j(r.get("semantic_coordinates"), {}),
+                state_attributes=_j(r.get("state_attributes"), {}),
+                entity_id=r.get("entity_id"),
+                access_count=int(r.get("access_count") or 0),
+                last_access=_f(r.get("last_access"), 0),
+                # legacy 标记：迁移进来的历史记忆无 CCG 5 要素，
+                # 资格判定据此判 DEFER（可检索、待补条件）而非 BLINDSPOT。
+                ccg_exempt=True,
+                migrated_from="aeis_memory.db",
+            )
+            written += 1
+            if verbose and i % 2000 == 0:
+                print(f"    …已写入 {i}/{len(rows)}（{time.time()-t0:.0f}s）", flush=True)
+        cg.flush()
+
+    # ---------- 全量等价校验 ----------
+    bad = []
+    if not dry_run:
+        for r in rows:
+            got = cg.get(r["id"])
+            if not got:
+                bad.append((r["id"], "missing"))
+                continue
+            fm = got["frontmatter"]
+            checks = [
+                ("content", (got["content"] or "").rstrip("\n") != _norm_text(r["content"] or "").rstrip("\n")),
+                ("tags", _j(fm.get("tags"), []) != _j(r.get("tags"), [])),
+                ("importance", abs(_f(fm.get("importance")) - _f(r.get("importance"))) > 1e-9),
+                ("confidence", abs(_f(fm.get("confidence")) - _f(r.get("confidence"))) > 1e-9),
+                ("condition_space", _j(fm.get("condition_space"), {}) != _j(r.get("condition_space"), {})),
+                ("edges", len(fm.get("edges") or []) != len(edges.get(r["id"], []))),
+                ("access_count", int(fm.get("access_count") or 0) != int(r.get("access_count") or 0)),
+                ("modality", (fm.get("modality") or "text") != (r.get("modality") or "text")),
+                ("created_at", abs(_f(fm.get("created_at")) - _f(r.get("created_at"))) > 1e-6),
+                ("entity_id", (fm.get("entity_id") or None) != (r.get("entity_id") or None)),
+            ]
+            for name, is_bad in checks:
+                if is_bad:
+                    bad.append((r["id"], name))
+                    break
+
+    report = {
+        "db": db, "root": root, "dry_run": dry_run,
+        "layers_filter": layers,
+        "sqlite_nodes": len(rows),
+        "md_nodes_total": len(cg.index["nodes"]),
+        "written": written,
+        "count_equal": (dry_run or len(rows) == written),
+        "field_mismatches": len(bad),
+        "samples": bad[:5],
+        "edges_total": sum(len(v) for v in edges.values()),
+        "unknown_layers": sorted(unknown_layers),
+        "elapsed_sec": round(time.time() - t0, 1),
+        "health": cg.health() if not dry_run else None,
+    }
+    if verbose:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    cg.close()
+    return report
+
+
+# 生效条件：从 argv 取 --db/--root，二者任一为假值时打印 __doc__ 并返回 1；二者均真值时 --layers 为真值则按逗号切分并 strip 成列表（否则 None），再以 limit=--limit、dry_run=("--dry-run" in argv)、clearance=--clearance 或 "private" 调用 migrate 并返回 0（表达式 0 if migrate(...) else 0 恒为 0）。
+def main(argv):
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
+# 生效条件：外层 main 作用域的 argv 中若含 name，则返回其后的下一个元素 argv[argv.index(name)+1]，否则返回 default（未传则 None）。
+    def opt(name, default=None):
+        return argv[argv.index(name) + 1] if name in argv else default
+    db = opt("--db")
+    root = opt("--root")
+    if not db or not root:
+        print(__doc__)
+        return 1
+    layers = opt("--layers")
+    layers = [x.strip() for x in layers.split(",")] if layers else None
+    return 0 if migrate(db, root, layers=layers, limit=opt("--limit"),
+                        dry_run="--dry-run" in argv,
+                        clearance=opt("--clearance", "private")) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/md_cg/migrate_roleplay.py

@@ -54,6 +54,7 @@ TURN_ROLE = {"user": "user", "bot": "assistant", "assistant": "assistant"}
 # 读取源数据
 # --------------------------------------------------------------------------
 
+# 生效条件：path 能被 io.open 以 encoding="utf-8" 打开且内容为合法 JSON 时返回 json.load(f)，否则在 OSError 或 JSON 解析的 ValueError 时返回 default（仅这两类被捕获，其余异常不返回 default）。
 def _read_json(path, default):
     try:
         with io.open(path, encoding="utf-8") as f:
@@ -62,6 +63,7 @@ def _read_json(path, default):
         return default
 
 
+# 生效条件：roleplay_dir 下 _roles.json 读出的 raw 是 dict 且 raw.get("meta") 也是 dict 时返回 raw["meta"]，raw 是 dict 但 "meta" 非 dict（缺键或非 dict 值）时返回 raw，raw 不是 dict 时返回 {}。
 def load_roles(roleplay_dir):
     """读取 `_roles.json`，归一化根/嵌套两种格式 → {role_id: meta}。"""
     raw = _read_json(os.path.join(roleplay_dir, "_roles.json"), {})
@@ -70,6 +72,7 @@ def load_roles(roleplay_dir):
     return raw if isinstance(raw, dict) else {}
 
 
+# 生效条件：os.path.isdir(transcripts_dir) 为真时返回 out（按文件名排序只取 .jsonl，stem 以 "__" 切出 role_id/client_id 且 client_id 为空串时回落 "shared"，逐行 strip 后跳过空行与 json.loads 的 ValueError 行，成功 append 后 idx 递增，单个文件 OSError 则跳过该文件）；os.path.isdir 为假时直接返回空 out；transcripts_dir 为 None 时 os.path.isdir 会抛 TypeError。
 def load_transcripts(transcripts_dir):
     """读取全部 `*.jsonl` 转录 → [(role_id, client_id, idx, entry)]。"""
     out = []
@@ -100,6 +103,7 @@ def load_transcripts(transcripts_dir):
     return out
 
 
+# 生效条件：mutual_dir 为真值且 os.path.isdir(join(mutual_dir,"tasks")) 为真时，先按文件名序对 result-*.json 追加 (tid, claim, result) 并记入 seen（claim 取 task-{tid}.json 的 payload.claim，缺 payload/claim 或为假值时 strip 前回落 ""，task 文件读出为假值则回落 {}），再对未出现在 seen 的 task-*.json 追加 (tid, claim, None)，返回 out；mutual_dir 为假值（""/None 等）或 tasks 非目录时返回空 out。
 def load_mutual(mutual_dir):
     """读取互维任务/裁决 → [(task_id, claim, result|None)]。"""
     out, seen = [], set()
@@ -131,6 +135,7 @@ def load_mutual(mutual_dir):
 # 迁移
 # --------------------------------------------------------------------------
 
+# 生效条件：对 role_id 与 meta，标题角色名取 meta.get("name") 为真值时的该值、为假值或缺失时回落 role_id，随后仅对 scenario/first_mes/nsfw 中 meta.get(key) 不属于 (None, "", False) 的键各追加一行后返回 "\n".join(lines)。
 def _role_content(role_id, meta):
     name = meta.get("name") or role_id
     lines = [f"# 角色 {name}（{role_id}）"]
@@ -140,6 +145,7 @@ def _role_content(role_id, meta):
     return "\n".join(lines)
 
 
+# 生效条件：以 data_dir 的 roleplay、transcripts 子目录收集计划节点，mutual_dir 为假值（None/空串）时不加载互维数据；按 tenant、actor 派生 principal 后，dry_run 为真则只汇总、written=0 且不回读，为假则逐条 override 写入并回读校验 content/layer/tags；clearance 非 "private" 时 sensitivity 取 DEFAULT_SENSITIVITY、否则为 "private"；verbose 为真时打印 report；最终返回该 report。
 def migrate(data_dir, root, mutual_dir=None, dry_run=False,
             clearance="private", tenant="default", actor="dsh-memory", verbose=True):
     """把角色扮演 / 互维数据迁入认知图。
@@ -264,9 +270,11 @@ def migrate(data_dir, root, mutual_dir=None, dry_run=False,
     return report
 
 
+# 生效条件：argv 中同时出现 "--data-dir" 与 "--root" 且各自后一元素的取值为真值（非空串）时，以 opt("--mutual-dir")、"--dry-run" in argv、clearance 缺省 "private"、tenant 缺省 "default"、actor 缺省 "dsh-memory" 调用 migrate 并返回 0；二者任一缺失或取到空串时打印 __doc__ 并返回 1；若 "--data-dir"/"--root" 位于 argv 末尾则取后一元素时抛 IndexError，而非走返回 1 分支。
 def main(argv):
     sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
 
+# 生效条件：name 出现在外层 main 的形参 argv（闭包读取）中且其后还有元素时返回 argv[argv.index(name)+1]，name 不在 argv 时返回 default（默认 None），name 位于 argv 末尾时 argv[index+1] 抛 IndexError 而不返回 default。
     def opt(name, default=None):
         return argv[argv.index(name) + 1] if name in argv else default
 

package/md_cg/migrate_wisdom_graph.py

@@ -43,6 +43,7 @@ DEFAULT_DB = os.path.join(_HERE, "whitebox_kb", "wisdom", "wisdom-book-cloud.db"
 DEFAULT_ROOT = os.path.join(os.path.dirname(_HERE), "_md_cg_wisdom_graph")
 
 
+# 生效条件：s 为假值（None/""/0 等）时返回 s or ""（None→""、0→""），否则返回把 "\r\n"、"\r" 依次替换为 "\n" 的字符串。
 def _norm_text(s):
     """统一换行：md 按 LF 存，源库常含 CRLF，不规范化会造成假失败。"""
     if not s:
@@ -50,6 +51,7 @@ def _norm_text(s):
     return s.replace("\r\n", "\n").replace("\r", "\n")
 
 
+# 生效条件：v 为 None 或等于 "" 时返回 default；v 是 dict 或 list 时原样返回 v；否则 json.loads(v)，遇 ValueError/TypeError 时返回 default。
 def _j(v, default):
     if v is None or v == "":
         return default
@@ -61,6 +63,7 @@ def _j(v, default):
         return default
 
 
+# 生效条件：float(v) 成功时返回该浮点值（含 v="" 之外的数值串），抛 TypeError/ValueError 时返回 default，default 缺省为 0.0。
 def _f(v, default=0.0):
     try:
         return float(v)
@@ -68,10 +71,12 @@ def _f(v, default=0.0):
         return default
 
 
+# 生效条件：任何传入的 db 都拼成 f"file:{db}?mode=ro" 并 uri=True 返回 sqlite3.connect 的连接（源码未对 db 做存在性或类型校验）。
 def _connect(db):
     return sqlite3.connect(f"file:{db}?mode=ro", uri=True)
 
 
+# 生效条件：db 经 _connect 只读打开，limit 为真值（非 None/0/""）时 SQL 追加 f" LIMIT {int(limit)}"，limit 为假值时无 LIMIT、返回按 created_at 排序的全部 nodes 字典列表。
 def load_nodes(db, limit=None):
     con = _connect(db)
     con.row_factory = sqlite3.Row
@@ -83,6 +88,7 @@ def load_nodes(db, limit=None):
     return rows
 
 
+# 生效条件：db 只读打开后逐条 edges 按 rel=(relation_type or "").strip() 分派——等于 LEVEL_REL 的记入 children[source_id]，其余记入 relations[source_id] 的边字典（target、relation_type、confidence=_f(conf,0.7)、verified=int(ver or 0)，且仅当 _j(cs,None) 为真值时加 condition_space、仅当 weight 不为 None 时加 weight=_f(weight,1.0)），返回 (children, relations)。
 def load_graph(db):
     """返回 (children_of, relations_of)。
 
@@ -115,6 +121,7 @@ def load_graph(db):
 # 写：sqlite → md
 # --------------------------------------------------------------------------
 
+# 生效条件：db/root 取默认 DEFAULT_DB/DEFAULT_ROOT（或调用方所传）；dry_run 为真值时不做写入，rep 只有统计字段而无 verify/ok；dry_run 为假值时以 MdCGOS(root) 把 load_nodes(db, limit)（limit 真值才加 LIMIT）的节点按 id 覆盖写入，并令 rep["verify"]=verify(db, root, verbose=verbose)、rep["ok"]=bool(rep["verify"]["ok"])；verbose 为真值时打印 rep。
 def export(db=DEFAULT_DB, root=DEFAULT_ROOT, limit=None, dry_run=False,
            verbose=True):
     rows = load_nodes(db, limit)
@@ -180,6 +187,7 @@ def export(db=DEFAULT_DB, root=DEFAULT_ROOT, limit=None, dry_run=False,
 # 校验：md 侧 vs sqlite 侧（逐节点全量，不抽样）
 # --------------------------------------------------------------------------
 
+# 生效条件：db/root 取默认 DEFAULT_DB/DEFAULT_ROOT（或调用方所传），在 md_ids 与 load_nodes(db) 的交集上做 L1 子/父集合比对、L2 非层级边 target 集合比对、L3 字段比对（condition_space 经 _cs_same 剔除 time_window）后，out["ok"] 仅当无缺失节点、无 child_bad/parent_bad/rel_bad/field_bad、roots_equal 为真且 sg.validate(cg, limit=5) 的 issues==0；verbose 为真值时打印去掉 tree_validate 键的 out。
 def verify(db=DEFAULT_DB, root=DEFAULT_ROOT, verbose=True):
     from . import subgraph as sg
 
@@ -219,6 +227,7 @@ def verify(db=DEFAULT_DB, root=DEFAULT_ROOT, verbose=True):
             rel_bad.append({"id": nid, "db": want, "md": got})
 
     # ---- L3 字段等价 ----
+# 生效条件：a、b 各自经 _j(a, {}) or {} 转成字典（None/"" 得空 dict）后 pop("time_window")，仅当剔除该槽后的两字典相等才返回 True，否则 False。
     def _cs_same(a, b):
         """md 写入侧按条件论纪律自动补 time_window（`mdcg.add` 的观测时间窗），
         比对时剔除该槽——它是有意增强，不是迁移失真。"""
@@ -278,6 +287,7 @@ REC_SUBTREE_SQL = (
     "WHERE e.relation_type = ?) SELECT id FROM sub")
 
 
+# 生效条件：db/root 取默认 DEFAULT_DB/DEFAULT_ROOT（或调用方所传），仅遍历 sg.roots(cg)∩md_ids 的前 n_roots 个根（n_roots 为 0 时切片为空、不做子树比对），每根比对 db 递归 CTE 子树与 sg.flatten(cg, nid, max_nodes=10**9) 的 nodes，out["ok"] 仅当该样本无失配且 forest_partition_ok（n_db==n_md==len(md_ids)）成立；verbose 为真值时打印 out。
 def bench_graph(db=DEFAULT_DB, root=DEFAULT_ROOT, n_roots=30, verbose=True):
     """L4 子树展开等价 + 森林完整性（回答「图**查询**能否由 md 承担」）。
 
@@ -295,6 +305,7 @@ def bench_graph(db=DEFAULT_DB, root=DEFAULT_ROOT, n_roots=30, verbose=True):
     con = _connect(db)
     roots_md = sorted(set(sg.roots(cg)) & md_ids)
 
+# 生效条件：用外层闭包的 con 执行 REC_SUBTREE_SQL、参数为 (nid, LEVEL_REL)，返回结果各行第 0 列构成的集合。
     def _db_subtree(nid):
         return {r[0] for r in con.execute(REC_SUBTREE_SQL, (nid, LEVEL_REL)).fetchall()}
 
@@ -323,10 +334,12 @@ def bench_graph(db=DEFAULT_DB, root=DEFAULT_ROOT, n_roots=30, verbose=True):
     return out
 
 
+# 生效条件：argv 含 "--verify-only" 时返回 0/1 取决于 verify(db, root)["ok"]，含 "--bench-graph" 时返回 0/1 取决于 bench_graph(db, root)["ok"]，否则以 opt 取的 --db/--root/--limit 调 export（opt("--limit") 缺失或为空串时 limit=None，否则 int(lim)；dry_run="--dry-run" in argv），rep.get("dry_run") 为真时直接返回 0，否则按 rep.get("ok") 真→0、假→1。
 def main(argv):
     if hasattr(sys.stdout, "reconfigure"):
         sys.stdout.reconfigure(encoding="utf-8")
 
+# 生效条件：name 出现在外层 argv 中时返回 argv[argv.index(name) + 1]（即首次出现位置的后一个元素），name 不在 argv 中时返回 default，default 缺省为 None。
     def opt(name, default=None):
         return argv[argv.index(name) + 1] if name in argv else default
 
@@ -345,4 +358,4 @@ def main(argv):
 
 
 if __name__ == "__main__":
-    sys.exit(main(sys.argv))
+    sys.exit(main(sys.argv))

package/md_cg/mreview/__main__.py

@@ -20,6 +20,7 @@ from . import candidates as CD
 from . import ruleset as RS
 
 
+# 生效条件：root 为假值（None/空串）时回落 mdcg_root()，sources 缺省取模块常量 CD.SOURCES 并透传给 CD.generate，返回 dict out，且仅当 full 为真值时额外带上 candidates_full、bundles_full、packages_full 三键。
 def run(root=None, *, sources=CD.SOURCES, cold_limit=500, patrol_window=200,
         max_per_bundle=50, limit=None, patrol_offset=None, rules_dir=None,
         full=False) -> dict:
@@ -55,6 +56,7 @@ def run(root=None, *, sources=CD.SOURCES, cold_limit=500, patrol_window=200,
     return out
 
 
+# 生效条件：d 必须已含 candidates、bundle_stats、assemble_stats、root、content_missing、llm_checks 这些键（直接下标取值，缺键即 KeyError），且仅当 d.get("assertions") 为真值（非空映射）时才追加断言集一行，其 failed 空或缺失时回落显示「无」。
 def _fmt_summary(d: dict) -> str:
     c, b, a = d["candidates"], d["bundle_stats"], d["assemble_stats"]
     lines = ["", "== M1 机械层（候选 → 捆绑 → 规则装配） ==",
@@ -77,6 +79,7 @@ def _fmt_summary(d: dict) -> str:
     return "\n".join(lines)
 
 
+# 生效条件：argv 为 None 时 argparse 改从 sys.argv[1:] 取参，--sources 按逗号切分并丢弃空串后组成元组传入 run，仅当 --out 为非空串时才以 UTF-8 落盘 JSON dump，各分支之后统一 return 0。
 def main(argv=None) -> int:
     ap = argparse.ArgumentParser(prog="python -m md_cg.mreview",
                                  description="M1 机械层：候选生成→捆绑→规则装配（只读零写入）")