@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/md_cg/tool_face.py

@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+"""工具面渐进披露（pi ① 上下文经济学 · 灵枢落地）。
+
+【为什么】
+MCP 工具的 op 参数空间全量 schema 常驻调用方上下文：kernel 暴露面（cg+stg）
+达 ~20k 字符，其中 cg 一个工具就有 169 个参数——绝大多数是「长尾 op 专属参数的
+解释文字」，只在少数场景才需要，却每次会话都要付费注入。
+
+pi 的做法（`system-prompt.ts:82-84` 工具只以一行 snippet 常驻系统提示，完整描述
+只进 API tools 字段；`skills.ts:355-383` 索引常驻、正文按需 read）证明：
+**常驻面只需「我知道它存在、且知道怎么问」**，完整语义按需取回即可。
+
+【怎么做 · 信息零丢失】
+本模块**不改 schema 真源**（`mcp_server.KERNEL_TOOLS` / `TOOLS` 仍是完整定义），
+只做运行时**投影**：
+  · 工具 description → `TOOL_BRIEFS` 一行职责（缺省回退首句）；
+  · 参数 description → 短提示：通用参数保留首段（≤30 字符）、op 专属参数压到
+    ≤16 字符，枚举型参数保留**完整值集**（值集是调用契约，不可省）；
+  · 顺带剔除 `_req`（`_p()` 写的内部标记，本不该出现在对外 schema）。
+被投影掉的原文既不复制也不搬运——`cg(op=help, query=…)` 直接从真源渲染，
+故不存在第二真源、无漂移面，信息守恒是结构性的而非靠人工维护。
+
+【守卫】`md_cg/test_tool_face.py` 机械断言：注入面 ≥50% 削减 + 工具名/参数名/
+required/类型/枚举值集逐位不变 + 每个被投影掉的参数描述都能由 op=help 无损取回。
+
+【关闭】`MDCG_TOOL_FACE=full` 返回完整真源（调试/兼容）。
+"""
+from __future__ import annotations
+
+import os
+import re
+
+FULL_ENV = "MDCG_TOOL_FACE"
+
+# --------------------------------------------------------------------------
+# 一行职责（唯一手写面：必须由人写，不能机械生成）
+# --------------------------------------------------------------------------
+CG_HELP_HINT = '完整 op/参数语义：cg(op="help", query="<op 名 | 参数名 | 工具名>")'
+
+TOOL_BRIEFS = {
+    "cg": "灵枢认知图唯一入口（32 op：写/读/审/护/演化/元认知/预测/白箱…）。" + CG_HELP_HINT,
+    "stg": "语义时空图 4 op：relation|timeline|anchors|consistency。" + CG_HELP_HINT,
+    "mdcg_remember": "写入记忆节点（gated=true 走主动遗忘闸门；正文建议含 CCG 五要素）。",
+    "mdcg_recall": "按 token 预算召回记忆包（RRF 多路融合，可开模糊/条件语义路与查询扩展）。",
+    "mdcg_search": "精确检索（T0–T3 阶梯 + 四态资格判定）。",
+    "mdcg_get": "按 id 读取单个节点（frontmatter + content）。",
+    "mdcg_reflect": "记录信息差 D(t,C) 与二阶 d²D/dt²（写 _reflection.jsonl）。",
+    "mdcg_verify": "节点外部裁决 confirmed/weakened/falsified（falsified 入负记忆）。",
+    "mdcg_flywheel": "误差（预期 vs 实际）转为 unresolved 条目，驱动补条件。",
+    "mdcg_mine_fix_pairs": "从行为日志挖掘「错误→修复」对（产修复知识 + 负记忆）。",
+    "mdcg_rejected": "写入负记忆（被证伪假设），同内容幂等。",
+    "mdcg_unresolved": "写入未解问题（驱动主动探索）。",
+    "mdcg_propose": "候选记忆入审核队列（海马体 inbox）。",
+    "mdcg_review_list": "列出待审核候选（红队打回者带 needs_reapproval）。",
+    "mdcg_review_decide": "审核裁决 accept|reject|edit|merge（redteam 打回需再审批）。",
+    "mdcg_review_records": "裁决记录审计（可复核 record_hash 一致性）。",
+    "mdcg_forget": "软删除（tombstone → trash/，受保护节点需 override）。",
+    "mdcg_protect": "写保护：stats|check|mark|snapshot|history|forgetting（mark 需 admin）。",
+    "mdcg_forgetting_history": "主动遗忘裁决留痕（四态 + 三问判据）。",
+    "mdcg_identity": "身份特征识别（self/user/role/agent 的锚点、位置效应、条件特征）。",
+    "mdcg_consistency": "节点间冲突检测（L0 情绪 → L1 反思 → L2 递归反思；可投飞轮）。",
+    "mdcg_metacognition": "独立元认知（情绪/校准/盲区/信任四面；只读留痕）。",
+    "mdcg_self_state": "自我状态层（薄自我 + 富索引：状态卡单例 + 关系节点）。",
+    "mdcg_predict": "生成式预测（候选未来；过滤门 + 四维评分 + 命中反馈校准）。",
+    "mdcg_causal": "因果推理（causal 边 = 条件依赖；path|gate|chain|explain）。",
+    "mdcg_evolution": "演化账本（每次修改 = 补一条缺失条件；可 rollback 留痕）。",
+    "mdcg_restore": "恢复被 forget 的节点（在删除清单中且未 force 则拒绝）。",
+    "mdcg_health": "健康度（分桶健康 + CCG 完整度 + 验证基底覆盖 + OS 指标）。",
+    "mdcg_whoami": "身份与权限（tenant/actor/clearance/可见节点/可读密级）。",
+    "mdcg_ingest": "设备驱动：从会话文件增量摄取事件（fix-pair 挖掘 + watermark 去重）。",
+    "mdcg_watermarks": "各事件源的摄取水位（增量摄取状态，可审计）。",
+    "mdcg_whitebox": "白箱能力库调用与能力验证（ask|remember|verify_*|ping|report）。",
+    "mdcg_service_info": "服务信息（身份/版本/根目录/节点统计/工具数/权限）。",
+}
+
+# --------------------------------------------------------------------------
+# 投影规则
+# --------------------------------------------------------------------------
+_ENUM_RE = re.compile(r"[A-Za-z_][\w\-]*(?:\|[A-Za-z_][\w\-]*)+")
+_OP_SEC_RE = re.compile(r"op=([a-z_]+)：(.+?)(?=op=[a-z_]+：|$)", re.S)
+
+GENERIC_LIMIT = 24      # 通用参数（k/limit/tags/importance…）保留首段长度
+OP_SPECIFIC_LIMIT = 12  # op 专属参数（长尾）压缩长度；超此长度整体外置
+ENUM_PLACEHOLDER = "取值随 op 变化，完整枚举见 op=help"
+
+# 高频参数：无论描述是否带 op 前缀，都按「通用」处理（保留短提示）
+# ——这些是每次调用都可能要传的旋钮，让 agent 靠 schema 就能用起来。
+GENERIC_PARAMS = frozenset({
+    "op", "action", "query", "content", "node_id", "k", "limit", "intent",
+    "tags", "importance", "layer", "pid", "reason", "force", "dry_run",
+    "session", "note", "evidence", "verdict", "decision", "content_kind",
+    "budget_tokens", "text", "path", "role", "subject",
+})
+
+
+def op_sections(desc):
+    """从工具 description 里切出 {op: 段落}（机械切分，无损）。"""
+    out = {}
+    for m in _OP_SEC_RE.finditer(desc or ""):
+        out[m.group(1)] = m.group(2).strip().rstrip("；;")
+    return out
+
+
+def op_vocab(tools):
+    """全量 op 词汇表（用于判定「这是 op 专属参数的描述」）。"""
+    vocab = set()
+    for t in tools:
+        vocab |= set(op_sections(t.get("description") or ""))
+        props = (t.get("inputSchema") or {}).get("properties") or {}
+        for key, spec in props.items():
+            if key in ("op", "action"):
+                d = spec.get("description") or ""
+                for m in _ENUM_RE.finditer(d):
+                    vocab |= set(m.group(0).split("|"))
+    return vocab
+
+
+def _is_op_specific(desc, vocab, prefix_len=18):
+    head = (desc or "")[:prefix_len]
+    return any(len(o) >= 3 and o in head for o in vocab)
+
+
+def short_desc(desc, vocab, op_specific=False):
+    """投影一条参数描述。
+
+    返回 None 表示「整体外置」——该参数（长尾 op 专属）的描述不进常驻面，
+    由 ``cg(op=help, query="<参数名>")`` 按需取回。
+    """
+    if not desc:
+        return None
+    d = " ".join(str(desc).split())
+    groups = _ENUM_RE.findall(d)
+    if len(groups) == 1:
+        return groups[0]
+    if len(groups) > 1:
+        return ENUM_PLACEHOLDER
+    if op_specific:
+        # 长尾参数：短的原样留（信息本就少），长的一句话整体外置。
+        return d if len(d) <= OP_SPECIFIC_LIMIT else None
+    if len(d) > GENERIC_LIMIT:
+        return d[:GENERIC_LIMIT].rstrip() + "…"
+    return d
+
+
+def _schema_of(tool):
+    return tool.get("inputSchema") or {}
+
+
+def slim_tool(tool, vocab):
+    """投影单个工具（不修改入参）。"""
+    name = tool["name"]
+    desc = tool.get("description") or ""
+    isch = _schema_of(tool)
+    req = list(isch.get("required") or [])
+    props = isch.get("properties") or {}
+    new_props = {}
+    for key, spec in props.items():
+        clean = {k: v for k, v in spec.items() if k != "_req"}
+        d = clean.get("description")
+        if d:
+            generic = key in GENERIC_PARAMS or not _is_op_specific(d, vocab)
+            short = short_desc(d, vocab, op_specific=not generic)
+            if short:
+                clean["description"] = short
+            else:
+                clean.pop("description", None)
+        new_props[key] = clean
+    out_schema = {"type": isch.get("type") or "object", "properties": new_props}
+    if req:
+        out_schema["required"] = req
+    return {"name": name, "description": TOOL_BRIEFS.get(name) or _first_sentence(desc, 140),
+            "inputSchema": out_schema}
+
+
+def _first_sentence(desc, limit):
+    d = " ".join((desc or "").split())
+    for ch in ("。", "；", ";"):
+        i = d.find(ch)
+        if 0 < i <= limit:
+            return d[:i + 1]
+    return (d[:limit].rstrip() + "…") if len(d) > limit else d
+
+
+def slim_tools(tools):
+    """投影整个工具面。MDCG_TOOL_FACE=full 时原样返回（调试/兼容）。"""
+    if (os.environ.get(FULL_ENV) or "").strip().lower() == "full":
+        return tools
+    vocab = op_vocab(tools)
+    return [slim_tool(t, vocab) for t in tools]
+
+
+# --------------------------------------------------------------------------
+# 按需披露：cg(op=help, query=…)
+# --------------------------------------------------------------------------
+def _params_for(tool, op, limit=40):
+    isch = _schema_of(tool)
+    props = isch.get("properties") or {}
+    req = set(isch.get("required") or [])
+    vocab = {op}
+    out = [{"name": k, "type": v.get("type"), "required": k in req,
+            "desc": v.get("description") or ""}
+           for k, v in props.items()
+           if _is_op_specific(v.get("description") or "", vocab)]
+    return out[:limit]
+
+
+def help_text(tools, query=None, limit=40):
+    """从**完整真源**按需渲染说明——被投影掉的原文在此无损取回。"""
+    q = (query or "").strip()
+    by_name = {t["name"]: t for t in tools}
+    if not q:
+        return {"ok": True,
+                "tool_index": [{"name": t["name"],
+                                "brief": TOOL_BRIEFS.get(t["name"])
+                                or _first_sentence(t.get("description") or "", 120)}
+                               for t in tools],
+                "usage": 'query 取 op 名 / 参数名 / 工具名，例如 '
+                         'cg(op="help", query="write")'}
+    if q in by_name:
+        t = by_name[q]
+        isch = _schema_of(t)
+        props = isch.get("properties") or {}
+        req = list(isch.get("required") or [])
+        return {"ok": True, "tool": t["name"],
+                "description": t.get("description") or "",
+                "ops": sorted(op_sections(t.get("description") or "")),
+                "params": [{"name": k, "type": v.get("type"),
+                            "required": k in req,
+                            "desc": v.get("description") or ""}
+                           for k, v in props.items()],
+                "required": req}
+    hits = []
+    for t in tools:
+        isch = _schema_of(t)
+        props = isch.get("properties") or {}
+        req = set(isch.get("required") or [])
+        secs = op_sections(t.get("description") or "")
+        if q in secs:
+            hits.append({"tool": t["name"], "op": q, "doc": secs[q],
+                         "params": _params_for(t, q, limit)})
+        # 不短路：op 名与参数名同名时（如 goal/ref/consistency），两者都要能取回。
+        for pname, spec in props.items():
+            if pname == q or (len(q) >= 4 and pname.startswith(q)):
+                hits.append({"tool": t["name"], "param": pname,
+                             "type": spec.get("type"), "required": pname in req,
+                             "desc": spec.get("description") or ""})
+    if not hits:
+        return {"ok": False, "error": f"未找到 op / 参数 / 工具：{q}",
+                "hint": "cg(op=help) 不带 query 可列出全部工具与一行职责"}
+    return {"ok": True, "query": q, "hits": hits[:max(1, limit)]}

package/md_cg/twophase.py

@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+"""写入两段式提交（Pi 可学习优点 ③）：先记意图，再记结果，崩溃后可对账。
+
+**问题（交接文档 §3③）**：写入只有**一条事后记录**——`_audit.jsonl` 只在
+`op=add` **成功之后**追加一行。进程在「闸门通过之后、落盘前后」被杀，日志里
+没有任何痕迹：
+  · 落盘成功但簿记没写 → 记忆存在、历史里查不到（静默的记忆）；
+  · 落盘只做了一半（原子写保证文件不半截，但索引增量可能没落）→ 对账无从下手，
+    只能人工翻目录。
+两段式把一次写入拆成两条记录：
+  1. **intent**（意图，**先行**持久化）：写下「我准备写 node_id，正文指纹 = h」；
+  2. **outcome**（结果）：写下「这笔以 committed / interrupted / error 结束」。
+崩溃后 `reconcile()` 扫日志配对，对**有 intent 无 outcome** 的逐条判定：
+  · 节点在库且正文指纹 == intent 的 h → **补账** outcome{committed, reconciled}；
+  · 节点不在、或指纹不符 → outcome{interrupted}，如实标记（**不假装成功**）。
+对账**幂等**：补出来的 outcome 与正常 outcome 同为 outcome 记录，第二次扫描
+不再有未配对 intent。
+
+**为何用独立文件 `_write_2pc.jsonl` 而非写进 `_audit.jsonl`**（对交接文档
+「落 `_audit.jsonl`」建议的偏离，取证理由）：
+  · `_audit.jsonl` 已被当作**单一语义流**消费——`test_p45_session_identity` 的 F
+    段断言 `rows[-1]` 必须带 harness / unit / session 归因，coggraph 会话串链按
+    `op` 值串链。混入两段式事件，同一文件的读者要多分辨三种事件语义，且既有
+    断言口径被无谓扰动（一次写入 = 三行日志）。
+  · 本仓已有「独立审计文件」惯例：`protect.py` 的 `_protected_audit.jsonl`。
+  · 两段式是**写路径的崩溃一致性账本**，不是访问审计——语义本就不同源。
+
+**诚实边界**：
+  · `append_jsonl` 在 Windows 上非原子（O_APPEND 是 lseek+write 两步），多进程
+    高并发下可能丢 intent——对账是**增益**，不是「保证不丢」；单进程/低并发足够，
+    且 kill -9 不会丢已 write 的数据（只有断电才丢，见 `fsutil` 注释）。
+  · 对账只做「补账 / 标记」，**不重放写入**——是否重做是使用者的决定。
+  · 账本是 append-only：对账不重写历史，只追加 outcome。
+"""
+
+import os
+import time
+import uuid
+
+from . import nodefile
+from .fsutil import append_jsonl
+
+#: 账本文件名（独立于 `_audit.jsonl`，理由见模块 docstring）
+LOG_FILE = "_write_2pc.jsonl"
+
+#: outcome 状态集
+STATUS_COMMITTED = "committed"      # 落盘完成（正常路径或对账补账）
+STATUS_INTERRUPTED = "interrupted"  # 有意图、未落盘（或指纹不符）——如实标记
+STATUS_ERROR = "error"              # 执行抛异常
+STATUS_ABORTED = "aborted"          # 闸门判定不落盘（reject/defer/丢弃）
+
+#: 对账判定码
+R_NODE_OK = "node_present_hash_match"   # 落盘已完成 → 补 committed
+R_NODE_MISSING = "node_missing"         # 未落盘 → interrupted
+R_MISMATCH = "content_mismatch"         # 落了别的正文 → interrupted（不覆盖）
+R_UNREADABLE = "node_unreadable"        # 读节点失败 → interrupted（不猜测）
+
+
+def log_path(cg) -> str:
+    return os.path.join(cg.root, LOG_FILE)
+
+
+def _norm(text: str) -> str:
+    """正文口径归一（**对账正确性的前提**）：`nodefile.dumps` 写盘时会给正文补尾
+    换行，`loads` 读回即带它。若 intent 按入参原文、对账按读回内容各算一次指纹，
+    两者**永远不会相等** → 每一笔都误报 interrupted——比不做对账更坏（假阳性会
+    淹没真问题，且诱人去"修"不存在的问题）。故两侧统一按「去尾换行」归一。
+    """
+    return (text or "").rstrip("\n")
+
+
+def _append(cg, rec: dict) -> None:
+    append_jsonl(log_path(cg), rec)
+
+
+def _ident(cg, actor=None) -> dict:
+    """归因字段（尽力而为）：principal 缺省时留空，不编造。"""
+    pr = getattr(cg, "principal", None) or getattr(cg, "session", None)
+    meta = {}
+    if isinstance(pr, str) and pr:
+        meta["session"] = pr
+    elif pr is not None:
+        sid = getattr(pr, "session", None)
+        if sid:
+            meta["session"] = sid
+        wid = getattr(pr, "writer", None) or getattr(pr, "unit", None)
+        if wid:
+            meta["writer"] = wid
+    if actor:
+        meta["actor"] = actor
+    return meta
+
+
+def begin(cg, node_id: str, content: str, layer: str = None,
+          actor: str = None, **meta) -> dict:
+    """记录写入**意图**（先行持久化）→ 返回令牌 tok（供 `commit` 配对）。
+
+    先于落盘调用；崩溃后据 tok 里的指纹判定该笔是否落盘完成。
+    """
+    tok = {
+        "iid": uuid.uuid4().hex[:16],
+        "node_id": node_id,
+        "content_hash": nodefile.content_hash(_norm(content)),
+    }
+    rec = {"t": time.time(), "phase": "intent", "iid": tok["iid"],
+           "id": node_id, "content_hash": tok["content_hash"]}
+    if layer:
+        rec["layer"] = layer
+    rec.update(_ident(cg, actor))
+    rec.update(meta)
+    _append(cg, rec)
+    return tok
+
+
+def commit(cg, tok: dict, status: str = STATUS_COMMITTED, node_id: str = None,
+           reason: str = None, **meta) -> dict:
+    """记录写入**结果**（与 intent 按 iid 配对）。返回结果记录。"""
+    nid = node_id or (tok or {}).get("node_id")
+    rec = {"t": time.time(), "phase": "outcome", "iid": (tok or {}).get("iid"),
+           "id": nid, "status": status}
+    if tok and tok.get("content_hash"):
+        rec["content_hash"] = tok["content_hash"]
+    if reason:
+        rec["reason"] = reason
+    rec.update(_ident(cg))
+    rec.update(meta)
+    _append(cg, rec)
+    return rec
+
+
+# ----------------------------------------------------------------------
+# 读侧：盘点 / 对账
+
+def records(cg) -> list:
+    """读全部账本记录（append-only，坏行跳过不炸）。"""
+    out = []
+    p = log_path(cg)
+    if not os.path.isfile(p):
+        return out
+    import json
+    with open(p, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            if not line.strip():
+                continue
+            try:
+                out.append(json.loads(line))
+            except Exception:
+                continue
+    return out
+
+
+def _pair(cg) -> dict:
+    """把账本配成 {iid: {"intent":…, "outcome":…}}（同时计入无 iid 的脏行）。"""
+    pairs = {}
+    for r in records(cg):
+        iid = r.get("iid")
+        if not iid:
+            continue
+        slot = pairs.setdefault(iid, {"intent": None, "outcome": None})
+        if r.get("phase") == "intent" and slot["intent"] is None:
+            slot["intent"] = r
+        elif r.get("phase") == "outcome" and slot["outcome"] is None:
+            slot["outcome"] = r
+    return pairs
+
+
+def pending(cg, limit: int = 200) -> list:
+    """未结清的写入意图（有 intent 无 outcome）——只读，不改盘。
+
+    供 `cg(op=recent)` / 巡检看「有没有半途而废的写入」。
+    """
+    out = []
+    for iid, slot in _pair(cg).items():
+        if slot["intent"] is not None and slot["outcome"] is None:
+            out.append({"iid": iid, **slot["intent"]})
+    out.sort(key=lambda r: r.get("t") or 0)
+    return out[:max(0, int(limit))]
+
+
+def _judge(cg, intent: dict):
+    """判定一笔未结清意图的真实结局 → `(status, code)`。**不猜测**：读不到就如实说。"""
+    nid = intent.get("id")
+    want = intent.get("content_hash")
+    if not nid:
+        return STATUS_INTERRUPTED, R_UNREADABLE
+    try:
+        node = cg.get(nid)
+    except Exception:
+        return STATUS_INTERRUPTED, R_UNREADABLE
+    if not node:
+        return STATUS_INTERRUPTED, R_NODE_MISSING
+    got = nodefile.content_hash(_norm(node.get("content") or ""))
+    if want and got != want:
+        return STATUS_INTERRUPTED, R_MISMATCH
+    return STATUS_COMMITTED, R_NODE_OK
+
+
+def reconcile(cg, apply: bool = True, limit: int = 2000) -> dict:
+    """启动/巡检对账：把半途写入**补账或如实标记**。
+
+    `apply=False` 为 dry-run（只报告，不写账本）。返回汇总：
+    `{"unpaired", "committed", "interrupted", "applied", "details"}`。
+    幂等——补出的 outcome 与正常 outcome 同形，二次扫描不再有未配对项。
+    """
+    pend = pending(cg, limit=limit)
+    rep = {"unpaired": len(pend), "committed": 0, "interrupted": 0,
+           "applied": bool(apply), "details": []}
+    for intent in pend:
+        status, code = _judge(cg, intent)
+        if status == STATUS_COMMITTED:
+            rep["committed"] += 1
+        else:
+            rep["interrupted"] += 1
+        rep["details"].append({"iid": intent.get("iid"), "id": intent.get("id"),
+                               "status": status, "reason": code})
+        if apply:
+            commit(cg, {"iid": intent.get("iid"), "node_id": intent.get("id"),
+                        "content_hash": intent.get("content_hash")},
+                   status=status, reason=code, reconciled=True,
+                   actor="twophase:reconcile")
+    return rep