@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/self_state.py

@@ -92,12 +92,14 @@ STATE_LINK_TYPE = "refers_to"
 
 # ---------------------------------------------------------------- 基础工具
 
+# 生效条件：对 required 形参 text，返回 str(text or "") 经正则把非中英文数字连续段折叠为下划线、strip('_') 并 lower 后的字符串（text 为假值时返回空串）；
 def _slug(text):
     """归一化 id 片段：保留中英文数字，其余折叠为下划线。"""
     s = re.sub(r"[^0-9A-Za-z\u4e00-\u9fff]+", "_", str(text or ""))
     return s.strip("_").lower()
 
 
+# 生效条件：对 required 形参 ts，当 float(ts) 可转换且 time.localtime 不抛 OSError 时返回本地时间 "%Y-%m-%d %H:%M:%S" 格式串；当 float(ts) 抛 TypeError/ValueError 或 time.localtime 抛 OSError 时返回空串；
 def _iso(ts):
     try:
         return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(float(ts)))
@@ -105,24 +107,29 @@ def _iso(ts):
         return ""
 
 
+# 生效条件：subject 未传时取模块常量 DEFAULT_SUBJECT，返回模块常量 STATE_PREFIX 拼接 _slug(subject) 的结果；
 def state_node_id(subject=DEFAULT_SUBJECT):
     """状态卡节点 id（单例：同一 subject 只有一个）。"""
     return STATE_PREFIX + _slug(subject)
 
 
+# 生效条件：对 required 形参 frm 与 to，返回模块常量 RELATION_PREFIX 拼接 _slug(frm)、"__"、_slug(to) 的字符串；
 def relation_node_id(frm, to):
     """关系节点 id（有向）。"""
     return f"{RELATION_PREFIX}{_slug(frm)}__{_slug(to)}"
 
 
+# 生效条件：对 required 形参 cg，返回 os.path.join(cg.root, LOG_FILE)（LOG_FILE 为模块常量）；
 def log_path(cg):
     return os.path.join(cg.root, LOG_FILE)
 
 
+# 生效条件：对 required 形参 dim 与 value，返回 f"{dim}:{_slug(value)}"；
 def dim_tag(dim, value):
     return f"{dim}:{_slug(value)}"
 
 
+# 生效条件：对 required 形参 p_trust，若 p_trust is None 或 float(p_trust) 抛 TypeError/ValueError 则返回 None；否则按模块常量 TRUST_BANDS 顺序取首个 v >= lo 的档名，均不满足返回 "low"；
 def trust_band(p_trust):
     """把 P_trust 映射到信任档（索引维度之一）。"""
     if p_trust is None:
@@ -139,6 +146,7 @@ def trust_band(p_trust):
 
 # ---------------------------------------------------------------- 留痕
 
+# 生效条件：对 required 形参 cg 与 rec，调用 append_jsonl(log_path(cg), rec)；若抛出 OSError 则静默忽略，无返回值；
 def _append_log(cg, rec):
     try:
         append_jsonl(log_path(cg), rec)
@@ -146,6 +154,7 @@ def _append_log(cg, rec):
         pass
 
 
+# 生效条件：对 required 形参 cg 与可选 limit/subject，读取 log_path(cg) 留痕（OSError 时为空列表）；subject 为真值时只保留 r.get("subject") == subject 的记录；倒序后，limit 为真值时返回 recs[:int(limit)]，limit 为假值（如 0）时返回全部倒序记录；
 def history(cg, limit=100, subject=None):
     """自我状态留痕（倒序）。"""
     try:
@@ -158,6 +167,7 @@ def history(cg, limit=100, subject=None):
     return recs[:int(limit)] if limit else recs
 
 
+# 生效条件：对 required 形参 cg 与可选 subject，调用 history(cg, limit=0, subject=subject) 取全部倒序留痕；有记录时返回 recs[0]（最新一条），否则返回 None；
 def _last_log(cg, subject=None):
     recs = history(cg, limit=0, subject=subject)
     return recs[0] if recs else None
@@ -165,6 +175,7 @@ def _last_log(cg, subject=None):
 
 # ---------------------------------------------------------------- 读卡
 
+# 生效条件：对 required 形参 cg 与 node_id，尝试返回 cg.get(node_id)；若 cg.get 抛任何异常则返回 None；
 def _node(cg, node_id):
     try:
         return cg.get(node_id)
@@ -172,15 +183,18 @@ def _node(cg, node_id):
         return None
 
 
+# 生效条件：对 required 形参 cg 与 node_id，取 _node(cg, node_id) 结果（假值时用空字典）的 "frontmatter" 值；该值假值时返回空字典，否则返回该 frontmatter；
 def _fm_of(cg, node_id):
     node = _node(cg, node_id)
     return (node or {}).get("frontmatter") or {}
 
 
+# 生效条件：对 required 形参 cg 与 node_id，从 cg.index（getattr 取不到或假值时用空字典）的 "nodes" 字段（假值时用空字典）中取 node_id 对应条目；缺键返回 None；
 def _entry(cg, node_id):
     return ((getattr(cg, "index", None) or {}).get("nodes") or {}).get(node_id)
 
 
+# 生效条件：对 required 形参 cg 与 subject（未传时 DEFAULT_SUBJECT），若 state_node_id(subject) 在 cg.index.nodes 中不存在，或该节点没有非空 frontmatter，返回 None；否则返回由该 frontmatter 扁平化出的 dict，其中 subject 为 fm.get("state_subject") or subject，d_current/p_trust 分别从 information_gap/trust 子字典取；
 def snapshot(cg, subject=DEFAULT_SUBJECT):
     """读当前状态卡 → 扁平 dict（不存在返回 None）。只读，不写盘。"""
     nid = state_node_id(subject)
@@ -205,6 +219,7 @@ def snapshot(cg, subject=DEFAULT_SUBJECT):
     return out
 
 
+# 生效条件：对 required 形参 state，返回对指定核心字段（subject、information_gap、trust、emotion、affect、importance_self、important_refs、identity_ref、short_term、relations、prediction、dimensions、state_links）做 sort_keys=True、ensure_ascii=False、default=str 的 JSON 序列化后 SHA-256 前 16 位十六进制（不含 state_version）；
 def _fingerprint(state):
     """状态指纹：只对「会漂移的实质字段」取哈希，用于幂等刷新与版本链。
 
@@ -232,6 +247,30 @@ def _fingerprint(state):
 
 # ---------------------------------------------------------------- 聚合（九项）
 
+# 生效条件：对 required 形参 cg，返回近 int(window)（缺省 20）条反思留痕里 d_meta.unmodeled_growth 的均值（仅收数值型、bool 不计），无可用留痕时回落 d_meta.pressure(d_meta.compute(cg))，d_meta 不可用或抛异常时返回 None；
+def _d_meta_trend(cg, window: int = 20):
+    """近 window 条反思留痕的 D_meta 边界压力均值（确定性函数，纯读）。
+
+    口径（智能论3.4 §2.7.0 DEV-002a）：只聚合已落盘的
+    `d_meta.unmodeled_growth`——**不合成三代理**、不参与 D_task。
+    留痕无该字段（旧记录/总闸关闭）时回落当前 `d_meta.compute` 的**单一
+    代理**值；两者皆不可用 → None（未知即未知，不编造）。
+    """
+    try:
+        from . import d_meta as _d_meta
+        vals = []
+        for r in metacognition._reflections(cg)[-int(window):]:
+            v = (r.get("d_meta") or {}).get("unmodeled_growth")
+            if isinstance(v, (int, float)) and not isinstance(v, bool):
+                vals.append(float(v))
+        if vals:
+            return round(sum(vals) / len(vals), 4)
+        return _d_meta.pressure(_d_meta.compute(cg))
+    except Exception:                                      # noqa: BLE001
+        return None
+
+
+# 生效条件：对 required 形参 cg，返回预测校准 dict；samples==0 时 ok=False、hit_rate=None 且 note 提示无预测留痕；samples>0 且 th.get("reflect") 为真时 note 建议反思，否则 note 正常；ece 与 calibration 仅在 metacognition.calibration 返回 ok 为真时给出，否则为 None；d_meta_trend 恒由 _d_meta_trend(cg) 给出（近 20 条反思的 D_meta 单代理均值，不可用时为 None）；
 def _prediction_face(cg):
     """预测校准（第九项）：我预测得准吗、该不该反思？
 
@@ -239,6 +278,8 @@ def _prediction_face(cg):
       · `predict._hit_history` / `predict.dynamic_hit_threshold`
         ← `_prediction.jsonl`（predict_feedback 留痕）
       · `metacognition.calibration` ← evidence_log（verify 留痕）的 ECE
+      · `d_meta.compute` / 反思留痕的 `d_meta` ← 边界压力趋势（d_meta_trend，
+        **不合成三代理**、不参与 D_task：D_task 与 D_meta 对象不同）
 
     诚实边界：无预测留痕 → ok=False、hit_rate=None（未知即未知）；
     ECE 仅在 metacognition 有足够证据时给出，否则 None。绝不编造。
@@ -257,6 +298,7 @@ def _prediction_face(cg):
         cal = metacognition.calibration(cg)
     except Exception:                                      # noqa: BLE001
         cal = {}
+    meta_trend = _d_meta_trend(cg)
     if samples == 0:
         note = "无预测留痕：先 predict_feedback() 积累命中记录"
     elif th.get("reflect"):
@@ -273,10 +315,12 @@ def _prediction_face(cg):
         "reflect": bool(th.get("reflect")),
         "ece": cal.get("ece") if cal.get("ok") else None,
         "calibration": cal.get("verdict") if cal.get("ok") else None,
+        "d_meta_trend": meta_trend,
         "note": note,
     }
 
 
+# 生效条件：对 required 形参 cg 与 window，尝试用 cg.recent_events(limit=int(window), newest_first=False) 取记录（异常时 recs=[]），返回 n=len(recs)、span=[min(ts), max(ts)] if ts else None、roles 角色计数、ptr 为 cg.recent_log 的 basename（缺省 "_recent.jsonl"）；
 def _recent_summary(cg, window):
     """短期记忆：只做窗口摘要，原文仍留在 _recent.jsonl（薄自我的关键取舍）。"""
     try:
@@ -293,6 +337,7 @@ def _recent_summary(cg, window):
             "ptr": os.path.basename(getattr(cg, "recent_log", "_recent.jsonl"))}
 
 
+# 生效条件：对 required 形参 cg 与 subject，若 identity.profile(cg, subject) 抛异常则返回 (None, 0)；否则返回 (prof.anchor.node_id（缺省 None）, len(prof.get("anchors") or []))；
 def _identity_ref(cg, subject):
     """身份：只存指针（锚点节点 id），锚点内容仍在 self 层原节点里。"""
     try:
@@ -304,6 +349,7 @@ def _identity_ref(cg, subject):
     return ref, len(anchors)
 
 
+# 生效条件：对 required 形参 cg 与 subject，遍历 cg.index.nodes 中标签含 TAG_RELATION 或以 RELATION_PREFIX 开头的节点，统计 tags 含 "rel_from:{_slug(subject)}" 的个数为 out、含 "rel_to:{_slug(subject)}" 的个数为 in，返回 {"out": out, "in": inn}；
 def _relation_counts(cg, subject):
     """关系：从索引里的关系节点统计出/入度（不读文件正文）。"""
     slug = _slug(subject)
@@ -320,6 +366,7 @@ def _relation_counts(cg, subject):
     return {"out": out, "in": inn}
 
 
+# 生效条件：对 required 形参 dimensions（假值时按空字典），只保留键 str(dim).strip().lower() 属于模块常量 DIMENSIONS 且 val 非 None 的维度；val 为 list/tuple/set 时展开，否则包装为单元素；过滤空字符串并去重后放入 out，返回 out；
 def _normalize_dimensions(dimensions):
     """维度入参 → {dim: [value...]}（只保留已知维度）。"""
     out = {}
@@ -337,6 +384,7 @@ def _normalize_dimensions(dimensions):
     return out
 
 
+# 生效条件：对 required 形参 cg、subject、window、importance、important_refs、dimensions、links、old，聚合 trace/trust/recent/identity/relations/prediction 等生成薄状态 dict；emotion 与 affect 仅在对应 trace/trust ok 且二阶值为非 None 时取 emotion，否则为 "unknown"；importance 为 None 时回落 old.importance_self 再回落 1.0；important_refs 为 None 时回落 old.important_refs；dimensions 归一化后为空则回落 old.dimensions，并自动追加 trust band 与今日时间；links 为 None 时回落 old.state_links；
 def _derive(cg, subject, window, importance, important_refs, dimensions,
             links, old):
     """聚合九项自我信息 → 薄状态（纯读，不写盘）。"""
@@ -394,6 +442,7 @@ def _derive(cg, subject, window, importance, important_refs, dimensions,
 
 # ---------------------------------------------------------------- 写卡
 
+# 生效条件：对 required 形参 state，读取其 information_gap、trust、short_term、prediction、dimensions 等字段，渲染并返回末尾带换行的状态卡正文（含 D_meta 边界压力趋势一行：prediction.d_meta_trend 缺失时显示 None）；span 为空时显示（无），角色为空时显示（无）；
 def _render(state):
     """状态卡正文：人类可读，且与 frontmatter 字段一一对应。"""
     ig, tt = state["information_gap"], state["trust"]
@@ -427,6 +476,8 @@ def _render(state):
         f"；后验可信度={pd.get('beta_mean')}"
         f"（95%CI {pd.get('beta_ci95')}）"
         f"；ECE={pd.get('ece')}（{pd.get('calibration')}）",
+        f"# D_meta：边界压力趋势（unmodeled_growth 均值）={pd.get('d_meta_trend')}"
+        f"（三代理分别观测、不合成单值，不参与 D_task）",
         "# 索引：" + "；".join(
             f"{d}={','.join(dims.get(d) or []) or '-'}" for d in DIMENSIONS),
         "# 说明：本卡是薄自我——只登记当前值与指针；具体任务/人物/会话/"
@@ -435,6 +486,7 @@ def _render(state):
     return "\n".join(lines) + "\n"
 
 
+# 生效条件：当 cg 可用时，refresh 以 subject（默认 DEFAULT_SUBJECT）和 window（默认 RECENT_WINDOW）聚合九项；若留痕末条存在且状态卡缺失或 state_version/state_hash 与留痕末条不一致，则按留痕重建元数据；若 force 为假且未触发重建且旧 state_hash 等于新指纹，返回 changed=False 的幂等跳过；否则若留痕末条存在且状态卡 state_hash（状态卡缺失时视为 None）与留痕末条不同，则 strict 为真时返回 ok=False、error='chain_broken'，strict 为假时以留痕末条 hash 修复 prev_hash 并写入，最终写入时返回 changed=True 及新 state_version/state_hash；
 def refresh(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW, importance=None,
             important_refs=None, dimensions=None, links=None,
             actor="self_state", force=False, strict=False, session=None):
@@ -559,6 +611,7 @@ def refresh(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW, importance=None,
 
 # ---------------------------------------------------------------- 关系
 
+# 生效条件：对 required 形参 cg、frm、to 与可选 relation_type/strength/reciprocal，若 _slug(frm) == _slug(to) 返回 {"ok": False, "error": "self_loop", ...}；否则 relation_type 不在模块常量 RELATION_TYPES 时回落 "other"，strength 的 float 失败时 w=0.5、成功时夹在 0.0~1.0，写入关系节点，reciprocal 为真时同时写反向，返回 ok=True 及 written 列表；
 def relate(cg, frm, to, relation_type="collaborator", strength=0.5,
            condition="", note="", reciprocal=False, actor="self_state"):
     """写一条有向关系（自我 ↔ 其他智能）。reciprocal=True 时同时写反向。"""
@@ -597,6 +650,7 @@ def relate(cg, frm, to, relation_type="collaborator", strength=0.5,
             "reciprocal": bool(reciprocal)}
 
 
+# 生效条件：对 required 形参 cg 与可选 subject/direction，遍历 cg.index.nodes 中标签含 TAG_RELATION 或以 RELATION_PREFIX 开头的节点；subject 为真值时按 _slug(subject) 过滤，direction 为 "out" 只保留出边、"in" 只保留入边、"both" 保留出或入边、其他 direction 不做方向过滤；返回按 strength（importance）降序、再按 node_id 升序排序的关系列表 out；
 def relations(cg, subject=None, direction="both"):
     """列出关系节点（按 subject 过滤出/入）。"""
     nodes = ((getattr(cg, "index", None) or {}).get("nodes") or {})
@@ -629,6 +683,7 @@ def relations(cg, subject=None, direction="both"):
 
 # ---------------------------------------------------------------- 索引
 
+# 生效条件：对 required 形参 cg、dim、value 与可选 limit/with_content，若 dim 小写去空白后不在模块常量 DIMENSIONS 中，返回 {"ok": False, "error": "unknown_dimension", "allowed": list(DIMENSIONS)}；否则匹配 cg.index.nodes 中 tags 含 dim_tag(dim, value) 的节点，按 importance 降序、created_at 降序排序，取 hits[:int(limit)]（limit=0 时切片为空），with_content 为真时附加节点 content 前 400 字符，返回 ok=True 及 count/items；
 def index(cg, dim, value, limit=50, with_content=False):
     """按五维索引反查具体详情节点（认知图连接，不是内容搬运）。"""
     d = str(dim or "").strip().lower()
@@ -640,7 +695,8 @@ def index(cg, dim, value, limit=50, with_content=False):
     hits = [(nid, e) for nid, e in nodes.items()
             if tag in (e.get("tags") or [])]
     hits.sort(key=lambda kv: (-float(kv[1].get("importance") or 0),
-                              -float(kv[1].get("created_at") or 0)))
+                              -float(kv[1].get("created_at") or 0),
+                              str(kv[0] or "")))
     items = []
     for nid, e in hits[:int(limit)]:
         item = {"node_id": nid, "layer": e.get("layer"),
@@ -654,6 +710,7 @@ def index(cg, dim, value, limit=50, with_content=False):
             "count": len(hits), "items": items}
 
 
+# 生效条件：对 required 形参 cg 与 subject（未传时 DEFAULT_SUBJECT），若 snapshot(cg, subject) 返回假值则返回 {"ok": False, "error": "no_state", "subject": subject}；否则返回 {"ok": True, "subject": subject, "dimensions": st.get("dimensions") or {}}；
 def dimensions(cg, subject=DEFAULT_SUBJECT):
     """状态卡登记的五维索引标签。"""
     st = snapshot(cg, subject)
@@ -665,12 +722,14 @@ def dimensions(cg, subject=DEFAULT_SUBJECT):
 
 # ---------------------------------------------------------------- 审计
 
+# 生效条件：对 required 形参 code、severity、why，返回含这三个键并合并 **extra 的 dict；
 def _issue(code, severity, why, **extra):
     d = {"code": code, "severity": severity, "why": why}
     d.update(extra)
     return d
 
 
+# 生效条件：当 cg 可用时，audit 对 subject（默认 DEFAULT_SUBJECT）和 window（默认 RECENT_WINDOW）执行一致性审计；若对应状态卡不存在则返回 ok=False、verdict='absent'（含已收集的 issues）；否则基于留痕历史与现算值收集 issues，按有无 error 返回 verdict='broken'、无 error 但有 warn 返回 'drift'、均无返回 'consistent'，且 ok 为无 error；
 def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
     """自我信息一致性审计：全部判定可重算（不依赖人的判断）。"""
     from . import protect as _protect
@@ -847,6 +906,7 @@ def audit(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW):
 
 # ---------------------------------------------------------------- 加载 / 概览
 
+# 生效条件：对 required 形参 cg 与可选 subject/window/auto_refresh/actor，先取 snapshot(cg, subject)；若 st 为 None 且 auto_refresh 为真则 refresh 后重新 snapshot；若 st 非 None 且 auto_refresh 为真且 st.state_ts 的年龄 > 模块常量 STALE_AFTER 则 refresh 后重新 snapshot；然后取 relations、history(limit=5, subject)、dimensions，返回 ok=st is not None 及这些字段；
 def bootstrap(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW,
               auto_refresh=True, actor="bootstrap"):
     """会话启动：加载自我状态卡 + 关系 + 最近留痕 + 索引概览。
@@ -874,6 +934,7 @@ def bootstrap(cg, subject=DEFAULT_SUBJECT, window=RECENT_WINDOW,
             "loaded_at": time.time()}
 
 
+# 生效条件：对 required 形参 cg、out、st、session，若 session 为假值直接返回 out；否则写入 out["session"]=str(session)、out["session_registered"]=bool(s in st.dimensions.session 列表)、out["session_refs"]（调用 index(cg, "session", s, limit=20) 的结果；异常时写入 count=0、degraded=True），返回 out；
 def _with_session_slice(cg, out, st, session):
     """给 summary 结果补「本会话切片」（薄卡 + 富索引，不改单例语义）。
 
@@ -895,6 +956,7 @@ def _with_session_slice(cg, out, st, session):
     return out
 
 
+# 生效条件：对 required 形参 cg 与可选 subject/session，取 snapshot(cg, subject)；若为假值，经 _with_session_slice 返回 {"ok": False, "subject": subject, "note": "无状态卡"}；否则构造含 version、d_current、emotion、p_trust、trust_band、text 等字段的 dict，再经 _with_session_slice 返回；
 def summary(cg, subject=DEFAULT_SUBJECT, session=None):
     """一句话自我状态（供 health / 面板）。
 
@@ -927,6 +989,7 @@ def summary(cg, subject=DEFAULT_SUBJECT, session=None):
     return _with_session_slice(cg, out, st, session)
 
 
+# 生效条件：无参调用时返回模块自描述 dict，内含模块常量 SCHEMA_VERSION、DEFAULT_SUBJECT、LOG_FILE、DIMENSIONS、TRUST_BANDS、RELATION_TYPES、DRIFT_TOL、STALE_AFTER 等；
 def catalog():
     """自描述：九项自我信息 + 五维索引 + 审计规则（供协议对照验证）。"""
     return {

package/md_cg/selfreport.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""常驻进程自报：把「我是谁 / 我从哪个 md_cg 包加载 / 我持哪一代 render 契约」
+落成**外部可读的事实**。
+
+# 生效条件：载体/位置：仓根 md_cg/selfreport.py（import 路径 md_cg.selfreport）；时间：常驻 md_cg MCP server 进程启动时由 mcp_server.main 调用 report()；方法：info() 采集进程事实（pid/ppid/cwd/argv/sys.path[0]），source_dir/source_file/render_version 由 codeindex 的实际加载位置与常量求出，report() 原子写 <tempdir>/md_cg_servers/<pid>.json；约束：**任何异常一律吞掉并返回 None/空**——自报是诊断设施，不得成为服务故障源；不记录环境变量值，只记录 MDCG_ROOT/MDCG_TOKEN 是否已设置。
+
+## 为什么需要它（根因，非猜测）
+
+判「一个常驻 md_cg 进程会不会用旧契约覆盖重建成果」，原先只能比「进程启动时间 vs
+md_cg/*.py 最新 mtime」。该判据有**活体盲区**：npm 副本内的进程启动于 11:37~11:39，
+而源码 mtime 为 09:24 —— `stale=False`，但它加载的是插件包 0.4.8 的
+`codeindex.render`（旧契约：合成 `# 生效条件：载体/位置：`），会把全量重建成果刷回
+`old_synth`（AGENTS.md §5 运维注记实证）。mtime 是**相对量**，每次须复算且天然滞后。
+
+自报给的是**绝对事实**：进程**自己**报出它实际加载的 `md_cg` 包目录与契约代际。
+外部脚本据此机械裁决，不再推断。旧包不含本模块，故**「无自报」本身即旧契约的证据**
+（唯一例外见 `scripts/mdcg_stale_servers.py` 的 cwd 兜底分支）。
+
+## 边界
+
+- 自报目录取 `tempfile.gettempdir()`（同用户跨端一致），不依赖 MDCG_ROOT——
+  库根未设时也要能判「进程持哪代契约」。
+- 只报事实，不做裁决：`render_version` 由消费方与本仓 `codeindex.RENDER_VERSION`
+  比对（同源，不写死版本号，避免两处漂移）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+
+# 自报目录：同用户、跨端一致（DSH 与 CodeBuddy 的 python 子进程共用同一 tempdir）。
+SELF_REPORT_DIR = os.path.join(tempfile.gettempdir(), "md_cg_servers")
+# 自报格式代际：本模块自身结构变化时才 +1（与 codeindex.RENDER_VERSION 无关，
+# 后者描述「节点正文由哪代 render 产出」，属索引契约，两者不可混用）。
+SELF_REPORT_SCHEMA = 1
+
+
+# 生效条件：无入参；返回 (source_dir, render_version, source_file)——均取自 codeindex 模块**实际加载位置**（而非本文件所在包），故包被 __path__ 重定向后报的是真源；import 失败时三项均 None，不抛。
+def _source():
+    try:
+        from . import codeindex
+        return (os.path.dirname(os.path.abspath(codeindex.__file__)),
+                getattr(codeindex, "RENDER_VERSION", None),
+                os.path.abspath(codeindex.__file__))
+    except Exception:                     # noqa: BLE001 —— 自报失败降级为 None
+        return None, None, None
+
+
+# 生效条件：tag 为任意字符串（缺省空串）；返回本进程自报字典，键固定为 schema/pid/ppid/ts/iso/tag/cwd/argv/sys_path0/python/source_dir/source_file/render_version/mdcg_root_set/mdcg_token_set；任何取值失败均降级为 None 而不抛。
+def info(tag: str = "") -> dict:
+    """采集本进程事实（纯读取，不写盘）。"""
+    sd, rv, sf = _source()
+    try:
+        cwd = os.getcwd()
+    except Exception:                     # noqa: BLE001
+        cwd = None
+    try:
+        ppid = os.getppid()
+    except Exception:                     # noqa: BLE001
+        ppid = None
+    try:
+        sp0 = sys.path[0] if sys.path else None
+    except Exception:                     # noqa: BLE001
+        sp0 = None
+    now = time.time()
+    return {
+        "schema": SELF_REPORT_SCHEMA,
+        "pid": os.getpid(),
+        "ppid": ppid,
+        "ts": now,
+        "iso": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now)),
+        "tag": str(tag or ""),
+        "cwd": cwd,
+        "argv": list(sys.argv),
+        "sys_path0": sp0,
+        "python": "%d.%d.%d" % sys.version_info[:3],
+        # 只报「是否设置」，不落值——避免令牌/库根出现在可被他人读取的临时文件里。
+        "mdcg_root_set": bool(os.environ.get("MDCG_ROOT")),
+        "mdcg_token_set": bool(os.environ.get("MDCG_TOKEN")),
+        "source_dir": sd,
+        "source_file": sf,
+        "render_version": rv,
+    }
+
+
+# 生效条件：tag 为任意字符串；成功时把 info(tag) 原子写入 <tempdir>/md_cg_servers/<pid>.json（先写 .tmp 再 os.replace），并追加 self_report_path 键后返回该字典；任何异常（目录不可建/不可写/序列化失败）一律吞掉并返回 None——自报故障绝不向上传播。
+def report(tag: str = "mcp_server"):
+    """写自报文件（fail-safe：失败返回 None，不抛）。"""
+    try:
+        data = info(tag)
+        os.makedirs(SELF_REPORT_DIR, exist_ok=True)
+        path = os.path.join(SELF_REPORT_DIR, "%d.json" % data["pid"])
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, indent=2)
+        os.replace(tmp, path)
+        data["self_report_path"] = path
+        return data
+    except Exception:                     # noqa: BLE001
+        return None
+
+
+# 生效条件：无入参；返回 {pid(int): 自报字典}——读 SELF_REPORT_DIR 下全部 *.json，逐文件 json.loads 失败或 pid 键缺失/非整数者静默跳过（坏文件不使整体失败）；目录不存在时返回空字典。
+def read_all() -> dict:
+    """读全部自报（只读，无副作用）。"""
+    out = {}
+    try:
+        names = os.listdir(SELF_REPORT_DIR)
+    except OSError:
+        return out
+    for n in names:
+        if not n.endswith(".json"):
+            continue
+        try:
+            with open(os.path.join(SELF_REPORT_DIR, n), "r",
+                      encoding="utf-8", errors="replace") as fh:
+                d = json.load(fh)
+            pid = int(d.get("pid"))
+        except Exception:                 # noqa: BLE001
+            continue
+        out[pid] = d
+    return out
+
+
+# 生效条件：pids 为可迭代的 pid 集合（通常是「当前进程表中仍在的 md_cg 进程」）；删除自报目录中 pid 不在该集合内的 *.json 与遗留 *.tmp，返回删除条数；目录不存在或删除失败逐项吞掉，不抛。
+def purge(pids) -> int:
+    """清掉不属于「仍在的进程」的自报文件（防目录随重启次数膨胀）。"""
+    keep = {int(p) for p in (pids or ())}
+    n = 0
+    try:
+        names = os.listdir(SELF_REPORT_DIR)
+    except OSError:
+        return 0
+    for name in names:
+        try:
+            if name.endswith(".tmp"):
+                os.remove(os.path.join(SELF_REPORT_DIR, name))
+                n += 1
+                continue
+            if not name.endswith(".json"):
+                continue
+            if int(name[:-5]) in keep:
+                continue
+            os.remove(os.path.join(SELF_REPORT_DIR, name))
+            n += 1
+        except Exception:                 # noqa: BLE001
+            continue
+    return n

package/md_cg/semantic/canonical.py

@@ -32,6 +32,7 @@ WIN = 6          # 组合共现窗口（token 距离，探针实证口径）
 _ATOMS_ZH = None
 
 
+# 生效条件：模块级常量 `_ATOMS_ZH` 为 None 时按 `__file__` 所在目录的 atoms.json 取 `data.get("atoms", [])` 各项 `zh` 建集合并缓存，非 None 时直接返回 `_ATOMS_ZH`。
 def atoms_zh():
     """标准语义基准词表（atoms.json 的 zh 概念集，模块级缓存）。"""
     global _ATOMS_ZH
@@ -44,6 +45,7 @@ def atoms_zh():
     return _ATOMS_ZH
 
 
+# 生效条件：`text` 为 None 或空串时 `(text or "").split()` 得空序列、返回空列表 out；否则按空白切分后逐段经 `zh_en_atoms.segment` 展开 extend 进 out 并返回。
 def semantic_atoms(text):
     """semantic 字段容错切分：按空格分段逐段贪心匹配。
 
@@ -57,6 +59,7 @@ def semantic_atoms(text):
     return out
 
 
+# 生效条件：`text` 传入后，返回 `semantic_atoms(text)` 结果中不属于 `atoms_zh()` 词表集合的 token 列表（无匹配项时为空列表）。
 def oov_of(text):
     """OOV 审计：切分产物中不在标准词表的 token 列表（空列表=全部合法）。"""
     zh = atoms_zh()
@@ -64,6 +67,7 @@ def oov_of(text):
 
 
 @functools.lru_cache(maxsize=256)
+# 生效条件：t = text or ""（text 为 None/空串时按 ""），仅当 t 含 [A-Za-z] 时经 normalize_en_query 归一——含字母的 term 原样保留、其余经 zh_en_atoms.segment 展开——返回 tuple(out)；归一抛异常或 t 无字母时返回 tuple(semantic_atoms(t))；
 def query_atoms(text):
     """query 侧归一（同 semantic_atoms，缓存——每轮检索全 doc 复用）。
 
@@ -91,6 +95,7 @@ def query_atoms(text):
     return tuple(semantic_atoms(t))
 
 
+# 生效条件：`doc_semantic` 经 `semantic_atoms` 切分后相邻原子对集合 pairs 为空（单原子或无原子）时返回 0.0；否则以 `query_atoms(qtext)` 建立 token→位置表，统计两原子位置差绝对值 ≤ `win`（默认形参 WIN）的命中对数 hit，返回 hit/len(pairs)。
 def pair_hits(doc_semantic, qtext, win=WIN):
     """组合窗口共现命中率 ∈ [0,1]。