@furongjun1999/dsh-memory 0.4.11 → 0.5.1

package/md_cg/review_cli.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""review_cli · 审核队列裁决命令行（设计者/管理权限专用）
+
+**包内入口**（2026-09-24 修复）：原实现只在 `scripts/review_cli.py`，而出货包
+`files` 不含 `scripts/` —— 于是包内所有给用户/智能体的提示（writepipe 的
+「已入审核队列 → 请裁决」）都指向一个安装态不存在的文件。本模块把同一实现
+搬进包内，统一入口 `python -m md_cg.review_cli`；`scripts/review_cli.py`
+在源码树内仍可用（同一代码路径：那里 _HERE 同为插件根）。
+
+背景：本机未配置外部验证器（MDCG_VERIFIER_MODULES）时，写入恒判 DEFER
+入审核队列——这是诚实行为（不假装通过）。裁决权专属 can_admin 角色
+（写入者不得自裁自决），agent 端被 AccessDenied 拒绝是设计行为；
+由设计者在本机直接运行本命令完成裁决。
+
+用法（root 须与待裁决部署一致：--root 或环境变量 MDCG_ROOT）：
+  python -m md_cg.review_cli list
+  python -m md_cg.review_cli accept  <pid> --reason "实跑测试证据"
+  python -m md_cg.review_cli reject  <pid> --reason "内容有误"
+  python -m md_cg.review_cli edit    <pid> --content "修正后内容" --reason "..."
+  python -m md_cg.review_cli merge   <pid> --into <已有节点id> --reason "..."
+  python -m md_cg.review_cli noop    <pid> --reason "已评估，判定无需改动"
+  python -m md_cg.review_cli rounds  <pid>        # 某提案裁决轮次历史
+  python -m md_cg.review_cli stats                # 裁决动作统计（含 noop）
+
+noop 语义：**已评估、判定不改变任何现有记忆**——只留痕（decisions.jsonl +
+审计 md 节点）并关闭提案，不落业务节点、不进负记忆。它与 reject 的区别是
+「评估过了、无需改动」而非「否掉这条候选」，故不可借 noop 绕过 accept 门控。
+
+裁决留痕：decisions.jsonl + 审计 md 节点（由 review_decide 内部完成）。
+"""
+import argparse
+import json
+import os
+import sys
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except AttributeError:
+    pass
+
+_HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+from md_cg.mdcos import MdCGSecure        # noqa: E402
+from md_cg.security import Principal      # noqa: E402
+
+
+# 生效条件：args 的 root 属性为真值（含 getattr 缺省 None 时回落）否则回落 os.environ.get("MDCG_ROOT", "")，两者皆空串或该值经 os.path.isdir 判定不是目录时 sys.exit 退出，否则返回该 root。
+def _root(args):
+    root = getattr(args, "root", None) or os.environ.get("MDCG_ROOT", "")
+    if not root:
+        sys.exit("错误：未指定存储根（--root 或环境变量 MDCG_ROOT）。\n"
+                 "root 必须与待裁决的部署一致——猜错会裁决到另一个空库。")
+    if not os.path.isdir(root):
+        sys.exit("错误：root 不存在：%s" % root)
+    return root
+
+
+# 生效条件：args 就绪时先构造写死权限的 Principal(actor="designer-cli", clearance="secret", can_write=True, can_admin=True, role="designer", auth_mode="local-cli")，再以 _root(args) 取到的存储根返回 MdCGSecure(root, principal=p)。
+def _cg(args):
+    p = Principal(actor="designer-cli", clearance="secret",
+                  can_write=True, can_admin=True, role="designer",
+                  auth_mode="local-cli")
+    return MdCGSecure(_root(args), principal=p)
+
+
+# 生效条件：rec 支持 .get 时，取 rec.get("content") 为假值则取 rec.get("statement")、再为假值则取空串，把其中的换行替换为空格，并按 width（缺省 66）切片后仅当 len(text) > width 才追加 "…"，返回该字符串。
+def _brief(rec, width=66):
+    text = (rec.get("content") or rec.get("statement") or "").replace("\n", " ")
+    return text[:width] + ("…" if len(text) > width else "")
+
+
+# 生效条件：cg 与 args 就绪时按 args.cmd 分派——"list" 时 cg.review_list() 为空则打印空队列并返回 0、非空则逐条打印（tags 取真值拼接、layer/round 为假值显示 "?"/0）后返回 0；"rounds" 时打印 cg.review_rounds(args.pid) 并返回 0；"stats" 时打印 cg.review_stats() 的记录数/提案数/待审数/已关闭数与动作分布（含 noop 计数）并返回 0；"edit" 时以 args.content 加真值 args.tags（按逗号分割并剔除空项）/args.layer 组成 edits 调 cg.review_decide；其余 cmd（含 noop）以 getattr(args, "into", None) 与 args.reason 调 cg.review_decide；后两类再按 out.get("ok") 为真返回 0，否则打印 out 并返回 1。
+def _execute(cg, args):
+    """按子命令执行裁决（cg 的生命周期由 main 统一收尾）。"""
+    if args.cmd == "list":
+        pend = cg.review_list()
+        if not pend:
+            print("审核队列为空（0 条待审）。")
+            return 0
+        print("待审 %d 条：" % len(pend))
+        for r in pend:
+            tags = (", tags=" + ",".join(r.get("tags") or [])) if r.get("tags") else ""
+            print("  [%s] %s · %s 层%s · round=%s\n      %s" % (
+                r.get("pid"), r.get("status"), r.get("layer") or "?",
+                tags, r.get("round") or 0, _brief(r)))
+        print('\n裁决示例：python -m md_cg.review_cli accept <pid> --reason "实跑测试证据"')
+        return 0
+
+    if args.cmd == "rounds":
+        print(json.dumps(cg.review_rounds(args.pid), ensure_ascii=False, indent=1))
+        return 0
+
+    if args.cmd == "stats":
+        st = cg.review_stats()
+        by = st.get("by_decision") or {}
+        print("裁决记录 %d 条 · 提案 %d 个 · 待审 %d 条 · 已关闭 %d 个" % (
+            st.get("records", 0), st.get("proposals", 0),
+            st.get("pending", 0), st.get("closed", 0)))
+        print("  动作分布：%s" % ("、".join(
+            "%s=%d" % (k, by[k]) for k in sorted(by)) or "（无记录）"))
+        print("  其中 noop（已评估、判定无需改动）= %d 条" % st.get("noop", 0))
+        return 0
+
+    if args.cmd == "edit":
+        edits = {"content": args.content}
+        if args.tags:
+            edits["tags"] = [t.strip() for t in args.tags.split(",") if t.strip()]
+        if args.layer:
+            edits["layer"] = args.layer
+        out = cg.review_decide(args.pid, "edit", edits=edits, reason=args.reason)
+    else:
+        out = cg.review_decide(args.pid, args.cmd,
+                               merge_into=getattr(args, "into", None),
+                               reason=args.reason)
+
+    if out.get("ok"):
+        print("已裁决：%s → %s%s" % (
+            args.pid, args.cmd,
+            ("，落盘节点 " + out["node_id"]) if out.get("node_id") else ""))
+        return 0
+    print("裁决未生效：%s" % json.dumps(out, ensure_ascii=False))
+    return 1
+
+
+# 生效条件：argv 为 None（默认）时由 argparse 解析 sys.argv、否则解析传入的 argv（子命令 dest="cmd" 为 required，已注册 list/accept/reject/edit/merge/rounds 并带 --root 等参数），解析成功后构造 cg=_cg(args) 并返回 _execute(cg, args)，finally 中执行 cg.close()。
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="python -m md_cg.review_cli",
+        description="灵枢审核队列裁决（designer 权限）")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--root", help="存储根目录（默认环境变量 MDCG_ROOT）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list", help="列出待审条目", parents=[common])
+    sub.add_parser("stats", help="裁决动作统计（含 noop）", parents=[common])
+    for name, help_ in (("accept", "按原样写入落盘"),
+                        ("reject", "丢弃（只记裁决）"),
+                        ("noop", "已评估、判定不改变现有记忆（只留痕）")):
+        s = sub.add_parser(name, help=help_, parents=[common])
+        s.add_argument("pid")
+        s.add_argument("--reason", default="", help="裁决理由（进留痕）")
+    s = sub.add_parser("edit", help="修订后写入", parents=[common])
+    s.add_argument("pid")
+    s.add_argument("--content", required=True)
+    s.add_argument("--tags", default=None, help="逗号分隔")
+    s.add_argument("--layer", default=None)
+    s.add_argument("--reason", default="")
+    s = sub.add_parser("merge", help="合并进已有节点", parents=[common])
+    s.add_argument("pid")
+    s.add_argument("--into", required=True, help="目标节点 id")
+    s.add_argument("--reason", default="")
+    s = sub.add_parser("rounds", help="某提案的裁决轮次历史", parents=[common])
+    s.add_argument("pid")
+    args = ap.parse_args(argv)
+
+    cg = _cg(args)
+    try:
+        return _execute(cg, args)
+    finally:
+        # 收尾（2026-09-16 取证）：裁决写入先进内存 _dirty，不落盘则「节点在盘上
+        # 但索引无条目」——已有 _index.json 的根重开不重扫目录，其它进程与重载后的
+        # 长驻进程都检索不到（只能靠某次全量 rebuild 偶然救回）。库层另有 atexit
+        # 兜底，但显式收尾才是正路：兜底只覆盖「正常退出」这一条路径。
+        cg.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/md_cg/roleviews.py

@@ -1,89 +1,89 @@
-# -*- coding: utf-8 -*-
-"""md_cg · 角色化读取视图（第四阶段 6.1，计划文档 §4）
-
-【为什么】同一认知图对不同消费角色应呈现不同侧面：主代理要「结论与
-修正历史」，验证端要「判据面与环境陷阱」，回执审计要「命令与预期输出」。
-三者的候选资格不同，但都建立在同一节点集上——视图是读取面的资格过滤，
-不是数据的第二副本（与超边的派生视图正交：超边是图结构增补，视图是
-候选资格过滤；计划 §3）。
-
-【设计】
-  - ROLE_VIEWS：声明式规则表（唯一真源），每个 view 声明四维资格：
-      content_kinds —— content_kind 必须落在集合内（None=不限）
-      layers        —— layer 必须落在集合内（None=不限）
-      roles         —— 非 None 时作为正向白名单（role 必须命中，
-                       短路返回；receipt 用）
-      include_work  —— False 时 role 落在工作角色（tool-output/
-                       command/edit）即一票否决（与候选池默认
-                       include_work=False 同口径）
-  - matches(fm, view)：单点谓词。fm 接受扁平 entry 或 frontmatter
-    字典（两者对 role/layer/content_kind 三键同名）。
-  - 非法 view 一律 ValueError（fail-closed，不静默回落）——合法性
-    判定单点在本模块；与节点缺字段 fail-open（缺 content_kind 按
-    "text" 对待）是两回事，后者是读取面惯例。
-
-【边界】
-  - 零内部依赖（不 import 本包其它模块，防循环导入）。规则表内的
-    工作角色白名单与 mdcos.WORK_ROLES 字面一致，一致性由
-    test_role_views 守卫断言钉住（防两处漂移）。
-  - 初版规则是类型启发，bench_role_views.py 的对照校准是法定修正
-    通道（改规则必须复跑对照，计划 §7.3）。
-"""
-
-# 规则表内的工作角色白名单，字面与 mdcos.WORK_ROLES 保持一致
-# （一致性由 test_role_views 守卫断言钉住，防两处漂移）。
-_WORK_ROLES = ("tool-output", "command", "edit")
-
-ROLE_VIEWS = {
-    # 主代理视图：结论与修正历史（正文/工作结论落在 knowledge 层）
-    "main": {
-        "content_kinds": ("text", "work_done"),
-        "layers": ("knowledge",),
-        "roles": None,
-        "include_work": False,
-    },
-    # 验证端视图：判据面与环境陷阱（marks 条目 + 知识正文，含 contextual）
-    "verifier": {
-        "content_kinds": ("ccg_marks", "text"),
-        "layers": ("knowledge", "contextual"),
-        "roles": None,
-        "include_work": False,
-    },
-    # 回执审计视图：恰是默认候选池剔除的工作角色节点（include_work
-    # 默认 False 的补集），roles 白名单短路命中即保留
-    "receipt": {
-        "content_kinds": None,
-        "layers": None,
-        "roles": _WORK_ROLES,
-        "include_work": True,
-    },
-}
-
-
-def views():
-    """合法视图名（排序稳定，供错误信息与文档引用）。"""
-    return tuple(sorted(ROLE_VIEWS))
-
-
-def matches(fm, view):
-    """节点元数据是否满足视图资格（单点谓词）。
-
-    fm：扁平 entry 或 frontmatter 字典（role/layer/content_kind 同名键）。
-    view：ROLE_VIEWS 键之一；非法值 ValueError（fail-closed）。
-    """
-    spec = ROLE_VIEWS.get(view)
-    if spec is None:
-        raise ValueError(
-            "非法 view：%r（合法三值：%s）" % (view, ", ".join(views())))
-    if spec["roles"] is not None:            # 正向白名单视图（receipt）
-        return fm.get("role") in spec["roles"]
-    ck = fm.get("content_kind")
-    if spec["content_kinds"] is not None \
-            and (ck or "text") not in spec["content_kinds"]:
-        return False
-    if spec["layers"] is not None \
-            and fm.get("layer") not in spec["layers"]:
-        return False
-    if not spec["include_work"] and fm.get("role") in _WORK_ROLES:
-        return False
-    return True
+# -*- coding: utf-8 -*-
+"""md_cg · 角色化读取视图（第四阶段 6.1，计划文档 §4）
+
+【为什么】同一认知图对不同消费角色应呈现不同侧面：主代理要「结论与
+修正历史」，验证端要「判据面与环境陷阱」，回执审计要「命令与预期输出」。
+三者的候选资格不同，但都建立在同一节点集上——视图是读取面的资格过滤，
+不是数据的第二副本（与超边的派生视图正交：超边是图结构增补，视图是
+候选资格过滤；计划 §3）。
+
+【设计】
+  - ROLE_VIEWS：声明式规则表（唯一真源），每个 view 声明四维资格：
+      content_kinds —— content_kind 必须落在集合内（None=不限）
+      layers        —— layer 必须落在集合内（None=不限）
+      roles         —— 非 None 时作为正向白名单（role 必须命中，
+                       短路返回；receipt 用）
+      include_work  —— False 时 role 落在工作角色（tool-output/
+                       command/edit）即一票否决（与候选池默认
+                       include_work=False 同口径）
+  - matches(fm, view)：单点谓词。fm 接受扁平 entry 或 frontmatter
+    字典（两者对 role/layer/content_kind 三键同名）。
+  - 非法 view 一律 ValueError（fail-closed，不静默回落）——合法性
+    判定单点在本模块；与节点缺字段 fail-open（缺 content_kind 按
+    "text" 对待）是两回事，后者是读取面惯例。
+
+【边界】
+  - 零内部依赖（不 import 本包其它模块，防循环导入）。规则表内的
+    工作角色白名单与 mdcos.WORK_ROLES 字面一致，一致性由
+    test_role_views 守卫断言钉住（防两处漂移）。
+  - 初版规则是类型启发，bench_role_views.py 的对照校准是法定修正
+    通道（改规则必须复跑对照，计划 §7.3）。
+"""
+
+# 规则表内的工作角色白名单，字面与 mdcos.WORK_ROLES 保持一致
+# （一致性由 test_role_views 守卫断言钉住，防两处漂移）。
+_WORK_ROLES = ("tool-output", "command", "edit")
+
+ROLE_VIEWS = {
+    # 主代理视图：结论与修正历史（正文/工作结论落在 knowledge 层）
+    "main": {
+        "content_kinds": ("text", "work_done"),
+        "layers": ("knowledge",),
+        "roles": None,
+        "include_work": False,
+    },
+    # 验证端视图：判据面与环境陷阱（marks 条目 + 知识正文，含 contextual）
+    "verifier": {
+        "content_kinds": ("ccg_marks", "text"),
+        "layers": ("knowledge", "contextual"),
+        "roles": None,
+        "include_work": False,
+    },
+    # 回执审计视图：恰是默认候选池剔除的工作角色节点（include_work
+    # 默认 False 的补集），roles 白名单短路命中即保留
+    "receipt": {
+        "content_kinds": None,
+        "layers": None,
+        "roles": _WORK_ROLES,
+        "include_work": True,
+    },
+}
+
+
+def views():
+    """合法视图名（排序稳定，供错误信息与文档引用）。"""
+    return tuple(sorted(ROLE_VIEWS))
+
+
+def matches(fm, view):
+    """节点元数据是否满足视图资格（单点谓词）。
+
+    fm：扁平 entry 或 frontmatter 字典（role/layer/content_kind 同名键）。
+    view：ROLE_VIEWS 键之一；非法值 ValueError（fail-closed）。
+    """
+    spec = ROLE_VIEWS.get(view)
+    if spec is None:
+        raise ValueError(
+            "非法 view：%r（合法三值：%s）" % (view, ", ".join(views())))
+    if spec["roles"] is not None:            # 正向白名单视图（receipt）
+        return fm.get("role") in spec["roles"]
+    ck = fm.get("content_kind")
+    if spec["content_kinds"] is not None \
+            and (ck or "text") not in spec["content_kinds"]:
+        return False
+    if spec["layers"] is not None \
+            and fm.get("layer") not in spec["layers"]:
+        return False
+    if not spec["include_work"] and fm.get("role") in _WORK_ROLES:
+        return False
+    return True