@dsh-bio/dsh-bio-gem 0.1.1

package/python/gapfill.py

@@ -0,0 +1,176 @@
+# gapfill.py — dsh-bio-gem 规则级补洞（L1 交换 / L2 转运，M1 不做 L3/MILP）
+# 防过补四闸门（ARCHITECTURE §6）：规则优先、max_add 封顶、逐条 provenance、修复后建议重验。
+# 用法: apply_fixes(model, medium=None, substrates=None, max_add=20, out=None)
+#       -> {"applied": [...], "skipped": [...], "out": path}
+import os
+import shutil
+import sys
+import cobra
+
+# Python -I isolated 模式下脚本目录不进 sys.path——显式插入以导入同目录 gapfind
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from gapfind import find_gaps, match_ex, build_ex_index, build_met_index, SYN, MET_ALIAS, norm
+
+
+def _new_e0_met(m, c0_id, tag):
+    """由胞内代谢物复制胞外 e0 版本（name/formula/charge 继承，compartment=e0）。"""
+    src = m.metabolites.get_by_id(c0_id)
+    e0_id = c0_id[:-3] + "_e0" if c0_id.endswith("_c0") else c0_id + "_e0"
+    if e0_id in m.metabolites:
+        return m.metabolites.get_by_id(e0_id)
+    new = cobra.Metabolite(e0_id, name=(src.name or ""),
+                           compartment="e0", formula=src.formula, charge=src.charge)
+    new.notes["source"] = "gem-gapfill"
+    new.notes["reason"] = f"L1: extracellular form of {c0_id} for exchange ({tag})"
+    m.add_metabolites([new])
+    return new
+
+
+def _add_ex_rxn(m, e0_met, tag):
+    ex_id = "EX_" + e0_met.id
+    if ex_id in m.reactions:
+        return None
+    r = cobra.Reaction(ex_id, name=(e0_met.name or "") + " exchange",
+                       lower_bound=0.0, upper_bound=1000.0)
+    r.add_metabolites({e0_met: -1})
+    m.add_reactions([r])
+    r.notes["source"] = "gem-gapfill"
+    r.notes["evidence"] = "EVIDENCE_rule"
+    r.notes["reason"] = f"L1: add exchange for medium component ({tag})"
+    return r
+
+
+def _add_tx_rxn(m, e0_id, c0_id, tag):
+    tx_id = "rxnGEM_tx_" + (e0_id.split("_")[0] if "_" in e0_id else e0_id)
+    if tx_id in m.reactions:
+        return None
+    r = cobra.Reaction(tx_id, name=(m.metabolites.get_by_id(e0_id).name or "") + " transport (gem)",
+                       lower_bound=-1000.0, upper_bound=1000.0)  # 转运默认开启（双向），否则补洞后仍无法流入
+    r.add_metabolites({m.metabolites.get_by_id(e0_id): -1,
+                       m.metabolites.get_by_id(c0_id): 1})
+    m.add_reactions([r])
+    r.notes["source"] = "gem-gapfill"
+    r.notes["evidence"] = "EVIDENCE_rule"
+    r.notes["reason"] = f"L2: connect extracellular {e0_id} to cytosol ({tag})"
+    return r
+
+
+def apply_fixes(model_path, medium=None, substrates=None, max_add=20, out=None, confirm_budget=False):
+    from silentio import silent_read_sbml, silent_write_sbml
+    if not (medium or substrates):
+        return {"error": "nothing to fix: provide medium and/or substrates"}
+    gaps = find_gaps(model_path, medium=medium, substrates=substrates)
+    m = silent_read_sbml(model_path)
+    # ---- 防过补第五闸门（全局预算）：本批计划 = 规则可修的 L1/L2 缺口数 ----
+    from budget import budget_gate
+    planned = sum(1 for g in (gaps["L1"] + gaps["L2"]) if g.get("fixable") == "yes")
+    gate = budget_gate(m, planned=planned, confirm_budget=confirm_budget)
+    if gate:
+        return {"ok": False, **gate, "gaps": {"L1": len(gaps["L1"]), "L2": len(gaps["L2"]),
+                                              "L3": len(gaps["L3"])}}
+    ex_idx = build_ex_index(m)
+    met_idx = build_met_index(m)
+    applied, skipped = [], []
+
+    def _budget():
+        return len(applied) < max_add
+
+    # ---- L1: 补交换 ----
+    for g in gaps["L1"]:
+        if not _budget():
+            skipped.append({**g, "why": "max_add cap"})
+            continue
+        if g["type"] == "exchange_missing":
+            mm = g["exchange"][3:]  # 去掉 EX_
+            base = mm[:-3] if mm.endswith("_e0") else mm
+            c0 = base + "_c0"
+            if c0 not in m.metabolites:
+                skipped.append({**g, "why": "no c0 metabolite to copy (unfixable by rules)"})
+                continue
+            e0 = _new_e0_met(m, c0, g["exchange"])
+            exr = _add_ex_rxn(m, e0, g["exchange"])
+            txr = _add_tx_rxn(m, e0.id, c0, g["exchange"])
+            if exr or txr:
+                applied.append({"type": "L1_exchange", "exchange": g["exchange"],
+                                "metabolite_e0": e0.id, "ex_rxn": exr.id if exr else None,
+                                "tx_rxn": txr.id if txr else None})
+        elif g["type"] in ("exchange_missing_name", "exchange_unresolved_name"):
+            key = norm(g["substrate"])
+            sid = met_idx.get(key)
+            if not sid:
+                s = SYN.get(g["substrate"].strip().lower())
+                if s:
+                    sid = met_idx.get(norm(s))
+            if not sid:
+                # MET_ALIAS：自然名 -> BiGG 短名（如 gluconate -> glcn）
+                al = MET_ALIAS.get((g["substrate"] or "").strip().lower())
+                if al:
+                    sid = met_idx.get(norm(al))
+            if not sid:
+                skipped.append({**g, "why": "no c0 metabolite by name (unfixable by rules)"})
+                continue
+            c0 = sid
+            e0 = _new_e0_met(m, c0, g["substrate"])
+            exr = _add_ex_rxn(m, e0, g["substrate"])
+            txr = _add_tx_rxn(m, e0.id, c0, g["substrate"])
+            if exr or txr:
+                applied.append({"type": "L1_exchange", "substrate": g["substrate"],
+                                "metabolite_e0": e0.id, "ex_rxn": exr.id if exr else None,
+                                "tx_rxn": txr.id if txr else None})
+
+    # ---- L2: 补转运 ----
+    for g in gaps["L2"]:
+        if not _budget():
+            skipped.append({**g, "why": "max_add cap"})
+            continue
+        if g["fixable"] != "yes":
+            skipped.append({**g, "why": "no c0 metabolite (unfixable by rules)"})
+            continue
+        e0_id = g["metabolite_e0"]
+        c0_id = g["metabolite_c0"]
+        txr = _add_tx_rxn(m, e0_id, c0_id, e0_id)
+        if txr:
+            applied.append({"type": "L2_transport", "metabolite_e0": e0_id,
+                            "metabolite_c0": c0_id, "tx_rxn": txr.id})
+        else:
+            skipped.append({**g, "why": "tx reaction already exists"})
+
+    # ---- L3: 仅报告（M1 不自动补）----
+    # ---- 保存 ----
+    if not applied:
+        return {"applied": [], "skipped": skipped, "gaps": gaps,
+                "out": None, "note": "no rule-level fix applied"}
+    out_path = out or (model_path[:-4] + "_gf.xml" if model_path.endswith(".xml") else model_path + "_gf.xml")
+    backup = None
+    # 只有就地覆写（out==model）才备份原文件；输出到新文件时原模型未被改动，无需备份
+    if os.path.normpath(out_path) == os.path.normpath(model_path):
+        backup = model_path + ".bak"
+        if not os.path.exists(backup):
+            shutil.copy2(model_path, backup)
+    silent_write_sbml(m, out_path)
+    # 模型卡 lineage 追加（源模型旁有 card 才传播+追加；无卡不凭空造卡）
+    card_version = None
+    try:
+        from model_card import append_operation, load_card, propagate_card
+        propagate_card(model_path, out_path)
+        if load_card(out_path) is not None:
+            card = append_operation(out_path, "gapfill", reactions_added=len(applied),
+                                    detail={"L1": sum(1 for a in applied if a["type"] == "L1_exchange"),
+                                            "L2": sum(1 for a in applied if a["type"] == "L2_transport")})
+            card_version = (card or {}).get("model_lineage", {}).get("version")
+    except Exception:
+        pass
+    return {"applied": applied, "skipped": skipped, "gaps": {
+        "L1": len(gaps["L1"]), "L2": len(gaps["L2"]), "L3": len(gaps["L3"])},
+        "out": out_path, "backup": backup, "fixed_rxns": len(applied),
+        "card_version": card_version}
+
+
+if __name__ == "__main__":
+    import json, sys
+    args = json.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {}
+    print(json.dumps(apply_fixes(args.get("model"), args.get("medium"),
+                                 args.get("substrates"), args.get("max_add", 20),
+                                 args.get("out"), args.get("confirm_budget", False)),
+                     ensure_ascii=False, indent=2))

package/python/gapfind.py

@@ -0,0 +1,397 @@
+# gapfind.py — dsh-bio-gem 缺口分级诊断（L1 缺交换 / L2 缺转运 / L3 内部路径）
+# 规格: docs/ARCHITECTURE.md §6；已知规律（P1 实测）：多数"不能利用某碳源"缺口是 L1/L2 而非 L3。
+# 用法: find_gaps(model, medium=None, substrates=None) -> {"L1": [...], "L2": [...], "L3": [...]}
+import os
+import re
+import sys
+import cobra
+
+# Python -I isolated 模式下脚本目录不进 sys.path——显式插入以导入同目录模块
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+EX_PREFIX = ("EX_", "DM_", "SK_")
+
+# 培养基常见成分别名（自然名 -> 模型代谢物名，去 -e0 后缀的小写形式）
+SYN = {
+    "orthophosphate": "phosphate", "oxygen": "o2", "l-ornithine": "ornithine",
+    "d-galactose": "galactose", "d-xylose": "xylose", "malate": "l-malate",
+    "mannose": "d-mannose", "ribose": "d-ribose", "mn": "mn2+",
+    "ca": "ca2+", "cl": "cl-", "k": "k+", "mg": "mg",
+    "sodium cation": "na+", "fe3+": "fe3", "fe2+": "fe2+",
+    "copper": "cu2+", "zinc cation": "zn2+", "biotin": "biot",
+    "thiamine": "thiamin", "raffinose": "trhl", "alpha,alpha-trehalose": "trhl",
+    "trehalose": "trhl", "4-aminobutanoate": "gaba", "akg": "2-oxoglutarate",
+    "fumarate": "fumarate", "beta-d-glucose": "d-glucose", "urea": "urea",
+    "galactonate": "d-galactonate", "lactose": "beta-lactose",
+    "mantiol": "d-mannitol", "maltotriose": "amylotriose",
+    "sn-glycerol 3-phosphate": "glycerol-3-phosphate",
+    "malic acid": "l-malate", "gluconate": "d-gluconate",
+    "glucose 1-phosphate": "glucose-1-phosphate", "glumate": "l-glutamate",
+}
+
+# CarveMe/BiGG 风格别名（跨引擎：gapseq 缩写 -> BiGG 全名；用于 resolve_medium）
+CARVE_ALIAS = {
+    "ca2+": "calcium", "k+": "potassium", "mg2+": "magnesium", "na+": "sodium",
+    "mn2+": "manganese", "zn2+": "zinc", "ni2+": "nickel", "cu2+": "copper",
+    "cl-": "chloride", "nh3": "ammonium", "nh4+": "ammonium", "ammonium": "ammonium",
+    "o2": "o2", "h2o": "h2o", "co2": "co2", "cobalt": "co2+", "co2+": "co2+",
+    "fe2+": "fe2+", "fe3+": "fe3+", "h+": "h+", "h": "h+",
+    "d-glucose": "d-glucose", "phosphate": "phosphate", "sulfate": "sulfate",
+    "glucose": "d-glucose", "ammonia": "ammonium",
+    # gapseq 命名（无 + 后缀）与 CarveMe 全名双候选
+    "mg": ["mg", "magnesium"], "mg2+": ["magnesium", "mg"],
+    "mn": ["mn2+", "manganese"], "zn": ["zn2+", "zinc"], "ca": ["ca2+", "calcium"],
+    "k": ["k+", "potassium"], "na": ["na+", "sodium"], "cl": ["cl-", "chloride"],
+    "fe": ["fe2+", "iron"],
+}
+
+# 常用介质预设（自然名成分 -> lb）。agent 只需传 {"medium_name": "AB"} 即可
+# 获得完整成分（金属离子绝不能省——gapseq 生物质方程直接消耗，缺金属生长恒 0）。
+MEDIA_PRESETS = {
+    "AB": {
+        "D-Glucose": -5, "NH3": -10, "O2": -12.5, "CO2": -15, "H+": -20, "H2O": -100,
+        "Phosphate": -10, "Sulfate": -10, "Cl-": -10, "Mn2+": -10, "Zn2+": -10,
+        "Co2+": -10, "Ni2+": -1, "Fe3+": -0.1, "Fe2+": -10, "Ca2+": -10, "Cu2+": -10,
+        "K+": -10, "Mg2+": -10, "Na+": -10,
+    },
+    "M9": {},  # 动态：由 _m9_preset() 从 carveme media_db 提取（BiGG ID 形式）
+}
+
+
+def _m9_preset():
+    """M9 预设：从 carveme media_db.tsv 提取（BiGG compound 名 -> EX_<c>_e，lb -10）。
+    找不到 carveme 时回退常用 M9 成分（BiGG ID 静态表）。"""
+    import csv
+    home = os.path.expanduser("~")
+    db = os.path.join(home, ".dsh", "dsh-bio-gem", "venv-carveme", "Lib",
+                      "site-packages", "carveme", "data", "input", "media_db.tsv")
+    comps = set()
+    if os.path.exists(db):
+        with open(db, encoding="utf-8") as f:
+            rd = csv.DictReader(f, delimiter="\t")
+            for row in rd:
+                if row.get("medium") == "M9" and row.get("compound"):
+                    comps.add(row["compound"].strip())
+    if comps:
+        return {"EX_" + c + "_e": -10.0 for c in sorted(comps)}
+    return {"EX_glc__D_e": -10.0, "EX_nh4_e": -10.0, "EX_o2_e": -12.5,
+            "EX_pi_e": -10.0, "EX_so4_e": -10.0, "EX_k_e": -10.0,
+            "EX_mg2_e": -10.0, "EX_ca2_e": -10.0, "EX_fe2_e": -10.0,
+            "EX_fe3_e": -0.1, "EX_mn2_e": -10.0, "EX_zn2_e": -10.0,
+            "EX_cobalt2_e": -10.0, "EX_ni2_e": -10.0, "EX_cu2_e": -10.0,
+            "EX_cl_e": -10.0, "EX_na1_e": -10.0, "EX_h2o_e": -100.0,
+            "EX_h_e": -20.0, "EX_co2_e": -15.0}
+
+
+def expand_medium(medium):
+    """medium 展开：支持 {"medium_name": "AB", ...覆盖成分}；M9 动态提取。
+    返回 (merged_dict, preset_name_or_None)。"""
+    if not medium:
+        return medium or {}, None
+    med = dict(medium)
+    name = med.pop("medium_name", None)
+    merged = {}
+    if name:
+        if name in MEDIA_PRESETS:
+            preset = MEDIA_PRESETS[name]
+            if name == "M9" and not preset:
+                preset = _m9_preset()
+            merged.update(preset)
+        else:
+            pass  # 未知预设：保留用户成分，调用方可记 unresolved
+    merged.update(med)
+    return merged, name
+
+
+# 代谢物 c0 短名别名（自然名/常用名 -> 模型胞内代谢物名；用于 L1 名字补洞）
+# 实测：gapseq 用 BiGG 短名（D-Gluconate-c0 名存为 'GLCN-c0'），SYN 只管 EX 名映射
+MET_ALIAS = {
+    "gluconate": "glcn", "d-gluconate": "glcn", "6-phospho-d-gluconate": "6pgc",
+    "sucrose": "sucrose", "glucose-1-phosphate": "glucose-1-phosphate",
+    "d-glucose-1-phosphate": "glucose-1-phosphate", "g1p": "glucose-1-phosphate",
+    "d-glucose": "d-glucose", "glucose": "d-glucose",
+    "l-malate": "mal__l", "malate": "mal__l", "malic acid": "mal__l",
+    "citrate": "cit", "succinate": "succ", "d-ribose": "rib__d", "ribose": "rib__d",
+}
+
+def norm(s):
+    return "".join(ch for ch in (s or "").strip().lower() if ch.isalnum() or ch in "+-")
+
+
+def build_met_index(m, compartment="c0"):
+    """胞内代谢物名索引（去 -c0 后缀小写）-> met id。"""
+    idx = {}
+    for x in m.metabolites:
+        if x.compartment == compartment:
+            nm = (x.name or "").strip().lower()
+            if nm.endswith("-c0"):
+                nm = nm[:-3]
+            if nm:
+                idx.setdefault(norm(nm), x.id)
+    return idx
+
+
+def build_ex_index(m):
+    """EX 交换名索引（去 -e0 后缀小写）-> EX 反应 id。
+    两级策略（阶段B）：
+      ① EX_/DM_/SK_ 前缀优先——现有行为逐字保留（仅 EX_ 前缀反应入索引）；
+      ② 仅当模型 EX_ 索引整体为空（全模型无 EX_ 前缀交换反应）时，回退用 boundary
+         单代谢物反应（恰好 1 个代谢物且 rxn.boundary=True）作为交换候选，返回
+         BoundaryExIndex（真实反应 id 为值；禁用受控子串层防跨命名空间误配）。
+    "单个名字未命中"不触发回退——有 EX_ 层的模型永不启用②（C58 零影响硬保证）。"""
+    idx = {}
+    for r in m.reactions:
+        if r.id.startswith("EX_"):
+            for x in r.metabolites:
+                nm = (x.name or "").strip().lower()
+                if nm.endswith("-e0"):
+                    nm = nm[:-3]
+                if nm:
+                    idx.setdefault(norm(nm), r.id)
+    if idx:
+        return idx
+    # 阶段B 两级策略②：EX_ 层整体缺失 -> boundary 单代谢物反应回退
+    bidx = BoundaryExIndex()
+    for r in m.reactions:
+        if r.boundary and len(r.metabolites) == 1:
+            x = next(iter(r.metabolites))
+            nm = (x.name or "").strip().lower()
+            if nm:
+                bidx.setdefault(norm(nm), r.id)
+            bidx.setdefault(norm("EX_" + x.id), r.id)  # 伪 EX 约定键（EX_M00081_e 形式可直传）
+            bidx.setdefault(norm(r.id), r.id)          # 真实反应 id 直键
+    return bidx
+
+
+def match_ex(sub, ex_idx, allow_substring=None):
+    """底物名 -> EX id；三层：精确(含 SYN 别名) -> CARVE_ALIAS -> 受控子串回退。
+    子串回退防误伤（2026-08-29 实测）：'o2' 曾命中 'R Acetoin C4H8O2'（名字尾部含 o2）
+    导致 O2 交换错配 -> 模型"AB 不生长"假象。规则：
+      - 短 key（<=4 且不含 '+'）：只允许前缀匹配（n.startswith(key)）
+      - 含 '+' 的 key（金属离子）：允许前缀或后缀（iron(fe3+)→ironfe3+ endswith fe3+）
+      - 长 key（>=5）：允许子串
+    阶段B：受控子串层可对单个索引禁用——boundary 回退索引（BoundaryExIndex）跨命名空间
+    短名易误配（实测 'd-glucose' ⊂ 'd-glucose1-phosphate' 会把 G1P 交换错当葡萄糖），
+    故其 allow_substring=False；普通 dict 索引默认 True，既有行为逐字保留。"""
+    key = norm(sub)
+    if key in ex_idx:
+        return ex_idx[key]
+    s = SYN.get((sub or "").strip().lower())
+    if s and norm(s) in ex_idx:
+        return ex_idx[norm(s)]
+    if allow_substring is None:
+        allow_substring = getattr(ex_idx, "allow_substring", True)
+    a = CARVE_ALIAS.get(key)
+    cands = a if isinstance(a, list) else [a]
+    for a in cands:
+        if not a:
+            continue
+        if a in ex_idx:
+            return ex_idx[a]
+        if not allow_substring:
+            continue  # boundary 回退索引：alias 展开的模糊匹配同样禁用（防 G1P 冒充葡萄糖类误配）
+        for n, rid in ex_idx.items():
+            if n.startswith(a) or (("+" in a or len(a) >= 5) and a in n):
+                return rid
+    if allow_substring is None:
+        allow_substring = getattr(ex_idx, "allow_substring", True)
+    if not allow_substring:
+        return None
+    for n, rid in ex_idx.items():
+        # 只做正向子串（key 是 n 的子串）；反向（n in key）误伤严重：
+        # "no" in "arabinose"、"co" in "gluconate"、"phosphate" in "glucose-1-phosphate"
+        if key in n:
+            if n.startswith(key):
+                return rid
+            if "+" in key or len(key) >= 5:
+                return rid
+    return None
+
+
+class BoundaryExIndex(dict):
+    """两级策略②的 boundary 回退索引（阶段B）。
+    仅当全模型无 EX_ 前缀交换反应时由 build_ex_index 产出；禁用受控子串回退层
+    （跨命名空间误配实证：d-glucose ⊂ d-glucose1-phosphate）。"""
+    allow_substring = False
+    boundary_style = True
+
+
+def ex_index_is_boundary(ex_idx):
+    """该索引是否为 boundary 回退型（boundary_style=True 的模型介质层）。"""
+    return isinstance(ex_idx, BoundaryExIndex)
+
+
+def has_ex_layer(m):
+    """模型是否有 EX_ 前缀交换层（决定是否启用 boundary 回退）。"""
+    return any(r.id.startswith("EX_") for r in m.reactions)
+
+
+def ex_display_name(m, rid):
+    """交换的规范展示名：boundary 型交换 -> EX_<met_id>（boundary-derived）；EX_ 型返回原 id。"""
+    try:
+        rxn = m.reactions.get_by_id(rid)
+    except Exception:
+        return rid
+    mets = list(rxn.metabolites)
+    if (not rid.startswith("EX_")) and len(mets) == 1:
+        return f"EX_{mets[0].id}（boundary-derived）"
+    return rid
+
+
+def resolve_medium(m, medium):
+    """介质字典 -> {EX_id: lb}。键可为 EX ID（直接用）或自然名/别名（跨引擎匹配）。
+    返回 (resolved, unresolved_names)。"""
+    ex_idx = build_ex_index(m)
+    resolved, unresolved = {}, []
+    for k, lb in (medium or {}).items():
+        if k.startswith("EX_") and k in m.reactions:
+            resolved[k] = lb
+            continue
+        exid = match_ex(k, ex_idx)
+        if exid:
+            resolved[exid] = lb
+        else:
+            unresolved.append(k)
+    return resolved, unresolved
+
+
+def _met_has_outlets(m, met_id):
+    """代谢物 e0 是否有非 EX 反应消耗（转运面）。"""
+    met = m.metabolites.get_by_id(met_id)
+    outlets = [r.id for r in met.reactions if not r.id.startswith(EX_PREFIX) and not r.boundary]
+    return outlets
+
+
+def _growth_with(m, medium, extra_ex, lb=-10.0):
+    """基底 medium + 额外交换 extra_ex G3 式判定；返回生长值。"""
+    with m:
+        for r in m.reactions:
+            if r.id.startswith(EX_PREFIX) or r.boundary:
+                r.lower_bound = 0.0
+        for rid, v in (medium or {}).items():
+            if rid in m.reactions:
+                m.reactions.get_by_id(rid).lower_bound = v
+        if extra_ex and extra_ex in m.reactions:
+            m.reactions.get_by_id(extra_ex).lower_bound = lb
+        return m.optimize().objective_value
+
+
+def _growth_with_solo(m, medium, extra_ex, lb=-10.0):
+    """严格语义：基底 medium 去掉含碳交换 + 额外交换（唯一碳源防 AB 背景掩盖）。
+    含碳判断用元素解析（parse_formula）——裸子串 'C' in formula 会把 Ca/Cl/Co/Cu 误滤
+    （2026-08-29 实测：氯被误滤后 sole 葡萄糖生长=0，造成 L3 假阳性）。"""
+    from silentio import silent_read_sbml
+    from validate import parse_formula
+    with m:
+        for r in m.reactions:
+            if r.id.startswith(EX_PREFIX) or r.boundary:
+                r.lower_bound = 0.0
+        for rid, v in (medium or {}).items():
+            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):
+                    continue  # 去碳
+                m.reactions.get_by_id(rid).lower_bound = v
+        if extra_ex and extra_ex in m.reactions:
+            m.reactions.get_by_id(extra_ex).lower_bound = lb
+        return m.optimize().objective_value
+
+
+def find_gaps(model_path, medium=None, substrates=None):
+    from silentio import silent_read_sbml
+    m = silent_read_sbml(model_path)
+    ex_idx = build_ex_index(m)
+    met_idx = build_met_index(m)
+    L1, L2, L3 = [], [], []
+
+    # medium 预设展开（支持 {"medium_name": "AB"|"M9"}）+ 跨引擎介质归一化
+    medium, preset_name = expand_medium(medium)
+    resolved_med, unresolved_names = resolve_medium(m, medium)
+
+    # ---- L1: 缺交换 ----
+    # (a) 用户显式声明的 EX ID 模型没有
+    for rid, lb in (medium or {}).items():
+        if rid.startswith("EX_") and rid not in m.reactions:
+            L1.append({
+                "type": "exchange_missing",
+                "exchange": rid, "medium_lb": lb,
+                "fixable": "yes" if _mids_exist(m, rid) else "no",
+            })
+    # (a2) 自然名匹配不到任何交换
+    for nm in unresolved_names:
+        L1.append({
+            "type": "exchange_unresolved_name", "substrate": nm,
+            "fixable": "yes" if _c0_exists(m, nm, met_idx) else "no",
+        })
+    # (b) 底物名匹配不到 EX（模型无对应交换）
+    for sub in (substrates or []):
+        exid = match_ex(sub, ex_idx)
+        if not exid:
+            L1.append({
+                "type": "exchange_missing_name", "substrate": sub,
+                "fixable": "yes" if _c0_exists(m, sub, met_idx) else "no",
+            })
+    # ---- L2: 缺转运（e0 代谢物无非 EX 出口）----
+    cand_e0 = set()
+    for rid, lb in resolved_med.items():
+        if rid.startswith("EX_") and rid in m.reactions:
+            for x in m.reactions.get_by_id(rid).metabolites:
+                if x.compartment == "e0":
+                    cand_e0.add(x.id)
+    for sub in (substrates or []):
+        exid = match_ex(sub, ex_idx)
+        if exid and exid in m.reactions:
+            for x in m.reactions.get_by_id(exid).metabolites:
+                if x.compartment == "e0":
+                    cand_e0.add(x.id)
+    for mid in sorted(cand_e0):
+        outlets = _met_has_outlets(m, mid)
+        if not outlets:
+            c0 = mid[:-3] + "c0" if mid.endswith("_e0") else None
+            L2.append({
+                "type": "transport_missing", "metabolite_e0": mid,
+                "metabolite_c0": c0 if c0 and c0 in m.metabolites else None,
+                "fixable": "yes" if (c0 and c0 in m.metabolites) else "no",
+            })
+
+    # ---- L3: 内部路径（有交换+转运但 FBA 不长；严格语义=唯一碳源防 AB 背景掩盖）----
+    for sub in (substrates or []):
+        exid = match_ex(sub, ex_idx)
+        if not exid or exid not in m.reactions:
+            continue  # L1 已报
+        g = _growth_with_solo(m, resolved_med, exid)
+        if g < 1e-6:
+            L3.append({"type": "internal_path", "substrate": sub,
+                       "exchange": exid, "growth": round(g, 6),
+                       "note": "需要文献反应或人工审核（M1 不自动补）"})
+
+    return {"L1": L1, "L2": L2, "L3": L3,
+            "medium_unresolved": unresolved_names,
+            "resolved_exchanges": sorted(resolved_med)}
+
+
+def _mids_exist(m, ex_id):
+    """EX_<mid>_e0 的形如解析，检查 mid 胞外/胞内是否存在。"""
+    mm = re.match(r"EX_(\S+?)_e0$", ex_id)
+    if not mm:
+        return False
+    base = mm.group(1)
+    c0 = base + "_c0"
+    e0 = base + "_e0"
+    return (c0 in m.metabolites) or (e0 in m.metabolites)
+
+
+def _c0_exists(m, sub, met_idx):
+    """底物名 -> 胞内代谢物是否存在（决定可否规则补交换+转运）。"""
+    key = norm(sub)
+    if key in met_idx:
+        return True
+    s = SYN.get((sub or "").strip().lower())
+    return bool(s and norm(s) in met_idx)
+
+
+if __name__ == "__main__":
+    import json, sys
+    args = json.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {}
+    print(json.dumps(find_gaps(args.get("model"), args.get("medium"), args.get("substrates")),
+                     ensure_ascii=False, indent=2))