@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/blindspot_tickets.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""盲区消解票据（阶段三 §5.4）：BLINDSPOT/DEFER 盲区 → 四类消解票据（任务卡形态）挂认知图。
+
+四类分类判据（确定性、声明式、可审计，不做语义猜测）：
+  task      — 盲区 query 精确命中某 unresolved 层节点正文首行 → 直接立工程任务卡
+  grilling  — defer 主导（defer > blindspot，信息不完整须澄清）；执行通道=宿主侧
+              访谈（grill），md_cg 库内无访谈工具，本模块只建卡不越权代答（边界如实）
+  research  — blindspot >= 3（反复未知）→ 研究议题（检索/调研补证）
+  prototype — 其余 → 最小探针实验验证
+
+幂等：tasks.upsert 同 slug 即同任务，重复生成不新建卡（updated 计数）。
+依赖挂接：票据即任务节点（认知图节点天然在图上、可检索）。「升级为正式工程
+任务时的机械 depends_on 边」由使用者在该卡更新时显式填写——本模块不伪造
+工程边，消解路径以正文声明。
+预演：apply=False 只出清单不落库（与 learn/reconstruct 的 opt-in 同构，
+默认链路零变更）。
+"""
+from . import metacognition, tasks
+
+TICKET_TYPES = ("research", "prototype", "grilling", "task")
+
+_RESOLVE = {
+    "research": "检索/调研补证（外部研究系列吸收流程），产出知识节点后复核 gap_hint",
+    "prototype": "构造最小探针实验验证，结论回写认知图",
+    "grilling": "澄清缺位：执行通道=宿主侧访谈（grill）；库内无访谈工具，不越权代答",
+    "task": "直接立工程任务推进（关联 unresolved 悬挂线索）",
+}
+
+_JUDGE = {
+    "research": "blindspot>=3（反复未知 → 研究议题）",
+    "prototype": "其余（偶发未知 → 最小探针）",
+    "grilling": "defer 主导（信息不完整 → 须澄清）",
+    "task": "query 精确命中 unresolved 节点正文首行",
+}
+
+
+def classify(item, unresolved_first_lines):
+    """按确定性判据给盲区分派票据类型。unresolved_first_lines={首行: node_id}。"""
+    q = str(item.get("query") or "").strip()
+    if q and q in unresolved_first_lines:
+        return "task"
+    b = int(item.get("blindspot") or 0)
+    d = int(item.get("defer") or 0)
+    if d > b:
+        return "grilling"
+    if b >= 3:
+        return "research"
+    return "prototype"
+
+
+def _plan_text(item, ttype, unresolved_first_lines):
+    q = str(item.get("query") or "").strip()
+    lines = [
+        "来源：盲区簇 key=%s（blindspot=%s defer=%s samples=%s）" % (
+            metacognition._key(q), item.get("blindspot"), item.get("defer"),
+            item.get("samples")),
+        "分类判据：%s" % _JUDGE[ttype],
+    ]
+    if ttype == "task" and q in unresolved_first_lines:
+        lines.append("关联悬挂：unresolved 节点 %s" % unresolved_first_lines[q])
+    lines.append("消解路径：%s" % _RESOLVE[ttype])
+    lines.append("完成判据：盲区簇后续反思记录中 BLINDSPOT/DEFER 归零（gap_hint 复核）")
+    return "\n".join(lines)
+
+
+def make_tickets(cg, *, types=None, limit=10, min_blindspot=0,
+                 apply=False, actor=None) -> dict:
+    """盲区 → 消解票据。apply=False 预演（零落库）；apply=True 经 tasks.upsert 落卡。"""
+    want = tuple(t for t in (types or TICKET_TYPES) if str(t).strip())
+    bad = [t for t in want if str(t).strip().lower() not in TICKET_TYPES]
+    if bad:
+        return {"ok": False,
+                "error": "未知票据类型：%s（可选 %s）" % (bad, list(TICKET_TYPES))}
+
+    mp = metacognition.blindspots(cg, limit=max(int(limit), 20))
+    items = []
+    for it in mp.get("items") or []:
+        b = int(it.get("blindspot") or 0)
+        d = int(it.get("defer") or 0)
+        if b >= int(min_blindspot) or d >= 1:
+            items.append(it)
+
+    unresolved_first_lines = {}
+    for u in mp.get("unresolved") or []:
+        first = str(u.get("content") or "").strip().splitlines()
+        if first and first[0].strip():
+            unresolved_first_lines.setdefault(first[0].strip(), u.get("node_id"))
+
+    out, created, updated, errors = [], 0, 0, 0
+    for it in items[:int(limit)]:
+        q = str(it.get("query") or "").strip()
+        if not q:
+            continue
+        ttype = classify(it, unresolved_first_lines)
+        if ttype not in [str(t).strip().lower() for t in want]:
+            out.append({"type": ttype, "query": q, "skipped": "types 过滤"})
+            continue
+        name = "票据:%s:%s" % (ttype, q[:24])
+        if not apply:
+            out.append({"type": ttype, "query": q, "name": name, "dry_run": True})
+            continue
+        r = tasks.upsert(
+            cg, name, plan=_plan_text(it, ttype, unresolved_first_lines),
+            status="active",
+            note="盲区簇 key=%s｜blindspot=%s｜defer=%s" % (
+                metacognition._key(q), it.get("blindspot"), it.get("defer")),
+            tags=["blindspot-ticket", "ticket:%s" % ttype],
+            actor=actor or "blindspot_tickets")
+        if r.get("ok"):
+            if r.get("created"):
+                created += 1
+            else:
+                updated += 1
+            out.append({"node_id": r.get("node_id"), "type": ttype,
+                        "query": q, "created": bool(r.get("created"))})
+        else:
+            errors += 1
+            out.append({"type": ttype, "query": q, "error": r.get("error")})
+
+    return {"ok": errors == 0, "action": "tickets", "op": "insight",
+            "scanned": len(items), "created": created, "updated": updated,
+            "errors": errors, "applied": bool(apply), "tickets": out,
+            "unresolved_count": len(unresolved_first_lines)}

package/md_cg/branches.py

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

package/md_cg/build_postings.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""倒排发布表构建/查看（S7 候选层）。
+
+用法：
+  python -X utf8 -m md_cg.build_postings --root <库根>            # 全量重建（幂等）
+  python -X utf8 -m md_cg.build_postings --root <库根> --stats     # 只看现状
+  python -X utf8 -m md_cg.build_postings --root <库根> --limit 500 # 抽样构建（冒烟用，永不算新鲜）
+  python -X utf8 -m md_cg.build_postings --root <库根> --if-stale  # 过期才重建（守候环用）
+
+说明：发布表是**派生索引**（<root>/_postings.json + _postings_meta.json），
+不修改任何节点内容；节点新增/修改后需重建（v1 不做增量维护）。
+"""
+import argparse
+import json
+import sys
+
+from . import postings
+from .mdcg import MdCG
+
+
+# 生效条件：st 为 dict 时返回其摘要——保留 schema/built_at/nodes/terms/postings/partial/rebuilt/rebuilt_from，
+# 并把 snapshot 折成 dirs/root_files 计数（快照本体含上千个目录键，直接打印会淹没日志）；st 非 dict 时原样返回。
+def _brief(st):
+    if not isinstance(st, dict):
+        return st
+    keys = ("schema", "built_at", "nodes", "terms", "postings", "partial",
+            "rebuilt", "rebuilt_from")
+    out = {k: st.get(k) for k in keys if k in st}
+    snap = st.get("snapshot")
+    if isinstance(snap, dict):
+        out["dirs"] = len(snap.get("dir_mtimes") or {})
+        out["root_files"] = len(snap.get("file_mtimes") or {})
+    return out
+
+
+# 生效条件：无条件解析参数（root 必填；stats/limit/if-stale 可选；if-stale 与 limit 互斥则 argparse 报错并退出 2）；
+# stats 为真时打开库打印 stats 摘要（含 stale_reason）并返回 0；if-stale 为真且快照新鲜时打印 {"rebuilt": false} 返回 0、
+# 过期时重建并打印摘要（附 rebuilt_from=过期原因）；否则一律重建并打印摘要，返回 0。
+# 三条路径打印的都是 _brief 摘要——不打印快照指纹本体。
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True)
+    ap.add_argument("--stats", action="store_true")
+    ap.add_argument("--limit", type=int, default=None)
+    ap.add_argument("--if-stale", action="store_true", dest="if_stale")
+    a = ap.parse_args(argv)
+    if a.if_stale and a.limit:
+        ap.error("--if-stale 与 --limit 互斥（抽样表不可当作新鲜快照）")
+    cg = MdCG(a.root)
+    nodes = cg.index.get("nodes") or {}
+    if a.stats:
+        st = postings.stats(a.root, nodes)
+        print(json.dumps({"terms": st.get("terms"), "postings": st.get("postings"),
+                          "stale_reason": st.get("stale_reason"),
+                          "meta": _brief(st.get("meta"))}, ensure_ascii=False))
+        return 0
+    if a.if_stale:
+        sr = postings.stale_reason(a.root, nodes)
+        if not sr:
+            print(json.dumps({"rebuilt": False, "reason": "fresh"}, ensure_ascii=False))
+            return 0
+        st = postings.build(cg)
+        print(json.dumps(_brief(dict(st, rebuilt_from=sr)), ensure_ascii=False))
+        return 0
+    st = postings.build(cg, limit=a.limit)
+    print(json.dumps(_brief(st), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    sys.exit(main())