@dsh-bio/dsh-bio-gem 0.1.1

package/python/validate.py

@@ -0,0 +1,393 @@
+# validate.py — dsh-bio-gem 五道验证关卡（M1）
+# G1 加载统计 / G2 内部反应元素平衡 / G3 生长真实性 / G4 底物表型(条件) / G5 必需基因抽检(条件)
+# 规格: docs/ARCHITECTURE.md §5；判据口径 = FBA objective_value（mmol/gDW/h，不用 μ）
+# 实现从 HANDOFF-03 五道关卡协议产品化（农杆菌项目验证过的逻辑）
+import re
+import os
+import json
+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_")
+CORE_ELEMS = ("C", "N", "P", "S")   # 硬核：不平衡必须 = 0
+REPORT_ELEMS = ("H", "O")           # 报告不阻塞
+ELM_RE = re.compile(r"([A-Z][a-z]?)(\d*)")
+
+# 关卡注册器（GLM 建议 + 2026-08-29 采纳）：未来加 G7 不改主流程
+GATE_REGISTRY = {}
+
+
+def register_gate(name):
+    def deco(fn):
+        GATE_REGISTRY[name] = fn
+        return fn
+    return deco
+
+
+def parse_formula(f):
+    """C10H13N5O13P3 -> {"C":10,...}; 忽略 R/X 等通用占位。"""
+    d = {}
+    if not f:
+        return d
+    for m in ELM_RE.finditer(f):
+        el = m.group(1)
+        n = int(m.group(2) or 1)
+        d[el] = d.get(el, 0) + n
+    return d
+
+
+def _rxn_elem_balance(rxn):
+    """内部反应元素平衡：返回 {elem: delta}（delta=产物-底物，应接近 0）。"""
+    bal = {}
+    for met, coeff in rxn.metabolites.items():
+        if not met.formula:
+            continue
+        d = parse_formula(met.formula)
+        for el, n in d.items():
+            bal[el] = bal.get(el, 0) + coeff * n
+    return bal
+
+
+class Validator:
+    def __init__(self, model_path):
+        from silentio import silent_read_sbml
+        self.path = model_path
+        self.m = silent_read_sbml(model_path)
+
+    # ------------------------------------------------------------------ G1
+    def g1_load(self):
+        m = self.m
+        from collections import Counter
+        repl = Counter()
+        bad_ids = []
+        for g in m.genes:
+            parts = g.id.split("_")
+            if len(parts) >= 3 and parts[0] == "NC":
+                repl["_".join(parts[:2])] += 1
+            else:
+                repl["other"] += 1
+                bad_ids.append(g.id)
+        n_genes_with_rxn = sum(1 for g in m.genes if len(g.reactions) > 0)
+        rep = {
+            "status": "PASS" if not bad_ids else "WARN",
+            "genes": len(m.genes), "reactions": len(m.reactions),
+            "metabolites": len(m.metabolites),
+            "replicons": dict(repl),
+            "non_nc_gene_ids": bad_ids[:10],
+            "gpr_gene_coverage": round(n_genes_with_rxn / len(m.genes), 4) if m.genes else 0,
+        }
+        return rep
+
+    # ------------------------------------------------------------------ G2
+    def g2_balance(self):
+        m = self.m
+        internal = [r for r in m.reactions
+                    if not (r.id.startswith(EX_PREFIX) or r.boundary)]
+        formula_coverage = sum(1 for x in m.metabolites if x.formula) / len(m.metabolites)
+        bad_core = {}   # elem -> [rxn ids]
+        bad_report = {}
+        checked = 0
+        for r in internal:
+            if not all(x.formula for x in r.metabolites):
+                continue  # 公式缺失不计入不平衡（先报覆盖率）
+            checked += 1
+            bal = _rxn_elem_balance(r)
+            for el in CORE_ELEMS:
+                v = bal.get(el, 0)
+                if abs(v) > 1e-6:
+                    bad_core.setdefault(el, []).append(r.id)
+            for el in REPORT_ELEMS:
+                v = bal.get(el, 0)
+                if abs(v) > 2:  # charged 公式惯例噪声容忍 ±2
+                    bad_report.setdefault(el, []).append(r.id)
+        n_bad = sum(len(v) for v in bad_core.values())
+        frac = 1.0 - n_bad / checked if checked else 0.0
+        status = "PASS" if n_bad == 0 else ("WARN" if frac >= 0.85 else "FAIL")
+        rep = {
+            "status": status,
+            "internal_reactions": len(internal), "formula_checked": checked,
+            "metabolite_formula_coverage": round(formula_coverage, 4),
+            "core_unbalanced": {k: len(v) for k, v in bad_core.items()},
+            "core_unbalanced_examples": {k: v[:5] for k, v in bad_core.items()},
+            "h_o_report": {k: len(v) for k, v in bad_report.items()},
+            "core_balance_frac": round(frac, 4),
+            # P0-2（2026-08-31 LBA9402 会话实测）：agent 会把 0.9985 心算换算成百分比而被防火墙拦——直接给原始百分数字段
+            "core_balance_frac_pct": round(frac * 100, 2),
+        }
+        return rep
+
+    # ------------------------------------------------------------------ G3
+    def g3_growth(self, medium, reference_growth=None):
+        """medium: {EX_id: lower_bound}; 三态：medium / no-carbon / all-closed。"""
+        m = self.m
+
+        def _setup(medium_dict):
+            for r in m.reactions:
+                if r.id.startswith(EX_PREFIX) or r.boundary:
+                    r.lower_bound = 0.0
+            for rid, lb in (medium_dict or {}).items():
+                if rid in m.reactions:
+                    m.reactions.get_by_id(rid).lower_bound = lb
+                else:
+                    return rid
+            return None
+
+        miss = _setup(medium or {})
+        if miss:
+            return {"status": "FAIL", "reason": f"medium exchange not in model: {miss}",
+                    "medium_provided": bool(medium)}
+        with m:
+            wt = m.optimize().objective_value
+        # no-carbon: 去掉 formula 含 C 的交换
+        no_c_medium = dict(medium or {})
+        for rid in list(no_c_medium):
+            if rid.startswith("EX_") and 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 no_c_medium[rid]
+        miss = _setup(no_c_medium)
+        with m:
+            g_no_c = m.optimize().objective_value
+        miss = _setup({})  # all closed
+        with m:
+            g_closed = m.optimize().objective_value
+        ok_grow = wt > 1e-6
+        ok_noc = abs(g_no_c) < 1e-6
+        ok_closed = abs(g_closed) < 1e-6
+        ratio = None
+        if reference_growth and reference_growth > 0:
+            ratio = wt / reference_growth
+        if not medium:
+            status = "WARN"  # 无声明培养基 -> 无法验证
+        elif ok_grow and ok_noc and ok_closed and (ratio is None or ratio >= 0.99):
+            status = "PASS"
+        else:
+            status = "FAIL"  # 有培养基但生长不达标（或对照泄漏）——构建侧必须走补洞闭环
+        rep = {
+            "status": status,
+            "medium_provided": bool(medium),
+            "growth_medium": round(wt, 6),
+            "growth_no_carbon": round(g_no_c, 6),
+            "growth_all_closed": round(g_closed, 6),
+            "ratio_vs_reference": round(ratio, 4) if ratio is not None else None,
+            "checks": {"medium>0": ok_grow, "no_carbon==0": ok_noc, "closed==0": ok_closed},
+            # 阶段A-M4 口径声明（只增）：单点 FBA 值非硬结论
+            "units": "mmol/gDW/h",
+            "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
+        }
+        return rep
+
+    # ------------------------------------------------------------------ G6
+    @register_gate("G6")
+    def g6_atp_leak(self, context=None):
+        """ATP 泄漏测试（MEMOTE 核心测试；G3 all-closed 的必要不充分检查）：
+        全关交换后最大化 ATP 代谢物的净消耗（demand），通量 > 0.01 → WARN。
+        补洞后必跑（context.post_gapfill 时不再跳过）。
+        P1-5 修复（2026-08-31 LBA9402 会话实测）：CarveMe 模型 ATP id 为 M_atp_c，
+        旧匹配只看 atp_c/cpd00002_c0 -> 误 SKIP「未找到 ATP」——扩展命名模式 + SKIP 时列出尝试模式与模型内候选。"""
+        m = self.m
+        atp_patterns = ("atp_c", "cpd00002_c0", "m_atp_c", "atp_c0", "cpd00002", "atp")
+        cands = [x for x in m.metabolites if (x.id or "").lower() in atp_patterns]
+        cyto = [x for x in cands if x.compartment in ("c0", "c")]
+        atp_c = (cyto or cands or [None])[0]
+        if atp_c is None:
+            atp_like = sorted({x.id for x in m.metabolites if "atp" in (x.id or "").lower()})[:10]
+            return {"status": "SKIP",
+                    "reason": "未找到 ATP 代谢物（已尝试命名模式: " + ", ".join(atp_patterns) + "）",
+                    "tried_patterns": list(atp_patterns),
+                    "atp_like_ids_in_model": atp_like,
+                    "note": "SKIP 系命名口径未命中（非模型缺陷证明）；若模型含 ATP 但 id 不在尝试模式中，"
+                            "补充模式或标注 atp 角色后重跑"}
+        dm = cobra.Reaction("DM_gem_atp_leak", name="G6 ATP 泄漏检测 demand",
+                            lower_bound=0.0, upper_bound=1000.0)
+        dm.add_metabolites({atp_c: -1})
+        m.add_reactions([dm])
+        try:
+            with m:
+                for r in m.reactions:
+                    if r.id.startswith(EX_PREFIX) or r.boundary:
+                        r.lower_bound = 0.0
+                v = m.optimize().objective_value
+        finally:
+            m.remove_reactions([dm])
+        leak = abs(v)
+        status = "PASS" if leak <= 0.01 else "WARN"
+        return {"status": status, "atp_leak_flux": round(leak, 6),
+                "atp_metabolite_found": atp_c.id,
+                "threshold": 0.01, "post_gapfill": bool((context or {}).get("post_gapfill")),
+                "note": "全关交换后 ATP demand 通量应≈0；>0.01 提示能量循环泄漏（L3 MILP 补洞最可能引入）"}
+
+    # ------------------------------------------------------------------ G4
+    def g4_phenotype(self, table_path=None, substrates=None, medium=None, carbon_mode="supplement"):
+        """条件执行：需参照表（TSV: substrate<TAB>published 0/1）或 substrates+published。
+        carbon_mode: supplement=基准培养基不变+底物-10（对齐 HANDOFF-03 关卡4 基线 16/19→17/19）；
+                     sole=去含碳交换后底物-10（唯一碳源严格语义，氮源类测试会误判）。"""
+        if table_path and os.path.exists(table_path):
+            rows = []
+            with open(table_path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.rstrip("\r\n")
+                    if not line or line.startswith("#") or line.startswith("substrate"):
+                        continue
+                    p = line.split("\t")
+                    if len(p) >= 2:
+                        rows.append((p[0].strip(), int(float(p[1]))))
+        elif substrates:
+            rows = substrates
+        else:
+            return {"status": "SKIP", "reason": "no phenotype reference provided"}
+        if not medium:
+            return {"status": "SKIP", "reason": "G4 needs medium to define base"}
+        from gapfind import build_ex_index, match_ex, SYN
+        m = self.m
+        # 统一走 gapfind 的 build_ex_index + match_ex（修复过子串误配规则；勿再各自实现）
+        ex_idx = build_ex_index(m)
+        results = []
+        matched = 0
+        for sub, pub in rows:
+            exid = match_ex(sub, ex_idx)
+            # 基底：medium（supplement）或去碳后加底物（sole）
+            med2 = dict(medium)
+            if carbon_mode == "sole":
+                for rid in list(med2):
+                    if rid.startswith("EX_") and 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]
+            if exid and exid in m.reactions:
+                med2[exid] = -10.0
+            for r in m.reactions:
+                if r.id.startswith(EX_PREFIX) or r.boundary:
+                    r.lower_bound = 0.0
+            for rid, lb in med2.items():
+                if rid in m.reactions:
+                    m.reactions.get_by_id(rid).lower_bound = lb
+            with m:
+                g = m.optimize().objective_value
+            pred = g > 1e-6
+            ok = (pred == bool(pub))
+            if ok:
+                matched += 1
+            results.append({"substrate": sub, "published": int(pub), "predicted": int(pred),
+                            "growth": round(g, 6), "exchange": exid or None, "match": bool(ok),
+                            # 阶段A-M4 口径声明（只增）：每底物 growth 为单点 FBA 值
+                            "units": "mmol/gDW/h",
+                            "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"})
+        rep = {
+            "status": "PASS" if rows and matched / len(rows) >= 0.8 else ("WARN" if rows else "SKIP"),
+            "carbon_mode": carbon_mode,
+            "matched": matched, "total": len(rows),
+            "rate": round(matched / len(rows), 4) if rows else None,
+            "results": results,
+        }
+        return rep
+
+    # ------------------------------------------------------------------ G5
+    def g5_essentiality(self, essential_test, medium, reference_essential=None):
+        """条件执行：对给定基因列表逐一手工敲除（with m: 循环），输出每个基因的必要性。
+        若给 reference_essential（已知必需基因集）→ 对交集算召回。"""
+        if not essential_test:
+            return {"status": "SKIP", "reason": "no essential_test gene list provided"}
+        if not medium:
+            return {"status": "SKIP", "reason": "G5 needs medium"}
+        m = self.m
+        present = [g for g in essential_test if g in m.genes]
+        if len(present) / len(essential_test) < 0.8:
+            return {"status": "SKIP", "reason": "gene mapping coverage < 80%",
+                    "present": len(present), "total": len(essential_test)}
+        results = []
+        for gid in present:
+            with m:
+                for r in m.reactions:
+                    if r.id.startswith(EX_PREFIX) or r.boundary:
+                        r.lower_bound = 0.0
+                for rid, lb in medium.items():
+                    if rid in m.reactions:
+                        m.reactions.get_by_id(rid).lower_bound = lb
+                m.genes.get_by_id(gid).knock_out()
+                g = m.optimize().objective_value
+            results.append({"gene": gid, "growth": round(g, 6),
+                            "essential": bool(g < 1e-6)})
+        n_ess = sum(1 for r_ in results if r_["essential"])
+        recall = None
+        if reference_essential:
+            ref = set(reference_essential)
+            tp = sum(1 for r_ in results if r_["essential"] and r_["gene"] in ref)
+            recall = round(tp / len(ref), 4) if ref else None
+        rep = {
+            "status": "PASS" if (recall is None or recall >= 0.4) else "WARN",
+            "tested": len(results), "essential_found": n_ess,
+            "recall_vs_reference": recall,
+            "details": results,
+        }
+        return rep
+
+    # ------------------------------------------------------------------ run
+    def run(self, medium=None, phenotype_table=None, essential_test=None,
+            reference_growth=None, reference_essential=None, carbon_mode="supplement",
+            context=None):
+        from gapfind import resolve_medium, expand_medium
+        medium, _preset = expand_medium(medium)
+        resolved_med, unresolved = resolve_medium(self.m, medium) if medium else ({}, [])
+        report = {"model": self.path,
+                  "units": {"growth": "mmol/gDW/h", "note": "objective_value 是 FBA 通量（mmol/gDW/h），不是比生长速率 μ（h⁻¹）"},
+                  "g1": self.g1_load(),
+                  "g2": self.g2_balance(),
+                  "g6": self.g6_atp_leak(context=context or {})}
+        g3 = self.g3_growth(resolved_med, reference_growth)
+        if unresolved:
+            g3["medium_unresolved"] = unresolved
+        report["g3"] = g3
+        if phenotype_table:
+            report["g4"] = self.g4_phenotype(table_path=phenotype_table, medium=resolved_med,
+                                             carbon_mode=carbon_mode)
+        else:
+            report["g4"] = {"status": "SKIP", "reason": "no phenotype reference provided"}
+        if essential_test:
+            report["g5"] = self.g5_essentiality(essential_test, resolved_med, reference_essential)
+        else:
+            report["g5"] = {"status": "SKIP", "reason": "no essential_test provided"}
+        # 总判定：G1/G2/G3/G6（FATAL 才 FAIL；G6 WARN 级不阻塞但补洞后必查）
+        blocked = ["g1", "g2", "g3"]
+        fails = [k for k in blocked if report[k]["status"] == "FAIL"]
+        warns = [k for k in blocked if report[k]["status"] == "WARN"]
+        report["overall"] = "FAIL" if fails else ("WARN" if warns else "PASS")
+        report["blocking"] = blocked
+        return report
+
+
+def validate_model(model_path, medium=None, phenotype_table=None,
+                   essential_test=None, reference_growth=None, reference_essential=None,
+                   carbon_mode="supplement"):
+    v = Validator(model_path)
+    return v.run(medium=medium, phenotype_table=phenotype_table,
+                 essential_test=essential_test, reference_growth=reference_growth,
+                 reference_essential=reference_essential, carbon_mode=carbon_mode)
+
+
+if __name__ == "__main__":
+    # 命令行直跑（开发/测试用）：python validate.py <model.xml> [--medium-json x] [--table t] [--g5 g1,g2]
+    import sys
+    path = sys.argv[1]
+    med = None
+    table = None
+    g5 = None
+    refg = None
+    i = 2
+    while i < len(sys.argv):
+        if sys.argv[i] == "--medium-json" and i + 1 < len(sys.argv):
+            med = json.loads(sys.argv[i + 1]); i += 2
+        elif sys.argv[i] == "--table" and i + 1 < len(sys.argv):
+            table = sys.argv[i + 1]; i += 2
+        elif sys.argv[i] == "--g5" and i + 1 < len(sys.argv):
+            g5 = sys.argv[i + 1].split(","); i += 2
+        elif sys.argv[i] == "--ref-growth" and i + 1 < len(sys.argv):
+            refg = float(sys.argv[i + 1]); i += 2
+        else:
+            i += 1
+    rep = validate_model(path, medium=med, phenotype_table=table, essential_test=g5,
+                         reference_growth=refg)
+    print(json.dumps(rep, ensure_ascii=False, indent=2))

package/skills/gem-expert.md

@@ -0,0 +1,88 @@
+---
+language: mixed
+---
+
+# dsh-bio-gem 主指引：基因组 → 可验证代谢模型（GEM）
+
+任何「代谢模型 / GEM / 基因组建模型 / 模型验证 / 模型补洞」需求先加载本 skill。
+
+## 工具分层（按任务选，别乱用）
+
+| 任务 | 工具 |
+|---|---|
+| 已有 SBML 模型文件，想知道概要（基因/反应/复制子）| `gem_report`（model 参数=绝对路径）|
+| 验证模型质量（五道关卡：加载/元素平衡/生长真实性/表型/必需性抽检）| `gem_validate`（model + medium）|
+| 模型在目标培养基不长，想知道为什么 | `gem_gapfind`（model + medium + substrates）|
+| gapfind 判 L3（内部路径）后自动补洞（白名单/MILP）| `gem_l3_fix`（model + medium + substrates；allow_math=true 才放数学连接；补后自动跑 G6 防能量循环）|
+| 看/改 biomass（FBA 目标函数）| `gem_biomass`（action=inspect 只读组分/对照参考；apply 显式 profile + 三联对照，原文件不动可回滚）|
+| 按缺口自动补洞（缺交换/转运规则修复）| `gem_gapfill`（model + medium）→ 补完重跑 `gem_validate` |
+| 从细菌基因组（蛋白 FASTA 或核苷酸 .fna）构建模型 | `gem_build`（input + 可选 target_medium；fna 自动注释）|
+| 只有裸基因组 .fna，先要蛋白序列 | `gem_annotate`（fna → faa；官方优先 + pyrodigal 兜底）|
+| 需要模型的全量必需基因清单 | `gem_essentiality`（FVA 预筛 + 手工敲除；medium 推荐 AB）|
+| 跨条件通量对比（哪个反应真变了）| `gem_fluxscan`（区间制：FVA 区间+pFBA 点值，区间分离=硬结论，overlap=伪影禁止引用）|
+| 量化模型不确定性（biomass/GAM 扰动下预测稳不稳）| `gem_sensitivity`（22 组合网格+稳定性三分类+单组分漂移；action=probe 秒级探测）|
+| 查询/更新模型预测（必需性/表型预测追踪与实验兑现）| `gem_ledger`（list/query/update；预测默认 unverified，兑现后回填状态）|
+| 两个模型规范对比（论文级基准表）| `gem_benchmark`（model_a+model_b：六关并列/生长/biomass 断供探针/必需性对比[退化侧只报结构]/表型/账本回填；export_md 落盘）|
+| 看模型能产/能分泌什么（L1 拓扑）| `gem_secretion`（production envelope 扫描；边界声明=纯拓扑 LP 结果，可分泌≠会分泌）|
+| 找合成致死基因对（L2 非平凡预测）| `gem_double_knockout`（GPR 穷尽先验+全扫预算；假设生成供实验设计参考非结论）|
+| 必需基因的功能解读（哪些通路富集）| `gem_enrichment`（超几何+BH FDR；通路源=SBML groups[MetaCyc]；无注释如实兜底）|
+| 给实验/编辑工具出靶点清单 | `gem_targets`（账本三类预测 -> 锁定 schema CSV/JSON；引物设计不做）|
+| 用 Biolog/文献表型表校准模型（提升匹配率）| `gem_phenotype`（phenotype_table + medium；自动补 L1/L2）|
+| 把自然名培养基转成模型交换（消费方统一入口）| `gem_media_resolve`（model + medium → EX ID 列表）|
+| gapseq 质量重建（需 WSL2）| `gem_gapseq`：setup → launch →（循环 status 直到 done）→ fetch，agent 编排 |
+| 需要跑 FBA/必需性/生产包络线分析 | 用 dsh-bio-genie 的 `bio_fba` / `bio_gene_knockout` / `bio_production_envelope` 等（模型文件直接用）|
+
+## 推荐工作流
+
+```
+基因组（蛋白 FASTA）
+  └─ gem_build(engine=carveme) ──► SBML + 模型卡（内置 M9 介质验证 G1-G3；target_medium 可选）
+        ├─ 通过 → gem_report 看概要 / gem_validate 全检 / 交给 bio_fba 等分析
+        └─ 目标介质 FAIL → gem_gapfind 分级诊断
+              ├─ L1 缺交换 / L2 缺转运 → gem_gapfill 自动补 → 重验
+              └─ L3 内部路径 → 诚实报告（需文献反应，不自动补）
+
+基因组（核苷酸 .fna，质量档）
+  └─ gem_gapseq 原子编排：setup（探测）→ launch（后台 doall，30-60min 不等）→
+     status 循环（2-5min/次，running 时不要干等可并行处理其他）→ fetch（产物拷回）
+     → gem_validate / gem_gapfind / gem_gapfill 继续质量闭环
+
+裸基因组（.fna）纯 Windows
+  └─ gem_annotate（fna→faa）→ gem_build(engine=carveme) → 验证/补洞闭环
+     （gem_build 内部自动调注释层；也可先 gem_annotate 单独出蛋白）
+
+模型质量进阶
+  └─ gem_essentiality（全量必需基因→模型卡章节）
+  └─ gem_phenotype（表型回填迭代，按 Biolog/文献表校准）
+  └─ gem_media_resolve（介质解析——任何下游要跑 FBA 前先解析介质）
+```
+
+## 硬规则（实测，违反会拿错结果）
+
+0. **外部事实断言必须带证据**（2026-08-29 采纳 GLM 教训）：凡涉及"某物种/文献/工具是否存在、是否已发表"等**模型外事实断言**，agent 必须真实检索并附来源（如 PubMed/PMC 链接）；无法检索时降级表述为"未验证假设 [假设]"，不得由记忆下断言。此项与 EVIDENCE 分级同位：**事实断言也有证据分级**（检索+来源=high；仅记忆=unverified）。
+1. **培养基一律用自然名成分**：`{"D-Glucose": -5, "NH3": -10, "O2": -12.5, ...}`。插件跨引擎自动解析（gapseq EX_cpdXXXXXX_e0 与 CarveMe/BiGG EX_glc__D_e 命名空间不同，硬编码 ID 会失配）。
+2. **数字必须来自工具输出**：agent 报告生长值/基因数/复制子数时引用工具 result，不要凭模型知识猜测（防幻觉铁律）。**生长值单位是 mmol/gDW/h（FBA 通量），不是 h⁻¹/μ**——汇报时不要换算成比生长速率。
+3. **CarveMe 模型的介质边界**：`gem_build` 默认在 M9 最小培养基验证（生长阳性）；**AB 等自定义培养基若 FAIL 且 gapfind 判定 L3（内部路径），规则补洞修不了**——此时如实报告「模型可用介质=M9，目标介质需要 L3 级文献补充」，绝不要假装自愈。
+4. **缺口 90% 是 L1/L2**（缺交换/转运，非缺分解酶）——先诊断再补，别直接加反应。
+5. **多复制子正常**：质粒/多染色体基因都在同一模型内（C58 实测 4 复制子：967/434/65/18 基因分布于 ChrⅠ/ChrⅡ/pTi/pAt）。
+6. **通量区间制（阶段A-M4 硬规则）**：无区间不点数——任何条件间通量对比必须消费 `gem_fluxscan` 的区间分离判定；两条件区间分离才是解空间无关硬结论（a_higher/b_higher）；overlap 反应的任何点值 diff 必须标注"伪影，禁止引用"。单点 FBA 生长/通量值（gem_validate/gem_phenotype/gem_essentiality 等输出）只是该条件下的一个解，跨条件直接 diff 是求解器伪影。
+7. **模型指代消歧（阶段D-E2E 硬规则）**：用户说"我们的 C58 模型"等未给路径的指代时——①先查预测账本（`gem_ledger query` 按 model 前缀）与项目档案中已登记的 canonical 路径；②同一名字存在多个模型（如 gapseq 原版 vs carveme 重建）时，必需性/富集等锚点敏感分析必须用登记在案的原始版本或向用户确认，并说明选择了哪个文件；③不同引擎重建的同一物种是不同模型（基因数/必需集都不同），不得混用结论。
+8. **文件出处/来源推断必须标注 [推断]（阶段D-P2 硬规则）**：凡非本次会话工具 result 直接给出、而是凭文件名/目录布局/常识推断的出处（如"这个 faa 是 gem_annotate 产出的"），汇报时必须标注 [推断]；可验证时先验证再陈述。例证：阶段 D 轮 1 agent 称 faa 为"前面流程 gem_annotate 产出"——事实上正确但出自文件名推断而非会话验证。
+
+## C58 回归锚（验证工具是否正常）
+
+- 未知 → `gem_validate` 对 C58.xml（AB 自然名介质）→ G1 PASS / G3 PASS 生长 **0.519981** / 无碳源 0
+- gapfind 对 C58.xml + 蔗糖 → L1（缺 EX_cpd00076_e0，fixable yes）
+- gapfill 后蔗糖生长 **0.97077**（与手工 P1 补洞一致）
+- gem_build 对 C58 protein.faa → M9 G3 PASS（growth>0），全流程 ~70s
+- gem_fluxscan（区间制）对 C58.xml：条件 {AB} growth **0.519981**；C58_P1.xml + 蔗糖 supplement growth **0.97077**；输出每反应 fva_min/fva_max/pfba，条件对比只认区间分离判定（overlap=伪影禁止引用）
+- gem_sensitivity 对 C58.xml（AB）：基准组合（biomass×1.0, GAM=orig 40.0）**精确复现 essential_scan 的 155**（155 vs 155 EXACT MATCH）；22 组合网格必需性恒 155
+- gem_ledger：C58 essentiality 155 条 + phenotype 19 条入账，**幂等**——同参复跑 appended=0/skipped=174（账本行数不变）
+- 对不上这些锚点 = 环境/模型被改动，先查再继续。
+
+## 常见坑
+
+- **gem_build 别误判超时**：1-2 分钟是正常的（C58 实测 70s），等待完成。
+- medium 自然名拼写：D-Glucose / NH3 / O2 / Phosphate / Sulfate / Mn2+ / Fe3+ 等；别名表已内置（malic acid、gluconate 等）。
+- G2 报告 WARN 且仅 1 个反应不平衡（如 bio1）→ 生物质方程簿记特性，不是模型坏了。
+- 产物模型文件优先给绝对路径；工作区管理沿用 dsh 会话工作区。

package/src/index.js

@@ -0,0 +1,19 @@
+// dsh-bio-gem — Cordis 插件主模块
+// 注入 tools（5 语义化工具：gem_report/validate/gapfind/gapfill/build）+ skills（gem-expert）。
+import { registerTools } from './tools.js'
+import { registerSkills } from './skills.js'
+
+/** Cordis 插件名（cordis.patch.yml row id 同名）。 */
+export const name = 'dsh-bio-gem'
+
+/** 需要的服务。M1：tools + skills（无浏览器半/无 server 路由）。 */
+export const inject = ['tools', 'skills']
+
+/**
+ * 装配插件。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ */
+export function apply(ctx) {
+  registerTools(ctx)
+  registerSkills(ctx)
+}

package/src/jobs.js

@@ -0,0 +1,152 @@
+// jobs.js — dsh-bio-gem 后台长任务管理（M1 基建，ESM）
+// gem_build 是 1-2 分钟级任务：startBuild(args) -> jobId（立即返回）；
+// jobStatus(jobId) -> 进度/结果（轮询）。进度事件落 <jobDir>/progress.jsonl，
+// 完成时 build.py 写 result.json（进程消失也可恢复读取）。
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = path.join(os.homedir(), '.dsh', 'dsh-bio-gem')
+const JOBS_DIR = path.join(ROOT, 'jobs')
+// 阶段D-E2E 修复：new URL(...).pathname 在 Windows 产生 "/C:/..." 前导斜杠，
+// path.join 后得 "\C:\...python"（不存在）→ spawn ENOENT → gem_build 恒 "result missing"。
+// 与 python.js 同款写法：fileURLToPath + dirname。
+const PYTHON_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'python')
+
+// 运行时探测：优先 miniconda（本机分析环境，cobra 已装），回退 env GEM_PYTHON / PATH
+export function pythonExe() {
+  const cands = [
+    process.env.GEM_PYTHON,
+    'C:/Users/shuai/miniconda3/python.exe',
+    'python',
+  ]
+  for (const c of cands) {
+    if (!c) continue
+    try {
+      if (c === 'python' || fs.existsSync(c)) return c
+    } catch { /* ignore */ }
+  }
+  return 'python'
+}
+
+const jobs = new Map() // jobId -> {cp, jobDir, ...}
+
+export function startBuild({ input, name, engine, medium, outDir }) {
+  const jobId = 'gem_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+  const jobDir = path.join(JOBS_DIR, jobId)
+  fs.mkdirSync(jobDir, { recursive: true })
+  const progressFile = path.join(jobDir, 'progress.jsonl')
+  const stdoutFile = path.join(jobDir, 'stdout.txt')
+  const stderrFile = path.join(jobDir, 'stderr.txt')
+
+  const py = pythonExe()
+  const args = ['-u', path.join(PYTHON_DIR, 'build.py'),
+    '--input', input, '--progress', progressFile]
+  if (engine) args.push('--engine', engine)
+  if (name) args.push('--name', name)
+  if (medium) args.push('--medium-json', JSON.stringify(medium))
+  if (outDir) args.push('--out-dir', outDir)
+
+  const cp = spawn(py, args, { cwd: PYTHON_DIR, windowsHide: true })
+  const so = fs.createWriteStream(stdoutFile, { flags: 'a' })
+  const se = fs.createWriteStream(stderrFile, { flags: 'a' })
+  cp.stdout.pipe(so)
+  cp.stderr.pipe(se)
+
+  const rec = {
+    jobId, jobDir, progressFile, stdoutFile, stderrFile,
+    cp, done: false, result: null, error: null, started: Date.now(),
+  }
+  jobs.set(jobId, rec)
+
+  cp.on('exit', (code) => {
+    se.end()
+    so.end()
+    try {
+      const txt = fs.readFileSync(stdoutFile, 'utf8')
+      const lines = txt.trim().split(/\r?\n/).filter(Boolean)
+      const last = JSON.parse(lines[lines.length - 1])
+      rec.result = last
+      rec.done = true
+      rec.code = code
+    } catch (e) {
+      rec.error = `parse result failed: ${e.message}`
+      rec.done = true
+      rec.code = code
+    }
+    fs.writeFileSync(path.join(jobDir, 'result.json'),
+      JSON.stringify({ result: rec.result, error: rec.error, code: rec.code }, null, 2))
+    jobs.delete(jobId)
+  })
+  cp.on('error', (e) => {
+    rec.error = e.message
+    rec.done = true
+    jobs.delete(jobId)
+  })
+  return { jobId, jobDir, progressFile }
+}
+
+export function readProgress(jobId) {
+  const pf = path.join(JOBS_DIR, jobId, 'progress.jsonl')
+  if (!fs.existsSync(pf)) return []
+  try {
+    return fs.readFileSync(pf, 'utf8').trim().split(/\r?\n/)
+      .filter(Boolean)
+      .map((l) => JSON.parse(l))
+  } catch {
+    return []
+  }
+}
+
+// 阶段D-P2：失败透明化——job 目录内容摘要 + stderr 尾部（成功路径不计算不返回）
+function jobDetail(jobDir) {
+  let files = []
+  try {
+    files = fs.readdirSync(jobDir).map((f) => {
+      let bytes = 0
+      try { bytes = fs.statSync(path.join(jobDir, f)).size } catch { /* ignore */ }
+      return { name: f, bytes }
+    })
+  } catch { /* ignore */ }
+  let stderr_tail = ''
+  try {
+    const sp = path.join(jobDir, 'stderr.txt')
+    if (fs.existsSync(sp)) stderr_tail = fs.readFileSync(sp, 'utf8').slice(-400)
+  } catch { /* ignore */ }
+  return { job_dir: jobDir, job_dir_files: files, stderr_tail }
+}
+
+// 轻量 in-memory 任务视图（进程存活期）；磁盘持久视图用 readProgress/result.json
+export function jobStatus(jobId) {
+  const m = jobs.get(jobId)
+  const jobDir = path.join(JOBS_DIR, jobId)
+  const resultFile = path.join(jobDir, 'result.json')
+  const events = readProgress(jobId)
+  const last = events.length ? events[events.length - 1] : null
+  let result = null
+  let error = null
+  let done = false
+  let code = null
+  if (fs.existsSync(resultFile)) {
+    try {
+      const r = JSON.parse(fs.readFileSync(resultFile, 'utf8'))
+      done = true; result = r.result; error = r.error; code = r.code
+    } catch { /* ignore */ }
+  } else if (m) {
+    done = m.done; result = m.result; error = m.error; code = m.code
+  } else {
+    const stderr = path.join(jobDir, 'stderr.txt')
+    error = fs.existsSync(stderr) ? fs.readFileSync(stderr, 'utf8').slice(-800) : 'job vanished'
+    done = true
+  }
+  // build.py 失败信封：{ok:true, result:null, error_hint}（exit 0）——也按失败透出 detail
+  const envelopeFailed = !!(result && result.error_hint && result.result == null)
+  const failed = !!error || envelopeFailed || (done && code !== 0 && !result)
+  return {
+    jobId, done, code, result, error, lastEvent: last, events, jobDir,
+    ...(failed ? { detail: jobDetail(jobDir) } : {}),
+    elapsed_ms: Date.now() - (m ? m.started : Date.now()),
+  }
+}