@furongjun1999/dsh-memory 0.4.7 → 0.4.9

package/md_cg/consistency.py

@@ -3,7 +3,7 @@
 
 理论出处（本仓原文，非外部知识）：
 
-  · **情绪 = 信息差的二阶变化 d²D/dt²**（`docs/智能的公理化基石.md` §十一，:412-510）
+  · **情绪 = 信息差的二阶变化 d²D/dt²**（`docs/theory/智能的公理化基石.md` §十一，:412-510）
     工程端对应 `emotional_bias`（approaching / avoiding / stable），并且原文明确：
     「情绪通道**独立、不参与信任计算**」。故本模块 L0 只做**流程调度**，
     绝不改动 confidence / 资格判定——避免把情绪混进事实判断。
@@ -81,9 +81,11 @@ DISCIPLINE_TAGS = ("discipline", "纪律", "work_discipline", "rule", "规则",
 VERDICTS = ("ACCEPT", "REJECT", "DEFER", "BLINDSPOT")
 
 
+# 生效条件：以 verdict 与 reason 构造异常（消息 `[{verdict}] {reason}`），conflicts 传假值（None/空容器等，源码 `conflicts or []`）时 self.conflicts 为 []，传真值时原样保留；
 class ConsistencyError(Exception):
     """硬冲突：写入被拒（自否定 / 违反纪律）。"""
 
+# 生效条件：verdict 与 reason 必传并赋给同名属性、拼成异常消息 `[{verdict}] {reason}`；conflicts 为假值（None/空容器等，源码 `conflicts or []`）时 self.conflicts 回落到 []，为真值时原样保留；
     def __init__(self, verdict, reason, conflicts=None):
         self.verdict = verdict
         self.reason = reason
@@ -95,6 +97,7 @@ class ConsistencyError(Exception):
 # 原语：延迟导入 mdcos（避免 mdcg ← mdcos ← consistency 的循环导入）
 # --------------------------------------------------------------------------
 
+# 生效条件：无 required 形参，任一调用返回 ( _ccg_field, _declared_conditions, _neg_hit, _weighted_coverage ) 四元组；
 def _prims():
     """取 md_cg 已有的条件匹配原语（条件论「反题」的既有实现）。"""
     from .mdcos import (_ccg_field, _declared_conditions, _neg_hit,
@@ -102,6 +105,7 @@ def _prims():
     return _ccg_field, _declared_conditions, _neg_hit, _weighted_coverage
 
 
+# 生效条件：xs 为可迭代对象时，逐项 str(x).strip() 后仅当结果非空且未出现过才加入 out 并返回 out；xs 为 None/False/0 时在 for 处迭代失败（TypeError）；
 def _dedup(xs):
     out = []
     for x in xs:
@@ -111,6 +115,7 @@ def _dedup(xs):
     return out
 
 
+# 生效条件：fm 给出时，遍历 fm.get("edges")（缺键或假值按空列表）中元素，dict 元素按 to→target→node→id 取首个真值、非 dict 元素直接作候选，候选真值时 str(t) 加入 out 并返回；
 def _edge_targets(fm):
     """节点声明的出边目标（兼容 dict / str 两种形态）。"""
     out = []
@@ -124,6 +129,7 @@ def _edge_targets(fm):
     return out
 
 
+# 生效条件：fm 与 node_id 给出时，若 fm.get("tags")（缺键/假值按空）小写后与 DISCIPLINE_TAGS 有交集，或 str(node_id) 以 "discipline_" 或 "work_discipline" 开头，返回 True；否则返回 False；
 def _is_discipline(fm, node_id):
     tags = {str(t).lower() for t in (fm.get("tags") or [])}
     if tags & set(DISCIPLINE_TAGS):
@@ -139,6 +145,7 @@ def _is_discipline(fm, node_id):
 SEPARATION_REL = "distinct_from"
 
 
+# 生效条件：fm 给出时，仅处理 fm.get("edges")（缺键/假值按空）中的 dict 元素，relation_type 或 relation（缺省空串）小写等于 SEPARATION_REL 时，按 target→to→id 取首个真值且未重复则加入 out；
 def separation_targets(fm):
     """节点已声明的分离对象（`distinct_from` 出边），用于幂等与去重。"""
     out = []
@@ -154,6 +161,7 @@ def separation_targets(fm):
     return out
 
 
+# 生效条件：fm 与 content 给出时，以 content（假值按空串）、fm.get("condition_space")、fm.get("non_applicable_conditions") 解析，返回去重后的 (set(pos), set(neg))；
 def condition_terms(fm, content):
     """节点声明的（正条件, 负条件）词面集合——分离判定与重构取线索共用。"""
     pos, neg = _new_terms(content or "", fm.get("condition_space"),
@@ -161,6 +169,7 @@ def condition_terms(fm, content):
     return set(pos), set(neg)
 
 
+# 生效条件：pos_a、neg_a、pos_b、neg_b 给出的条件词面小写化后，两侧并集均空时返回 overlap 0.0、distinct False；否则计算交集/并集比并返回 distinct 为 overlap <= CLASH_LOW；
 def condition_distinct(pos_a, neg_a, pos_b, neg_b):
     """两组条件是否「实质不同」：任一侧条件词面几乎不重合即为不同情境。
 
@@ -177,6 +186,7 @@ def condition_distinct(pos_a, neg_a, pos_b, neg_b):
     return {"overlap": round(overlap, 4), "distinct": overlap <= CLASH_LOW}
 
 
+# 生效条件：content、condition_space、non_applicable_conditions 给出时，content 的 `生效条件` 字段与 condition_space 中键不以 `__` 开头且不为 `time_window` 的值并入 pos（list/tuple/set 展平，其他非 None/"" 值 str 化），non_applicable_conditions 各项及 content 的 `不适用条件` 字段值并入 neg，最后 _dedup 返回；
 def _new_terms(content, condition_space, non_applicable_conditions):
     """新节点声明的（正条件, 负条件）——与既有节点同口径解析。"""
     _ccg_field, _declared, _neg_hit, _cov = _prims()
@@ -198,6 +208,7 @@ def _new_terms(content, condition_space, non_applicable_conditions):
     return _dedup(pos), _dedup(neg)
 
 
+# 生效条件：content 与 neg_texts 给出时，neg_texts 中任一短语去掉「不得/禁止/严禁/不能/不可/不要/勿」前缀且长度 >=2 后作为子串出现在 content（假值按空串）中则返回 True，否则 False；
 def _ban_hit(content, neg_texts):
     """纪律禁令命中：去掉「不得/禁止/…」前缀后，短语是否**整体出现**在正文中。
 
@@ -215,6 +226,7 @@ def _ban_hit(content, neg_texts):
     return False
 
 
+# 生效条件：content 为真时按行过滤，跳过 strip 后以 "#" 开头且含全角或半角冒号的行，其余原行以换行连接返回；content 假值按空串返回 ""；
 def _body_text(content):
     """去掉 CCG 声明行（`# 字段：值`）后的正文。
 
@@ -231,6 +243,7 @@ def _body_text(content):
     return "\n".join(out)
 
 
+# 生效条件：content 给出时（假值按空串）解析 CCG 的 `# 功能名` 与 `# 子功能` 字段并返回两者；
 def _slot_text(content):
     """结论槽：CCG 声明的 `# 功能名` / `# 子功能`（结构字段，非正文词面）。
 
@@ -250,6 +263,7 @@ def _slot_text(content):
 # L0 情绪通道（信息差二阶变化）
 # --------------------------------------------------------------------------
 
+# 生效条件：conflict_strength 被夹取到 [0,1]（假值按 0.0），prev_strength 为 None 时 d2=0.0，否则 d2=c-夹取后的 prev_strength；按 c>=EMO_AVOID 或 d2>0.2 返回 avoiding，或 c<=EMO_APPROACH 且 d2<=0 返回 approaching，否则 stable；
 def emotional_bias(conflict_strength, prev_strength=None):
     """L0：把冲突强度映射为情绪倾向（approaching / stable / avoiding）。
 
@@ -279,6 +293,7 @@ def emotional_bias(conflict_strength, prev_strength=None):
             "note": "情绪通道独立，不参与信任/资格计算（智能论 §十一）"}
 
 
+# 生效条件：cg 给出时，若 cg.root 下 LOG_FILE 可读，则逐行解析 JSON 并取 .get("conflict_strength")，返回最后一条可解析记录的该键值（缺键或值为 None 则为 None）；路径不可用或 OSError 返回 None；
 def _last_strength(cg):
     """上一条留痕的冲突强度（二阶差分的基线）。流式读，不载全量。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -304,6 +319,7 @@ def _last_strength(cg):
 # L2 递归反思（受深度 / 节点数 / 循环 / 增益门槛约束）
 # --------------------------------------------------------------------------
 
+# 生效条件：以 cg 节点图、seeds 中非空项为初始 frontier、tw_pos/tw_neg 词权，在 d=1..int(max_depth) 每轮先判 frontier 空返回 frontier_exhausted，再逐 nid 处理时若 nodes_visited > max_nodes 先返回 node_budget（可先于同层 discriminators），否则处理完该层后有 discriminators（非 seed_set 节点声明条件与 tw_pos/tw_neg 覆盖 >= CLASH_HIGH）返回 resolved，否则 last_gain < min_gain 返回 gain_below_threshold，循环耗尽返回 depth_exceeded；seeds 假值时 frontier 空，在 d=1 进入循环后由首判返回 frontier_exhausted（depth=0）；
 def _recursive_reflect(cg, seeds, tw_pos, tw_neg, max_depth=MAX_DEPTH,
                        max_nodes=MAX_NODES, min_gain=MIN_GAIN):
     """递归反思：沿关系链找「区分条件」，每层检查信息增益。
@@ -366,6 +382,7 @@ def _recursive_reflect(cg, seeds, tw_pos, tw_neg, max_depth=MAX_DEPTH,
 # 主入口：三级决策
 # --------------------------------------------------------------------------
 
+# 生效条件：以 cg.index.nodes 为既有节点、content（假值按 ""）经 _new_terms 得 pos/neg 并算 tw_pos/tw_neg，按循环中 hard（自否定或纪律命中）→ divergences（同条件槽且 concl < CONCLUSION_SAME）→ strength ≥ CLASH_HIGH → strength ≥ CLASH_LOW → comparable==0 且 (pos or neg) → 否则 ACCEPT 的顺序定 verdict；DEFER 且 int(depth)>0 且 emo["bias"] != "approaching" 时调 _recursive_reflect 补 recursion，auto_flywheel 且 verdict∈{REJECT,DEFER,BLINDSPOT} 时加 unresolved_id，最后 log 并返回 rec；
 def check(cg, content, layer=None, condition_space=None,
           non_applicable_conditions=None, tags=None, exclude=None,
           limit=MAX_SCAN, depth=MAX_DEPTH, auto_flywheel=False,
@@ -554,6 +571,7 @@ def check(cg, content, layer=None, condition_space=None,
     return rec
 
 
+# 生效条件：missing 为假值（None/空容器/空串）返回 ""；否则逐项仅取 m.get("need") 真值者，格式化为 `need（why）`（why 缺键用 ""，值为 None 则格式化 "None"），以 "；" 连接；
 def _missing_text(missing):
     """结构化缺口 → 一行文本（作为飞轮的 known_clues）。
 
@@ -567,6 +585,7 @@ def _missing_text(missing):
                     for m in missing if m.get("need"))
 
 
+# 生效条件：cg 提供可调用 flywheel_step 时，以 query（假值按空串）前 200 字符、verdict、missing 文本（空则 reason）、conflicts 非 None 则作 detail 否则 missing 调用；结果 dict 的 unresolved_id 真值时返回它，否则回落 id；无 flywheel_step 或异常返回 None；
 def _fire_flywheel(cg, query, verdict, reason, missing, conflicts=None):
     """把冲突作为「误差」投给知识飞轮，返回 unresolved 条目 id（失败不阻塞写入）。
 
@@ -592,6 +611,7 @@ def _fire_flywheel(cg, query, verdict, reason, missing, conflicts=None):
 # 留痕 / 统计 / 自描述
 # --------------------------------------------------------------------------
 
+# 生效条件：cg 与 rec 给出时，将 rec 序列化为 JSON 行追加到 cg.root 下 LOG_FILE，OSError 被吞掉，返回 rec；
 def log(cg, rec):
     """append-only 留痕：每条判定可审计。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -603,6 +623,7 @@ def log(cg, rec):
     return rec
 
 
+# 生效条件：cg 给出时，若 cg.root 下 LOG_FILE 可读，则逐行解析 JSON（空行/解析失败跳过）；limit 真值时返回 out[-int(limit):][::-1]（int(limit)=0 时为全部倒序），limit 为假值（0/None/""）时返回 out[::-1]；路径不可用或 OSError 返回 []；
 def history(cg, limit=100):
     """最近冲突判定留痕（倒序）。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -624,6 +645,7 @@ def history(cg, limit=100):
     return out[-int(limit):][::-1] if limit else out[::-1]
 
 
+# 生效条件：逐行 json.loads 计数（不可解析行跳过、OSError 忽略、路径缺失则计数为 0），每行 total 加 1 并按 r.get("verdict")（缺键即 None 键）与 emotional.bias 为真值时的 b 累加，返回 {'records','by_verdict','by_bias','max_scan','max_depth','min_gain'}，后三者取模块常量 MAX_SCAN/MAX_DEPTH/MIN_GAIN；
 def summary(cg):
     """冲突面汇总（流式计数，供 health 审计）。"""
     p = os.path.join(cg.root, LOG_FILE)
@@ -652,6 +674,7 @@ def summary(cg):
             "min_gain": MIN_GAIN}
 
 
+# 生效条件：无 required 形参，调用即返回引用 EMO_AVOID/EMO_APPROACH、VERDICTS、CLASH_HIGH/CLASH_LOW、SAME_COND_HIGH/SLOT_HIGH/CONCLUSION_SAME、MAX_DEPTH/MAX_NODES/MIN_GAIN 等模块级常量的自描述字典；
 def catalog():
     """自描述：三级决策 + 四态 + 递归约束（供 MCP / 文档对照验证）。"""
     return {
@@ -692,4 +715,4 @@ def catalog():
         "discipline_detection": {"tags": list(DISCIPLINE_TAGS),
                                  "id_prefixes": ["discipline_", "work_discipline"]},
         "honest_boundary": "条件级（结构化）冲突检测，非语义蕴含证明；无法比对时 BLINDSPOT",
-    }
+    }

package/md_cg/consolidate.py

@@ -111,6 +111,7 @@ _CCG_LINE_RE = re.compile(
     r"^\s*#\s*(功能名|生效条件|子功能|执行|验证方式|不适用条件)\s*[:：]")
 
 
+# 生效条件：给定 content，返回剔除所有匹配 _CCG_LINE_RE 的行后以换行连接的非声明正文；content 为 None 时按空串处理。
 def body_text(content: str) -> str:
     """剥掉 CCG 声明行后的正文——验证只认正文，不认已写下的声明。"""
     return "\n".join(l for l in (content or "").split("\n")
@@ -171,6 +172,7 @@ VERIFY_PROMPT = (
 
 # ---- LLM 侧（黑箱只在离线工序，产出候选）--------------------------------
 
+# 生效条件：给定 role，按显式参数、角色环境变量、通用兜底依次解析并返回 (model, base, key)；key 不落 DEEPSEEK_API_KEY 除非 role 为 REFLECT_ROLE。
 def role_config(role: str, model: str = None, base: str = None,
                 key: str = None) -> tuple:
     """解析某角色的 (model, base, key)：显式参数 > 角色环境变量 > 通用兜底。
@@ -197,6 +199,7 @@ def role_config(role: str, model: str = None, base: str = None,
     return model, base, key
 
 
+# 生效条件：给定 prompt 且 role 解析或通用兜底得到非空 key 时，向 base 的 /chat/completions 发 POST 并返回首个 choice 的 message.content；key 为空则抛 RuntimeError。
 def http_llm(prompt: str, model: str = None, base: str = None, key: str = None,
              role: str = None, timeout: int = 120, max_tokens: int = 1200) -> str:
     """标准库 HTTP 调 LLM（OpenAI 兼容 /chat/completions）。零第三方依赖。
@@ -234,6 +237,7 @@ def http_llm(prompt: str, model: str = None, base: str = None, key: str = None,
     return data["choices"][0]["message"]["content"]
 
 
+# 生效条件：给定 role，若 role_config 得到非空 key 则 GET base/models 并返回含 ok/model_available/models 的字典；无 key 或请求异常则返回 ok=False 及错误信息。
 def probe_models(role: str, timeout: int = 20) -> dict:
     """零 token 探测：列出该角色网关的可用模型 id（GET /models）。"""
     model, base, key = role_config(role)
@@ -258,6 +262,7 @@ def probe_models(role: str, timeout: int = 20) -> dict:
     return res
 
 
+# 生效条件：raw 为 None 或 strip 后不含 "{"（i<0）、或末个 "}" 的位置 j<=i 时返回 None；否则对 s 从首个 "{" 到末个 "}" 的切片 json.loads，成功则返回解析结果，抛 ValueError 时返回 None。
 def _extract_json_obj(raw: str):
     """从 LLM 输出里抠出第一个 JSON 对象（容忍代码围栏 / 前后废话）。"""
     s = (raw or "").strip()
@@ -270,6 +275,7 @@ def _extract_json_obj(raw: str):
         return None
 
 
+# 生效条件：v 为 None 返回 []；否则按 v 是 str 取 [v]、是 list/tuple 取逐项、其他取 [str(v)]，逐项 strip 并去两端包裹标点后跳过空串及长度超 MAX_TERM_LEN 的项，未出现过的才 append，每次 append 后若 len(out) >= limit 即 break 返回 out（故 limit<=0 且存在有效项时仍返回 1 项）。
 def _as_terms(v, limit: int = MAX_TERMS):
     """把 LLM 给的值规范成去重、限长的短语列表。"""
     if v is None:
@@ -292,6 +298,7 @@ def _as_terms(v, limit: int = MAX_TERMS):
     return out
 
 
+# 生效条件：给定 raw，若 _extract_json_obj 解析出 dict，则按 CCG_FIELDS 与 FIELD_ALIASES 提取非空字段并规范为列表或单值返回字典；否则返回 {}。
 def parse_candidate(raw: str) -> dict:
     """LLM 原始输出 → {字段: 列表/字符串}；解析失败返回 {}。"""
     obj = _extract_json_obj(raw)
@@ -317,6 +324,7 @@ def parse_candidate(raw: str) -> dict:
     return out
 
 
+# 生效条件：给定 raw，若解析出 dict，则按 CCG_FIELDS 提取 keep/drop/has_keep/reason 结构返回字典；否则返回 {}。
 def parse_verdict(raw: str) -> dict:
     """验证单元输出 → {字段: {keep, drop, has_keep, reason}}；解析失败返回 {}。"""
     obj = _extract_json_obj(raw)
@@ -342,6 +350,7 @@ def parse_verdict(raw: str) -> dict:
     return out
 
 
+# 生效条件：给定 kept 与 verdict，若 verdict 为空则返回 (dict(kept), {})；否则按 drop 与 has_keep 收窄候选并返回 (收窄后候选, 被剔除明细)。
 def narrow_by_verdict(kept: dict, verdict: dict):
     """按验证单元裁决收窄候选——**只能否决，不能新增**。
 
@@ -377,6 +386,7 @@ def narrow_by_verdict(kept: dict, verdict: dict):
 
 # ---- 确定性验证（零 LLM）-------------------------------------------------
 
+# 生效条件：给定 term 与 body，若 term 的 bigram 序列非空则返回命中 bigram 数除以总 bigram 数，否则返回 0.0。
 def grounding_score(term: str, body: str) -> float:
     """候选短语在正文里的字符级支撑度 = 命中 bigram 数 / 总 bigram 数。"""
     bg = bigrams(term or "")
@@ -386,6 +396,7 @@ def grounding_score(term: str, body: str) -> float:
     return hit / len(bg)
 
 
+# 生效条件：给定 cand 与 body，按 thresholds 更新 DEFAULT_GROUNDING 后逐字段过滤候选，返回 (达标 kept, detail)；不达标者丢弃。
 def grounding_filter(cand: dict, body: str, thresholds: dict = None):
     """逐字段过滤候选：返回 (kept, detail)。不达标者丢弃（对应「不猜测」）。"""
     th = dict(DEFAULT_GROUNDING)
@@ -405,6 +416,7 @@ def grounding_filter(cand: dict, body: str, thresholds: dict = None):
     return kept, detail
 
 
+# 生效条件：给定 pos_terms、neg_terms、body，返回含 pos_recall、neg_separated、no_conflict、ok 的回放判定字典。
 def replay_check(pos_terms, neg_terms, body: str) -> dict:
     """回放生产判定：正例召回 + 负例剔除 + 无自相矛盾。
 
@@ -438,10 +450,12 @@ def replay_check(pos_terms, neg_terms, body: str) -> dict:
 
 # ---- 写盘（固化）---------------------------------------------------------
 
+# 生效条件：给定 content 与 field，当 content 含 "# field：" 或 "# field:" 时返回 True，否则 False。
 def _has_ccg_line(content: str, field: str) -> bool:
     return f"# {field}：" in (content or "") or f"# {field}:" in (content or "")
 
 
+# 生效条件：给定 fm 与 content，对每个 CCG_FIELDS，若 frontmatter.comment 值非空或正文含对应 CCG 行则记入，返回已有字段字典。
 def existing_fields(fm: dict, content: str) -> dict:
     """节点当前已有的四要素：正文 CCG 行 或 frontmatter.comment 任一存在即算有。"""
     comment = (fm.get("state_attributes") or {}).get("comment") or {}
@@ -455,6 +469,7 @@ def existing_fields(fm: dict, content: str) -> dict:
     return out
 
 
+# 生效条件：给定 content、field、value，若已有 "# field：" 行则替换并返回新正文；否则插在 "# 功能名" 之后，若无则该行前置。
 def _upsert_ccg_line(content: str, field: str, value: str) -> str:
     """在正文里写入/替换 `# <字段>：<值>`，优先插在「# 功能名」之后。"""
     lines = (content or "").split("\n")
@@ -474,12 +489,14 @@ def _upsert_ccg_line(content: str, field: str, value: str) -> str:
     return newline + "\n" + (content or "")
 
 
+# 生效条件：给定 kept 字段字典，返回一句话规律字符串，列出缺失字段名并声明补齐后可路由。
 def _evo_pattern(kept: dict) -> str:
     """规律（一句话）：这一类节点反复缺的正是这批条件。"""
     names = "、".join(kept.keys())
     return f"缺「{names}」的节点条件不可判；补齐后四要素完整、可路由"
 
 
+# 生效条件：给定 prov 字典，拼接 reflect/verify 模型、grounding、replay、verification_basis 中存在的证据项并返回。
 def _evo_evidence(prov: dict) -> str:
     """证据：本次固化凭什么成立（模型 / 闸门 / 回放）。"""
     parts = []
@@ -499,6 +516,7 @@ def _evo_evidence(prov: dict) -> str:
     return " · ".join(parts)
 
 
+# 生效条件：给定 cg、e、fm、content、kept、prov，将 kept 字段写入正文 CCG 行与 frontmatter.comment，不适用条件同步 non_applicable_conditions，并写 llm_consolidation 与演化记录，返回 None。
 def _apply_node(cg, e, fm: dict, content: str, kept: dict, prov: dict,
                 basis: str = "", basis_enum: str = BASIS_ENUM_DEFAULT):
     """把通过验证的字段固化进 md：正文 CCG 行 + frontmatter.comment + 负条件 + provenance。
@@ -543,6 +561,7 @@ def _apply_node(cg, e, fm: dict, content: str, kept: dict, prov: dict,
         before=before, after=evolution.state_of(cg, nid) or {})
 
 
+# 生效条件：给定 root，扫描正排层节点并执行反思→白箱闸门→验证→固化，返回报表 rep；require_verify=True 且无 verify_fn 时全部 DEFER。
 def consolidate(root: str, layer: str = None, limit: int = None, apply: bool = False,
                 overwrite: bool = False, llm_fn=None, reflect_fn=None,
                 verify_fn=None, reflect_model: str = "", verify_model: str = "",
@@ -569,6 +588,7 @@ def consolidate(root: str, layer: str = None, limit: int = None, apply: bool = F
            "per_field": {f: 0 for f in CCG_FIELDS}, "verify_dropped": 0,
            "verification_basis_missing": 0, "samples": []}
 
+# 生效条件：以 reason 为键写入闭包 rep["reasons"]，计数按 rep["reasons"].get(reason, 0) + 1 递增（键缺失从 0 起算），无返回值。
     def _bump(reason):
         rep["reasons"][reason] = rep["reasons"].get(reason, 0) + 1
 
@@ -695,6 +715,7 @@ def consolidate(root: str, layer: str = None, limit: int = None, apply: bool = F
     return rep
 
 
+# 生效条件：给定 root 与 basis，对缺 "# 验证方式" 行的节点补写验证方式并在需要时写入 basis_enum，返回统计 rep。
 def fill_verification_basis(root: str, basis: str, layer: str = None,
                             limit: int = None, apply: bool = False,
                             basis_enum: str = BASIS_ENUM_DEFAULT) -> dict:
@@ -755,6 +776,7 @@ MAINTAIN_LOG = "_maintain.jsonl"
 CCG_REQUIRED = ("生效条件", "子功能", "执行", "不适用条件")
 
 
+# 生效条件：给定 cg、nid、e、fm、content、target_layer，把节点写入目标层（必要时按 routing 分桶）并删除旧路径，返回新相对路径与 bucket。
 def _relocate_layer(cg, nid, e, fm, content, target_layer):
     """把节点正文迁到目标层的正确目录（含分桶），删除旧文件。返回新相对路径。"""
     d = os.path.join(cg.root, target_layer)
@@ -773,6 +795,7 @@ def _relocate_layer(cg, nid, e, fm, content, target_layer):
             "bucket": bucket}
 
 
+# 生效条件：给定 root，把 source_layer 中命中次数不小于 min_merge 或 importance 不小于 min_importance 且条件完整的节点提升到 target_layer，返回统计 rep。
 def promote_memories(root, source_layer="contextual", target_layer="knowledge",
                      min_merge=2, min_importance=0.6, require_conditions=True,
                      limit=None, apply=False, actor="maintain") -> dict:
@@ -844,6 +867,7 @@ def promote_memories(root, source_layer="contextual", target_layer="knowledge",
     return rep
 
 
+# 生效条件：给定 root，按 _maintain.jsonl 中 action=promote 记录（可再按 node_ids/batch 过滤）把节点迁回原层，成功返回 ok=True/reverted/ids，无记录返回 ok=False/error=no_records。
 def rollback_promotion(root, node_ids=None, batch=None, actor="maintain") -> dict:
     """回滚情境提升：把 promoted_from 层迁回，并记一条演化条目。"""
     cg = MdCGOS(root)
@@ -902,11 +926,13 @@ def rollback_promotion(root, node_ids=None, batch=None, actor="maintain") -> dic
 CONTEXTUALIZE_REASON_DEFAULT = "情境性内容归位（批次流水账 / 感知产物）"
 
 
+# 生效条件：给定 e，返回 e.id 字符串，若缺 id 则回落到 basename(e.path) 去掉 .md。
 def _entry_id(e) -> str:
     """索引条目取 id：优先 `id` 字段，回落到文件名（索引不保证带 id）。"""
     return str(e.get("id") or os.path.basename(e.get("path") or "")[:-3])
 
 
+# 生效条件：给定 root 与 base，若 base 不在维护日志已用批次中则返回 base，否则返回 base.n 且 n 为最小未用序号。
 def _unique_batch(root, base) -> str:
     """批次号去重：**同一秒内的两次调用不得共用批次号**。
 
@@ -921,6 +947,7 @@ def _unique_batch(root, base) -> str:
     return f"{base}.{n}"
 
 
+# 生效条件：给定 root 且 prefixes 或 node_ids 至少一个非空，把 source_layer 中匹配的节点迁到 target_layer，返回统计 rep；两者皆空则抛 ValueError。
 def contextualize_prefixes(root, prefixes=None, node_ids=None,
                            source_layer="knowledge", target_layer="contextual",
                            reason="", limit=None, apply=False,
@@ -938,6 +965,7 @@ def contextualize_prefixes(root, prefixes=None, node_ids=None,
                          "（如 ['note_','imgpart_']），拒绝对整层无差别改写")
     cg = MdCGOS(root)
 
+# 生效条件：e 经 _entry_id 得到 nid 后，若闭包 ids 不为 None 则返回 nid in ids 的真假，若 ids 为 None 则返回 nid.startswith(pref) 的真假。
     def _hit(e) -> bool:
         nid = _entry_id(e)
         return nid in ids if ids is not None else nid.startswith(pref)
@@ -999,6 +1027,7 @@ def contextualize_prefixes(root, prefixes=None, node_ids=None,
     return rep
 
 
+# 生效条件：给定 root，按 _maintain.jsonl 中 action=contextualize 记录（可再按 node_ids/batch 过滤）把节点迁回原层，成功返回 ok=True/reverted/ids，无记录返回 ok=False/error=no_records。
 def rollback_contextualize(root, node_ids=None, batch=None, actor="maintain") -> dict:
     """回滚层归位：按 `_maintain.jsonl` 的 contextualize 记录把节点迁回原层。"""
     cg = MdCGOS(root)
@@ -1040,6 +1069,7 @@ def rollback_contextualize(root, node_ids=None, batch=None, actor="maintain") ->
     return {"ok": True, "reverted": reverted, "ids": ids}
 
 
+# 生效条件：对 _read_maintain(root) 中 action 为 "contextualize" 或 "contextualize_rollback" 的记录，取 recs[-(int(limit) or 50):] 作为 records 返回 {'ok': True, ...}——仅当 int(limit) 成功且为 0 时回落 50，limit 为 None/""/[] 等无法 int() 的值会先抛 TypeError/ValueError。
 def contextualize_history(root, limit=50):
     """层归位的批次记录（只读）。"""
     recs = [r for r in _read_maintain(root)
@@ -1047,6 +1077,7 @@ def contextualize_history(root, limit=50):
     return {"ok": True, "records": recs[-(int(limit) or 50):]}
 
 
+# 生效条件：给定 root，读取 root 下 MAINTAIN_LOG 的 JSONL 并返回记录列表。
 def _read_maintain(root):
     from .fsutil import read_jsonl
     return list(read_jsonl(os.path.join(root, MAINTAIN_LOG)))
@@ -1076,10 +1107,15 @@ CONCEPT_MEMBER_REL = "instance_of"   # member → concept（inferred）
 CONCEPT_PREFIX = "concept_"
 CONCEPT_IMPORTANCE = 0.5
 CONCEPT_TAGS = ("concept", "induced")
+# 巩固留痕字段（2026-09-19 阶段一）：**字段名真源在 md_cg/nodefile.py**，
+# 本处只做短别名引用（非复制），与 `nodefile.VALID_FROM_FIELD` 的登记纪律同构。
+CONSOLIDATED_AT_FIELD = nodefile.CONSOLIDATED_AT_FIELD
+CONSOLIDATED_INTO_FIELD = nodefile.CONSOLIDATED_INTO_FIELD
 # 归纳候选排除：受保护节点，以及洞察/场景/前馈/概念等派生物（避免自我进食）
 INDUCE_SKIP_TAGS = ("insight", "scene", "reconstructed", "gap_hint", "concept")
 
 
+# 生效条件：给定 members，返回 CONCEPT_PREFIX 拼接排序后成员串的 SHA1 前 10 位。
 def _concept_id(members):
     """概念节点 id：由成员清单派生，保证「同成员 ⇒ 同 id」的幂等性。"""
     h = hashlib.sha1("|".join(sorted(str(m) for m in members))
@@ -1087,12 +1123,14 @@ def _concept_id(members):
     return CONCEPT_PREFIX + h[:10]
 
 
+# 生效条件：给定 a 与 b，若任一为空集则返回 0.0，否则返回交集大小除以并集大小。
 def _jaccard(a, b):
     if not a or not b:
         return 0.0
     return len(a & b) / float(len(a | b))
 
 
+# 生效条件：给定 term_sets，返回出现次数不小于 max(2, ceil(min_share * len(term_sets))) 的词面排序列表；空输入返回 []。
 def _common_terms(term_sets, min_share=0.6):
     """出现在 ≥ min_share 比例成员中的词面（共同条件）；少于 2 个成员共享不算。"""
     if not term_sets:
@@ -1105,6 +1143,7 @@ def _common_terms(term_sets, min_share=0.6):
     return sorted(t for t, c in cnt.items() if c >= need)
 
 
+# 生效条件：给定 term_sets，按集合排序去重拼接后返回前 limit（默认 INDUCE_MAX_TERMS）个词面。
 def _union_terms(term_sets, limit=INDUCE_MAX_TERMS):
     seen = []
     for s in term_sets:
@@ -1114,6 +1153,7 @@ def _union_terms(term_sets, limit=INDUCE_MAX_TERMS):
     return seen[:limit]
 
 
+# 生效条件：给定 cg、cid、members、reason、actor、batch，为概念节点与成员节点写对称 inferred 边（已存在则跳过），返回含 concept 与 members 的字典。
 def _link_concept(cg, cid, members, reason, actor, batch):
     """写概念↔成员对称 inferred 边（幂等：已存在则不重复写）。"""
     nodes = (getattr(cg, "index", None) or {}).get("nodes") or {}
@@ -1150,6 +1190,12 @@ def _link_concept(cg, cid, members, reason, actor, batch):
                       "reason": reason, "created_at": time.time(),
                       "confidence": 0.5, "verified": 0, "evidence": "inferred"})
         fm["edges"] = edges
+        # 巩固留痕（2026-09-19 阶段一）：`consolidated_into` 为**规范名**，
+        # `induced_concept` 保留为历史别名（既有读取面零破坏）；`consolidated_at`
+        # 补齐**成员侧**巩固时刻——此前只有概念侧 `induced_at`，成员侧无从判定
+        # 「何时被并进去」，故「合并后前身可定位」只在概念侧半成立。
+        fm[CONSOLIDATED_INTO_FIELD] = cid
+        fm[CONSOLIDATED_AT_FIELD] = time.time()
         fm["induced_concept"] = cid
         ent = nodes.get(m) or {}
         cg._write_node(m, os.path.join(cg.root, ent.get("path") or f"{m}.md"),
@@ -1160,6 +1206,7 @@ def _link_concept(cg, cid, members, reason, actor, batch):
     return out
 
 
+# 生效条件：给定 members、common_pos、neg_union，返回标注 inferred 的概念节点正文，含功能名、生效条件、子功能、执行、验证方式、不适用条件。
 def _concept_payload(members, common_pos, neg_union):
     """概念节点正文：把成员的共性条件抽象为可追溯的知识条目（显式标注 inferred）。"""
     label = "、".join(common_pos[:INDUCE_MAX_TERMS])
@@ -1176,6 +1223,7 @@ def _concept_payload(members, common_pos, neg_union):
     )
 
 
+# 生效条件：给定 cg_or_root，从 source_layer 聚类归纳为 target_layer 概念节点，apply=True 才写盘并返回统计 rep。
 def induce_memories(cg_or_root, source_layer="contextual", target_layer="knowledge",
                     min_cluster=INDUCE_MIN_CLUSTER, min_jaccard=INDUCE_MIN_JACCARD,
                     max_nodes=INDUCE_MAX_NODES, require_conditions=True,
@@ -1271,9 +1319,11 @@ def induce_memories(cg_or_root, source_layer="contextual", target_layer="knowled
             continue
         content = _concept_payload(p["members"], p["common_conditions"],
                                    p["non_applicable"])
+        _consolidated_at = time.time()   # 概念形成时刻 = 巩固时刻（单一取值，禁两处取时）
         cg.add(cid, content, layer=target_layer, tags=list(CONCEPT_TAGS),
                importance=CONCEPT_IMPORTANCE, verification_basis="other",
-               induced_from=list(p["members"]), induced_at=time.time(),
+               induced_from=list(p["members"]), induced_at=_consolidated_at,
+               consolidated_at=_consolidated_at,
                induction={"method": "bigram_jaccard", "min_jaccard": float(min_jaccard),
                           "common_conditions": p["common_conditions"], "batch": batch,
                           "actor": actor, "evidence": "inferred"},
@@ -1294,6 +1344,7 @@ def induce_memories(cg_or_root, source_layer="contextual", target_layer="knowled
 
 # ---- CLI ----------------------------------------------------------------
 
+# 生效条件：不适用（无必需形参与模块级常量）
 def _cli(argv=None) -> int:
     ap = argparse.ArgumentParser(
         description="md_cg 离线固化：反思单元(LLM)产出候选 → 白箱闸门 → "
@@ -1386,4 +1437,4 @@ def _cli(argv=None) -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(_cli())
+    raise SystemExit(_cli())

package/md_cg/corpus.py

@@ -40,6 +40,7 @@ MARKS = ("# 功能名：", "# 生效条件：", "# 子功能：", "# 执行：",
 EXPECTED_NODES = sum(len(points) for _dom, points in DOMAINS) * len(ASPECTS)
 
 
+# 生效条件：给定 dom、point、aspect 且 marks 取默认 True（真值）时，返回带「# 功能名/生效条件/子功能/执行/验证方式/不适用条件」MARKS 行的完整正文；marks 为假值时返回不含 MARKS 行、仅叙述「{point} 是 {dom} 领域的知识点」的正文。
 def body(dom, point, aspect, marks=True):
     """节点正文。marks=True 给完整 CCG 五要素，否则给纯叙述正文（无 MARKS 行）。"""
     if marks:
@@ -56,10 +57,12 @@ def body(dom, point, aspect, marks=True):
             "常用于条件化检索与召回对照。\n")
 
 
+# 生效条件：给定 di、pi、ai 时返回 f-string 拼成的字符串 `kp_{di:02d}_{pi:02d}_{ai}`（di 与 pi 之间由下划线分隔，di、pi 两位补零后接 ai）。
 def node_id(di, pi, ai):
     return f"kp_{di:02d}_{pi:02d}_{ai}"
 
 
+# 生效条件：给定 cg 及默认 marks=True、layer="knowledge"、verification_basis="data" 时，按模块级 DOMAINS 与 ASPECTS 逐组合调用 cg.add（节点 id 取自 node_id，importance=0.4+0.1*ai，tags 为 domain:{dom}，condition_space 含 observation_position/observation_tool/existence_constraint），每写一个 n 加一，最后 cg.flush() 并返回 n。
 def seed(cg, marks=True, layer="knowledge", verification_basis="data"):
     """把整套语料写进 cg，返回写入节点数。幂等：节点 id 固定（同 id 原子覆盖）。"""
     n = 0
@@ -81,10 +84,11 @@ def seed(cg, marks=True, layer="knowledge", verification_basis="data"):
     return n
 
 
+# 生效条件：给定 root 且 clean 为真、os.path.isdir(root) 成立时先 shutil.rmtree(root)，随后无论 clean 取值都以 exist_ok=True 调用 os.makedirs(root)。
 def reset_root(root, clean=False):
     """确保测试根存在：保证「重跑 ≡ 首跑」，且上一轮残留节点不会被当成先验。
 
-    默认**不删目录**（对齐本仓已裁决的设计，见 docs/认知图_MD目录方案_v0.1.md
+    默认**不删目录**（对齐本仓已裁决的设计，见 docs/mdcg/认知图_MD目录方案_v0.1.md
     「幂等性：迁移按 node id 原子覆盖写，可反复执行，**不需要先清空目录**」）：
     `seed()` 用固定 node id 原子覆盖，同一套语料重跑落在同一批文件上，集合封闭。