@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/md_cg/metacognition.py

@@ -3,7 +3,7 @@
 
 理论出处（本仓原文，非外部知识）
 ------------------------------
-· **情绪 = 信息差的二阶变化 d²D/dt²**（`docs/智能的公理化基石.md` §十一，:412-510）：
+· **情绪 = 信息差的二阶变化 d²D/dt²**（`docs/theory/智能的公理化基石.md` §十一，:412-510）：
       「情绪不是状态本身，而是状态变化的变化」。元认知正是对认知过程做
       二阶观测的单元：一阶 = 检索结果好坏，二阶 = 认知状态在如何变化。
 · **情感 = 信任的二阶变化 d²T/dt²**（同文档 :469-508）。
@@ -12,7 +12,7 @@
 · **推论三 局部不可知**（同文档 :277-288）：
       「知道什么不知道，同样属于知识」——盲区地图是法定输出，不是失败记录。
 · **信任 P_trust / P_gap**（同文档 :393-408）。
-· **导航税**（`docs/智能的认知过程.md`:84-86）：维持认知过程一致性需要显式
+· **导航税**（`docs/theory/智能的认知过程.md`:84-86）：维持认知过程一致性需要显式
       状态记录——元认知就是付这笔税的单元。
 
 独立性的三重含义（本模块的硬约束）

package/md_cg/mreview/__init__.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线（M1 机械层 / M2 蜂巢并发 / M3 定位）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 / §5 / §6。
+
+    [1 候选生成] → [2 捆绑] → [3 规则装配] → [4 蜂巢评审] → [5 落库治理]
+      确定性        确定性       确定性        LLM(M2)       确定性(M4)
+
+* candidates.py 级 1：四源候选（断言超限 / 闸门 DEFER / 冷节点 / 轮巡）
+* bundle.py     级 2：按模板签名/血缘/主题捆绑（同模板组一包一评）
+* ruleset.py    级 3：D3 规则装配（规则全落 rules/*.json，引擎零改动）
+* pipeline.py   M2 级 4+5：投递收卷（蜂巢）+ 意见落库（verify 令牌 + writepipe）
+* locate.py     M3 D1：字段级定位——意见说「有问题」，定位说「在第几个字段/哪一段」
+* govern.py     M4 落库治理（确定性部分）：规则驱动 · 只回填 · 永不删除
+  plan（预演）/ apply（执行 + 留痕）/ rollback（按留痕回滚）/ history / stats
+
+边界：M1/M3 只读不写；机械可算的在蜂巢 job 前跑完（LLM 只看语义问题）；
+本条流水线不产出「删除」动作（治理只有合并/降权/回填/移层，M4 终裁）。
+M4 只做**确定性**部分；依赖语义判断的合并/降权建议（LLM 面）不在本模块。
+"""
+
+__all__ = ["candidates", "bundle", "ruleset", "pipeline", "locate", "govern",
+           "SPEC_VERSION"]
+
+SPEC_VERSION = 1

package/md_cg/mreview/__main__.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""M1 机械层入口（零写入）：
+
+    python -m md_cg.mreview [--root R] [--out dump.json] [--full] [--limit N]
+
+默认只打印/落盘**摘要 + 包清单 + 机械聚合**；``--full`` 追加条目明细与逐条机械 issue
+（真源全量 dump 会很大，默认裁剪是为可审查性服务，不是隐藏内容）。
+"""
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import os
+
+from .. import conformance as CF
+from ..datapath import mdcg_root
+from . import bundle as BD
+from . import candidates as CD
+from . import ruleset as RS
+
+
+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:
+    root = root or mdcg_root()
+    nodes = CF.load_index(root) or {}       # load_index 直接返回 nodes 字典
+    gen = CD.generate(root, sources=sources, nodes=nodes, limit=limit,
+                      cold_limit=cold_limit, patrol_window=patrol_window,
+                      patrol_offset=patrol_offset, with_report=True)
+    bd = BD.bundle(gen["candidates"], nodes=nodes, root=root,
+                   max_per_bundle=max_per_bundle)
+    asm = RS.assemble_all(bd, rules_dir=rules_dir)
+    by_rule = collections.Counter(i["rule_id"] for p in asm["packages"] for i in p["mechanical"])
+    out = {
+        "root": root,
+        "candidates": {"by_source": gen["by_source"], "total_raw": gen["total_raw"],
+                       "total": gen["total"], "skipped": gen["skipped"]},
+        "report": gen.get("report"),
+        "assertions": gen.get("assertions"),
+        "bundles": [{"bundle_id": b["bundle_id"], "group_kind": b["group_kind"],
+                     "group_key": b["group_key"], "size": b["size"], "refs": b["refs"]}
+                    for b in bd["bundles"]],
+        "bundle_stats": bd["stats"],
+        "content_missing": bd["content_missing"],
+        "assemble_stats": asm["stats"],
+        "mechanical_by_rule": dict(by_rule),
+        "llm_checks": sorted({(c["rule_id"], c["check"]) for p in asm["packages"]
+                              for c in p["llm"]}),
+    }
+    if full:
+        out["candidates_full"] = gen["candidates"]
+        out["bundles_full"] = bd["bundles"]
+        out["packages_full"] = asm["packages"]
+    return out
+
+
+def _fmt_summary(d: dict) -> str:
+    c, b, a = d["candidates"], d["bundle_stats"], d["assemble_stats"]
+    lines = ["", "== M1 机械层（候选 → 捆绑 → 规则装配） ==",
+             "真源：%s" % d["root"],
+             "候选：原始 %d 条 → 去重后 %d 条（按源：%s）"
+             % (c["total_raw"], c["total"],
+                ", ".join("%s=%d" % kv for kv in sorted(c["by_source"].items()))),
+             "跳过（未落盘/无节点）：%d 条" % len(c["skipped"]),
+             "捆绑：%d 包（最大 %d 条/包；分组类型 %s）"
+             % (b["bundles"], b["largest"], b["by_group_kind"]),
+             "正文缺失：%d 条（读盘失败计入，不冒充内容）" % d["content_missing"],
+             "规则：%d 条（%s）" % (len(a["rules"]), ", ".join(a["rules"])),
+             "机械检查：%d 条 issue（按类 %s）" % (a["mechanical_total"], a["mechanical_by_kind"]),
+             "待 LLM 检查项：%d 条（%s）"
+             % (a["llm_checks"], ", ".join("%s:%s" % t for t in d["llm_checks"]))]
+    asr = d.get("assertions") or {}
+    if asr:
+        lines.append("断言集交叉核对：verdict=%s，未达标项 %s"
+                     % (asr.get("verdict"), ", ".join(asr.get("failed") or []) or "无"))
+    return "\n".join(lines)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m md_cg.mreview",
+                                 description="M1 机械层：候选生成→捆绑→规则装配（只读零写入）")
+    ap.add_argument("--root", default=None, help="认知图根（缺省 MDCG_ROOT/默认路径）")
+    ap.add_argument("--sources", default=",".join(CD.SOURCES))
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--cold-limit", type=int, default=500)
+    ap.add_argument("--patrol-window", type=int, default=200)
+    ap.add_argument("--patrol-offset", type=int, default=None)
+    ap.add_argument("--max-per-bundle", type=int, default=50)
+    ap.add_argument("--rules-dir", default=None)
+    ap.add_argument("--out", default=None, help="落盘 dump（JSON）")
+    ap.add_argument("--full", action="store_true", help="含条目明细与逐条 issue")
+    a = ap.parse_args(argv)
+    d = run(a.root, sources=tuple(s for s in a.sources.split(",") if s),
+            cold_limit=a.cold_limit, patrol_window=a.patrol_window, limit=a.limit,
+            patrol_offset=a.patrol_offset, max_per_bundle=a.max_per_bundle,
+            rules_dir=a.rules_dir, full=a.full)
+    print(_fmt_summary(d))
+    if a.out:
+        with open(os.path.abspath(a.out), "w", encoding="utf-8") as f:
+            json.dump(d, f, ensure_ascii=False, indent=1)
+        print("已落盘：%s" % os.path.abspath(a.out))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/md_cg/mreview/bundle.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线 · 级 2：捆绑（确定性，零写入）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 第 2 级。
+
+**同模板组一包一评**：批次报告类节点（「批次N收官记忆」）正文各不相同但同模板，
+逐条评审＝重复劳动且立场漂移；成组评审＝一次裁决整组。分组键优先级：
+
+1. ``template`` 模板签名——复用 :func:`writelimit.template_signature`（强信号 ``t:``）；
+   长文（≥ MAX_CONTENT）无标题签名时回退**首行骨架**（弱信号 ``h:``）——真源知识节点
+   正文多为长文四要素，标题/首行才是同模板流水的载体（该回退只在评审分组内生效，
+   不改写侧聚合口径）。
+2. ``lineage``  血缘——branch_id / branched_from / derived_from[0]（同源迁移一起看）。
+3. ``topic``    标签前缀集合（无标签回退层）。
+4. ``batch``    无任何分组特征的孤立候选，按确定性顺序成批（不误聚、不丢弃）。
+
+组内条数 < ``min_group`` 的组降级并入 batch；组内超 ``max_per_bundle`` 切分多包。
+包号确定性：``b1_<kind>_<sha1(key)[:8]>_c<idx>``；同一输入两次运行逐字节一致。
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import os
+
+from .. import conformance as CF
+from .. import writelimit as WL
+
+GROUP_TEMPLATE = "template"
+GROUP_LINEAGE = "lineage"
+GROUP_TOPIC = "topic"
+GROUP_BATCH = "batch"
+
+
+def _sig_of(content: str):
+    """模板签名（强/弱）。返回 (sig, kind) 或 (None, None)。"""
+    if not content:
+        return None, None
+    s = WL.template_signature(content)
+    if s:
+        return s, "strong"
+    for line in content.splitlines():
+        t = line.strip()
+        if not t:
+            continue
+        sk = WL._skeleton(t)
+        if len(sk) >= WL.MIN_SKELETON:
+            return "h:" + sk, "head"
+        return None, None
+    return None, None
+
+
+def _lineage_key(meta: dict):
+    for f in ("branched_from", "branch_id"):
+        v = meta.get(f)
+        if v and str(v) != "None":
+            return str(v)
+    d = meta.get("derived_from")
+    if isinstance(d, (list, tuple)) and d:
+        return str(d[0])
+    if isinstance(d, str) and d and d not in ("[]", "None"):
+        return d
+    return None
+
+
+def _topic_key(meta: dict, tags: list):
+    pref = sorted(CF._tag_prefixes(meta)) if meta else []
+    if not pref and tags:
+        pref = sorted({str(t).split(":", 1)[0] for t in tags if t})
+    if pref:
+        return "+".join(pref)
+    layer = str((meta or {}).get("layer") or "")
+    return ("layer:" + layer) if layer else None
+
+
+def _group_of(meta: dict, tags: list, content: str):
+    sig, kind = _sig_of(content)
+    if sig:
+        return GROUP_TEMPLATE, sig, kind
+    lin = _lineage_key(meta)
+    if lin:
+        return GROUP_LINEAGE, lin, None
+    top = _topic_key(meta, tags)
+    if top:
+        return GROUP_TOPIC, top, None
+    return GROUP_BATCH, "misc", None
+
+
+def _load_content(root: str, meta: dict, limit: int):
+    if not root or not meta:
+        return None
+    rel = str(meta.get("path") or "")
+    if not rel:
+        return None
+    p = os.path.join(root, rel.replace("\\", os.sep).replace("/", os.sep))
+    try:
+        with open(p, encoding="utf-8", errors="replace") as f:
+            return f.read(int(limit))
+    except OSError:
+        return None
+
+
+def _entry(cand: dict, meta: dict, content: str, limit: int) -> dict:
+    return {"ref": cand.get("key"), "node_id": cand.get("node_id"),
+            "proposal_id": cand.get("proposal_id"), "origin": cand.get("origin"),
+            "layer": cand.get("layer"), "tags": list(cand.get("tags") or []),
+            "role": (meta or {}).get("role"),
+            "importance": (meta or {}).get("importance"),
+            "evidence_count": (meta or {}).get("evidence_count"),
+            "verification_basis": (meta or {}).get("verification_basis"),
+            "lifecycle_state": (meta or {}).get("lifecycle_state"),
+            "content_hash": cand.get("content_hash") or (meta or {}).get("content_hash"),
+            "issue_kinds": list(cand.get("issue_kinds") or []),
+            "evidence": list(cand.get("evidence") or []),
+            "excerpt": (content or "")[:int(limit)] or None}
+
+
+def _chunks(ids: list, size: int) -> list:
+    size = max(1, int(size))
+    return [ids[i:i + size] for i in range(0, len(ids), size)]
+
+
+def bundle(candidates: list, nodes=None, root=None, *, max_per_bundle=50,
+           min_group=2, read_content=True, content_limit=3000) -> dict:
+    """候选清单 → 待评包（含条目上下文与机械字段，供级 3 装配与级 4 spec）。"""
+    nodes = nodes or {}
+    bykey = {c.get("key"): c for c in candidates}
+    groups, contents = {}, {}
+    for c in candidates:
+        nid = c.get("node_id")
+        meta = (nodes.get(nid) or {}) if nid else {}
+        content = c.get("content") or ""
+        if not content and read_content and nid:
+            content = _load_content(root, meta, content_limit) or ""
+        content = (content or "")[:int(content_limit)]
+        kind, key, sig_kind = _group_of(meta, c.get("tags") or [], content)
+        g = groups.get((kind, key))
+        if g is None:
+            g = groups[(kind, key)] = {"ids": [], "sig_kind": sig_kind}
+        g["ids"].append(c.get("key"))
+        contents[c.get("key")] = content
+
+    # 小组降级并入 batch（不误聚、不丢弃）
+    demoted = []
+    for k in [k for k, g in groups.items()
+              if k[0] != GROUP_BATCH and len(g["ids"]) < int(min_group)]:
+        demoted += groups.pop(k)["ids"]
+    for k in [k for k in groups if k[0] == GROUP_BATCH]:
+        demoted += groups.pop(k)["ids"]
+    demoted = sorted(demoted)
+    if demoted:
+        groups[(GROUP_BATCH, "misc")] = {"ids": demoted, "sig_kind": None}
+
+    bundles = []
+    for (kind, key) in sorted(groups):
+        g = groups[(kind, key)]
+        for i, chunk in enumerate(_chunks(sorted(g["ids"]), int(max_per_bundle))):
+            bid = "b1_%s_%s_c%d" % (kind, hashlib.sha1(str(key).encode("utf-8")).hexdigest()[:8], i)
+            bundles.append({
+                "bundle_id": bid, "group_kind": kind, "group_key": str(key),
+                "group_sig_kind": g["sig_kind"], "size": len(chunk), "refs": chunk,
+                "entries": [_entry(bykey[r], nodes.get(bykey[r].get("node_id") or "") or {},
+                                   contents.get(r) or "", content_limit)
+                            for r in chunk]})
+    stats = {"candidates": len(candidates), "bundles": len(bundles),
+             "largest": max([b["size"] for b in bundles] or [0]),
+             "by_group_kind": dict(collections.Counter(b["group_kind"] for b in bundles))}
+    return {"bundles": bundles, "stats": stats,
+            "content_missing": sum(1 for c in candidates
+                                   if not contents.get(c.get("key")))}

package/md_cg/mreview/candidates.py

@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线 · 级 1：候选生成（确定性，零写入）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 第 1 级。
+
+四源（可单独关闭）：
+
+* ``assertion``   断言集超限项的**条目级展开**——复用 conformance 的**同一判据函数**
+  （`_coverage_metrics` / `unanalyzed` / `_dup_metrics` / `_edge_metrics`），
+  保证「报告聚合数」与「条目清单」两个入口同口径（见 test_mr_m1 T4）。
+* ``defer_queue`` 闸门待裁决提案（inbox 未被 decisions 覆盖）＋遗忘日志 DEFER 留痕；
+  未落盘的 node_id 计入 ``skipped``，**如实上报不冒充候选**。
+* ``cold``        access log 触达集合之外、且重要度不低的节点（久未触达者更值得评审）。
+* ``patrol``      sha1(node_id) 排序切片轮巡（offset 决定窗口位置），多轮不重不漏。
+
+纪律：零写入；输出顺序由 (优先级, node_id) 决定；每条候选必带证据。
+"""
+from __future__ import annotations
+
+import collections
+import hashlib
+import json
+import os
+import time
+
+from .. import conformance as CF
+from ..datapath import mdcg_root
+
+SOURCES = ("assertion", "defer_queue", "cold", "patrol")
+_PRIORITY = {"assertion": 0, "defer_queue": 1, "cold": 2, "patrol": 3}
+FORGET_LOG = "_forgetting.jsonl"
+PATROL_EPOCH = 3600.0          # 轮巡窗口推进周期（秒）：默认每窗口周期轮转一格
+COLD_IMPORTANCE_MIN = 0.6      # 冷节点抽样门槛（importance 解析失败按 0 计）
+
+
+def _read_jsonl(path: str) -> list:
+    if not os.path.exists(path):
+        return []
+    out = []
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return out
+
+
+def _touched(root: str, nodes: dict) -> set:
+    """access log 触达集（与 conformance._reach_metrics 同一解析口径：ids / id / node_id / nid）。"""
+    p = os.path.join(root, CF.ACCESS_LOG)
+    seen = set()
+    if not os.path.exists(p):
+        return seen
+    with open(p, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            got = rec.get("ids")
+            if isinstance(got, (list, tuple)):
+                seen.update(str(x) for x in got if x)
+            nid = rec.get("id") or rec.get("node_id") or rec.get("nid")
+            if nid:
+                seen.add(str(nid))
+    return seen & set(nodes)
+
+
+def _assertion_items(nodes: dict) -> list:
+    """断言集超限项 → 条目级（判据函数与 conformance 同源，不另立口径）。"""
+    out = []
+    kn = {nid: r for nid, r in nodes.items() if str(r.get("layer")) == "knowledge"}
+    for nid, r in kn.items():
+        if not r.get("role"):
+            out.append({"node_id": nid, "issue_kind": "missing_field",
+                        "evidence": "role 为空（口径=conformance.stratum.role_coverage，knowledge 层分母）"})
+        if CF._as_int(r.get("evidence_count")) == 0:
+            out.append({"node_id": nid, "issue_kind": "missing_field",
+                        "evidence": "evidence_count=0（口径=conformance.stratum.evidence_coverage）"})
+        if {"doc", "code"} & CF._tag_prefixes(r):
+            out.append({"node_id": nid, "issue_kind": "mixed_layer",
+                        "evidence": "knowledge 层带 doc/code 标签（口径=conformance.stratum.mixed_ratio）"})
+    for nid, r in nodes.items():
+        if (CF._as_int(r.get("evidence_count")) == 0 and not CF._basis_of(r)
+                and not r.get("lifecycle_state")):
+            out.append({"node_id": nid, "issue_kind": "unanalyzed",
+                        "evidence": "无一维分析痕迹（口径=conformance.unanalyzed 派生判据）"})
+    ch = collections.Counter(str(r.get("content_hash")) for r in nodes.values())
+    dup = {h for h, c in ch.items() if c > 1 and h not in ("None", "")}
+    if dup:
+        for nid, r in nodes.items():
+            h = str(r.get("content_hash"))
+            if h in dup:
+                out.append({"node_id": nid, "issue_kind": "dup_content",
+                            "evidence": "content_hash 重复组 %s（%d 条同指纹；口径=conformance.dup.content)" % (h, ch[h])})
+    for nid, r in nodes.items():
+        es = r.get("edges") or []
+        if not isinstance(es, (list, tuple)):
+            continue
+        for e in es:
+            if not isinstance(e, dict):
+                continue
+            keys = [k for k in CF.CANONICAL_EDGE_KEYS + ("type",) if e.get(k)]
+            if not any(k in CF.CANONICAL_EDGE_KEYS for k in keys):
+                out.append({"node_id": nid, "issue_kind": "edge_non_canonical",
+                            "evidence": "边键非规范：%s（口径=conformance.edge.key.canonical）"
+                                        % ("+".join(keys) or "<无关系键>")})
+                break
+    return out
+
+
+def _defer_items(root: str, nodes: dict):
+    """闸门待裁决提案 + 遗忘日志 DEFER 留痕。返回 (items, skipped)。"""
+    ib = _read_jsonl(os.path.join(root, CF.INBOX_LOG))
+    dc = _read_jsonl(os.path.join(root, CF.DECISION_LOG))
+    done = {str(x.get("pid")) for x in dc if x.get("pid")}
+    out, skipped = [], []
+    for r in ib:
+        pid = str(r.get("pid") or "")
+        if not pid or pid in done:
+            continue
+        out.append({"node_id": str(r.get("id") or "") or None, "origin": "proposal",
+                    "proposal_id": pid, "issue_kind": "gate_defer",
+                    "layer": r.get("layer"), "content": r.get("content") or "",
+                    "tags": r.get("tags") or [], "content_hash": r.get("payload_hash") or "",
+                    "evidence": "闸门待裁决提案（inbox 中 %s 未被 decisions 覆盖）" % pid})
+    for r in _read_jsonl(os.path.join(root, FORGET_LOG)):
+        if str(r.get("verdict")) != "DEFER":
+            continue
+        nid = str(r.get("node_id") or "")
+        if nid and nid in nodes:
+            out.append({"node_id": nid, "issue_kind": "gate_defer",
+                        "evidence": "遗忘闸门 DEFER 留痕：%s" % str(r.get("reason"))})
+        else:
+            skipped.append({"source": "defer_queue", "reason": "node_not_landed",
+                            "detail": nid or str(r.get("reason"))})
+    return out, skipped
+
+
+def _cold_items(root: str, nodes: dict, limit: int) -> list:
+    seen = _touched(root, nodes)
+
+    def _imp(r):
+        try:
+            return float(r.get("importance") or 0.0)
+        except (TypeError, ValueError):
+            return 0.0
+
+    rows = [(nid, r) for nid, r in nodes.items() if nid not in seen]
+    rows.sort(key=lambda kv: (-_imp(kv[1]), kv[0]))
+    picked = [(nid, r) for nid, r in rows if _imp(r) >= COLD_IMPORTANCE_MIN][:int(limit)]
+    return [{"node_id": nid, "issue_kind": "cold",
+             "evidence": "access log 未触达（importance=%.2f，排名第 %d）" % (_imp(r), i + 1)}
+            for i, (nid, r) in enumerate(picked)]
+
+
+def _patrol_items(nodes: dict, window: int, offset: int) -> list:
+    if int(window) <= 0 or not nodes:
+        return []
+    ordered = sorted(nodes, key=lambda nid: hashlib.sha1(nid.encode("utf-8")).hexdigest())
+    n = len(ordered)
+    start = (int(offset) * int(window)) % n
+    picked = ordered[start:start + int(window)]
+    if len(picked) < int(window):                       # 环绕补足：多轮不重不漏
+        picked = picked + ordered[:int(window) - len(picked)]
+    return [{"node_id": nid, "issue_kind": "patrol",
+             "evidence": "轮巡窗口 #%d（窗口 %d 条，按 sha1(node_id) 排序切片）" % (int(offset), int(window))}
+            for nid in picked]
+
+
+def _merge(items: list, nodes: dict) -> list:
+    """按条目（节点/提案）聚合：一条候选 = 一个待评条目，多个问题挂在 issue_kinds 上。"""
+    acc = {}
+    for it in items:
+        nid = it.get("node_id")
+        key = str(nid) if nid else "pid:" + str(it.get("proposal_id"))
+        rec = acc.get(key)
+        if rec is None:
+            meta = nodes.get(nid) or {} if nid else {}
+            rec = acc[key] = {
+                "key": key, "node_id": nid or None, "proposal_id": it.get("proposal_id") or None,
+                "origin": it.get("origin") or "node",
+                "layer": it.get("layer") or meta.get("layer"),
+                "sources": [], "issue_kinds": [], "evidence": [],
+                "content": it.get("content") or "",
+                "tags": list(it.get("tags") or meta.get("tags") or []),
+                "content_hash": it.get("content_hash") or str(meta.get("content_hash") or ""),
+            }
+        src = it.get("source")
+        if src and src not in rec["sources"]:
+            rec["sources"].append(src)
+        ik = it.get("issue_kind")
+        if ik and ik not in rec["issue_kinds"]:
+            rec["issue_kinds"].append(ik)
+        ev = it.get("evidence")
+        if ev and len(rec["evidence"]) < 8:
+            rec["evidence"].append(ev)
+    out = list(acc.values())
+    for r in out:
+        r["sources"] = sorted(set(r["sources"])) or ["-"]
+        r["priority"] = min(_PRIORITY.get(s, 9) for s in r["sources"])
+        r["issue_kinds"] = sorted(r["issue_kinds"])
+    out.sort(key=lambda r: (r["priority"], str(r["key"])))
+    return out
+
+
+def generate(root=None, *, sources=SOURCES, nodes=None, limit=None, cold_limit=500,
+             patrol_window=200, patrol_offset=None, with_report=False, now=None) -> dict:
+    """四源候选生成。nodes 可注入（测试用合成库，免读真源）。"""
+    root = root or mdcg_root()
+    if nodes is None:
+        nodes = CF.load_index(root) or {}   # load_index 直接返回 nodes 字典
+    wanted = [s for s in SOURCES if s in (sources or SOURCES)]
+    items, skipped, by_source = [], [], {}
+    if "assertion" in wanted:
+        got = _assertion_items(nodes)
+        by_source["assertion"] = len(got)
+        items += [dict(x, source="assertion") for x in got]
+    if "defer_queue" in wanted:
+        got, sk = _defer_items(root, nodes)
+        by_source["defer_queue"] = len(got)
+        items += [dict(x, source="defer_queue") for x in got]
+        skipped += sk
+    if "cold" in wanted:
+        got = _cold_items(root, nodes, cold_limit)
+        by_source["cold"] = len(got)
+        items += [dict(x, source="cold") for x in got]
+    if "patrol" in wanted:
+        off = int(patrol_offset) if patrol_offset is not None \
+            else int((now if now is not None else time.time()) // PATROL_EPOCH)
+        got = _patrol_items(nodes, patrol_window, off)
+        by_source["patrol"] = len(got)
+        items += [dict(x, source="patrol") for x in got]
+    merged = _merge(items, nodes)
+    if limit:
+        merged = merged[:int(limit)]
+    rep = {"root": root, "generated_at": float(now if now is not None else time.time()),
+           "sources": wanted, "by_source": by_source, "total_raw": len(items),
+           "total": len(merged), "candidates": merged, "skipped": skipped}
+    if with_report:
+        rep0 = CF.check(root, check_paths=False)
+        rep["report"] = CF.metrics_of(rep0)
+        rep["assertions"] = {"verdict": rep0.get("verdict"), "counts": rep0.get("counts"),
+                             "failed": [c.get("id") for c in rep0.get("checks") or []
+                                        if not c.get("ok")]}
+    return rep