@dsh-bio/dsh-bio-gem 0.1.1

package/python/enrichment.py

@@ -0,0 +1,182 @@
+# enrichment.py — 阶段C-C3 必需基因通路富集（超几何 + BH FDR；菌种通用）
+# 通路注释源（C3 开工探索结论）：gapseq 模型在 SBML groups 里写入 MetaCyc 通路分组
+#   （C58 实测 1051 个 PWY groups，9942 个反应成员关系）；BiGG 静态下载模型无 groups
+#   （iML1515 实测 0）——无 groups 时按契约返回 annotation_unavailable 兜底（不伪造通路）。
+# gene_list 缺省从账本读该模型 essentiality 预测的基因。不登记账本（统计描述非单条预测）。
+import os
+import sys
+import csv
+import time
+import json
+from math import comb
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from silentio import silent_read_sbml
+
+NOTE_UNAVAILABLE = ("模型无 SBML groups（通路）注释。可补途径：①用 gapseq 重建（自带 MetaCyc pathway "
+                    "groups）；②从 BiGG API 取模型 subsystem 后注入 groups；③按 ec-code 注释做粗分类。")
+
+
+def _hypergeom_sf(x, N, K, n):
+    """P(X >= x)，X~Hypergeom(N, K, n)。scipy 优先，缺失回退精确求和。"""
+    try:
+        from scipy.stats import hypergeom
+        return float(hypergeom.sf(x - 1, N, K, n))
+    except Exception:
+        lo, hi = max(x, 0), min(K, n)
+        if hi < lo:
+            return 1.0
+        total = comb(N, n)
+        s = sum(comb(K, i) * comb(N - K, n - i) for i in range(lo, hi + 1))
+        return min(1.0, s / total) if total else 1.0
+
+
+def _bh_fdr(pvals):
+    """Benjamini-Hochberg FDR 校正（单调保序）。"""
+    m = len(pvals)
+    if m == 0:
+        return []
+    order = sorted(range(m), key=lambda i: pvals[i])
+    fdr = [0.0] * m
+    prev = 1.0
+    for rank, i in enumerate(reversed(order), 1):
+        idx = m - rank + 1  # 从大到小累计 min
+        v = min(prev, pvals[i] * m / (m - rank + 1))
+        fdr[i] = v
+        prev = v
+    return fdr
+
+
+def _pathway_gene_sets(m):
+    """SBML groups -> {pathway_name: gene set}（成员反应的 GPR 基因并集）。"""
+    out = {}
+    for g in getattr(m, "groups", []) or []:
+        genes = set()
+        for member in g.members:
+            try:
+                for gene in member.genes:
+                    genes.add(gene.id)
+            except Exception:
+                continue
+        if genes:
+            out[g.name or g.id] = genes
+    return out
+
+
+def _ledger_essential_genes(model_path, ledger_path):
+    import ledger as _ledger
+    if not ledger_path:
+        ledger_path = _ledger.model_ledger_path(model_path)  # 2026-08-31：默认=该模型自己的账本
+    rows, corrupt = _ledger.load_rows(ledger_path)
+    genes = []
+    for r in rows:
+        # 单模型账本语义：账本里都是该模型（basename 组，含路径变体）的预测，不再精确匹配 model
+        if r.get("type") == "essentiality":
+            gid = (r.get("content") or "").split(" 在 ")[0].strip()
+            if gid:
+                genes.append(gid)
+    return sorted(set(genes)), len(rows), corrupt
+
+
+def enrichment(model_path, gene_list=None, pathway_source=None, ledger_path=None,
+               export_csv=None, progress=None):
+    log = progress or (lambda s: sys.stderr.write(str(s) + "\n"))
+    t0 = time.time()
+    m = silent_read_sbml(model_path)
+
+    pw_sets = _pathway_gene_sets(m) if (pathway_source or "groups") == "groups" else {}
+    if not pw_sets:
+        # 注释缺失兜底（必须）：不伪造通路
+        return {
+            "model": model_path, "annotation_unavailable": True,
+            "note": NOTE_UNAVAILABLE,
+            "groups_found": len(getattr(m, "groups", []) or []),
+            "ec_code_reactions": sum(1 for r in m.reactions
+                                     if (r.annotation or {}).get("ec-code")),
+            "gene_list_provided": bool(gene_list),
+            "timing_seconds": round(time.time() - t0, 1),
+        }
+
+    # gene_list：显式传入优先；缺省从账本 essentiality 预测读取（本模型）
+    source_note = None
+    if not gene_list:
+        gene_list, total_rows, corrupt = _ledger_essential_genes(model_path, ledger_path)
+        source_note = (f"gene_list 缺省来自账本 essentiality 预测（model 精确匹配 {model_path}，"
+                       f"账本总行 {total_rows}，corrupt {corrupt}）")
+        log(f"[enrich] gene_list from ledger: {len(gene_list)} genes")
+    gene_list = sorted(set(gene_list or []))
+
+    # 背景 = 模型内所有有 GPR 关联的基因（可被通路注释到的全体基因）
+    bg_genes = {g.id for g in m.genes if g.reactions}
+    input_in_bg = [g for g in gene_list if g in bg_genes]
+    N, n = len(bg_genes), len(input_in_bg)
+
+    rows = []
+    for pw_name, pw_genes in pw_sets.items():
+        bg_hit = pw_genes & bg_genes
+        if not bg_hit:
+            continue
+        K = len(bg_hit)
+        hits = sorted(set(input_in_bg) & bg_hit)
+        x = len(hits)
+        if x == 0:
+            continue
+        p = _hypergeom_sf(x, N, K, n)
+        exp = K * n / N if N else 0.0
+        rows.append({"pathway": pw_name, "genes_hit": hits, "genes_hit_count": x,
+                     "background_hit": K, "pathway_size": len(pw_genes),
+                     "total_bg": N, "n_input": n, "expected_count": round(exp, 3),
+                     "fold_enrichment": round(x / exp, 3) if exp > 0 else None,
+                     "p_value": p})
+    fdrs = _bh_fdr([r["p_value"] for r in rows])
+    for r, f in zip(rows, fdrs):
+        r["fdr"] = f
+    rows.sort(key=lambda r: (r["p_value"], r["pathway"]))
+    sig = [r for r in rows if r["fdr"] <= 0.05]
+    log(f"[enrich] pathways tested={len(rows)} significant(FDR<=0.05)={len(sig)}")
+
+    out = {
+        "model": model_path,
+        "pathway_source": "sbml_groups(MetaCyc PWY)",
+        "annotation_unavailable": False,
+        "gene_list_source": source_note or "explicit",
+        "gene_list": gene_list,
+        "background_size": N,
+        "n_input": n,
+        "n_too_small": n < 10,
+        "n_too_small_note": (f"有效映射基因 n={n} < 10，统计功效有限，结果仅供方向参考" if n < 10 else None),
+        "pathways_tested": len(rows),
+        "significant_count_fdr05": len(sig),
+        "results": rows,
+        "multiple_testing": "hypergeom 单侧富集 + Benjamini-Hochberg FDR",
+        "timing_seconds": round(time.time() - t0, 1),
+    }
+    if export_csv:
+        with open(export_csv, "w", newline="", encoding="utf-8-sig") as f:
+            w = csv.writer(f)
+            w.writerow(["pathway", "genes_hit_count", "genes_hit", "background_hit",
+                        "pathway_size", "total_bg", "n_input", "expected_count",
+                        "fold_enrichment", "p_value", "fdr"])
+            for r in rows:
+                w.writerow([r["pathway"], r["genes_hit_count"], ";".join(r["genes_hit"]),
+                            r["background_hit"], r["pathway_size"], r["total_bg"],
+                            r["n_input"], r["expected_count"], r["fold_enrichment"],
+                            r["p_value"], r["fdr"]])
+        out["export_csv"] = export_csv
+        out["export_csv_rows"] = len(rows)
+        log(f"[enrich] CSV {export_csv}: {len(rows)} rows")
+    return out
+
+
+if __name__ == "__main__":
+    args = {}
+    if len(sys.argv) > 1:
+        with open(sys.argv[1], encoding="utf-8") as f:
+            args = json.load(f)
+    elif not sys.stdin.isatty():
+        args = json.loads(sys.stdin.read())
+    a = args.get("args", args)
+    print(json.dumps({"ok": True, "result": enrichment(
+        a.get("model"), gene_list=a.get("gene_list"), pathway_source=a.get("pathway_source"),
+        ledger_path=a.get("ledger_path"), export_csv=a.get("export_csv"))}, ensure_ascii=False))

package/python/essential_scan.py

@@ -0,0 +1,195 @@
+# essential_scan.py — G5 全量必需性扫描（路线 P0：FVA 预筛 + 手工敲除）
+# 流程: 介质设置 -> FVA(全范围) 预筛可通量基因（死基因免敲）-> 手工单基因敲除
+#       -> 必需基因列表 + 模型卡章节数据（证据分级配色字段）
+# Windows 纪律: FVA processes=1（无 fork）；手工敲除循环；GLPK 快速线性
+# 阶段A-M2: 介质 setup 与扫描核心拆为 setup_model_medium/scan_essentiality 供 sensitivity 复用
+#           （行为不变，C58 AB 必需 155 锚点必须原样复现）
+import os
+import sys
+import time
+import cobra
+from cobra.flux_analysis import flux_variability_analysis
+
+from silentio import silent_read_sbml
+from gapfind import expand_medium, resolve_medium
+
+EPS = 1e-6
+FVA_EPS = 1e-9
+
+
+def setup_model_medium(m, medium=None):
+    """介质 setup（对齐 validate G3）：expand_medium -> 全交换清零 -> resolve_medium 设 bounds。
+    阶段A-M2 抽出：essential_scan 与 sensitivity 共用同一介质口径。返回 (resolved, unresolved, preset)。"""
+    med, preset = expand_medium(medium) if medium else ({}, None)
+    resolved, unresolved = resolve_medium(m, med) if med else ({}, [])
+    for r in m.reactions:
+        if r.id.startswith(("EX_", "DM_", "SK_")) or r.boundary:
+            r.lower_bound = 0.0
+    for exid, lb in resolved.items():
+        if exid in m.reactions:
+            m.reactions.get_by_id(exid).lower_bound = lb
+    return resolved, unresolved, preset
+
+
+def prescreen_candidates(m, gene_subset=None):
+    """FVA(fraction=0) 预筛（阶段C-C2 抽出复用）：返回 (active_rxns, cand_genes, n_tested, fva_s)。
+    cand_genes = 关联至少一个可通量反应的基因（死基因免敲）；n_tested = FVA 检查的反应总数。"""
+    t0 = time.time()
+    fva = flux_variability_analysis(m, fraction_of_optimum=0.0, processes=1)
+    fva_s = round(time.time() - t0, 1)
+    active_rxns = set(fva.index[((fva["maximum"] > FVA_EPS) | (fva["minimum"] < -FVA_EPS))])
+    cand_genes = set()
+    for g in m.genes:
+        if gene_subset and g.id not in gene_subset:
+            continue
+        if any(r.id in active_rxns for r in g.reactions):
+            cand_genes.add(g.id)
+    print(f"[scan] FVA {fva_s}s；可通量反应 {len(active_rxns)}/{len(fva)}；候选基因 {len(cand_genes)}",
+          file=sys.stderr)
+    return active_rxns, cand_genes, len(fva), fva_s
+
+
+def scan_essentiality(m, gene_subset=None, progress=None, return_candidates=False):
+    """必需性扫描核心（阶段A-M2 抽出复用）。输入：介质 bounds 已设好的模型。
+    FVA(fraction=0) 预筛 -> 可通量反应关联基因 -> 手工敲除（<EPS 判必需）。
+    返回 {wt_growth, total_genes, fva_tested_reactions, active_reactions, tested_genes,
+    essential_count, essential_genes, organs, fva_seconds, knock_seconds}。"""
+    with m:
+        wt = m.optimize().objective_value
+    print(f"[scan] wt = {wt:.6f}; genes = {len(m.genes)}", file=sys.stderr)
+
+    # 1) FVA 预筛（fraction_of_optimum=0 全范围）：无通量的反应关联基因免敲
+    active_rxns, cand_genes, n_fva, fva_s = prescreen_candidates(m, gene_subset=gene_subset)
+    print(f"[scan] 候选基因（关联可通量反应）{len(cand_genes)}", file=sys.stderr)
+    print(f"[scan]         预计免敲 {max(0, len(m.genes) - len(cand_genes))} 个（{max(0, len(m.genes)-len(cand_genes))/max(1,len(m.genes))*100:.0f}%）", file=sys.stderr)
+
+    # 2) 手工敲除循环（HANDOFF-03：不用 single_gene_deletion）
+    t0 = time.time()
+    essential = []
+    for gid in sorted(cand_genes):
+        with m:
+            m.genes.get_by_id(gid).knock_out()
+            v = m.optimize().objective_value
+        if v < EPS:
+            essential.append(gid)
+        if progress and len(essential) % 50 == 0:
+            progress({"tested": len(cand_genes), "essential_so_far": len(essential)})
+    knock_s = round(time.time() - t0, 1)
+
+    out = {
+        "wt_growth": round(wt, 6),
+        "total_genes": len(m.genes),
+        "fva_tested_reactions": n_fva,
+        "active_reactions": len(active_rxns),
+        "tested_genes": len(cand_genes),
+        "essential_count": len(essential),
+        "essential_genes": essential,
+        "organs": {"essential_count": len(essential), "viable_ratio": round(1 - len(essential)/max(1, len(cand_genes)), 4)},
+        "fva_seconds": fva_s,
+        "knock_seconds": knock_s,
+    }
+    if return_candidates:  # 阶段C-C2：double_knockout 复用（避免二次 FVA 预筛）
+        out["candidate_genes"] = sorted(cand_genes)
+        out["active_rxn_ids"] = sorted(active_rxns)
+    return out
+
+
+def _load_gene_table(path):
+    """gene_table.tsv（gem_annotate 产出）-> {gene_id: {locus_tag, gene_name, product}}。"""
+    import csv
+    mp = {}
+    if not path or not os.path.exists(path):
+        return mp
+    with open(path, encoding="utf-8") as f:
+        rd = csv.DictReader(f, delimiter="\t")
+        for row in rd:
+            gid = (row.get("gene_id") or "").strip()
+            if gid:
+                mp[gid] = {"locus_tag": (row.get("locus_tag") or "").strip(),
+                           "gene_name": (row.get("gene_name") or "").strip(),
+                           "product": (row.get("product") or "").strip()}
+    return mp
+
+
+def _attach_gene_table(result, gene_table):
+    """P1-4（2026-08-31 LBA9402 会话实测）：坐标型基因 ID 无功能语义，73 个必需基因无法解读。
+    关联 gem_annotate 的 gene_table.tsv -> essential_gene_details 带 locus_tag/product。
+    只增字段不破坏 essential_genes（str 列表）既有消费方（model_card/ledger/sensitivity/benchmark）。"""
+    result["gene_table_loaded"] = False
+    if not gene_table or not os.path.exists(gene_table):
+        return result
+    try:
+        mp = _load_gene_table(gene_table)
+        details = []
+        for g in result.get("essential_genes") or []:
+            info = mp.get(g) or {}
+            details.append({"gene_id": g,
+                            "locus_tag": info.get("locus_tag") or None,
+                            "gene_name": info.get("gene_name") or None,
+                            "product": info.get("product") or None})
+        result["gene_table_loaded"] = True
+        result["gene_table_path"] = os.path.abspath(gene_table)
+        result["essential_gene_details"] = details
+        result["gene_table_note"] = ("基因注释表已关联：essential_gene_details 提供坐标ID→locus_tag/product 映射，"
+                                     "用于解读必需基因功能（坐标型 ID 无此表时不可读）")
+    except Exception as e:
+        sys.stderr.write(f"[scan] gene_table WARN: {type(e).__name__}: {e}\n")
+    return result
+
+
+def essential_scan(model_path, medium=None, gene_subset=None, progress=None, ledger_path=None,
+                   gene_table=None):
+    """全量必需基因扫描。返回 {wt, total_genes, tested, essential, essential_genes,
+    predicted_viable, timeout_aborted, fva_seconds, knock_seconds}。"""
+    m = silent_read_sbml(model_path)
+    resolved, unresolved, preset = setup_model_medium(m, medium)
+    print(f"[scan] medium_unresolved = {unresolved}", file=sys.stderr)
+
+    result = scan_essentiality(m, gene_subset=gene_subset, progress=progress)
+    result.update({
+        "medium_preset": preset,
+        "medium_unresolved": unresolved,
+        "note": "必需判定=A 培养基下敲除生长<1e-6；evidence 分级按基因支撑反应是否含 EVIDENCE_math（Q2）",
+        # 阶段A-M4 口径声明（只增）：wt_growth 为单点 FBA 值
+        "units": "mmol/gDW/h",
+        "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
+    })
+    # 模型卡 schema v2 回写（产物旁已有 card 才写；无卡不凭空造卡）
+    try:
+        from model_card import load_card, set_essential_genes
+        if load_card(model_path) is not None:
+            set_essential_genes(model_path, result, model=m)
+    except Exception:
+        pass
+    # 阶段A遗留修正（退化护栏，只增分支）：wt<=EPS 时必需性判定恒真（v=0 使全部候选判"必需"，
+    # M5 实测曾把 iNX1344_v4 的 1066 条此类退化预测写入真实账本）——跳过 ledger 自动登记。
+    # C58 正常路径（wt>EPS）不进此分支，登记行为不变。
+    if result["wt_growth"] <= EPS:
+        warn = "wt<=EPS：必需性判定恒真，扫描结果无生物学意义，未登记"
+        sys.stderr.write(f"[scan] WARN wt_growth={result['wt_growth']} {warn}（ledger）\n")
+        result["ledger_registration"] = {"appended": 0,
+                                         "skipped_degraded": len(result["essential_genes"]),
+                                         "degraded": True, "warn": warn}
+        return result
+    # 阶段A-M3: prediction ledger 自动登记（每必需基因一条；幂等去重；写入失败仅 WARN 不阻塞）
+    try:
+        import ledger as _ledger
+        from model_card import load_card as _load_card
+        lineage_v = ((_load_card(model_path) or {}).get("model_lineage") or {}).get("version")
+        cond = preset or (f"custom({len(resolved)} EX)" if resolved else "unspecified")
+        result["ledger_registration"] = _ledger.register_essentiality(
+            model_path, result, model=m, condition=cond, lineage_version=lineage_v,
+            path=ledger_path)
+    except Exception as e:
+        sys.stderr.write(f"[scan] ledger registration WARN: {type(e).__name__}: {e}\n")
+    # P1-4：关联基因注释表（坐标ID→locus_tag/product），让必需基因可解读
+    if result["wt_growth"] > EPS:
+        _attach_gene_table(result, gene_table)
+    return result
+
+
+if __name__ == "__main__":
+    import json
+    args = json.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {}
+    print(json.dumps(essential_scan(args.get("model"), args.get("medium"),
+                                    args.get("gene_subset")), ensure_ascii=False, indent=2))

package/python/fluxscan.py

@@ -0,0 +1,302 @@
+# fluxscan.py — M1 通量区间制（阶段 A 可信度内核第一件）
+# 语义（bsp 锁稿，一字不改）：每反应输出 fva_min/fva_max/pfba；条件对比消费区间分离判定；
+#   overlap = 点值差异是求解器伪影，禁止引用。
+# 计算口径：每 condition 独立 silent_read_sbml 重读模型（勿深拷贝）；介质 setup 对齐 validate G3
+#   （expand_medium -> 全交换清零 EX_/DM_/SK_/boundary -> resolve_medium 设 bounds）；
+#   substrates 对齐 validate g4_phenotype（supplement=基准不变+底物 lb=-10；sole=去含碳交换[元素级
+#   parse_formula]+底物 lb=-10）；FVA processes=1（Windows 无 fork）。
+# 区间分离判定（核心，单测锁定）：
+#   分离 = ua + tol < lb  -> direction=b_higher
+#          ub + tol < la  -> direction=a_higher
+#   否则 overlap=true / hard_conclusion=false / direction=null
+# 判定用四舍六入到 6 位后的区间值（与输出/CSV 展示值自洽，tol=1e-6 仍完全覆盖求解器噪声）。
+import os
+import sys
+import csv
+import time
+import json
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from silentio import silent_read_sbml
+from gapfind import expand_medium, resolve_medium, build_ex_index, match_ex
+from validate import parse_formula
+
+EX_PREFIX = ("EX_", "DM_", "SK_")
+DEFAULT_FRACTION = 0.9999
+DEFAULT_TOL = 1e-6
+ROUND_N = 6
+
+LABEL_OVERLAP = "区间重叠：点值差异=求解器伪影，禁止引用"
+LABEL_A_HIGHER = "区间分离：条件 A 恒高于 B（解空间无关硬结论）"
+LABEL_B_HIGHER = "区间分离：条件 B 恒高于 A（解空间无关硬结论）"
+
+
+def judge_interval(la, ua, lb, ub, tol=DEFAULT_TOL):
+    """区间分离判定（锁定公式）。输入四舍五入后的区间端点，返回 verdict dict。"""
+    if ua + tol < lb:
+        return {"overlap": False, "hard_conclusion": True, "direction": "b_higher"}
+    if ub + tol < la:
+        return {"overlap": False, "hard_conclusion": True, "direction": "a_higher"}
+    return {"overlap": True, "hard_conclusion": False, "direction": None}
+
+
+def _r(x):
+    """FVA/pFBA 数值规整：None/NaN -> 0.0（可行模型下不应出现，防御性），-0.0 -> 0.0，保留 6 位。"""
+    if x is None:
+        return 0.0
+    f = float(x)
+    if f != f:  # NaN
+        return 0.0
+    v = round(f, ROUND_N)
+    return 0.0 if v == 0.0 else v
+
+
+def _setup_condition(model_path, cond, log=lambda s: None):
+    """单条件：独立重读模型 + 介质 setup（对齐 validate G3）+ 底物（对齐 g4_phenotype）。
+    返回 (model, info)；model 的 bounds 已按该条件设好，供 FBA/FVA/pFBA 使用。"""
+    from cobra.flux_analysis import flux_variability_analysis, pfba
+    name = cond.get("name")
+    carbon_mode = cond.get("carbon_mode", "supplement")
+    subs = cond.get("substrates") or []
+    if carbon_mode not in ("supplement", "sole"):
+        raise ValueError(f"condition {name}: unknown carbon_mode {carbon_mode!r}（supplement|sole）")
+
+    t0 = time.time()
+    m = silent_read_sbml(model_path)
+    t_read = time.time() - t0
+
+    med, preset = expand_medium(cond.get("medium"))
+    resolved, unresolved = resolve_medium(m, med) if med else ({}, [])
+    for r in m.reactions:
+        if r.id.startswith(EX_PREFIX) or r.boundary:
+            r.lower_bound = 0.0
+    med2 = dict(resolved)
+    if carbon_mode == "sole":
+        # 去含碳交换（元素级 parse_formula——裸子串会把 Ca/Cl/Co/Cu 误判为碳，历史 bug 勿复刻）
+        for rid in list(med2):
+            if rid in m.reactions:
+                met = list(m.reactions.get_by_id(rid).metabolites)[0]
+                if met.formula and "C" in parse_formula(met.formula):
+                    del med2[rid]
+    ex_idx = build_ex_index(m)
+    sub_ex, sub_unresolved = {}, []
+    for sub in subs:
+        exid = match_ex(sub, ex_idx)
+        if exid and exid in m.reactions:
+            med2[exid] = -10.0
+            sub_ex[sub] = exid
+        else:
+            sub_unresolved.append(sub)
+    for rid, lb in med2.items():
+        if rid in m.reactions:
+            m.reactions.get_by_id(rid).lower_bound = lb
+
+    t0 = time.time()
+    with m:
+        wt = m.optimize().objective_value
+    if wt is None:
+        sys.stderr.write(f"[fluxscan] {name}: FBA infeasible -> growth treated as 0.0\n")
+        wt = 0.0
+    t_fba = time.time() - t0
+
+    t0 = time.time()
+    fva = flux_variability_analysis(m, fraction_of_optimum=DEFAULT_FRACTION
+                                    if cond.get("_fraction") is None else cond["_fraction"],
+                                    processes=1)
+    t_fva = time.time() - t0
+
+    t0 = time.time()
+    sol = pfba(m)
+    t_pfba = time.time() - t0
+
+    info = {
+        "name": name,
+        "growth": round(float(wt), ROUND_N),
+        "medium_preset": preset,
+        "resolved_exchanges": sorted(med2),
+        "unresolved": unresolved,
+        "substrate_exchanges": sub_ex,
+        "substrate_unresolved": sub_unresolved,
+        "carbon_mode": carbon_mode,
+        "_timing": {"read_s": round(t_read, 1), "fba_s": round(t_fba, 2),
+                    "fva_s": round(t_fva, 1), "pfba_s": round(t_pfba, 1)},
+    }
+    data = {}
+    pf = sol.fluxes
+    for rid in fva.index:
+        data[rid] = {
+            "pfba": _r(pf.get(rid, 0.0)),
+            "fva_min": _r(fva.at[rid, "minimum"]),
+            "fva_max": _r(fva.at[rid, "maximum"]),
+        }
+    log(f"[fluxscan] condition {name}: growth={info['growth']} read={t_read:.1f}s "
+        f"fba={t_fba:.2f}s fva={t_fva:.1f}s pfba={t_pfba:.1f}s "
+        f"resolved={len(med2)} unresolved={unresolved} substrate_unresolved={sub_unresolved}")
+    return data, info
+
+
+def _pair_result(a_name, b_name, data_a, data_b, scope, tol, only_diff):
+    """条件对比较：scope 反应逐一区间判定。summary 与 comparisons 同口径（同一 scope）。"""
+    comparisons = []
+    n_hard = n_a = n_b = 0
+    for rid in scope:
+        ra, rb = data_a[rid], data_b[rid]
+        verdict = judge_interval(ra["fva_min"], ra["fva_max"], rb["fva_min"], rb["fva_max"], tol)
+        if verdict["hard_conclusion"]:
+            n_hard += 1
+            if verdict["direction"] == "a_higher":
+                n_a += 1
+            else:
+                n_b += 1
+        if only_diff and not verdict["hard_conclusion"]:
+            continue
+        comparisons.append({
+            "rxn": rid,
+            "a": {"pfba": ra["pfba"], "fva_min": ra["fva_min"], "fva_max": ra["fva_max"]},
+            "b": {"pfba": rb["pfba"], "fva_min": rb["fva_min"], "fva_max": rb["fva_max"]},
+            "overlap": verdict["overlap"],
+            "hard_conclusion": verdict["hard_conclusion"],
+            "direction": verdict["direction"],
+            "label": (LABEL_OVERLAP if verdict["overlap"]
+                      else (LABEL_A_HIGHER if verdict["direction"] == "a_higher" else LABEL_B_HIGHER)),
+        })
+    summary = {"total": len(scope), "hard_conclusions": n_hard,
+               "overlapping": len(scope) - n_hard, "a_higher": n_a, "b_higher": n_b}
+    return {"a": a_name, "b": b_name, "summary": summary, "comparisons": comparisons}
+
+
+def _export_csv(path, model_reactions, pair_results):
+    """全量 CSV：每行 = 条件对 × 反应（双侧区间/点值/判定）。返回 (rows, bytes)。"""
+    names = {r.id: r for r in model_reactions}
+    rows = 0
+    with open(path, "w", newline="", encoding="utf-8-sig") as f:
+        w = csv.writer(f)
+        w.writerow(["pair", "cond_a", "cond_b", "rxn", "reaction_name", "gpr",
+                    "a_pfba", "a_fva_min", "a_fva_max",
+                    "b_pfba", "b_fva_min", "b_fva_max",
+                    "overlap", "hard_conclusion", "direction", "label"])
+        for pr in pair_results:
+            key = f"{pr['a']}|vs|{pr['b']}"
+            for c in pr["comparisons"]:
+                rxn = names.get(c["rxn"])
+                w.writerow([key, pr["a"], pr["b"], c["rxn"],
+                            (rxn.name if rxn is not None else ""),
+                            (rxn.gpr if rxn is not None else ""),
+                            c["a"]["pfba"], c["a"]["fva_min"], c["a"]["fva_max"],
+                            c["b"]["pfba"], c["b"]["fva_min"], c["b"]["fva_max"],
+                            int(c["overlap"]), int(c["hard_conclusion"]),
+                            c["direction"] or "", c["label"]])
+                rows += 1
+    return rows, os.path.getsize(path)
+
+
+def fluxscan(model_path, conditions, reactions=None, pairs=None,
+             fraction_of_optimum=DEFAULT_FRACTION, tolerance=DEFAULT_TOL,
+             only_diff=False, export_csv=None, progress=None):
+    """M1 通量区间制主入口。conditions.name 必须唯一（重复直接报错）。
+    FVA/pFBA 恒全模型计算；reactions 仅收窄 comparisons/summary 口径（两者同口径）。"""
+    log = progress or (lambda s: sys.stderr.write(str(s) + "\n"))
+    if not conditions or not isinstance(conditions, list):
+        raise ValueError("conditions required（非空数组，每项 {name, medium, substrates?, carbon_mode?}）")
+    names = [c.get("name") for c in conditions]
+    if any(not n for n in names):
+        raise ValueError("every condition needs a name")
+    if len(set(names)) != len(names):
+        dup = sorted({n for n in names if names.count(n) > 1})
+        raise ValueError(f"conditions.name must be unique, duplicated: {dup}")
+
+    t0 = time.time()
+    m0 = silent_read_sbml(model_path)  # 仅用于 reaction 元数据/scope 校验
+    all_ids = [r.id for r in m0.reactions]
+    log(f"[fluxscan] model {model_path}: {len(all_ids)} reactions; "
+        f"fraction_of_optimum={fraction_of_optimum} tolerance={tolerance}")
+
+    if reactions:
+        idset = set(all_ids)
+        missing = [x for x in reactions if x not in idset]
+        scope = [x for x in reactions if x in idset]  # 保持用户给定顺序
+        if not scope:
+            raise ValueError(f"none of the given reactions exist in model; missing={missing[:10]}")
+    else:
+        missing = []
+        scope = all_ids
+
+    cond_names = set(names)
+    if pairs:
+        for p in pairs:
+            if len(p) != 2 or p[0] not in cond_names or p[1] not in cond_names:
+                raise ValueError(f"invalid pair {p!r}: need two existing condition names")
+    else:
+        pairs = [[names[i], names[j]] for i in range(len(names)) for j in range(i + 1, len(names))]
+
+    data_by_cond, info_by_cond = {}, {}
+    for cond in conditions:
+        cond = dict(cond)
+        cond["_fraction"] = fraction_of_optimum
+        data, info = _setup_condition(model_path, cond, log=log)
+        data_by_cond[info["name"]] = data
+        info_by_cond[info["name"]] = info
+
+    pair_results = [_pair_result(p[0], p[1], data_by_cond[p[0]], data_by_cond[p[1]],
+                                 scope, tolerance, only_diff) for p in pairs]
+    total_s = round(time.time() - t0, 1)
+
+    out = {
+        "model": model_path,
+        "fraction_of_optimum": fraction_of_optimum,
+        "tolerance": tolerance,
+        "units": "mmol/gDW/h",
+        "reactions_not_found": missing,
+        "conditions": [{k: v for k, v in info_by_cond[n].items() if not k.startswith("_")}
+                       for n in names],
+        "pairs": pair_results,
+        "timing_seconds": total_s,
+    }
+    if export_csv:
+        rows, size = _export_csv(export_csv, m0.reactions, pair_results)
+        out["export_csv"] = export_csv
+        out["export_csv_rows"] = rows
+        out["export_csv_bytes"] = size
+        log(f"[fluxscan] CSV {export_csv}: {rows} rows, {size} bytes")
+    log(f"[fluxscan] done in {total_s}s: {len(pair_results)} pairs, scope={len(scope)}")
+    return out
+
+
+if __name__ == "__main__":
+    # 双协议（历史坑：stdin 与 argv-file 两派并存，新脚本必须都支持）
+    if "--selftest" in sys.argv:
+        cases = [
+            # (la, ua, lb, ub, tol, direction, hard)  —— 任务书 5 组判定样例
+            (1.0, 2.0, 5.0, 6.0, 1e-6, "b_higher", True),      # ① 分离：b 高
+            (5.0, 6.0, 1.0, 2.0, 1e-6, "a_higher", True),      # ① 分离：a 高
+            (1.0, 3.0, 2.0, 4.0, 1e-6, None, False),           # ② 重叠（伪影）
+            (1.0, 3.0, 3.0, 5.0, 1e-6, None, False),           # ② 接触容差内仍 overlap（边界）
+            (-5.0, -2.0, 0.0, 0.0, 1e-6, "b_higher", True),    # ③ 零通量/负向
+            (-5.0, -2.0, 0.0, 0.0, 0.0, "b_higher", True),     # ④ 精确边界（tol=0）
+            # ⑤ 容差：锁定公式下 gap=5e-7 < tol=1e-6 -> overlap（任务书该行样例期望"分离"，
+            #    与锁定公式 ua+tol<lb 矛盾：5e-7 不大于 1e-6。按公式实现，差异上报 bsp 裁决）
+            (1.0, 1.0000005, 1.000001, 2.0, 1e-6, None, False),
+            # 同数字、tol(1e-7)<gap(5e-7) -> 分离：证明容差机制本身生效
+            (1.0, 1.0000005, 1.000001, 2.0, 1e-7, "b_higher", True),
+            (0.0, 0.0, 3.0, 5.0, 1e-6, "b_higher", True),      # 附加：单侧有通量
+            (3.0, 5.0, 0.0, 0.0, 1e-6, "a_higher", True),      # 附加：另一侧 [0,0]
+        ]
+        for la, ua, lb, ub, tol, d, h in cases:
+            v = judge_interval(la, ua, lb, ub, tol)
+            assert v["direction"] == d and v["hard_conclusion"] == h and v["overlap"] == (d is None), \
+                f"judge_interval({la},{ua},{lb},{ub},tol={tol}) -> {v}, expect direction={d} hard={h}"
+        print(json.dumps({"ok": True, "result": {"selftest": "pass", "cases": len(cases)}}))
+    else:
+        args = {}
+        if len(sys.argv) > 1:
+            with open(sys.argv[1], encoding="utf-8") as f:
+                args = json.load(f)
+        elif not sys.stdin.isatty():
+            args = json.loads(sys.stdin.read())
+        a = args.get("args", args)
+        print(json.dumps({"ok": True, "result": fluxscan(
+            a.get("model"), a.get("conditions"), reactions=a.get("reactions"),
+            pairs=a.get("pairs"), fraction_of_optimum=a.get("fraction_of_optimum", DEFAULT_FRACTION),
+            tolerance=a.get("tolerance", DEFAULT_TOL), only_diff=a.get("only_diff", False),
+            export_csv=a.get("export_csv"))}, ensure_ascii=False))