@furongjun1999/dsh-memory 0.4.8 → 0.4.10

package/md_cg/mreview/pipeline.py

@@ -79,6 +79,7 @@ SYSTEM_PROMPT = """你是记忆评审流水线中的【验证单元】。
 
 # ---- 级 4-A · spec 构造 ---------------------------------------------------
 
+# 生效条件：exe 为真值时返回 str(exe)，否则 HIVE_EXE 经 (os.environ.get("HIVE_EXE") or "").strip() 后非空则返回该值，否则按 os.name 返回 os.path.join(_ROOT, "hive", "target", "release", "hive.exe" 或 "hive")；
 def hive_exe(exe=None) -> str:
     """蜂巢可执行文件：显式参数 > HIVE_EXE > 仓内 release 构建。"""
     if exe:
@@ -90,10 +91,12 @@ def hive_exe(exe=None) -> str:
     return os.path.join(_ROOT, "hive", "target", "release", name)
 
 
+# 生效条件：name 为假值（None/""/0/False 等）时以 "pkg" 为输入，否则 str(name)，结果经 re.sub(r"[^0-9A-Za-z_.\-]", "_", ...) 替换并截取前 120 字符；
 def _safe(name) -> str:
     return re.sub(r"[^0-9A-Za-z_.\-]", "_", str(name or "pkg"))[:120]
 
 
+# 生效条件：path 与 obj 给定后，若 os.path.dirname(path) 非空则 os.makedirs 该目录，随后以 UTF-8、ensure_ascii=False、indent=2 将 obj 写入 path 并返回 path；
 def _dump_json(path: str, obj) -> str:
     d = os.path.dirname(path)
     if d:
@@ -109,6 +112,7 @@ _ENTRY_KEYS = ("ref", "node_id", "proposal_id", "origin", "layer", "tags", "role
                "excerpt")
 
 
+# 生效条件：pkg/asm/workdir 给定，base 取 _safe(pkg.get("bundle_id"))（bundle_id 假值→"pkg"），entries 取 pkg.get("entries") or [] 的前 int(entry_limit) 项且仅保留 _ENTRY_KEYS，写出 workdir/base.bundle.json 与 workdir/base.rules.json（asm 原样），返回这两个 join(workdir,...) 路径（workdir 相对时不保证绝对）；
 def dump_context(pkg: dict, asm: dict, workdir: str, *, entry_limit=64) -> list:
     """包 + 规则装配 → context 文件（**绝对路径**，工人执行期内有效）。
 
@@ -128,6 +132,7 @@ def dump_context(pkg: dict, asm: dict, workdir: str, *, entry_limit=64) -> list:
     return [bp, rp]
 
 
+# 生效条件：pkg/asm 给定，节点清单标题恒输出、节点项取 pkg.get("entries") or []；机械命中取 asm.get("mechanical") or []，非空列前 int(max_mech) 条否则输出「无」，llm 取 asm.get("llm") or [] 非空列前 40 条；返回 join(L)；
 def build_prompt(pkg: dict, asm: dict, *, max_mech=120) -> str:
     """user_prompt：节点清单 + 机械命中 + 待检问题 + 输出要求。"""
     ents = pkg.get("entries") or []
@@ -167,6 +172,7 @@ def build_prompt(pkg: dict, asm: dict, *, max_mech=120) -> str:
     return "\n".join(L)
 
 
+# 生效条件：pkg/asm 给定，model 按 model or os.environ.get('HIVE_MODEL') or DEFAULT_MODEL 取值（空串/假值均回落），context_files 按 list(context_files or [])，timeout_s 转 int、temperature 转 float、max_tokens 转 int，node_ids 取 pkg.entries 中 node_id 真值的 str，返回含 meta 的 spec 字典；
 def build_spec(pkg: dict, asm: dict, *, context_files=None, model=None,
                timeout_s=600, temperature=0.0, max_tokens=4096) -> dict:
     """(pkg, asm) → hive spec（文件协议的可投递单元）。"""
@@ -186,6 +192,7 @@ def build_spec(pkg: dict, asm: dict, *, context_files=None, model=None,
                      "size": pkg.get("size"), "node_ids": nids}}
 
 
+# 生效条件：当模块级常量 CD.SOURCES 可用时，sources 为假值则回落 CD.SOURCES，调用 CD.generate 生成候选，再经 BD.bundle(c.get('candidates') or [], nodes, root, max_per_bundle) 与 RS.assemble_all(b, rules_dir) 组装，最终将 bundles 与 packages 按 zip 配对返回。
 def build_packages(*, root=None, sources=None, limit=None, nodes=None,
                    max_per_bundle=50, rules_dir=None, now=None) -> dict:
     """级 1-3 串联：候选 → 捆包 → 规则装配，产出配对的 (pkg, asm) 列表。"""
@@ -202,6 +209,7 @@ def build_packages(*, root=None, sources=None, limit=None, nodes=None,
 
 # ---- 级 4-B · 投递 / 收卷 -------------------------------------------------
 
+# 生效条件：argv 给定，环境变量副本强制 PYTHONUTF8="1"，env 真值时用其 str 值更新，随后 subprocess.run(argv, capture_output=True, text=True, encoding="utf-8", errors="replace", env=e, timeout=timeout, cwd=cwd, input=stdin_text, shell=False)；
 def _run(argv, *, env=None, timeout=120, cwd=None, stdin_text=None):
     """统一子进程入口：argv 列表 + 显式 UTF-8 + PYTHONUTF8=1，不经 shell（第15条）。"""
     e = dict(os.environ)
@@ -213,6 +221,7 @@ def _run(argv, *, env=None, timeout=120, cwd=None, stdin_text=None):
                           input=stdin_text, shell=False)
 
 
+# 生效条件：text 为假值时 (text or "").strip().splitlines() 为空、循环不执行并返回 None；否则从末尾行向前找以 "{" 开头且 json.loads 成功且 isinstance(obj, dict) 的行返回该 dict，未找到返回 None；
 def _last_json(text: str):
     """stdout 逐行解析取最后一个 JSON 对象（容忍前导日志行）。"""
     for line in reversed((text or "").strip().splitlines()):
@@ -228,6 +237,7 @@ def _last_json(text: str):
     return None
 
 
+# 生效条件：exe/jobs_dir/spec 给定，创建 jobs_dir 并在临时目录写 spec.json 后执行 [exe,"submit","--spec",sp,"--jobs",jobs_dir]；returncode 非 0 返回 ok False + error，否则 _last_json(p.stdout) 为假（含 None/空 dict）返回 ok False「submit 输出非 JSON」，否则 d.setdefault("ok", True) 后返回 d；
 def submit(exe: str, jobs_dir: str, spec: dict, *, timeout=120) -> dict:
     """投递单包 spec → {"ok":True,"job_id":...}；失败返回 ok=False + error。"""
     os.makedirs(jobs_dir, exist_ok=True)
@@ -245,11 +255,13 @@ def submit(exe: str, jobs_dir: str, spec: dict, *, timeout=120) -> dict:
     return d
 
 
+# 生效条件：specs 为可迭代列表时逐项调用 submit(exe, jobs_dir, s, timeout=timeout) 并返回等长列表；specs 为空则返回空列表；
 def submit_many(exe: str, jobs_dir: str, specs: list, *, timeout=120) -> list:
     """批量投递（hive 侧并发消费；本函数逐条投递并保序配对）。"""
     return [submit(exe, jobs_dir, s, timeout=timeout) for s in specs]
 
 
+# 生效条件：exe/jobs_dir 给定，job_id 为真值时 argv 追加 str(job_id)，假值（None/""）时仅列全部；运行后 returncode 非 0 返回 ok False + error，否则 _last_json(p.stdout) 为真值（非空 dict）时返回该 dict，为假值时返回 ok False「poll 输出非 JSON」；
 def poll(exe: str, jobs_dir: str, job_id=None, *, timeout=120) -> dict:
     """查询 job 状态（不传 job_id = 列出全部）。"""
     argv = [exe, "poll"]
@@ -265,10 +277,12 @@ def poll(exe: str, jobs_dir: str, job_id=None, *, timeout=120) -> dict:
                  "stdout": (p.stdout or "")[:800]}
 
 
+# 生效条件：j.get("job_id") 为真值时返回该值，否则返回 j.get("id")（若 id 为 0/""/False 则原样返回该假值，若 id 缺失返回 None）；
 def _job_id(j: dict):
     return j.get("job_id") or j.get("id")
 
 
+# 生效条件：j.get("state") 为真值时返回 str(state)；否则 j.get("status") 为 dict 时返回 str(status.get("state") or "")；否则返回 str(status or "")；
 def _job_state(j: dict) -> str:
     """state 读取兼容两种形态（扁平 / status 嵌套）；仅供轮询判终态。"""
     s = j.get("state")
@@ -280,6 +294,7 @@ def _job_state(j: dict) -> str:
     return str(st or "")
 
 
+# 生效条件：exe/jobs_dir 给定，job_ids 真值集合限观测；循环 poll 直到 pending 为空且（want 为 None 或 want <= 已观测）返回 ok=not failed，若 pending 非空或 want 未全观测且到 max(1.0,float(timeout_s)) 截止则返回 ok False + error，每次间隔 sleep(max(0.05,float(interval_s)))；
 def wait_jobs(exe: str, jobs_dir: str, job_ids=None, *, timeout_s=900,
               interval_s=1.0, on_tick=None) -> dict:
     """轮询至全部终态（或超时）→ done/failed/pending 三分类 + 原始快照。"""
@@ -321,6 +336,7 @@ def wait_jobs(exe: str, jobs_dir: str, job_ids=None, *, timeout_s=900,
         time.sleep(max(0.05, float(interval_s)))
 
 
+# 生效条件：jobs_dir/job_id 给定，join(jobs_dir,str(job_id),"result.json") 路径缺失时返回 ok False「result.json 不存在」，读取时 OSError/ValueError 返回 ok False「读取失败」，json 对象非 dict 返回 ok False「result 非对象」，否则返回该 dict；
 def read_result(jobs_dir: str, job_id: str) -> dict:
     """读工人产出（job 目录的 result.json）。"""
     p = os.path.join(jobs_dir, str(job_id), "result.json")
@@ -334,6 +350,7 @@ def read_result(jobs_dir: str, job_id: str) -> dict:
     return obj if isinstance(obj, dict) else {"ok": False, "error": "result 非对象"}
 
 
+# 生效条件：jobs_dir/job_ids 给定，job_ids 为假值（None/[]）时返回空 dict，否则返回 {str(j): read_result(jobs_dir, j) for j in job_ids}；
 def collect(jobs_dir: str, job_ids) -> dict:
     """按 job_id 收卷（读 result.json），返回 {job_id: result} 保序映射。"""
     return {str(j): read_result(jobs_dir, j) for j in (job_ids or [])}
@@ -341,6 +358,7 @@ def collect(jobs_dir: str, job_ids) -> dict:
 
 # ---- 级 5-A · 意见解析与格式校验（校验率 100% 是验收口径）-----------------
 
+# 生效条件：text 去空格后为空返回 None；否则先 try json.loads(整体)，成功返回；否则找 ```(?:json)?...``` 围栏内 json.loads 成功返回；否则取 s.find("{") 与 s.rfind("}") 且 0<=i<k 的切片 json.loads 成功返回；均失败返回 None；
 def _extract_json(text: str):
     """从模型文本抽 JSON 对象：整体 → ```围栏``` → 首尾大括号切片。"""
     s = (text or "").strip()
@@ -365,6 +383,7 @@ def _extract_json(text: str):
     return None
 
 
+# 生效条件：result 非 dict 返回 ok False；result.get("error") 真值返回 ok False「工人报错」；v=result.get("verdicts")，v is None 时从 result.get("content") or "" 经 _extract_json 取 dict，非 dict 返回 ok False，否则 v=obj.get("verdicts") 且 summary=obj.get("summary") or summary；v 非 list 返回 ok False；否则返回 ok True、verdicts=v、summary=str(summary)；
 def parse_opinions(result: dict) -> dict:
     """result.json → {"ok":True,"verdicts":[...],"summary":...}。
 
@@ -389,11 +408,13 @@ def parse_opinions(result: dict) -> dict:
     return {"ok": True, "verdicts": v, "summary": str(summary)}
 
 
+# 生效条件：v 经 str(v or "").strip().upper() 得 s，若 s 在模块级 VERDICTS 中则返回 s，否则返回 None；
 def _norm_verdict(v):
     s = str(v or "").strip().upper()
     return s if s in VERDICTS else None
 
 
+# 生效条件：op 非 dict 返回「意见非对象」；nid 为空返回「缺 node_id」；node_ids 非 None 且 nid 不在其中返回越界错误；_norm_verdict(op.get("verdict")) 为 None 返回「verdict 越界」；reason 去空格空返回「缺 reason」；vd=="REJECT" 且 evidence 去空格空返回「REJECT 缺 evidence」；否则返回 None；
 def validate_opinion(op, node_ids=None):
     """单条意见格式校验：合法返回 None，非法返回错误串。"""
     if not isinstance(op, dict):
@@ -413,6 +434,7 @@ def validate_opinion(op, node_ids=None):
     return None
 
 
+# 生效条件：verdicts 为假值（None/[]）时 total=0、rate=1.0、ok=False；否则逐条 validate_opinion，无效记入 invalid，有效项复制并写入 _norm_verdict(op.get("verdict"))，最后返回 total、valid、invalid、rate=len(valid)/total、ok=bool(valid) and not invalid；
 def validate_opinions(verdicts, node_ids=None) -> dict:
     """批量校验：valid/invalid 明细 + 通过率（用于 100% 口径断言）。"""
     total = len(verdicts or [])
@@ -434,6 +456,7 @@ def validate_opinions(verdicts, node_ids=None) -> dict:
 
 # ---- 级 5-B · 落库（verify 令牌 + writepipe 六道闸；不自造通道）-----------
 
+# 生效条件：当 actor 给出时，从 TK.role_spec('verify') 读取 clearance_cap/can_write/can_admin/layers_allow 构造 Principal；session 为假值时生成 'mrev_' + uuid 前 12 位；layers_allow 为假值时回落 spec.get('layers_allow') 或 []；ops_allow 原样传入。
 def verifier_principal(*, actor="mreview-verifier", session=None,
                        layers_allow=None, ops_allow=None) -> Principal:
     """验证单元 Principal——角色规格取自 tokens 真源（避免手写漂移）。"""
@@ -447,6 +470,7 @@ def verifier_principal(*, actor="mreview-verifier", session=None,
                      ops_allow=ops_allow, auth_mode="mreview")
 
 
+# 生效条件：pkg、opinions、reviewer 给定时恒返回 "\n".join(L)；summary 为真值才追加「整包结论」行，invalid 为真值才追加「【未落库条目】」行，二者取默认 "" / None 时不追加；
 def opinion_doc(pkg: dict, opinions: list, *, reviewer: str, summary="",
                 invalid=None) -> str:
     """评审意见节点正文（核心修改四要素：内容/原因/位置/验证）。"""
@@ -487,6 +511,7 @@ def opinion_doc(pkg: dict, opinions: list, *, reviewer: str, summary="",
     return "\n".join(L)
 
 
+# 生效条件：cg/pkg/opinions/reviewer/applier 给定，CC.detect_self_verify 判 reviewer 与 applier 同一→refused self_verify_disallowed；opinions 为空→ok True skipped no_opinions；dry_run 真→ok True committed False；否则 (pipe or WP.default_pipeline()).execute，AccessDenied→refused layer_denied，其他异常→write_error，成功→ok 取 out.ok、committed 取 out.committed、moved_to 取 out.moved_to、deferred=bool(out.moved_to) and not out.committed；
 def apply_opinions(cg, pkg: dict, opinions: list, *, reviewer, applier,
                    dry_run=False, pipe=None, layer=OPINION_LAYER,
                    importance=0.4, tags=None, node_id=None,
@@ -550,6 +575,7 @@ def apply_opinions(cg, pkg: dict, opinions: list, *, reviewer, applier,
 
 # ---- 编排 ----------------------------------------------------------------
 
+# 生效条件：pkg/asm/cg 给定，exe=hive_exe(exe)，jobs_dir/ctx_dir 假值回落到 tempfile.gettempdir() 下路径；dump_context 后 build_spec、submit，若 submit 无 ok 或无 _job_id 返回 stage submit；wait_jobs 后若 failed 或 done 空返回 stage wait；read_result+parse_opinions 失败返回 stage parse；否则 validate_opinions 并 apply_opinions，返回 ok=app.ok 及计数；
 def run_package(*, pkg, asm, cg, exe=None, jobs_dir=None, ctx_dir=None,
                 reviewer="mreview-worker", applier="mreview-applier",
                 model=None, timeout_s=900, interval_s=1.0, dry_run=False,
@@ -590,6 +616,7 @@ def run_package(*, pkg, asm, cg, exe=None, jobs_dir=None, ctx_dir=None,
             "apply": app, "stages": {"submit": True, "wait": True, "parse": True}}
 
 
+# 生效条件：pairs/cg 给定，先对每对 pkg,asm 执行 dump_context/build_spec/submit，收集 ok 且有 job_id 的 jids；wait_jobs 后逐 jid 若 state!="done" 记 stage wait，否则 read_result/parse_opinions/validate_opinions/apply_opinions 并累计；返回 ok=all(results.ok) and bool(results) 及聚合计数；
 def run_batch(*, pairs, cg, exe=None, jobs_dir=None, ctx_dir=None,
               reviewer="mreview-worker", applier="mreview-applier", model=None,
               timeout_s=1800, interval_s=1.0, dry_run=False, on_tick=None) -> dict:
@@ -666,6 +693,7 @@ def run_batch(*, pairs, cg, exe=None, jobs_dir=None, ctx_dir=None,
 
 # ---- CLI -----------------------------------------------------------------
 
+# 生效条件：当 argv 给出时，argparse 解析命令行；root 取 a.root 或 os.environ.get('MDCG_ROOT')，若 root 为假值则 SystemExit；否则用 verifier_principal(actor=a.applier) 构造 MdCGSecure，build_packages(root=root, limit=None) 得到 pairs，按 a.packages（假值 0 则取全部）切片，run_batch 以 dry_run=(a.dry_run or not a.apply) 运行，打印 JSON 报告，返回 0（rep['ok'] 为真）或 1。
 def main(argv=None):                                        # pragma: no cover
     import argparse
     ap = argparse.ArgumentParser(prog="python -m md_cg.mreview.pipeline",
@@ -698,4 +726,4 @@ def main(argv=None):                                        # pragma: no cover
 
 
 if __name__ == "__main__":                                  # pragma: no cover
-    raise SystemExit(main())
+    raise SystemExit(main())

package/md_cg/mreview/ruleset.py

@@ -35,12 +35,14 @@ SEVERITIES = ("INFO", "WARN", "HIGH")
 _BLANK = (None, "", "None", "[]", "{}")
 
 
+# 生效条件：v 为 list/tuple/dict 时返回 not v（空容器为 True、非空为 False），其余类型返回 v is None 或 str(v).strip() 属于 ("", "None")。
 def _blank(v) -> bool:
     if isinstance(v, (list, tuple, dict)):
         return not v
     return v is None or str(v).strip() in ("", "None")
 
 
+# 生效条件：int(v) 可转换时返回该整数值，v 触发 TypeError 或 ValueError 时返回 0（源码未校验正负或范围）。
 def _as_int(v) -> int:
     try:
         return int(v)
@@ -48,6 +50,7 @@ def _as_int(v) -> int:
         return 0
 
 
+# 生效条件：以 entry.get("ref")/entry.get("node_id")（缺键得 None）、field、kind、evidence、rule["id"]（rule 缺 id 键抛 KeyError）组装 dict，severity 取 severity or rule.get("severity") or "WARN"，故 severity 传 None/空串时依次回落到规则 severity、再回落 "WARN"。
 def _issue(entry, rule, kind, field, evidence, severity=None) -> dict:
     return {"ref": entry.get("ref"), "node_id": entry.get("node_id"),
             "field": field, "issue_kind": kind, "evidence": evidence,
@@ -56,18 +59,21 @@ def _issue(entry, rule, kind, field, evidence, severity=None) -> dict:
 
 # ---------------------------- 机械检查器注册表 ----------------------------
 
+# 生效条件：field 取 spec.get("field")（缺键为 None），对每个 _blank(e.get(field)) 为真的条目生成一条 issue，issue_kind 取 spec.get("issue_kind") or "missing_field"（空串/None 回落 "missing_field"），无此类条目时返回空列表。
 def _chk_field_absent(entries, spec, rule):
     field = spec.get("field")
     return [_issue(e, rule, spec.get("issue_kind") or "missing_field", field,
                    "字段 %s 为空" % field) for e in entries if _blank(e.get(field))]
 
 
+# 生效条件：issue_kind 取 spec.get("issue_kind") or "missing_field"，field 固定为 "evidence_count"，对每个 _as_int(e.get("evidence_count")) == 0 的条目生成一行证据计数 issue（缺键、空串、非法值均折算为 0 而命中），无此类条目时返回空列表。
 def _chk_evidence_zero(entries, spec, rule):
     return [_issue(e, rule, spec.get("issue_kind") or "missing_field", "evidence_count",
                    "evidence_count=0（无验证证据计数）")
             for e in entries if _as_int(e.get("evidence_count")) == 0]
 
 
+# 生效条件：field 取 spec.get("field")、thr 取 float(spec.get("ratio", 1.0))（缺 ratio 键默认 1.0），非空 field 条目数除以 max(len(entries), 1) 得 ratio，ratio < thr 时返回一条 ref/node_id 为 None、issue_kind="package_ratio"、severity 取 rule.get("severity") or "INFO" 的 issue，ratio >= thr 时返回 []。
 def _chk_field_ratio_below(entries, spec, rule):
     field, thr = spec.get("field"), float(spec.get("ratio", 1.0))
     ratio = sum(1 for e in entries if not _blank(e.get(field))) / max(len(entries), 1)
@@ -78,6 +84,7 @@ def _chk_field_ratio_below(entries, spec, rule):
              "rule_id": rule["id"], "severity": rule.get("severity") or "INFO"}]
 
 
+# 生效条件：h 取 str(e.get("content_hash") or "")（缺键或假值均为 ""），_blank(h) 或 h == "None" 的条目跳过，h 已在 seen 中时按 dup_content/"content_hash" 出 issue，首次出现则以 seen[h]=e.get("ref") 记录，返回累积的 out。
 def _chk_dup_hash_group(entries, spec, rule):
     seen, out = {}, []
     for e in entries:
@@ -92,6 +99,7 @@ def _chk_dup_hash_group(entries, spec, rule):
     return out
 
 
+# 生效条件：骨架 sk 取 WL._skeleton(e.get("excerpt") or "")，sk 为空或 len(sk) < WL.MIN_SKELETON 的条目跳过，sk 已在 seen 中时按 template_flow/"content" 出 issue，首次出现则记 seen[sk]=e.get("ref")，返回累积的 out。
 def _chk_template_flow(entries, spec, rule):
     seen, out = {}, []
     for e in entries:
@@ -106,6 +114,7 @@ def _chk_template_flow(entries, spec, rule):
     return out
 
 
+# 生效条件：basis 取 e.get("verification_basis")，_blank(basis) 的条目跳过；其余条目以 CC.classify_track({"layer": e.get("layer"), "tags": e.get("tags") or []}, e.get("excerpt") or "") 判 CC.basis_licensed(track, basis)，为假时按 weak_source/"verification_basis" 出 issue，返回 out。
 def _chk_basis_licensed(entries, spec, rule):
     out = []
     for e in entries:
@@ -134,6 +143,7 @@ MECH_CHECKS = {
 
 # ---------------------------- 规则库加载 ----------------------------
 
+# 生效条件：d 取 rules_dir or RULES_DIR（rules_dir 为 None 或空串时回落 RULES_DIR），os.path.isdir(d) 为假则 files 为空列表；为目录时读其中 *.json，任一规则缺 id/matcher/severity、severity 不在 SEVERITIES、id 重复、mechanical 项 check 不在 MECH_CHECKS 均抛 ValueError，全部合法则返回 {"rules_dir": d, "files": files, "rules": rules, "count": len(rules)}。
 def load_rules(rules_dir=None) -> dict:
     """读 `rules/*.json`。格式非法/字段缺失/id 重复 → 抛 ValueError（不静默降级）。"""
     d = rules_dir or RULES_DIR
@@ -159,6 +169,7 @@ def load_rules(rules_dir=None) -> dict:
     return {"rules_dir": d, "files": files, "rules": rules, "count": len(rules)}
 
 
+# 生效条件：m 取 rule.get("matcher") or {}；m["layer"] 为真且与 ctx["layers"] 无交集时返回 (False, "包内无 X 层条目")，m["tags_any"] 为真且与 ctx["tag_prefixes"] 无交集时返回 (False, 标签提示)，两者均不触发时返回 (True, "matcher 命中")。
 def _match(rule, ctx) -> tuple:
     """matcher 语义：包内**存在**该类条目即入包（执行时按同条件过滤）。"""
     m = rule.get("matcher") or {}
@@ -169,6 +180,7 @@ def _match(rule, ctx) -> tuple:
     return True, "matcher 命中"
 
 
+# 生效条件：rule.get("matcher") or {} 的 "layer" 为真时，返回 str(e.get("layer")) 落在 set(m["layer"]) 内的条目列表；matcher 无 layer 或为假值时返回 list(entries) 全量。
 def _scope(entries, rule) -> list:
     m = rule.get("matcher") or {}
     if m.get("layer"):
@@ -177,6 +189,7 @@ def _scope(entries, rule) -> list:
     return list(entries)
 
 
+# 生效条件：rules 为 None 时返回 load_rules(rules_dir)["rules"]；rules 为 dict 且不含 "rules" 键时抛 ValueError，含该键时返回 list(rules.get("rules") or [])；其余形态返回 list(rules)。
 def _as_rules(rules, rules_dir=None) -> list:
     """规则入参防呆：None→读规则库；{"rules":[...]}→取内层；列表→原样。
 
@@ -191,6 +204,7 @@ def _as_rules(rules, rules_dir=None) -> list:
     return list(rules)
 
 
+# 生效条件：pkg 为 dict 时 entries 取 pkg.get("entries") or []，规则先经 _as_rules(rules, rules_dir) 归一，ctx 由 entries 的 layer 与 tags 冒号前缀集构成，逐条规则 _match 命中后经 _scope 过滤并对 mechanical 项调 MECH_CHECKS[spec["check"]]、对 llm 项列出 scope_refs 前 200，返回含 bundle_id/group_kind/group_key/size/matched/mechanical/llm/mechanical_by_kind/mechanical_flagged 的 dict。
 def assemble(pkg: dict, *, rules=None, rules_dir=None) -> dict:
     """单个待评包 → 规则集 + 机械检查结果 + 待 LLM 检查清单。"""
     rl = _as_rules(rules, rules_dir)
@@ -222,6 +236,7 @@ def assemble(pkg: dict, *, rules=None, rules_dir=None) -> dict:
             "mechanical_flagged": len({i.get("ref") for i in mech if i.get("ref")})}
 
 
+# 生效条件：result 为 dict 时规则先经 _as_rules(rules, rules_dir) 得 rl，再对 result.get("bundles") or [] 逐包调用 assemble(p, rules=rl)（rules_dir 不向 assemble 透传），返回 {"packages": out, "stats": {bundles/mechanical_total/mechanical_by_kind/llm_checks/rules}, "bundles_input": result.get("stats")}。
 def assemble_all(result: dict, *, rules=None, rules_dir=None) -> dict:
     """全部包装配 + 汇总（包级统计供 M2 spec 与 M4 量化复跑）。"""
     rl = _as_rules(rules, rules_dir)
@@ -235,4 +250,4 @@ def assemble_all(result: dict, *, rules=None, rules_dir=None) -> dict:
         "mechanical_by_kind": dict(kinds),
         "llm_checks": sum(len(a["llm"]) for a in out),
         "rules": [r["id"] for r in rl]},
-        "bundles_input": result.get("stats")}
+        "bundles_input": result.get("stats")}