@furongjun1999/dsh-memory 0.9.12 → 0.9.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +21 -4
  2. package/codebuddy/CODEBUDDY.md +8 -3
  3. package/codebuddy/README.md +92 -92
  4. package/docs/discipline/templates/zcode-user.md.tmpl +52 -52
  5. package/docs//345/267/245/344/275/234/347/272/252/345/276/213_/350/256/244/347/237/245/345/233/276/346/235/241/347/233/256_v1.1.json +488 -461
  6. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203_/347/201/265/346/236/242/351/200/202/351/205/215.md +45 -45
  7. package/dsh/README.md +82 -82
  8. package/lib/hooks.d.ts +7 -1
  9. package/lib/hooks.js +62 -31
  10. package/lib/index.js +4 -1
  11. package/md_cg/config_registry_bulk.py +2 -0
  12. package/md_cg/config_validate.py +463 -461
  13. package/md_cg/conformance_core.py +28 -0
  14. package/md_cg/consistency.py +9 -2
  15. package/md_cg/mcp_server.py +91 -0
  16. package/md_cg/mdcg.py +162 -7
  17. package/md_cg/mdcos.py +53 -6
  18. package/md_cg/nodefile.py +39 -1
  19. package/md_cg/op_table.py +1 -0
  20. package/md_cg/relations.py +91 -0
  21. package/md_cg/scrub.py +20 -3
  22. package/md_cg/test_exact_text_cache.py +12 -4
  23. package/md_cg/test_issue218_postcondition_value_blind.py +4 -2
  24. package/md_cg/test_issue644_637_636.py +84 -0
  25. package/md_cg/test_issue650_658_f26.py +98 -0
  26. package/md_cg/test_issue659_r26_batch2.py +74 -0
  27. package/md_cg/test_issue665_scrub_process_records.py +59 -0
  28. package/md_cg/test_issue669_ccg_empty_colon.py +69 -0
  29. package/md_cg/test_issue672_validity_scope.py +47 -0
  30. package/md_cg/version_anchor.py +160 -0
  31. package/package.json +2 -2
  32. package/src/hooks.ts +64 -31
  33. package/src/index.ts +4 -1
  34. package/zcode/AGENTS.md +8 -3
  35. package/zcode/README.md +41 -41
@@ -425,6 +425,33 @@ def _steps():
425
425
  ok = out["i2_ok"] and out["i17_ok"]
426
426
  return (PASS if ok else FAIL), out
427
427
 
428
+ def s_inv_i18_anchor(ctx):
429
+ """I18:对外材料必须携带版本锚(理论/架构/投影 三元)。
430
+
431
+ 为什么归在 conformance 里:I17 说「任何投影不得自称权威」,而版本锚是
432
+ 读者回溯到「信息+条件空间+证据链」的唯一入口——缺锚的投影不可回溯。
433
+ 本步只验证**判定能力**(解析器行为),不校验真实文档路径
434
+ (fixture 在临时库上跑,不应依赖仓内文件)。
435
+ """
436
+ from . import version_anchor as va
437
+ ok_full = va.check_anchor(
438
+ "> **版本锚**:理论=智能论 3.4 | 架构=统一架构 v1.2 | 投影=样例 v1")
439
+ ok_yaml = va.check_anchor(
440
+ "version_anchor:\n theory: 智能论 3.4\n"
441
+ " architecture: 统一架构 v1.2\n projection: 样例 v1")
442
+ bad_missing = va.check_anchor("> **版本锚**:理论=智能论 3.4")
443
+ bad_absent = va.check_anchor("没有任何锚的文档")
444
+ out = {
445
+ "single_line_ok": ok_full[0],
446
+ "yaml_ok": ok_yaml[0],
447
+ "missing_field_rejected": bad_missing[0] is False,
448
+ "missing_fields": bad_missing[1]["missing"],
449
+ "absent_rejected": bad_absent[0] is False,
450
+ }
451
+ ok = (out["single_line_ok"] and out["yaml_ok"]
452
+ and out["missing_field_rejected"] and out["absent_rejected"])
453
+ return (PASS if ok else FAIL), out
454
+
428
455
  def s_inv_i8_trace(ctx):
429
456
  """I8:无 _evolution 记录即未发生——状态变更必须留痕。
430
457
 
@@ -653,6 +680,7 @@ def _steps():
653
680
  ("inv_write_trace", s_inv_write_trace),
654
681
  ("inv_zero_llm", s_inv_zero_llm),
655
682
  ("inv_i2_i17", s_inv_i2_i17),
683
+ ("inv_i18_anchor", s_inv_i18_anchor),
656
684
  ("inv_i8_trace", s_inv_i8_trace),
657
685
  ("inv_envelope_i1", s_inv_envelope_i1),
658
686
  ("gap_cs_not_indexed", s_gap_cs_not_indexed),
@@ -804,9 +804,16 @@ def check(cg, content, layer=None, condition_space=None,
804
804
 
805
805
  # ---- L1-a 自否定:自己的负条件排除自己的生效条件/正文 ----
806
806
  body = _body_text(content)
807
- if neg and (_ban_hit(" ".join(pos), neg) or _ban_hit(body, neg)):
807
+ _hit_pos = bool(neg) and _ban_hit(" ".join(pos), neg)
808
+ _hit_body = bool(neg) and _ban_hit(body, neg)
809
+ if _hit_pos or _hit_body:
810
+ # issue #669②:两个面压成同一句话会让作者看不出「到底哪一面命中」——
811
+ # 判据(type/score)不变(N238 契约:正文面命中仍是 self_negation 1.0),
812
+ # 只把命中面写进 detail,可诊断性提升不改变任何行为。
813
+ _face = ("生效条件面" if _hit_pos else "") + ("+正文面" if _hit_body else "")
808
814
  hard.append({"type": "self_negation", "with": None,
809
- "detail": "不适用条件命中自身生效条件/正文:条件自相矛盾",
815
+ "detail": "不适用条件命中自身%s:条件自相矛盾(命中面=%s)"
816
+ % ("生效条件/正文" if (_hit_pos and _hit_body) else "正文", _face),
810
817
  "score": 1.0})
811
818
  strength = 1.0
812
819
  elif neg and _cov(tw_neg, body) >= SELF_NEGATION:
@@ -129,7 +129,52 @@ def _s(_desc, **props):
129
129
  [k for k, v in props.items() if v.get("_req")]}
130
130
 
131
131
 
132
+ # 生效条件:把任意 MCP 入参收敛成布尔。bool 原样返回;数字 0/非 0 判假/真;
133
+ # 字符串按 true/1/yes/on 判真(大小写与空白不敏感),其余判假;None 判假。
134
+ def _as_flag(v):
135
+ if isinstance(v, bool):
136
+ return v
137
+ if v is None:
138
+ return False
139
+ if isinstance(v, (int, float)):
140
+ return v != 0
141
+ return str(v).strip().lower() in ("1", "true", "yes", "on")
142
+
143
+
132
144
  # 生效条件:始终返回 {"type":t,"description":desc},仅当 req 为真值时该字典额外含 "_req": True。
145
+ def drop_doc_nodes(items, id_of, enabled=False):
146
+ """过滤 doc_ 索引节点(会话日志切片)——**单一判据**,供所有可达路径共用。
147
+
148
+ issue #653:此前该过滤只活在 cg(op=read) 的非 budget 分支里:
149
+ · mdcg_recall / mdcg_search 直调库层,从不读该键(传了无效、无告警);
150
+ · cg(op=read) 的 budget_tokens 早退分支在过滤块之前 return(静默忽略);
151
+ · 唯一生效的 cg(op=read) 面其 inputSchema 未声明该参数。
152
+ 本函数把判据收成一处,调用方只负责传 enabled 与取 id 的方式。
153
+ """
154
+ # issue #659 F26-28:调用方可能传字符串(MCP 客户端不保证类型)——
155
+ # 旧实现直接 if enabled,字符串 "false" 是真值 → 反向开启过滤。
156
+ enabled = _as_flag(enabled)
157
+ if not enabled:
158
+ return list(items or []), 0
159
+ kept, dropped = [], 0
160
+ for it in items or []:
161
+ nid = str(id_of(it) or "")
162
+ if nid.startswith("doc_"):
163
+ dropped += 1
164
+ continue
165
+ kept.append(it)
166
+ return kept, dropped
167
+
168
+
169
+ def _note_doc_filter(meta, dropped, enabled):
170
+ """把过滤读数如实体现在 meta 上(不静默)。"""
171
+ if dropped and isinstance(meta, dict):
172
+ meta = dict(meta)
173
+ meta["excluded_doc"] = dropped
174
+ meta["exclude_doc"] = bool(enabled)
175
+ return meta
176
+
177
+
133
178
  def _p(t, desc, req=False, **extra):
134
179
  d = {"type": t, "description": desc}
135
180
  if req:
@@ -227,6 +272,9 @@ TOOLS = [
227
272
  semantic=_p("boolean", "启用第 6 路条件空间结构化匹配"
228
273
  "(白箱语义路:CCG 生效条件 + condition_space "
229
274
  "四槽,不适用条件命中即剔除;默认否)"),
275
+ exclude_doc=_p("boolean", "检索面排除 doc_ 索引节点(会话日志切片;"
276
+ "默认 false = 保持既有契约——test_p27_docindex ⑤ 断言"
277
+ "文档节点必须可被检索到;需要「只看真记忆卡」的调用方显式传 true)"),
230
278
  expand=_p("array", "LLM 查询侧扩展词:[{term,weight}] 或 [\"词\"];"
231
279
  "仅在查询时刻生效,索引侧仍白箱"),
232
280
  session=_p("string", "会话归属过滤(frontmatter.session;"
@@ -743,6 +791,9 @@ KERNEL_TOOLS = [
743
791
  "receipt(回执审计:命令与预期输出);"
744
792
  "非法值库层报错(fail-closed)"),
745
793
  budget_tokens=_p("integer", "read 的 token 预算"),
794
+ exclude_doc=_p("boolean", "检索面排除 doc_ 索引节点(会话日志切片;"
795
+ "默认 false = 保持既有契约——test_p27_docindex 断言"
796
+ "文档节点必须可被检索到;需要只看真记忆卡时显式传 true)"),
746
797
  excerpt_strategy=_p("string", "read 超预算条目摘录方式:prefix(默认)或 query(查询相关原文片段)"),
747
798
  bm25=_p("boolean", "read:显式使用 BM25 倒排评分(默认否)"),
748
799
  evidence=_p("string", "verify 的证据;state_event:出处(五元之一,"
@@ -2647,19 +2698,45 @@ def _cg_dispatch(cg, a):
2647
2698
  session=a.get("session"),
2648
2699
  validity=a.get("validity"),
2649
2700
  **({"paths": ("bm25",)} if a.get("bm25", True) and hasattr(cg, "search_rrf") else {}), **_tkw)
2701
+ # issue #653:budget 早退分支此前在过滤之前 return,exclude_doc 静默忽略。
2702
+ if isinstance(_out, dict):
2703
+ _pack2, _drop2 = drop_doc_nodes(
2704
+ _out.get("pack") or [], lambda it: (it or {}).get("id"),
2705
+ a.get("exclude_doc", False))
2706
+ if _drop2:
2707
+ _out = dict(_out)
2708
+ _out["pack"] = _pack2
2709
+ _out["meta"] = _note_doc_filter(_out.get("meta"), _drop2,
2710
+ a.get("exclude_doc", False))
2650
2711
  if _kwarn and isinstance(_out, dict):
2651
2712
  _out = dict(_out)
2652
2713
  _out["warning"] = _kwarn
2653
2714
  return _out
2654
2715
  from . import refindex
2716
+ # issue #659 F26-11:过滤发生在 k 截断**之后**,当 top-k 全被 doc_ 占满时
2717
+ # 结果直接空掉(配额被吃光)。开启过滤时按 k 的若干倍超取,过滤后再截回 k。
2718
+ _doc_filter_on = _as_flag(a.get("exclude_doc", False))
2655
2719
  search_args = dict(layer=a.get("layer"), k=_int_arg(a, "k", 20),
2656
2720
  context=a.get("context"), session=a.get("session"),
2657
2721
  validity=a.get("validity"), **_tkw)
2722
+ _k_want = search_args["k"]
2723
+ if _doc_filter_on:
2724
+ # 只在过滤开启时超取(过滤后再截回 _k_want,对外语义不变)
2725
+ search_args["k"] = min(max(_k_want * 4, _k_want + 32), 400)
2658
2726
  if a.get("bm25", True) and hasattr(cg, "search_rrf"):
2659
2727
  ranked, meta = cg.search_rrf(q, paths=("bm25",), **search_args)
2660
2728
  res = [(n, s, qual) for n, s, qual, _provenance in ranked]
2661
2729
  else:
2662
2730
  res, meta = cg.search(q, **search_args)
2731
+ # read 面过滤 doc_ 索引节点(2026-10-23 使用者批准):doc_ 为会话日志切片,
2732
+ # 与真记忆卡同分(0.016)且占 top5 的 60–80%,稀释可达性。默认 true,可显式关。
2733
+ # issue #653:判据收敛到 drop_doc_nodes(单一真源),不再就地手写第二条。
2734
+ res, _excluded_doc = drop_doc_nodes(
2735
+ res, lambda x: (x[0] or {}).get("id"), _doc_filter_on)
2736
+ # 截回调用方要的 k(超取只为让 doc_ 不占配额,不改变对外语义)
2737
+ if _doc_filter_on and len(res) > _k_want:
2738
+ res = res[:_k_want]
2739
+ meta = _note_doc_filter(meta, _excluded_doc, _doc_filter_on)
2663
2740
  _out = {"meta": meta, "results": [
2664
2741
  {"node": _node_view(n), "score": s, "state": q2.get("state"),
2665
2742
  "reason": q2.get("reason"), **refindex.ref_fields(n)}
@@ -4300,6 +4377,16 @@ def _dispatch(cg, name, args):
4300
4377
  _pack.setdefault("meta", {})["untrusted_excluded"] = _drop
4301
4378
  except Exception:
4302
4379
  pass
4380
+ # issue #653:recall 面此前完全不读 exclude_doc(schema 挂在它身上却不生效)。
4381
+ if isinstance(_pack, dict):
4382
+ _pk, _pk_drop = drop_doc_nodes(
4383
+ _pack.get("pack") or [], lambda it: (it or {}).get("id"),
4384
+ a.get("exclude_doc", False))
4385
+ if _pk_drop:
4386
+ _pack = dict(_pack)
4387
+ _pack["pack"] = _pk
4388
+ _pack["meta"] = _note_doc_filter(_pack.get("meta"), _pk_drop,
4389
+ a.get("exclude_doc", False))
4303
4390
  return _pack
4304
4391
 
4305
4392
  if name == "mdcg_search":
@@ -4368,6 +4455,10 @@ def _dispatch(cg, name, args):
4368
4455
  pools=a.get("pools"),
4369
4456
  session=a.get("session"),
4370
4457
  validity=a.get("validity"))
4458
+ # issue #653:search 面此前同样不读 exclude_doc(直调库层)。
4459
+ res, _sd_drop = drop_doc_nodes(
4460
+ res, lambda x: (x[0] or {}).get("id"), a.get("exclude_doc", False))
4461
+ meta = _note_doc_filter(meta, _sd_drop, a.get("exclude_doc", False))
4371
4462
  from . import conflict_surface
4372
4463
  _cf = conflict_surface.as_meta([n for n, _s, _q in res])
4373
4464
  if _cf:
package/md_cg/mdcg.py CHANGED
@@ -39,6 +39,23 @@ from .fsutil import (FileLock, ShardedLog, atomic_write, append_jsonl,
39
39
  # 单点守卫:写入 / 发出路径的 6 处调用点统一走 _ensure_list——str 按「一个值」
40
40
  # 处理(不再逐字符展开);None / 空串按空列表(与改动前逐位一致);其余可迭代
41
41
  # 仍 list(x)。
42
+ # 生效条件:把原始环境变量值解析成**有限浮点**门槛。缺省/空串返回 default;
43
+ # 非数值或 nan/inf 返回 default 且状态 invalid(调用方须如实记账,不得静默)。
44
+ # 为什么单独成单点:issue #659 F26-06 实测 MDCG_MIN_SCORE=inf 时 inf > 0 恒真,
45
+ # 全量结果被滤空;F26-12 又实测两处开关判据不一致(>0 与 >=0)。判据只写一次。
46
+ def parse_min_score(raw, default=0.0):
47
+ """→ (value, status),status 取 default / ok / invalid。"""
48
+ if raw is None or str(raw).strip() == "":
49
+ return float(default), "default"
50
+ try:
51
+ v = float(raw)
52
+ except (TypeError, ValueError):
53
+ return float(default), "invalid"
54
+ if v != v or v in (float("inf"), float("-inf")):
55
+ return float(default), "invalid"
56
+ return v, "ok"
57
+
58
+
42
59
  def _ensure_list(x):
43
60
  """归一成列表:任何假值(None/空串/0/False/[])-> [];str -> [str];其它可迭代 -> list(x)。"""
44
61
  if not x:
@@ -593,6 +610,51 @@ def _norm_word_mem(w: str) -> str:
593
610
  return r
594
611
 
595
612
  # 生效条件:给定 text(假值按 "" 处理),先清除非中文/空格/字母数字字符,再对长度 ≥2 的英文词小写、若在 EN_STOPWORDS 中剔除否则 strip_tense_en 去时态复数,压缩空白后返回;中文保持不变。
613
+ def fold_accents(text: str) -> str:
614
+ """检索面重音折叠单点(issue #636):NFKC → NFD 去组合记号 → NFC。
615
+
616
+ 为什么单独一个函数:本仓的 NFKC 单点是 routing.nfkc_text(#362),它**不剥离重音**——
617
+ café 与 cafe 因此互不可命中;而把折叠塞进 nfkc_text 会连带改掉负条件/边界摘词等
618
+ 判据面的语义(那是另一类判据,不该跟着变)。故新增这一个只服务检索归一化的单点,
619
+ 由 normalize_en 与 _like_body_lower 共用。
620
+
621
+ 形态边界(诚实声明):NFD 会把预合成 é 拆成 e+U+0301,去掉 Mn 后即 e;反向同样成立,
622
+ 所以「预合成正文 vs 组合查询」「组合正文 vs 无重音查询」都对称。
623
+ """
624
+ import unicodedata as _ud
625
+ s = routing.nfkc_text(text or "")
626
+ s = _ud.normalize("NFD", s)
627
+ s = "".join(ch for ch in s if not _ud.category(ch).startswith("Mn"))
628
+ return _ud.normalize("NFC", s)
629
+
630
+
631
+ def is_void_content(text) -> bool:
632
+ """「空白即无内容」的判据单点(#644 首版 + #651 扩展)。
633
+
634
+ #644 首版只剥 str.strip() 的 White_Space;#651 实测被三类不可见字符完整绕过:
635
+ · Cf(U+200B/U+200C/U+200D/U+FEFF/U+2060/U+00AD 等零宽/软连字符,isspace 全 False);
636
+ · 纯 Mn/Me 组合记号(U+0301 重复 n 次)——能落盘,但 fold_accents 折成空串,
637
+ 成为永不可检索的幽灵节点;
638
+ · Cc 控制符(x00-x1f 等)。
639
+
640
+ 判据:去掉「空白 + 控制符 + 格式符 + 组合记号 + 变体选择子」后若一个字符都不剩,即为无内容。
641
+ **不误伤**:NFD 正文(如 cafe + U+0301)里有字母残留 → 非空,照常写入。
642
+ """
643
+ import unicodedata as _ud
644
+ if not isinstance(text, str):
645
+ return True
646
+ for ch in text:
647
+ cat = _ud.category(ch)
648
+ if cat[0] in ("Z", "C"): # 分隔符 / 控制符 / 格式符 / 未分配 / 代理
649
+ continue
650
+ if cat in ("Mn", "Me"): # 组合记号:单独存在不构成内容
651
+ continue
652
+ if 0xFE00 <= ord(ch) <= 0xFE0F or 0xE0100 <= ord(ch) <= 0xE01EF:
653
+ continue # 变体选择子
654
+ return False
655
+ return True
656
+
657
+
596
658
  def normalize_en(text: str) -> str:
597
659
  """英文归一化:小写 + 去停用词 + 去时态复数。中文部分不动。
598
660
 
@@ -606,7 +668,7 @@ def normalize_en(text: str) -> str:
606
668
  # 拉丁/数字(ABC123,U+FF01–FF5E)整段清成空格 ⇒ 查询词直接消失,全角与半角双向不可命中。
607
669
  # 故先过 routing.nfkc_text(本仓 NFKC 唯一单点),再做字符类清理——一处改动同时覆盖
608
670
  # _like 召回 / _score 打分 / reach 前筛三条腿(它们都由本函数产出 bigram)。
609
- cleaned = re.sub(r'[^\u4e00-\u9fff a-zA-Z0-9]', ' ', routing.nfkc_text(text) or "")
671
+ cleaned = re.sub(r'[^\u4e00-\u9fff a-zA-Z0-9]', ' ', fold_accents(text))
610
672
  # 生效条件:m.group(0) 小写后交模块级 _norm_word_mem 查词级 memo(纯函数精确键控:命中返回缓存值,未命中按 EN_STOPWORDS 剔除/strip_tense_en 同口径计算并回填)——命中值≡逐词现算值,返回串接进归一结果;
611
673
  def _norm_word(m):
612
674
  return _norm_word_mem(m.group(0).lower())
@@ -773,7 +835,11 @@ def fold_for_match(text) -> str:
773
835
  「全角/大小写」处理,是因为那正是本仓反复出现的**同语义多落点判据分裂**
774
836
  (`routing.nfkc_text` 是 NFKC 的唯一单点,由守卫 E 组做源码面断言)。
775
837
  """
776
- return compact_exact_text(routing.fold_variants(text))
838
+ # issue #650:判据面此前只做 NFKC+casefold+繁简,不剥组合记号,
839
+ # 而召回面用的是 fold_accents(会剥)——两侧口径不一致时,
840
+ # 声明 non_applicable_conditions: ["cafe"] 的节点对查询 "cafe" 不会被 REJECT。
841
+ # 判据面与召回面必须同一口径,故这里补一次 Mn/Me 剥离(fold_accents 单点)。
842
+ return compact_exact_text(routing.fold_variants(fold_accents(text)))
777
843
 
778
844
 
779
845
  # 生效条件:text 与 term 均为 str 时,把 text 中所有「与 term 同形(去全部空白 + NFKC + casefold + 繁简折叠后相等)」的区间替换为空格并返回;term 归一后为空或未找到同形区间时原样返回。
@@ -1006,7 +1072,10 @@ def index_key_hits(entry, terms, query) -> dict:
1006
1072
  q = str(query or "")
1007
1073
  post = e.get(nodefile.POSTCONDITION_TERMS_KEY) or []
1008
1074
  if post:
1009
- if any(t in " ".join(post) for t in (terms or [])):
1075
+ # issue #652:索引键侧同样要折叠——terms 是 fold 后的查询词项,
1076
+ # post 是落盘原文;不同口径会让带重音的索引键对无重音查询不可命中。
1077
+ _post_folded = fold_accents(" ".join(str(x) for x in post))
1078
+ if any(t and fold_accents(t) in _post_folded for t in (terms or [])):
1010
1079
  hits["post"] = True
1011
1080
  hits["post_source"] = "term"
1012
1081
  hits["why"].append("postcondition_terms:term")
@@ -2849,6 +2918,33 @@ class MdCG:
2849
2918
  """
2850
2919
  if layer not in LAYERS:
2851
2920
  raise ValueError(f"未知层:{layer}(允许:{LAYERS})")
2921
+ # issue #644(2026-10-23):**空白即无内容**——与 state_events.is_void
2922
+ # (#383/#384 台账面的空白拒收单点)同一判据文化在记忆直写面的落点。
2923
+ # 此前 add(id, "") / add(id, " \n ") 会静默落成完整 .md 节点:库统计虚高、
2924
+ # consolidate/maintain 要处理无意义节点,且与台账面「空白被拒」自相矛盾。
2925
+ # 非字符串(int/list)此前抛内部 AttributeError('int' has no 'split')——
2926
+ # 那是实现泄漏而非校验,这里一并收成显式 ValueError(fail-closed,零落盘)。
2927
+ # issue #669 P1:**写入面前置守卫**——「带冒号空值 + 换行正文」这种形态,
2928
+ # 取值面(ccg_field_value 只看同一行)与剥除面(_strip_ccg_segments 见冒号
2929
+ # 算非空、只剥标题行)读法不一致,后续列表项残留进 body 后被自否定判据
2930
+ # 当断言命中,报成「条件自相矛盾」(实测 self_negation 1.0 假 REJECT)。
2931
+ # 闸门放行的形态判定面必须能吃;吃不了就在闸门挡,别让作者在判定面看假陈述。
2932
+ _bad_ccg = nodefile.ccg_empty_colon_before_body(content) if isinstance(content, str) else []
2933
+ if _bad_ccg:
2934
+ _where = ";".join("第 %d 行「# %s:」" % (ln, mark) for mark, ln in _bad_ccg)
2935
+ raise ValueError(
2936
+ "CCG 要素行冒号后为空、值写在后续行:%s——该形态会让取值面读到空串"
2937
+ "而剥除面只剥标题行,列表项残留进正文后被误判「条件自相矛盾」"
2938
+ "(issue #669)。两种修法任选:①写成单行(多项用「;」分隔),"
2939
+ "如「# 不适用条件:甲;乙」;②多项走 frontmatter 的 "
2940
+ "non_applicable_conditions 列表,CCG 行只留一句摘要。" % _where)
2941
+ if not isinstance(content, str) or is_void_content(content):
2942
+ raise ValueError(
2943
+ "content 不能为空:空白即无内容(issue #644)。"
2944
+ f"收到 {type(content).__name__}"
2945
+ + ("(纯空白/空串)" if isinstance(content, str) else "")
2946
+ + "——要表达「这里没有内容」请改用 layer=unresolved 的说明性正文,"
2947
+ "或不要写这个节点;空白节点会落成合法 .md 并虚高库统计。")
2852
2948
  # P0-1(批次 24,外部审查报告):node_id 是模型可控输入,直接拼
2853
2949
  # 文件路径——`..` 穿越出 root、Windows 绝对路径(C:/x)在
2854
2950
  # os.path.join 下直接丢弃前缀 = 任意 .md 覆盖。白名单先行
@@ -4303,7 +4399,9 @@ class MdCG:
4303
4399
  normalize_en 产出的词去 body 里找,而 body 若保留全角(ABC123),
4304
4400
  半角查询就永远找不到它。NFKC 单点同样只用 routing 那一份。
4305
4401
  """
4306
- return routing.nfkc_text(self._positive_body(entry, content)).lower()
4402
+ # issue #636:正文侧也要折叠重音,否则 normalize_en 产出的 cafe(无重音)
4403
+ # 永远找不到 café(预合成)正文。
4404
+ return fold_accents(self._positive_body(entry, content)).lower()
4307
4405
 
4308
4406
  def _doc_exact_text(self, entry, content):
4309
4407
  """Whitespace-free full content for the existing exact-hit tie break.
@@ -4604,6 +4702,8 @@ class MdCG:
4604
4702
  self._maybe_reload_index() # P1b-2:读面代际感知(空查询早退后、读索引前)
4605
4703
  pool_cfg = pooling.resolve(pooling.from_env(pools))
4606
4704
  now = time.time() if validity else None # 统一取一次 now,保判定口径一致
4705
+ # issue #672:口径落 stat,_emit 据此透出 meta.validity_scope(只排过期 / off)
4706
+ stat_validity_on = bool(validity)
4607
4707
 
4608
4708
  terms = expand_query_terms(q)
4609
4709
  # 英文归一化后再取 bigram(小写+去停用词+去时态;中文不动)
@@ -4746,10 +4846,15 @@ class MdCG:
4746
4846
  except (OSError, UnicodeDecodeError):
4747
4847
  continue
4748
4848
  # issue #150:空词项会使本判据恒真 ⇒ 全部负记忆都被算作「覆盖本查询」。
4749
- if any(t and t in content for t in terms):
4849
+ # issue #656(#636 回归):terms 是 fold 后的查询词项、content 是原始正文;
4850
+ # 两侧不同口径时 "cafe" in "café" 为假 ⇒ 带重音的负记忆覆盖判定失效
4851
+ # (covered_neg 空、_neg_tail 提示消失、S5 抑制不触发)。正文侧也折叠。
4852
+ _folded_content = fold_accents(content or "")
4853
+ if any(t and fold_accents(t) in _folded_content for t in terms):
4750
4854
  neg_coverage.append(e)
4751
4855
 
4752
- stat = {"scanned": 0, "query": q, "gates": gates}
4856
+ stat = {"scanned": 0, "query": q, "gates": gates,
4857
+ "validity_on": stat_validity_on} # issue #672:口径透出给 _emit
4753
4858
  if _tf_audit:
4754
4859
  stat["time_filter"] = _tf_audit
4755
4860
  route_bucket = None
@@ -5106,7 +5211,9 @@ class MdCG:
5106
5211
  body = (positive_body(entry, content) if positive_body is not None
5107
5212
  else nodefile.positive_body(content))
5108
5213
  body_l = body.lower()
5109
- tags_l = tags.lower()
5214
+ # issue #652(#636 回归):query 侧词项已过 fold_accents,tags 臂若仍裸 lower,
5215
+ # 带重音的 tag 对无重音查询永远不可召回。两臂必须同口径。
5216
+ tags_l = fold_accents(tags).lower()
5110
5217
  # issue #150:空词项恒真(`"" in s` → True)⇒ 必须滤掉;否则 LIKE 预筛恒真、
5111
5218
  # 全库入池。Rust `retrieval.rs::like` 同款(跨侧守卫钉住一致性)。
5112
5219
  return any(t and (t in body_l or t.lower() in tags_l) for t in terms)
@@ -5308,6 +5415,13 @@ class MdCG:
5308
5415
  """
5309
5416
  if self._zero_filler_only(tier, n_real):
5310
5417
  return 0
5418
+ # issue #637(2026-10-23):T3_global_scan 是「全量兜底、无词法闸」的出口——
5419
+ # 只要有一个折叠后 bigram 重合就会进候选,其中大量条目 score=0.0(零相关)。
5420
+ # 这些条目此前随 k 截断混入返回集,调用方(自动召回注入)无法区分
5421
+ # 「有相关记忆」与「库里有字就回」。T3 出口按**分数>0** 裁切:
5422
+ # 零分条目既不出现在结果里,也不再占用 k 配额。
5423
+ # 边界:只作用于 T3;T2 里被 S5 降到 0 的真候选、reach 图扩散邻居(#89② 收窄
5424
+ # 保护的两种形态)不受影响——它们是「有信号但被降权」,与 T3 的「本来就没信号」不同。
5311
5425
  return self._primary_slots(k, n_neg)
5312
5426
 
5313
5427
 
@@ -5401,8 +5515,36 @@ class MdCG:
5401
5515
  # 负覆盖信号**不失传**:仍从**既有**统计/审计面读到——meta["covered_neg"]
5402
5516
  # (全部被覆盖路径,恒在)与 stat["gates"]["s5"]["neg"](S5 门控开启时的
5403
5517
  # 计数位数)——两者皆非为本次修复新增,故不新增协议字段。
5518
+ # issue #637:**可配最低分门槛**(MDCG_MIN_SCORE,默认 0 = 关)。
5519
+ # 默认关的理由:T3 出口要保留 score=0 的「门控回退 / 异桶节点」
5520
+ # (test_retr_s1b / test_retr_s7 钉住的契约),默认裁切会打破它们。
5521
+ # 需要「只要相关结果」的部署设 MDCG_MIN_SCORE=0.01 即启用(零分条目
5522
+ # 既不进结果、也不占 k 配额)。位置在 _n_real/_neg_tail 之前 ⇒ 过滤后的
5523
+ # scored 自然参与 k 预算与提示让位,且 _neg_tail 仍只调用一次(D1 守卫)。
5524
+ # issue #659 F26-06/#F26-12:判据单点化——非有限值(nan/inf)不再被当成「门槛很高」
5525
+ # 把结果整体滤空,而是回落默认并如实记账(stat 落 min_score_input)。
5526
+ _min_score, _ms_status = parse_min_score(os.environ.get("MDCG_MIN_SCORE", "0"), 0.0)
5527
+ # issue #655:门槛**只作用于 T3 全量兜底出口**。T2 里被 S5 降到 0 的真候选、
5528
+ # reach 显式补入的图扩散邻居是「有信号但被降权 / 被显式补入」,与 T3 的
5529
+ # 「本来就没信号」不同——按 #89② 契约(S5 只降权不删除)不得被门槛删掉。
5530
+ if _min_score > 0 and tier == TIER_GLOBAL_SCAN:
5531
+ scored = [_p for _p in scored if _p[1] >= _min_score]
5532
+ stat["min_score"] = _min_score
5533
+ stat["min_score_scope"] = "T3_global_scan"
5534
+ elif _min_score > 0:
5535
+ stat["min_score_ignored_outside_t3"] = _min_score
5536
+ if _ms_status == "invalid":
5537
+ # 非法输入不静默:原始值原样记账,运行口径 = 默认(关)。
5538
+ stat["min_score_input"] = "invalid"
5404
5539
  _n_real = min(max(0, int(k)), sum(1 for _, s in scored if s > 0))
5405
5540
  _neg_tail = self._neg_tail(neg_coverage, max(0, int(k) - _n_real))
5541
+ # issue #659 F26-15:负覆盖尾在过滤**之后**才独立 extend,此前绕过门槛
5542
+ # (0.0 分提示条照进结果)。门槛生效时同一判据也要过一遍,并如实记账。
5543
+ if _min_score > 0 and _neg_tail:
5544
+ _kept_tail = [_t for _t in _neg_tail if float(_t[1] or 0) >= _min_score]
5545
+ if len(_kept_tail) != len(_neg_tail):
5546
+ stat["min_score_dropped_neg_tail"] = len(_neg_tail) - len(_kept_tail)
5547
+ _neg_tail = _kept_tail
5406
5548
  # issue #89②(2026-10-09 DSH 端实施、zcode 端收窄靶区):**0 分(无质量信号)
5407
5549
  # 条目不得装进结果**——它们对调用方无价值且有误导(LLM 会当成相关内容)。
5408
5550
  # 但与 `try_stage` 的 `valid` 同一口径的 `_n_real`(= min(k, sum(s>0)))**只服务
@@ -5543,6 +5685,19 @@ class MdCG:
5543
5685
  # 未启用则 meta 键集合与改动前逐字节一致(默认关零变更纪律)。
5544
5686
  if stat.get("time_filter"):
5545
5687
  meta["time_filter"] = stat["time_filter"]
5688
+ # issue #672:时效口径如实透出(只排过期 / 未启用),避免名字误读。
5689
+ meta["validity_scope"] = "expired_only" if stat.get("validity_on") else "off"
5690
+ # issue #659 F26-14:stat["min_score"] 此前写入后无人读(meta 是显式白名单)。
5691
+ # 门槛生效时把生效值、作用域、被丢弃数一并透出,调用方才能判断「为什么结果变少」。
5692
+ if stat.get("min_score") is not None:
5693
+ meta["min_score"] = stat["min_score"]
5694
+ meta["min_score_scope"] = stat.get("min_score_scope")
5695
+ if stat.get("min_score_ignored_outside_t3") is not None:
5696
+ meta["min_score_ignored_outside_t3"] = stat["min_score_ignored_outside_t3"]
5697
+ if stat.get("min_score_input") == "invalid":
5698
+ meta["min_score_input"] = "invalid"
5699
+ if stat.get("min_score_dropped_neg_tail"):
5700
+ meta["min_score_dropped_neg_tail"] = stat["min_score_dropped_neg_tail"]
5546
5701
  # issue #89①:次级排序键用毕即剥离——EXACT_HIT_KEY 是**内部键**,
5547
5702
  # 不得随 doc 引用透出。MCP 面(_node_view / 三处显式取键)本就是白名单,
5548
5703
  # 本步是第二道防线,也为将来新增的消费面兜底。
package/md_cg/mdcos.py CHANGED
@@ -27,7 +27,9 @@ import re
27
27
  import time
28
28
  import uuid
29
29
 
30
- from .mdcg import (MdCG, expand_query_terms, bigrams, normalize_en, STATE_ACCEPT,
30
+ from .mdcg import (MdCG, expand_query_terms, bigrams, normalize_en, fold_accents,
31
+ parse_min_score,
32
+ STATE_ACCEPT,
31
33
  STATE_REJECT, STATE_DEFER, STATE_BLINDSPOT, TIER_BUCKET_LIKE,
32
34
  TIER_BUCKET_SCAN, TIER_GLOBAL_LIKE, TIER_GLOBAL_SCAN,
33
35
  GLOBAL_CAP, expand_query_terms_weighted,
@@ -1289,7 +1291,9 @@ class MdCGOS(MdCG):
1289
1291
  if not fm:
1290
1292
  continue
1291
1293
  content = self._open_content(fm.get("id"), fm, content)
1292
- if content and any(t in content for t in terms):
1294
+ # issue #656:terms 已折叠、content 是原文;正文侧同样折叠才算同口径。
1295
+ if content and any(t and fold_accents(t) in fold_accents(content)
1296
+ for t in terms):
1293
1297
  out.append(e)
1294
1298
  return out
1295
1299
 
@@ -1354,7 +1358,8 @@ class MdCGOS(MdCG):
1354
1358
 
1355
1359
  返回 (results, meta),与 MdCG.search 完全同构(T0–T3 阶梯 + 资格判定)。
1356
1360
  pools:§七 召回分池(None=关闭原行为 / True=内置表 / dict=自定义表)。
1357
- validity:时效过滤(显式启用,缺省不过滤)——只排已过期,未生效保留;
1361
+ validity:时效过滤(显式启用,缺省不过滤)。**只排「已过期」,不排「未生效」**
1362
+ (名字容易读成「只给有效的」,实际是「别看已过期的」,见 issue #672);
1358
1363
  view:角色化读取视图(第四阶段 6.1,显式启用,缺省 None 零变更);
1359
1364
  详见 _candidates。
1360
1365
  """
@@ -1386,7 +1391,9 @@ class MdCGOS(MdCG):
1386
1391
  # 否则大小写断裂 → 词法分恒 0 → LIKE 层失效(p33 ⑤ 回归根因);
1387
1392
  # + 英→中语素 bigram 补充(与 mdcg.search/_lexical 打分口径同步)
1388
1393
  qb = bigrams(normalize_en(q)) | en_zh_bigrams(q)
1389
- stat = {"scanned": 0, "query": q}
1394
+ # issue #672:时效口径透出——父类 _emit 据 stat["validity_on"] 落
1395
+ # meta.validity_scope(只排过期 / off),避免 validity 名字被读成「只给有效的」。
1396
+ stat = {"scanned": 0, "query": q, "validity_on": bool(validity)}
1390
1397
  # 时间算子审计(阶段二 4.1):候选层过滤在 `_candidates` 已完成,此处把
1391
1398
  # 审计块交给父类 `_emit` 落进 meta —— 与 search_rrf 的 `stat["time_filter"]`
1392
1399
  # 同构。缺此步则过滤**确实生效但审计不可见**:调用方无法区分「未启用过滤」
@@ -2164,7 +2171,8 @@ class MdCGOS(MdCG):
2164
2171
  REJECT / BLINDSPOT 剔除,DEFER 降权 ×0.5,ACCEPT 保位。候选池取
2165
2172
  fused 前 max(k*2,10) 再裁决补位。语义联系可以是认知噪声(等权 RRF
2166
2173
  双重奖励「多路都靠前」的干扰项),唯有条件证据可授予优先级。
2167
- validity: 时效过滤(显式启用,缺省不过滤)。**只排已过期**,未生效
2174
+ validity: 时效过滤(显式启用,缺省不过滤)。**只排「已过期」,不排「未生效」**——
2175
+ 名字读作「只给有效的」会误解,实际是「别看已过期的」(issue #672);未生效
2168
2176
  (valid_from 未到)保留——两者语义相反(scrub 纪律「valid_from 绝不
2169
2177
  并入 _EXPIRY_KEYS」)。详见 _candidates。
2170
2178
  start_time/end_time/start_operator/end_operator/time_axis:时间算子
@@ -2487,6 +2495,25 @@ class MdCGOS(MdCG):
2487
2495
  boundary_counts = {"hit": 0, "terms": 0,
2488
2496
  "counts": {"accept": 0, "reject": 0, "defer": 0,
2489
2497
  "blindspot": 0}}
2498
+ # issue #654:MDCG_MIN_SCORE 此前只活在 MdCG._emit 内,而默认读路径
2499
+ # (cg(op=read) 默认 bm25=True → search_rrf)**从不经过 _emit**,开关静默失效。
2500
+ # 这里按同一环境变量、同一语义在融合面补一刀:过滤发生在资格判定之前,
2501
+ # 被滤掉的不参与 boundary_counts(否则统计会把已丢弃条目算成命中)。
2502
+ # issue #659 F26-06/F26-12:与 mdcg._emit 共用同一解析单点(nan/inf 不再把结果滤空)。
2503
+ _rrf_min, _rrf_status = parse_min_score(os.environ.get("MDCG_MIN_SCORE", "0"), 0.0)
2504
+ _rrf_dropped = 0
2505
+ if _rrf_status == "invalid":
2506
+ _rrf_note = {"min_score_input": "invalid"}
2507
+ else:
2508
+ _rrf_note = None
2509
+ if _rrf_min > 0:
2510
+ _kept = []
2511
+ for _nid, _fs in fused:
2512
+ if float(_fs) >= _rrf_min:
2513
+ _kept.append((_nid, _fs))
2514
+ else:
2515
+ _rrf_dropped += 1
2516
+ fused = _kept
2490
2517
  for nid, fs in fused:
2491
2518
  node, s = node_by_id[nid]
2492
2519
  if quals.get(nid):
@@ -2593,7 +2620,16 @@ class MdCGOS(MdCG):
2593
2620
  k=k, layer=layer,
2594
2621
  session=session, branch=branch, validity=validity,
2595
2622
  view=view, extra=_cache_extra, clock_window=_query_window)
2596
- return results, {"tier": "RRF", "scanned": stat["scanned"],
2623
+ if _rrf_dropped:
2624
+ stat["min_score"] = _rrf_min
2625
+ # issue #672:把生效的时效口径如实透出——调用方看名字容易以为「只给有效的」,
2626
+ # 读 meta 一眼可辨(只排过期 / 未启用)。
2627
+ _validity_meta = ({"validity_scope": "expired_only"} if validity
2628
+ else {"validity_scope": "off"})
2629
+ return results, {"tier": "RRF", "scanned": stat["scanned"], **_validity_meta,
2630
+ **({"min_score": _rrf_min, "min_score_dropped": _rrf_dropped}
2631
+ if _rrf_min > 0 else {}),
2632
+ **(_rrf_note or {}),
2597
2633
  "paths": per_path, "fused": len(results),
2598
2634
  "judge_ranking": bool(judge and judge_ranking),
2599
2635
  "judge_filtered": filtered,
@@ -2715,6 +2751,17 @@ class MdCGOS(MdCG):
2715
2751
  skipped.append({"id": node["id"], "tokens": t,
2716
2752
  "reason": "oversize_or_over_budget"})
2717
2753
  continue # 关闭截断或预算不足:跳过,继续尝试更小的
2754
+ # issue #637:**召回面可配最低分**(MDCG_RECALL_MIN_SCORE,默认 -1 = 关)。
2755
+ # 默认关的理由:test_validity_filter ⑤⑦ 依赖 RRF 旁系低分条目可见;
2756
+ # 需要「只装相关记忆」的部署设 0.01 即启用(零分条目连同 reason 记账跳过)。
2757
+ # issue #659 F26-12:此处原为 >=0、另一处为 >0,两处开关判据相反
2758
+ # (=0 时一处关、一处开;-0.0 >= 0 为真会开闸)。统一成 >0 一个判据,
2759
+ # 且解析走同一单点(nan/inf 回落默认 -1 = 关)。
2760
+ _rmin, _rmin_status = parse_min_score(os.environ.get("MDCG_RECALL_MIN_SCORE", "-1"), -1.0)
2761
+ if _rmin > 0 and score < _rmin:
2762
+ skipped.append({"id": node["id"], "tokens": t,
2763
+ "reason": "below_min_score", "score": score})
2764
+ continue
2718
2765
  used += t
2719
2766
  # Only summarize already available qualification/frontmatter data;
2720
2767
  # query suitability and persistent verification are distinct states.
package/md_cg/nodefile.py CHANGED
@@ -251,6 +251,44 @@ def is_dep_sentinel(value) -> bool:
251
251
  return False
252
252
 
253
253
 
254
+
255
+ # 生效条件:content 中某 CCG 要素行写成「带冒号但冒号后为空」(如 '# 不适用条件:'),
256
+ # 且其后到下一个标题之间**存在非空非标题行**时,返回 [(要素名, 行号), ...];否则 []。
257
+ def ccg_empty_colon_before_body(content):
258
+ """检测「带冒号空值 + 换行正文」形态(issue #669 P1 前置守卫)。
259
+
260
+ 为什么这是坏形态:判定面的两个函数对它的读法**不一致**——
261
+ · 取值面 ccg_field_value 严格取冒号后同一行 ⇒ 得空串,**不看下一行**;
262
+ · 剥除面 _strip_ccg_segments 见 rest.strip() 非空(冒号算非空)⇒ 只剥标题行。
263
+ 于是后续列表项全部残留进 body,被 _ban_hit(body, neg) 当断言命中,
264
+ 报成「条件自相矛盾」(实测 self_negation 1.0)。闸门放行的形态判定面吃不了,
265
+ 就该在闸门挡——本判据即那道闸。
266
+
267
+ 不是「换行即坏」:裸标题(# 不适用条件,无冒号)+ 单行值两个面读法一致,合法。
268
+ """
269
+ lines = (content or "").split("\n")
270
+ bad = []
271
+ for i, ln in enumerate(lines):
272
+ hit = None
273
+ for mark in CCG_MARKS:
274
+ rest = _ccg_heading_rest(ln, mark)
275
+ if rest is None:
276
+ continue
277
+ if rest.strip() in (":", ":"):
278
+ hit = mark
279
+ break
280
+ if not hit:
281
+ continue
282
+ for nxt in lines[i + 1:]:
283
+ t = nxt.strip()
284
+ if not t:
285
+ continue
286
+ if t.startswith("#"):
287
+ break
288
+ bad.append((hit, i + 1))
289
+ break
290
+ return bad
291
+
254
292
  # 生效条件:content 中不存在形如 `# <field_name>` 的标题行 → 返回 None;存在 → 返回该行的值(行内冒号之后的 strip 结果;无冒号则取标题后首个非空非标题行),可为空串;
255
293
  def ccg_field_value(content, field_name: str):
256
294
  """读取 `# <字段>` 的值(首个命中行;全/半角冒号兼容)。无该行 → None。
@@ -922,4 +960,4 @@ def ccg_element_terms(content: str, field_name: str,
922
960
  叠加**切分**,绝不自己 `re.match(r"^#\\s*验证方式")` ——那会立刻长出第二套
923
961
  行语义(`ccg_mark_present` 的取单点动因即此类分叉)。
924
962
  """
925
- return element_terms_from_text(ccg_field_value(content, field_name), min_len)
963
+ return element_terms_from_text(ccg_field_value(content, field_name), min_len)
package/md_cg/op_table.py CHANGED
@@ -55,6 +55,7 @@ _OP_TABLE = {
55
55
  "offset",
56
56
  "view",
57
57
  "budget_tokens",
58
+ "exclude_doc",
58
59
  "excerpt_strategy",
59
60
  "bm25",
60
61
  "session",