@dsh-bio/dsh-bio-gem 0.1.1

package/python/model_card.py

@@ -0,0 +1,248 @@
+# model_card.py — 模型卡 schema v2 统一写入器（B' 收尾 + Q2 工程质量件）
+# 职责: init_card（build 起卡）/ load / save / append_operation（lineage 版本递增 + changelog）
+#       / set_verified_phenotypes（phenotype 结果）/ set_essential_genes（必需基因 + 证据分级）
+# 纪律: 各工具完成后**仅当产物模型旁已有 card** 才向后追加；无卡不动（不凭空造卡）。
+# 兼容: build.py 旧卡（无 schema 字段）读取时即时迁移到 v2（新增字段缺失不报错）。
+# units: growth_rate 一律 mmol/gDW/h（schema v2 规定，勿用 1/h）。
+import os
+import json
+import time
+
+CARD_SUFFIX = ".card.json"
+SCHEMA = "v2"
+GROWTH_UNITS = "mmol/gDW/h"
+
+
+def _now():
+    return time.strftime("%Y-%m-%dT%H:%M:%S")
+
+
+def card_path_for(model_path):
+    return (model_path[:-4] if model_path.endswith(".xml") else model_path) + CARD_SUFFIX
+
+
+def load_card(model_path):
+    p = card_path_for(model_path)
+    if not os.path.exists(p):
+        return None
+    with open(p, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_card(model_path, card):
+    p = card_path_for(model_path)
+    with open(p, "w", encoding="utf-8") as f:
+        json.dump(card, f, ensure_ascii=False, indent=2)
+    return p
+
+
+def _ensure_v2(card):
+    """legacy 卡（build 直写，无 schema/lineage）即时迁移到 v2。
+    v3 卡（阶段A-M2 起，含 robustness 章节）视为已迁移，不降级。"""
+    if card.get("schema") in (SCHEMA, "v3") and "model_lineage" in card:
+        return card
+    card.setdefault("schema", SCHEMA)
+    card.setdefault("growth_units", GROWTH_UNITS)
+    card["model_lineage"] = {"version": "0.1.0", "operations": card.get("model_lineage", {}).get("operations", [])}
+    card.setdefault("changelog", [])
+    if not any("adopt" in str(x).lower() for x in card["changelog"]):
+        card["changelog"].append(f"{_now()} legacy card adopted into schema v2 (build-time fields preserved)")
+    return card
+
+
+def init_card(model_path, name=None, engine=None, changelog_note="build", **fields):
+    """build 起卡：已有字段 + schema v2 基座（lineage v0.1.0 起始, changelog=[build]）。幂等。"""
+    existing = load_card(model_path)
+    fresh = existing is None
+    card = existing or {"name": name or os.path.basename(model_path), "model": model_path,
+                        "created": _now()}
+    if engine:
+        card.setdefault("engine", engine)
+    card.update({k: v for k, v in fields.items() if v is not None})
+    if fresh:
+        card["schema"] = SCHEMA
+        card.setdefault("growth_units", GROWTH_UNITS)
+        card["model_lineage"] = {"version": "0.1.0", "operations": []}
+        card["changelog"] = []
+        if changelog_note:
+            card["changelog"].append(f"{_now()} {changelog_note}")
+    else:
+        _ensure_v2(card)
+    p = save_card(model_path, card)
+    return card, p
+
+
+def propagate_card(src_model_path, dst_model_path):
+    """把源模型旁的 card 复制到派生产物旁（dst 已有卡则不动）。
+    派生工具（gapfill/l3_fix/phenotype_fix/biomass_apply）产物是新文件——
+    先传播再 append_operation，保证派生模型自带完整 lineage。"""
+    sp, dp = card_path_for(src_model_path), card_path_for(dst_model_path)
+    if os.path.exists(sp) and not os.path.exists(dp):
+        import shutil
+        shutil.copyfile(sp, dp)
+        return dp
+    return None
+
+
+def append_operation(model_path, operation, reactions_added=0, reactions_removed=0, detail=None):
+    """模型旁已有 card 时追加操作记录：lineage 版本递增（patch 号）+ changelog push。
+    无 card 返回 None（调用方不应凭空造卡）。"""
+    card = load_card(model_path)
+    if card is None:
+        return None
+    _ensure_v2(card)
+    lin = card["model_lineage"]
+    major, minor, patch = str(lin.get("version", "0.1.0")).split(".")
+    lin["version"] = f"{major}.{minor}.{int(patch) + 1}"
+    op = {"seq": len(lin["operations"]) + 1, "at": _now(), "operation": operation,
+          "reactions_added": reactions_added, "reactions_removed": reactions_removed}
+    if detail:
+        op["detail"] = detail
+    lin["operations"].append(op)
+    card["changelog"].append(f"{_now()} {operation} (+{reactions_added}/-{reactions_removed})"
+                             + (f" — {json.dumps(detail, ensure_ascii=False)[:160]}" if detail else ""))
+    save_card(model_path, card)
+    return card
+
+
+def set_verified_phenotypes(model_path, phenotype_result, semantics="sole"):
+    """phenotype_fix 结果写入 card.verified_phenotypes。
+    phenotype_result: phenotype_fix() 返回（含 before/after/after_results/model）。"""
+    card = load_card(model_path)
+    if card is None:
+        return None
+    _ensure_v2(card)
+    after = phenotype_result.get("after") or {}
+    rows = []
+    for r in (phenotype_result.get("after_results") or []):
+        rows.append({"substrate": r.get("substrate"), "published": r.get("published"),
+                     "predicted": r.get("predicted"), "growth": r.get("growth"),
+                     "exchange": r.get("exchange"), "match": r.get("match"),
+                     "source": "phenotype_fix/G4-sole"})
+    card["verified_phenotypes"] = {
+        "semantics": semantics, "units": GROWTH_UNITS,
+        "matched": after.get("matched"), "total": after.get("total"),
+        "rate": after.get("rate"), "source": "gem_phenotype", "updated_at": _now(),
+        "results": rows,
+    }
+    save_card(model_path, card)
+    return card
+
+
+def set_essential_genes(model_path, scan_result, model=None):
+    """essential_scan 结果写入 card.essential_genes。
+    evidence_level: high_confidence 默认；基因支撑反应含 EVIDENCE_math（l3_fix 数学连接/
+    bounds 放宽）→ contains_EVIDENCE_math（必需性判定可能被数学证据反应影响，标注降置信）。"""
+    card = load_card(model_path)
+    if card is None:
+        return None
+    _ensure_v2(card)
+    math_rxn_ids = set()
+    if model is not None:
+        for r in model.reactions:
+            n = r.notes or {}
+            if n.get("evidence") == "EVIDENCE_math" or n.get("bound_relaxed_by"):
+                math_rxn_ids.add(r.id)
+    genes = []
+    for gid in (scan_result.get("essential_genes") or []):
+        lvl = "high_confidence"
+        try:
+            if model is not None and any(r.id in math_rxn_ids for r in model.genes.get_by_id(gid).reactions):
+                lvl = "contains_EVIDENCE_math"
+        except KeyError:
+            pass
+        genes.append({"gene_id": gid, "evidence_level": lvl})
+    n_math = sum(1 for g in genes if g["evidence_level"] != "high_confidence")
+    card["essential_genes"] = {
+        "units": GROWTH_UNITS, "medium_preset": scan_result.get("medium_preset"),
+        "wt_growth": scan_result.get("wt_growth"), "count": len(genes),
+        "n_contains_EVIDENCE_math": n_math, "source": "gem_essentiality", "updated_at": _now(),
+        "genes": genes,
+    }
+    save_card(model_path, card)
+    return card
+
+
+def set_robustness(model_path, sensitivity_result):
+    """sensitivity 结果写入 card.robustness（阶段A-M2：schema v3 起步，向后兼容 v2 卡只增字段）。
+    sensitivity_result: sensitivity() 返回（含 wt_growth_grid/stability/component_sensitivity/gam_carrier）。
+    无 card 返回 None（不凭空造卡——纪律同 set_essential_genes）。"""
+    card = load_card(model_path)
+    if card is None:
+        return None
+    _ensure_v2(card)
+    card["schema"] = "v3"  # v3 = v2 + robustness 章节（读取方按 JSON 字段访问，向后兼容）
+    grid = sensitivity_result.get("wt_growth_grid") or []
+    stab = sensitivity_result.get("stability") or {}
+    comp = (sensitivity_result.get("component_sensitivity") or {}).get("top_sensitive") or []
+    card["robustness"] = {
+        "units": GROWTH_UNITS,
+        "combinations": sensitivity_result.get("combinations"),
+        "baseline_reproduced": sensitivity_result.get("baseline_reproduced"),
+        "wt_growth_grid": [{"biomass": r.get("biomass"), "gam": r.get("gam"),
+                            "growth": r.get("growth"), "essential_count": r.get("essential_count")}
+                           for r in grid],
+        "stability": {"always_essential_count": len(stab.get("always_essential") or []),
+                      "always_essential": stab.get("always_essential") or [],
+                      "conditionally_essential_count": len(stab.get("conditionally_essential") or []),
+                      "conditionally_essential": stab.get("conditionally_essential") or [],
+                      "never_essential_count": stab.get("never_essential_count")},
+        "component_sensitivity_top": comp,
+        "gam_carrier": sensitivity_result.get("gam_carrier"),
+        "source": "gem_sensitivity", "updated_at": _now(),
+    }
+    save_card(model_path, card)
+    return card
+
+
+if __name__ == "__main__":
+    import sys, tempfile
+    # 自检（smoke 用，纯 JSON 层，秒级）：init → append ×2 → 版本递增 → phenotype/essential 形状
+    if "--selftest" in sys.argv:
+        d = tempfile.mkdtemp(prefix="card-selftest-")
+        mp = os.path.join(d, "selftest.xml")
+        open(mp, "w").close()
+        card, p = init_card(mp, name="selftest", engine="test", validations_m9={"g1": "PASS"})
+        assert card["model_lineage"]["version"] == "0.1.0" and card["schema"] == "v2"
+        c1 = append_operation(mp, "gapfill", reactions_added=2, detail={"note": "sucrose L1"})
+        assert c1["model_lineage"]["version"] == "0.1.1" and len(c1["changelog"]) == 2
+        c2 = append_operation(mp, "l3_fix", reactions_added=3)
+        assert c2["model_lineage"]["version"] == "0.1.2" and c2["model_lineage"]["operations"][0]["reactions_added"] == 2
+        set_verified_phenotypes(mp, {"after": {"matched": 13, "total": 19, "rate": 0.684},
+                                     "after_results": [{"substrate": "Arabinose", "published": 1,
+                                                        "predicted": 1, "match": True}]})
+        set_essential_genes(mp, {"essential_genes": ["NC_003062_2_1", "NC_003062_2_2"],
+                                 "wt_growth": 0.52, "medium_preset": "AB"}, model=None)
+        back = load_card(mp)
+        assert back["verified_phenotypes"]["matched"] == 13
+        assert back["essential_genes"]["count"] == 2
+        assert back["essential_genes"]["genes"][0]["evidence_level"] == "high_confidence"
+        # 阶段A-M2：robustness 章节（v2→v3 只增字段）+ 无 card 不造卡
+        assert set_robustness(mp + ".nonexistent", {"wt_growth_grid": []}) is None
+        c4 = set_robustness(mp, {"combinations": 22, "baseline_reproduced": True,
+                                 "wt_growth_grid": [{"biomass": 1.0, "gam": 40.0, "growth": 0.519981,
+                                                     "essential_count": 155}],
+                                 "stability": {"always_essential": ["g1"], "conditionally_essential": [],
+                                               "never_essential_count": 0},
+                                 "component_sensitivity": {"top_sensitive": [{"component": "cpd00023_c0",
+                                                                             "delta_pct": -12.5}]},
+                                 "gam_carrier": {"type": "inside_biomass", "gam_orig": 40.0}})
+        assert c4["schema"] == "v3" and c4["robustness"]["combinations"] == 22
+        assert c4["essential_genes"]["count"] == 2 and c4["model_lineage"]["version"] == "0.1.2"
+        # legacy 迁移
+        legacy = {"name": "legacy", "engine": "carveme", "growth_g3_m9": 0.782}
+        with open(card_path_for(mp), "w", encoding="utf-8") as f:
+            json.dump(legacy, f)
+        c3 = append_operation(mp, "gapfill", reactions_added=1)
+        assert c3["schema"] == "v2" and c3["model_lineage"]["version"] == "0.1.1" and c3["growth_g3_m9"] == 0.782
+        print('{"ok": true, "result": {"selftest": "pass", "version_after": "%s"}}' % back["model_lineage"]["version"])
+    else:
+        import json as _j
+        args = _j.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {}
+        model = args.get("model")
+        op = args.get("action", "show")
+        if op == "init":
+            card, p = init_card(model, name=args.get("name"), engine=args.get("engine"), **(args.get("fields") or {}))
+            print(_j.dumps({"ok": True, "result": {"card": p, "version": card["model_lineage"]["version"]}}))
+        else:
+            print(_j.dumps({"ok": True, "result": load_card(model)}))

package/python/phenotype_fix.py

@@ -0,0 +1,115 @@
+# phenotype_fix.py — 路线 A3：表型回填迭代
+# 流程: G4 表型对照（supplement）-> 失配底物逐个 gapfind 分级
+#       -> L1/L2 规则补洞（累积到新模型）-> L3 列候选清单 -> 重跑 G4 对比匹配率
+# 输出: {before_rate, after_rate, fixed, unresolved_L3, model}
+import os
+import sys
+import cobra
+
+from silentio import silent_read_sbml, silent_write_sbml
+from validate import validate_model
+from gapfind import find_gaps, expand_medium, resolve_medium
+from gapfill import apply_fixes
+
+
+def _note(*a):
+    """进度走 stderr（stdout 是 JSON 协议通道，绝不能污染）。"""
+    print(*a, file=sys.stderr)
+
+
+# 排除纯 N 源底物（sole 无碳时不长属正常，非缺口）
+N_SOURCES = {"nh3", "nitrate", "nitrite", "ammonia", "ammonium", "nitrogen", "urea"}
+def _is_n_source(name):
+    return (name or "").strip().lower() in N_SOURCES
+
+
+def phenotype_fix(model_path, phenotype_table=None, medium=None, max_add=20, out=None, ledger_path=None):
+    if not phenotype_table or not os.path.exists(phenotype_table):
+        return {"error": "phenotype_table 必需（TSV: substrate<TAB>published 0/1）"}
+    med, preset = expand_medium(medium)
+    med_resolved, unresolved = resolve_medium(silent_read_sbml(model_path), med) if med else ({}, [])
+
+    def g4_on(path):
+        rep = validate_model(path, medium=med, phenotype_table=phenotype_table,
+                             carbon_mode="sole")   # 缺口检测用唯一碳源语义（防 AB 葡萄糖掩盖）
+        g4 = rep.get("g4") or {}
+        if g4.get("status") == "SKIP":
+            return None, g4
+        return (g4.get("matched", 0), g4.get("total", 0)), g4
+
+    # before（sole 语义）
+    (bm, bt), g4b = g4_on(model_path)
+    before_rate = bm / bt if bt else None
+    targets = [x for x in (g4b.get("results") or [])
+               if x.get("published") == 1 and x.get("predicted") == 0
+               and not _is_n_source(x.get("substrate"))]
+    print(f"[before] 匹配 {bm}/{bt}（{before_rate:.1%}）；需修复底物 {len(targets)} 个", file=sys.stderr)
+
+    # 逐个修复（L1/L2 规则；L3 列清单）
+    cur = model_path
+    fixed, l3_list = [], []
+    if targets:
+        for t in targets:
+            gf = apply_fixes(cur, medium=med, substrates=[t["substrate"]],
+                             max_add=max_add, out=(out or (model_path[:-4] + "_pf.xml")))
+            new_fixed = gf.get("applied") or []
+            if new_fixed and gf.get("out"):
+                cur = gf["out"]  # 累积：后续修复基于最新模型
+            fixed.extend(new_fixed)
+            # L3 候选（gapfind 单独跑该底物）
+            gaps = find_gaps(cur, medium=med, substrates=[t["substrate"]])
+            for x in gaps.get("L3", []):
+                l3_list.append({"substrate": t["substrate"], **x})
+        print(f"修复 {len(fixed)} 项；L3 候选 {len(l3_list)} 个", file=sys.stderr)
+
+    # after
+    (am, at), g4a = g4_on(cur)
+    after_rate = am / at if at else None
+    print(f"[after] 匹配 {am}/{at}（{after_rate:.1%}）", file=sys.stderr)
+
+    result = {
+        "before": {"matched": bm, "total": bt, "rate": before_rate},
+        "after": {"matched": am, "total": at, "rate": after_rate},
+        "improved": (after_rate or 0) > (before_rate or 0),
+        "fixed": fixed,
+        "l3_remaining": l3_list,
+        "after_results": g4a.get("results") or [],
+        "model": cur,
+        "medium_preset": preset,
+        "medium_unresolved": unresolved,
+    }
+    # 模型卡 schema v2 回写（源模型旁有 card 才传播+追加；无卡不凭空造卡）
+    card_version = None
+    try:
+        from model_card import append_operation, load_card, propagate_card, set_verified_phenotypes
+        propagate_card(model_path, cur)
+        if load_card(cur) is not None:
+            set_verified_phenotypes(cur, result, semantics="sole")
+            card = append_operation(cur, "phenotype_fix", reactions_added=len(fixed),
+                                    detail={"before": result["before"], "after": result["after"],
+                                            "l3_remaining": len(l3_list)})
+            card_version = (card or {}).get("model_lineage", {}).get("version")
+    except Exception:
+        pass
+    result["card_version"] = card_version
+    # 阶段A-M3: prediction ledger 自动登记（每底物一条 G4 结果；幂等去重；失败仅 WARN）
+    try:
+        import ledger as _ledger
+        from model_card import load_card as _load_card
+        lineage_v = ((_load_card(cur) or {}).get("model_lineage") or {}).get("version")
+        cond = (preset or "custom") + "/sole"
+        result["ledger_registration"] = _ledger.register_phenotype(
+            cur, result.get("after_results") or [], condition=cond, lineage_version=lineage_v,
+            model=silent_read_sbml(cur), path=ledger_path)
+    except Exception as e:
+        print(f"[phenotype_fix] ledger registration WARN: {type(e).__name__}: {e}", file=sys.stderr)
+    return result
+
+
+if __name__ == "__main__":
+    import json
+    import sys
+    args = json.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {}
+    print(json.dumps(phenotype_fix(args.get("model"), args.get("phenotype_table"),
+                                   args.get("medium"), args.get("max_add", 20),
+                                   args.get("out")), ensure_ascii=False, indent=2))

package/python/roundtrip_check.py

@@ -0,0 +1,45 @@
+# roundtrip_check.py — SBML 往返保真自检（Q2 工程质量件 A）
+# cobra 读 → write_sbml_model → 读回：断言反应/代谢物/基因数一致 + GPR 字符串精确一致
+# （GLM 经典暗坑：序列化静默丢 GPR——fbc v2 写入路径回归护栏；≥5 个复合 GPR 反应样本必查）
+import os
+import sys
+import json
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+
+def roundtrip_check(model_path, min_complex_gpr=5):
+    from silentio import silent_read_sbml, silent_write_sbml
+    m = silent_read_sbml(model_path)
+    gpr = {r.id: r.gene_reaction_rule for r in m.reactions if r.gene_reaction_rule}
+    # 复合 GPR：and/or 混合或带括号（最容易在序列化中丢结构）
+    complex_ids = [k for k, v in gpr.items() if (" and " in v and " or " in v) or "(" in v]
+    out = os.path.join(tempfile.mkdtemp(prefix="gem-rt-"), os.path.basename(model_path))
+    silent_write_sbml(m, out)
+    m2 = silent_read_sbml(out)
+    gpr2 = {r.id: r.gene_reaction_rule for r in m2.reactions if r.gene_reaction_rule}
+    counts = {"reactions": [len(m.reactions), len(m2.reactions)],
+              "metabolites": [len(m.metabolites), len(m2.metabolites)],
+              "genes": [len(m.genes), len(m2.genes)]}
+    counts_ok = all(v[0] == v[1] for v in counts.values())
+    diffs = {k: {"before": gpr[k], "after": gpr2.get(k)} for k in gpr if gpr[k] != gpr2.get(k)}
+    sampled = sorted(complex_ids)[:min_complex_gpr]
+    sample_diffs = [k for k in sampled if gpr[k] != gpr2.get(k)]
+    return {
+        "ok": counts_ok and not diffs and len(sampled) >= min_complex_gpr and not sample_diffs,
+        "model": model_path,
+        "counts": counts,
+        "gpr_total": len(gpr), "gpr_complex_available": len(complex_ids),
+        "gpr_compared": len(sampled), "gpr_diffs": len(diffs), "gpr_sample_diffs": sample_diffs,
+        "detail_first_diffs": dict(list(diffs.items())[:3]),
+    }
+
+
+if __name__ == "__main__":
+    # 协议与 gem_ops 一致：JSON 走 stdin（smoke runPy 直传）；兼容 argv 文件
+    raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+    args = json.loads(raw) if raw.strip() else (
+        json.loads(open(sys.argv[1], encoding="utf-8").read()) if len(sys.argv) > 1 else {})
+    print(json.dumps(roundtrip_check(args.get("model"), args.get("min_complex_gpr", 5)),
+                     ensure_ascii=False, indent=2))

package/python/secretion.py

@@ -0,0 +1,179 @@
+# secretion.py — 阶段C-C1 可分泌代谢物谱（菌种通用）
+# 候选 = 介质层两级策略导出的交换反应（build_ex_index：EX_ 型与 boundary 型模型都适用）。
+# 可分泌判定 = production envelope 扫描：固定生长分数 {0.25,0.5,0.75,0.9,0.99,1.0} 下产物交换最大化
+#   （强制 biomass 通量 >= fraction*wt，最大化交换反应的分泌方向通量）；
+#   任一分数 >0 且产物交换 > 1e-6 → 可分泌。
+# 边界声明（方案文件要求，内置于输出）：未考虑毒性/渗透压/调控，纯拓扑/线性规划结果。
+# 退化护栏（阶段 A/B 教训）：被测模型 wt<=EPS（介质下不生长，如 AB 预设对非根瘤菌科物种——
+#   阶段B-B3 molybdate 教训）→ 不扫描不登记账本，输出 degenerate:true + 介质适配提示。
+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 build_ex_index, ex_index_is_boundary
+from essential_scan import setup_model_medium
+from sensitivity import find_biomass_gam
+
+EPS = 1e-6
+GROWTH_FRACTIONS = [0.25, 0.5, 0.75, 0.9, 0.99, 1.0]
+BOUNDARY_NOTE = "未考虑毒性/渗透压/调控，纯拓扑/线性规划结果"
+
+
+def _envelope_for(m, bio, rxn, wt, fractions):
+    """单候选 envelope：各生长分数下分泌方向最大通量。返回 (env_rows, max_prod, growth_at_max)。"""
+    met = list(rxn.metabolites)[0]
+    c = rxn.metabolites[met]
+    env, best, best_f = [], 0.0, None
+    for f in fractions:
+        with m:
+            bio.lower_bound = f * wt
+            m.objective = rxn
+            m.objective_direction = "max" if c < 0 else "min"
+            v = m.slim_optimize()
+        prod = round(abs(v), 6) if (v is not None and v == v) else 0.0
+        env.append({"fraction": f, "prod": prod})
+        if prod > best:
+            best, best_f = prod, f
+    return env, best, (best_f if best_f is not None else 0.0)
+
+
+def secretion(model_path, medium=None, fractions=None, export_csv=None,
+              ledger_refs=True, ledger_path=None, progress=None,
+              mode="full", summary_top=20):
+    """可分泌代谢物谱。
+    P0-1（2026-08-31 LBA9402 会话实测）：full 模式 185KB 输出被引擎省略截断，agent 绕道 bio_python
+    又不被防火墙背书 -> 死锁。mode=summary（op 层默认）只返回 top N 可分泌物（不含 envelope）；
+    完整数据请 export_csv 落盘 CSV，返回里给 full_data_file 显式路径。全量语义保持 mode=full。"""
+    log = progress or (lambda s: sys.stderr.write(str(s) + "\n"))
+    medium = medium or {"medium_name": "AB"}
+    fractions = sorted(fractions or GROWTH_FRACTIONS)
+    t0 = time.time()
+    m = silent_read_sbml(model_path)
+    idx = build_ex_index(m)
+    boundary_style = ex_index_is_boundary(idx)
+    resolved, unresolved, preset = setup_model_medium(m, medium)
+    gi = find_biomass_gam(m)
+    bio = m.reactions.get_by_id(gi["biomass_rxn"])
+    with m:
+        wt = m.optimize().objective_value
+    wt = round(float(wt), 6) if wt is not None else 0.0
+    log(f"[secretion] {model_path} medium={medium} wt={wt} candidates={len(set(idx.values()))} "
+        f"boundary_style={boundary_style}")
+
+    out = {
+        "model": model_path, "medium": medium, "medium_preset": preset,
+        "units": "mmol/gDW/h", "boundary_note": BOUNDARY_NOTE,
+        "growth_fractions": fractions, "boundary_style": boundary_style,
+        "candidates": len(set(idx.values())), "unresolved_medium": unresolved,
+        "wt_growth": wt,
+        "degenerate": wt <= EPS,
+    }
+    if out["degenerate"]:
+        out["degenerate_note"] = (f"wt_growth={wt}<=EPS：被测模型在指定介质下不生长，production envelope 无意义，"
+                                  "未扫描、未登记账本。提示：内置介质预设为根瘤菌科（C58）调校，非根瘤菌模型需先做介质适配"
+                                  "（阶段B-B3 教训：iML1515 严格 AB 缺 molybdate）。")
+        try:
+            from benchmark import medium_adaptation_hints
+            out["medium_adaptation_hints"] = medium_adaptation_hints(model_path, medium)
+        except Exception as e:
+            sys.stderr.write(f"[secretion] hints WARN: {type(e).__name__}: {e}\n")
+        log(f"[secretion] DEGENERATE wt={wt} <= EPS：不扫描不登记")
+        return out
+
+    rows = []
+    for rid in sorted(set(idx.values())):
+        rxn = m.reactions.get_by_id(rid)
+        mets = list(rxn.metabolites)
+        if len(mets) != 1:
+            continue  # 交换候选恒单代谢物；多代谢物防御性跳过
+        env, best, best_f = _envelope_for(m, bio, rxn, wt, fractions)
+        met = mets[0]
+        rows.append({"rxn": rid, "met_id": met.id, "name": met.name or "",
+                     "max_prod": best, "growth_at_max": round(best_f * wt, 6),
+                     "feasible": best > EPS, "envelope": env})
+    feasible = [r for r in rows if r["feasible"]]
+    log(f"[secretion] scan done: {len(rows)} candidates, {len(feasible)} feasible "
+        f"({round(time.time() - t0, 1)}s)")
+
+    # 账本登记（每个可分泌代谢物一条 type=secretion；幂等 sha256 去重）
+    reg = None
+    if ledger_refs:
+        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")
+            reg = _ledger.register_secretion(model_path, feasible, condition=cond,
+                                             lineage_version=lineage_v, path=ledger_path)
+            out["ledger_registration"] = reg
+            log(f"[secretion] ledger: appended={reg['appended']} skipped={reg['skipped_duplicates']}")
+        except Exception as e:
+            sys.stderr.write(f"[secretion] ledger registration WARN: {type(e).__name__}: {e}\n")
+
+    out.update({
+        "mode": mode,
+        "secretable_count": len(feasible),
+        "timing_seconds": round(time.time() - t0, 1),
+    })
+    if mode == "summary":
+        # P0-1：只返回 top N（瘦身：不含 envelope），防大输出省略截断
+        top = sorted(feasible, key=lambda r: r["max_prod"], reverse=True)[:summary_top]
+        slim = [{k: r[k] for k in ("rxn", "met_id", "name", "max_prod", "growth_at_max", "feasible")}
+                for r in top]
+        out["summary_top"] = len(slim)
+        out["summary_note"] = (f"summary 模式仅返回 top{len(slim)}（按 max_prod）可分泌条目，未内联 envelope 曲线；"
+                               f"完整 {len(feasible)} 条及 envelope 数据见 full_data_file（CSV）或用 mode=full。"
+                               f"本工具默认 summary 是为避免大输出被平台省略截断——不要在 summary 返回里找截断区数字。")
+        out["results"] = slim
+    else:
+        out["results"] = rows
+    if reg is not None:
+        out["ledger_registration"] = reg
+    if export_csv:
+        n = _export_csv(export_csv, rows, out)
+        out["export_csv"] = export_csv
+        out["export_csv_rows"] = n
+        out["export_csv_bytes"] = os.path.getsize(export_csv)
+        # 数据位置显式置顶提示字段（P0-1：agent 不再需要从省略输出里找数字）
+        out["full_data_file"] = export_csv
+        out["full_data_file_note"] = "完整可分泌清单+envelope 曲线的权威文件（以上输出无论 summary/full 均指此为准）"
+        log(f"[secretion] CSV {export_csv}: {n} rows")
+    elif mode == "summary":
+        out["full_data_file"] = None
+        out["full_data_file_note"] = ("本次未导出 CSV；需要完整可分泌清单请以 export_csv 参数指定落盘路径后重跑"
+                                      "（幂等，账本跳过重复）")
+    return out
+
+
+def _export_csv(path, rows, out):
+    n = 0
+    with open(path, "w", newline="", encoding="utf-8-sig") as f:
+        w = csv.writer(f)
+        w.writerow(["# boundary_note", out["boundary_note"]])
+        w.writerow(["rxn", "met_id", "name", "feasible", "max_prod", "growth_at_max",
+                    "fraction", "prod"])
+        for r in rows:
+            for e in r["envelope"]:
+                w.writerow([r["rxn"], r["met_id"], r["name"], int(r["feasible"]),
+                            r["max_prod"], r["growth_at_max"], e["fraction"], e["prod"]])
+                n += 1
+    return n
+
+
+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": secretion(
+        a.get("model"), medium=a.get("medium"), fractions=a.get("fractions"),
+        export_csv=a.get("export_csv"), ledger_refs=a.get("ledger_refs", True),
+        ledger_path=a.get("ledger_path"))}, ensure_ascii=False))