@dsh-bio/dsh-bio-gem 0.1.15 → 0.1.17

package/python/gapseq_wsl.py

@@ -1,6 +1,6 @@
 # gapseq_wsl.py — dsh-bio-gem M2：gapseq 引擎的 WSL 桥（Windows → WSL2）
 # 实测背景（农杆菌 C58 项目 2026-08）：gapseq 2.1.0 部署于 WSL2 Ubuntu-22.04
-# conda env "gapseq"（TUNA 渠道），序列库 F:\Datasets\gapseq\db\Bacteria（v1.5）。
+# conda env "gapseq"（TUNA 渠道）+ 本地序列库（路径见文件内常量，换机器需相应调整）。
 # 关键实测（2026-08-29）：
 #   - 新版 wsl.exe（Win11）输出 UTF-8；旧版 UTF-16LE —— decode 双兼容（UTF-8 strict 优先）
 #   - wsl.exe 命令行传含空格路径 + 引号必坏 -> 一切路径进脚本文件，脚本用 base64 传输
@@ -25,6 +25,7 @@ WSL_DISTRO = os.environ.get("GEM_GAPSEQ_DISTRO", "Ubuntu-22.04")
 CONDA_SH = "/opt/miniforge3/etc/profile.d/conda.sh"
 GAPSEQ_ENV = "gapseq"
 WSL_WORK = "/opt/gem-gapseq-work"
+SEQDB_DIR = f"/opt/miniforge3/envs/{GAPSEQ_ENV}/share/gapseq/dat/seq/Bacteria"
 
 
 def wsl_run(bash_cmd, timeout=300):
@@ -79,13 +80,34 @@ def probe():
     import re
     mm = re.search(r"gapseq version:\s*([\d.]+)", out)
     res["gapseq_version"] = mm.group(1) if mm else out[:80]
-    seqdb = "/mnt/f/Datasets/gapseq/db"
+    # doall 实际读取 conda 环境内的 seq/Bacteria；旧探针却查 F: 备份并调用
+    # update-sequences -c，后者依赖 Zenodo 在线记录。网络解析失败会误报后端缺失。
+    # 本地元数据 + 三类序列文件同时检查，缺任何一项都不宣称可用。
     rc, out, err = wsl_run(
-        f"source {CONDA_SH} && conda activate {GAPSEQ_ENV} && "
-        f"gapseq update-sequences -t Bacteria -D {seqdb} -q -c 2>&1", 300)
-    res["checks"]["seqdb"] = "up-to-date" in out.lower()
+        f"set -o pipefail; cat {SEQDB_DIR}/version_seqDB.json && "
+        f"find {SEQDB_DIR}/rev -type f | wc -l && "
+        f"find {SEQDB_DIR}/rxn -type f | wc -l && "
+        f"find {SEQDB_DIR}/unrev -type f | wc -l", 120)
+    try:
+        meta, offset = json.JSONDecoder().raw_decode(out)
+        counts = [int(value) for value in out[offset:].split()]
+        metadata_ok = (isinstance(meta, dict)
+                       and isinstance(meta.get("version"), list)
+                       and len(meta["version"]) == 1
+                       and isinstance(meta["version"][0], str)
+                       and bool(meta["version"][0])
+                       and isinstance(meta.get("zenodoID"), list)
+                       and len(meta["zenodoID"]) == 1
+                       and isinstance(meta["zenodoID"][0], int)
+                       and meta["zenodoID"][0] > 0)
+        res["checks"]["seqdb"] = rc == 0 and metadata_ok and len(counts) == 3 and all(n > 0 for n in counts)
+        if res["checks"]["seqdb"]:
+            res["seqdb_version"] = meta["version"][0]
+            res["seqdb_counts"] = dict(zip(("rev", "rxn", "unrev"), counts))
+    except (IndexError, ValueError, TypeError, json.JSONDecodeError):
+        res["checks"]["seqdb"] = False
     if not res["checks"]["seqdb"]:
-        res["detail"] = f"序列库未注册（可能触发在线下载灾难）: {out[:400]}"
+        res["detail"] = f"gapseq 实际序列库缺失或不完整: {(out or err)[:400]}"
         res["level"] = "DEGRADED"
         return res
     res["capable"] = True
@@ -248,4 +270,4 @@ if __name__ == "__main__":
             f"source {CONDA_SH} && conda activate {GAPSEQ_ENV} && gapseq -v 2>&1", 120)
         print(out[:300] or err[:300])
     else:
-        print("unknown cmd")
+        print("unknown cmd")

package/python/gem_ops.py

@@ -243,7 +243,7 @@ def op_media_resolve(args):
 
 
 # ---------------------------------------------------------------------------
-# op: l3_fix — B' 后半：L3 内部路径补洞（L3a 模型内连通性 + L3b 白名单/BiGG 反应式）
+# op: l3_fix — L3 内部路径补洞（L3a 模型内连通性 + L3b 白名单/BiGG 反应式）
 # 证据分级 EVIDENCE_sequence/math；防过补第五闸门（budget.py）；补后 G1-G6 重验 + G6 失败回滚
 # ---------------------------------------------------------------------------
 def op_l3_fix(args):
@@ -264,7 +264,7 @@ def op_l3_fix(args):
 
 # ---------------------------------------------------------------------------
 # op: fluxscan — 阶段A-M1 通量区间制（FVA 区间 + pFBA 点值 + 条件对区间分离判定）
-# 语义 bsp 锁稿：overlap = 求解器伪影禁止引用；判定公式见 fluxscan.judge_interval（单测锁定）
+# 语义锁定：overlap = 求解器伪影禁止引用；判定公式见 fluxscan.judge_interval（单测锁定）
 # ---------------------------------------------------------------------------
 def op_fluxscan(args):
     from fluxscan import fluxscan, DEFAULT_FRACTION, DEFAULT_TOL
@@ -371,7 +371,7 @@ OPS = {
 
 
 # ---------------------------------------------------------------------------
-# op: biomass_inspect / biomass_apply — Q2 任务一：biomass 精修（可选 profile，不默认替换）
+# op: biomass_inspect / biomass_apply — biomass 精修（可选 profile，不默认替换）
 # ---------------------------------------------------------------------------
 def op_biomass_inspect(args):
     from biomass_tools import inspect_biomass
@@ -533,7 +533,7 @@ OPS["targets"] = op_targets
 # ---------------------------------------------------------------------------
 # op: precursor_scan — 阻塞前体分析
 #   「模型为什么不长」的结构级定位：逐前体做移除测试，找出卡住生长的前体。
-#   来源：2026-09-11 E2E 绕道归因（agent 手写该逻辑 6+ 次，无工具可用）。
+#   来源：2026-09-11 实测归因（agent 手写该逻辑 6+ 次，无工具可用）。
 #   判据刻意用「相对判断」而非绝对可达性 —— 对可生长模型天然零误报。
 # ---------------------------------------------------------------------------
 def op_precursor_scan(args):

package/python/l3_fix.py

@@ -1,4 +1,4 @@
-# l3_fix.py — B' 后半：L3 内部路径补洞（两级）
+# l3_fix.py — L3 内部路径补洞（两级）
 #   L3a 模型内连通性: 先"全内部反应放开方向"LP 预检（快速严谨判负），可行才用 cobra GapFiller
 #        universal=模型自身反应池（放开方向副本，NEW id），MILP 选最小集 → 对原反应放宽 bounds（不复制反应）。
 #        注: cobra 0.32.1 GapFiller(universal=None) 语义是"空反应池"（只加 demand），不是"模型自身反应池"
@@ -28,7 +28,7 @@ EX_PREFIX = ("EX_", "DM_", "SK_")
 SOURCE_TAG = "gem-l3fix"
 NEW_RXN_SUFFIX = "_l3fix"
 
-# BiGG 基名 -> ModelSEED cpd 号（2026-08-29 本机以 C58 名字+公式+电荷逐一验证；
+# BiGG 基名 -> ModelSEED cpd 号（2026-08-29 以 C58 名字+公式+电荷逐一验证；
 # 映射时仍做公式/电荷校验，不一致即弃用防静默污染化学计量）
 COFACTOR_BRIDGE = {
     "h2o": "00001", "atp": "00002", "nad": "00003", "nadh": "00004",
@@ -42,9 +42,15 @@ COFACTOR_BRIDGE = {
 COMP_MAP = {"c": "c0", "e": "e0", "p": "p0"}  # BiGG 区室后缀 -> gapseq 区室 id
 
 WHITELIST_DIR = os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "whitelist")
-# 本地白名单数据库（license 守则: 仅本机，不进 git/发布包；GEM_WHITELIST_DB_DIR 可覆盖）
-RXN_DB_DIR = os.environ.get("GEM_WHITELIST_DB_DIR", r"D:\Program\hermes\temp\gem_whitelist")
-DEFAULT_UNIVERSAL = r"D:\Program\hermes\temp\gem_universal\iML1515.xml"
+# 本地白名单数据库（license 守则: 仅本地留存，不进 git/发布包；GEM_WHITELIST_DB_DIR 可覆盖）
+RXN_DB_DIR = os.environ.get(
+    "GEM_WHITELIST_DB_DIR",
+    os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "whitelist-db"),
+)
+DEFAULT_UNIVERSAL = os.environ.get(
+    "GEM_UNIVERSAL_MODEL",
+    os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "models", "iML1515.xml"),
+)
 
 PTS_RE = re.compile(r"(?i)\bpts\b|phosphotransferase|pep:pyr")
 

package/python/ledger.py

@@ -7,7 +7,7 @@
 # 幂等: 同 model+condition+type+content 哈希去重，重复运行不追加。
 # 完整性: 逐行 JSON 解析校验，损坏行跳过并在返回里报 corrupt_rows + 行号（不阻塞）；
 #         写入失败只 WARN 不使主流程失败。update 重写文件但保留损坏行原样（不删行）。
-# 证据分级优先级（任务书锁定）: EVIDENCE_literature > EVIDENCE_sequence > EVIDENCE_rule > EVIDENCE_math
+# 证据分级优先级（口径锁定）: EVIDENCE_literature > EVIDENCE_sequence > EVIDENCE_rule > EVIDENCE_math
 import os
 import re
 import sys
@@ -29,7 +29,7 @@ def _now_iso():
 
 
 def _content_hash(model, condition, rtype, content):
-    # 阶段D-E2E P1：Windows 路径斜杠/大小写差异（"F:/a" vs "F:\a"）会使同一模型的
+    # 实测发现：Windows 路径斜杠/大小写差异（"F:/a" vs "F:\a"）会使同一模型的
     # 重复登记漏过去重——hash 前做 normcase+normpath 归一化（首登记的存储格式不变）。
     m = os.path.normcase(os.path.normpath(model)) if model else ""
     raw = "\x1f".join([m, condition or "", rtype or "", content or ""])

package/python/model_card.py

@@ -1,10 +1,10 @@
-# model_card.py — 模型卡 schema v2 统一写入器（B' 收尾 + Q2 工程质量件）
+# model_card.py — 模型卡 schema v2 统一写入器（工程质量件）
 # 职责: init_card（build 起卡）/ load / save / append_operation（lineage 版本递增 + changelog）
 #       / set_verified_phenotypes（phenotype 结果）/ set_essential_genes（必需基因 + 证据分级）
 # 纪律: 各工具完成后**仅当产物模型旁已有 card** 才向后追加；无卡不动（不凭空造卡）。
 # 兼容: build.py 旧卡（无 schema 字段）读取时即时迁移到 v2（新增字段缺失不报错）。
 # units: growth_rate 一律 1/h（比生长速率；biomass 反应 gDW 归一化口径，数值 = μ）。
-# 2026-09-21 由 mmol/gDW/h 演进为 1/h：数值不变、生物语义更准（外部评审 P0；schema 向后兼容，旧卡照读）。
+# 2026-09-21 由 mmol/gDW/h 演进为 1/h：数值不变、生物语义更准（schema 向后兼容，旧卡照读）。
 import os
 import json
 import time

package/python/precursor_scan.py

@@ -1,6 +1,6 @@
 # precursor_scan.py — dsh-bio-gem 阻塞前体分析（「模型为什么不长」的结构级定位）
 #
-# 来源（2026-09-11 E2E 绕道归因）：agent 在不生长模型上反复手写「逐前体探测」逻辑
+# 来源（2026-09-11 实测归因）：agent 在不生长模型上反复手写「逐前体探测」逻辑
 # （6+ 次调用），本模块把它固化为工具。
 #
 # ⚠️ 判据设计——**刻意不用「绝对可达性」**：

package/python/quality.py

@@ -14,6 +14,7 @@ from cobra.flux_analysis import fastcc, find_blocked_reactions
 
 from gapfind import expand_medium, resolve_medium
 from silentio import silent_read_sbml
+from fsutil import ensure_parent_dir
 
 
 EX_PREFIXES = ("EX_", "DM_", "SK_")
@@ -357,6 +358,7 @@ def _connectivity(model):
 
 def _write_export_csv(path, records):
     """Write long-form complete lists; JSON samples remain deliberately capped."""
+    path = ensure_parent_dir(path)
     with open(path, "w", encoding="utf-8", newline="") as handle:
         writer = csv.DictWriter(handle, fieldnames=("check", "item_id", "detail"))
         writer.writeheader()

package/python/roundtrip_check.py

@@ -1,6 +1,6 @@
-# roundtrip_check.py — SBML 往返保真自检（Q2 工程质量件 A）
+# roundtrip_check.py — SBML 往返保真自检（工程质量件）
 # cobra 读 → write_sbml_model → 读回：断言反应/代谢物/基因数一致 + GPR 字符串精确一致
-# （GLM 经典暗坑：序列化静默丢 GPR——fbc v2 写入路径回归护栏；≥5 个复合 GPR 反应样本必查）
+# （经典暗坑：序列化静默丢 GPR——fbc v2 写入路径回归护栏；≥5 个复合 GPR 反应样本必查）
 import os
 import sys
 import json

package/python/sampling.py

@@ -11,6 +11,7 @@ from cobra.util.solver import linear_reaction_coefficients
 
 from gapfind import expand_medium, resolve_medium
 from silentio import silent_read_sbml
+from fsutil import ensure_parent_dir
 
 
 EX_PREFIXES = ("EX_", "DM_", "SK_")
@@ -219,6 +220,7 @@ def sample_fluxes(
     growth_summary = _describe(samples[growth_reaction.id].to_numpy())
 
     if export_csv:
+        export_csv = ensure_parent_dir(export_csv)
         samples.to_csv(export_csv, index=False)
 
     if growth_floor_fraction is None:

package/python/secretion.py

@@ -18,6 +18,7 @@ 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
+from fsutil import ensure_parent_dir, write_meta_sidecar
 
 EPS = 1e-6
 GROWTH_FRACTIONS = [0.25, 0.5, 0.75, 0.9, 0.99, 1.0]
@@ -151,10 +152,15 @@ def secretion(model_path, medium=None, fractions=None, export_csv=None,
 
 
 def _export_csv(path, rows, out):
+    """纯数据 CSV（标准表头）+ 旁车 meta。
+
+    2026-10-05 修：boundary_note 移出 CSV 首行（原为 `"# boundary_note", note` 双字段行，
+    pandas/自动解析会当表头或脏行）→ 写入 <path>.meta.json（返回体 export_csv_meta）。
+    """
+    path = ensure_parent_dir(path)
     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:
@@ -162,6 +168,17 @@ def _export_csv(path, rows, out):
                 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
+    meta = write_meta_sidecar(path, {
+        "boundary_note": out.get("boundary_note"),
+        "model": out.get("model"),
+        "medium": out.get("medium"),
+        "medium_preset": out.get("medium_preset"),
+        "units": out.get("units"),
+        "growth_fractions": out.get("growth_fractions"),
+        "wt_growth": out.get("wt_growth"),
+    })
+    if meta:
+        out["export_csv_meta"] = meta
     return n
 
 

package/python/sensitivity.py

@@ -19,6 +19,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from silentio import silent_read_sbml
 from validate import parse_formula
 from essential_scan import setup_model_medium, scan_essentiality
+from fsutil import ensure_parent_dir
 
 BIOMASS_SCALES = [0.75, 1.0, 1.25]
 GAM_GRID = [1, 5, 10, 20, 30, 40, 50]
@@ -127,7 +128,7 @@ def find_biomass_gam(m):
 
 def _apply_biomass_scale(m, bio_id, f, gam_info):
     """biomass 组分缩放 ×f（排除 GAM stub 与 Biomass 产物——正交化）。
-    cobra add_metabolites 是增量语义：绝对设定必须用 delta = 目标-现值（Q2 教训），回读校验。
+    cobra add_metabolites 是增量语义：绝对设定必须用 delta = 目标-现值（实测教训），回读校验。
     注意：原始系数必须在 add 之前快照（add 后 bio.metabolites 已是新值）。"""
     bio = m.reactions.get_by_id(bio_id)
     skip = set((gam_info.get("gam_mets") or {}).values()) | \
@@ -216,7 +217,7 @@ def sensitivity(model_path, medium=None, biomass_scales=None, gam_grid=None,
                 run_component_sensitivity=True, run_drift=True, top_n=10,
                 export_csv=None, progress=None, baseline_check=None):
     """M2 主入口。baseline_check: 可选外部基线必需集（来自 essential_scan 直跑）——
-    基准组合与其做集合相等断言（任务书锚点）。返回完整结果 dict。"""
+    基准组合与其做集合相等断言（基准锚点）。返回完整结果 dict。"""
     log = progress or (lambda s: sys.stderr.write(str(s) + "\n"))
     biomass_scales = biomass_scales or BIOMASS_SCALES
     gam_grid = gam_grid or GAM_GRID
@@ -421,6 +422,7 @@ def sensitivity(model_path, medium=None, biomass_scales=None, gam_grid=None,
 
 
 def _export_csv(path, grid, comp_rows, drift, stability):
+    path = ensure_parent_dir(path)
     rows = 0
     with open(path, "w", newline="", encoding="utf-8-sig") as f:
         w = csv.writer(f)

package/python/targets.py

@@ -13,6 +13,8 @@ import json
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
+from fsutil import ensure_parent_dir
+
 SCHEMA_FIELDS = ["target_id", "type", "genes", "met_ids", "condition", "rationale",
                  "evidence_tier", "status", "growth_or_maxprod", "source", "exported_at"]
 TYPE_ORDER = ["essentiality", "synthetic_lethal", "secretion"]
@@ -112,6 +114,7 @@ def targets(model_path=None, types=None, condition=None, ledger_path=None,
         d = os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "exports")
         os.makedirs(d, exist_ok=True)
         export_path = os.path.join(d, f"targets_{time.strftime('%Y%m%d_%H%M%S')}.{export_format}")
+    export_path = ensure_parent_dir(export_path)
     if export_format == "json":
         with open(export_path, "w", encoding="utf-8") as f:
             json.dump(out_rows, f, ensure_ascii=False, indent=1)

package/python/validate.py

@@ -1,7 +1,7 @@
-# validate.py — dsh-bio-gem 五道验证关卡（M1）
+# validate.py — dsh-bio-gem 五道验证关卡
 # G1 加载统计 / G2 内部反应元素平衡 / G3 生长真实性 / G4 底物表型(条件) / G5 必需基因抽检(条件)
 # 规格: docs/ARCHITECTURE.md §5；判据口径 = FBA objective_value（biomass 归一化 → 比生长速率 μ，单位 1/h）
-# 实现从 HANDOFF-03 五道关卡协议产品化（农杆菌项目验证过的逻辑）
+# 五道关卡协议产品化（农杆菌项目验证过的逻辑）
 import re
 import os
 import json
@@ -16,7 +16,7 @@ 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 不改主流程
+# 关卡注册器（2026-08-29 采纳）：未来加 G7 不改主流程
 GATE_REGISTRY = {}
 
 
@@ -107,7 +107,7 @@ class Validator:
         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")
 
-        # 2026-09-11 修复（agent 在真实 E2E 中发现并指出）：**公式覆盖率是 PASS 结论的
+        # 2026-09-11 修复（agent 在真实会话中发现并指出）：**公式覆盖率是 PASS 结论的
         # 作用域上界** —— 覆盖率低时「无反应不平衡」只说明被检查的那部分没问题，不能
         # 外推为整体 PASS。实测 iNX1344_v3：覆盖率 68.35% 却判 PASS，agent 据此指出
         # 「g2 的 PASS 是假阳性，因为它只检查了有 formula 的 68.35% 代谢物」。
@@ -210,7 +210,7 @@ class Validator:
         补洞后必跑（context.post_gapfill 时不再跳过）。
         P1-5 修复（2026-08-31 LBA9402 会话实测）：CarveMe 模型 ATP id 为 M_atp_c，
         旧匹配只看 atp_c/cpd00002_c0 -> 误 SKIP「未找到 ATP」——扩展命名模式 + SKIP 时列出尝试模式与模型内候选。
-        P2-9 修复（2026-09-10 iNX1344 E2E 实测）：MetaCyc/BioCyc 导出模型 ATP 为 M00002_c
+        P2-9 修复（2026-09-10 iNX1344 实测）：MetaCyc/BioCyc 导出模型 ATP 为 M00002_c
         （name='ATP'，formula 为去质子化变体），仍不在模式表内 → 二次误 SKIP（G6 直接失效）。
         改为三级通用解析：id 模式 → name 匹配 → formula 匹配，跨 ID 体系自适应。"""
         m = self.m
@@ -262,7 +262,7 @@ class Validator:
     # ------------------------------------------------------------------ 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）；
+        carbon_mode: supplement=基准培养基不变+底物-10（对齐关卡4 基线 16/19→17/19）；
                      sole=去含碳交换后底物-10（唯一碳源严格语义，氮源类测试会误判）。"""
         if table_path and os.path.exists(table_path):
             rows = []

package/skills/gem-expert.md

@@ -61,15 +61,15 @@ language: mixed
 
 ## 硬规则（实测，违反会拿错结果）
 
-0. **外部事实断言必须带证据**（2026-08-29 采纳 GLM 教训）：凡涉及"某物种/文献/工具是否存在、是否已发表"等**模型外事实断言**，agent 必须真实检索并附来源（如 PubMed/PMC 链接）；无法检索时降级表述为"未验证假设 [假设]"，不得由记忆下断言。此项与 EVIDENCE 分级同位：**事实断言也有证据分级**（检索+来源=high；仅记忆=unverified）。
+0. **外部事实断言必须带证据**（2026-08-29 采纳）：凡涉及"某物种/文献/工具是否存在、是否已发表"等**模型外事实断言**，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⁻¹/μ**——汇报时不要换算成比生长速率。
+2. **数字必须来自工具输出**：agent 报告生长值/基因数/复制子数时引用工具 result，不要凭模型知识猜测（防幻觉铁律）。**生长值单位以工具返回的 `units` 字段为准**：归一化 biomass 反应（产物系数=1）的生长值为 **1/h（比生长速率 μ）**；一般反应通量为 mmol/gDW/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 产出"——事实上正确但出自文件名推断而非会话验证。
+6. **通量区间制（硬规则）**：无区间不点数——任何条件间通量对比必须消费 `gem_fluxscan` 的区间分离判定；两条件区间分离才是解空间无关硬结论（a_higher/b_higher）；overlap 反应的任何点值 diff 必须标注"伪影，禁止引用"。单点 FBA 生长/通量值（gem_validate/gem_phenotype/gem_essentiality 等输出）只是该条件下的一个解，跨条件直接 diff 是求解器伪影。
+7. **模型指代消歧（实测硬规则）**：用户说"我们的 C58 模型"等未给路径的指代时——①先查预测账本（`gem_ledger query` 按 model 前缀）与项目档案中已登记的 canonical 路径；②同一名字存在多个模型（如 gapseq 原版 vs carveme 重建）时，必需性/富集等锚点敏感分析必须用登记在案的原始版本或向用户确认，并说明选择了哪个文件；③不同引擎重建的同一物种是不同模型（基因数/必需集都不同），不得混用结论。
+8. **文件出处/来源推断必须标注 [推断]（硬规则）**：凡非本次会话工具 result 直接给出、而是凭文件名/目录布局/常识推断的出处（如"这个 faa 是 gem_annotate 产出的"），汇报时必须标注 [推断]；可验证时先验证再陈述。例证：一次实测中 agent 称 faa 为"前面流程 gem_annotate 产出"——事实上正确但出自文件名推断而非会话验证。
 
 ## C58 回归锚（验证工具是否正常）
 

package/src/capabilities.js

@@ -1,6 +1,6 @@
 // dsh-bio-gem — capabilities 单源（single source of truth for tool manifest & capability metadata）
 //
-// 目的（外部评审共识，2026-09-21 裁决 §3.3）：
+// 目的（2026-09-21 设计共识）：
 //   1. 工具清单/能力分级/成本与副作用元数据集中一处，供 integration API（/v1/capabilities）
 //      与 genie 宿主侧动态消费——消灭「工具数变化需同步 ≥12 处」的手工漂移。
 //   2. 校验脚本 scripts/check-capabilities.mjs 强制本 MANIFEST 与 tools.js 真实注册集合一致；

package/src/integration.js

@@ -225,7 +225,7 @@ async function probeGapseqEnvironment({ isWindows, distro, runner }) {
     return { available: false, detail: 'gapseq 仅支持 Windows WSL 的只读探测。' }
   }
   // 快速预检：先确认目标发行版存在（wsl.exe -l -q 亚秒级），避免发行版缺失时
-  // 白等一次 bash 长命令直到超时刹车（真实运行时实测：本机 bash 启动即 ~3s）。
+  // 白等一次 bash 长命令直到超时刹车（实测：bash 启动即 ~3s）。
   try {
     const listed = await runner('wsl.exe', ['-l', '-q'])
     const names = String(listed?.stdout ?? '')

package/src/python.js

@@ -10,7 +10,7 @@ import os from 'node:os'
 const PYTHON_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'python')
 
 /**
- * 候选解释器，按优先级（**通用化，不写死任何本机路径**）：
+ * 候选解释器，按优先级（**通用化，不写死任何机器特定路径**）：
  *
  *   1. `GEM_PYTHON`            — 用户显式指定，最高优先级
  *   2. 宿主插件自举环境         — `$DSH_HOME/dsh-bio-genie/python-env`
@@ -125,7 +125,7 @@ export function callGem(op, args, opts = {}) {
   return new Promise((resolve, reject) => {
     const py = pythonExe()
     const script = join(PYTHON_DIR, 'gem_ops.py')
-    const cp = spawn(py, ['-I', script], { cwd: PYTHON_DIR, windowsHide: true })
+    const cp = spawn(py, ['-I', script], { cwd: opts.cwd || PYTHON_DIR, windowsHide: true })
     let out = ''
     let err = ''
     cp.stdout.on('data', (d) => { out += d })

package/src/tools.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { spawn } from 'node:child_process'
 import { callGem, stampProvenance } from './python.js'
 import { startBuild, jobStatus } from './jobs.js'
+import { resolveWorkdir } from './workdir.js'
 
 /** 校验输入存在（绝对路径或用户给定路径）。 */
 function requirePath(v, label) {
@@ -27,8 +28,8 @@ function gemTool(opts) {
       schema: { type: 'object', additionalProperties: true },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args) {
-      return callGem(opts.op, args, { timeoutMs: opts.timeoutMs ?? 300_000 })
+    async execute(args, exec) {
+      return callGem(opts.op, args, { timeoutMs: opts.timeoutMs ?? 300_000, cwd: resolveWorkdir(exec) })
     },
   })
 }
@@ -41,7 +42,7 @@ function buildTool() {
       '从细菌全基因组构建基因组尺度代谢模型（GEM）。' +
       'engine=carveme（默认，纯 Windows 快）：输入蛋白 FASTA（*.faa），CarveMe -g M9 gapfill → M9 介质验证 → 目标介质 L1/L2 补洞，' +
       '约 1-2 分钟（C58 实测 70s）。' +
-      'engine=gapseq（质量档，需本机 WSL2 gapseq 环境）：输入核苷酸 FASTA（*.fna），WSL 桥 gapseq doall → 模型拷回 → 目标介质验证，' +
+      'engine=gapseq（质量档，需 WSL2 gapseq 环境）：输入核苷酸 FASTA（*.fna），WSL 桥 gapseq doall → 模型拷回 → 目标介质验证，' +
       '约 30-60 分钟（后台进度日志旁观，不要误判超时）。' +
       '输出标准 SBML（fbc v2）+ 模型卡（sidecar JSON：引擎版本/验证结果/补洞记录）。' +
       '生长值为比生长速率口径（1/h，biomass 归一化）；通量为单点 FBA 值（mmol/gDW/h，非硬结论）。条件间通量对比用 gem_fluxscan（区间制）。' +
@@ -259,7 +260,7 @@ export function registerTools(ctx) {
     timeoutMs: 120_000,
   })))
 
-  // gem_l3_fix：L3 内部路径补洞（B' 后半：L3a 模型内连通性 + L3b 白名单/BiGG 反应式 + 证据分级）
+  // gem_l3_fix：L3 内部路径补洞（L3a 模型内连通性 + L3b 白名单/BiGG 反应式 + 证据分级）
   disposers.push(ctx.tools.register(gemTool({
     name: 'gem_l3_fix',
     description:
@@ -287,7 +288,7 @@ export function registerTools(ctx) {
     timeoutMs: 900_000,
   })))
 
-  // gem_biomass：biomass 精修（Q2：inspect 只读 / apply 显式覆盖表 + 三联对照）
+  // gem_biomass：biomass 精修（inspect 只读 / apply 显式覆盖表 + 三联对照）
   disposers.push(ctx.tools.register(defineTool({
     name: 'gem_biomass',
     description:
@@ -317,9 +318,9 @@ export function registerTools(ctx) {
       schema: { type: 'object', additionalProperties: true },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args) {
+    async execute(args, exec) {
       const op = args.action === 'apply' ? 'biomass_apply' : 'biomass_inspect'
-      return callGem(op, args, { timeoutMs: 900_000 })
+      return callGem(op, args, { timeoutMs: 900_000, cwd: resolveWorkdir(exec) })
     },
   })))
 
@@ -416,7 +417,7 @@ export function registerTools(ctx) {
     name: 'gem_benchmark',
     description:
       '通用基准对比（benchmark）：任何两个代谢模型跑规范对比表，产出论文级对比。model_a/model_b 支持本地 SBML 绝对路径' +
-      '或 "bigg:<model_id>" URI（如 bigg:iML1515，BiGG 静态库下载到 ~/.dsh/dsh-bio-gem/models/，直连失败自动走本机代理，下载后缓存）。' +
+      '或 "bigg:<model_id>" URI（如 bigg:iML1515，BiGG 静态库下载到 ~/.dsh/dsh-bio-gem/models/，直连失败时按环境变量代理（HTTP_PROXY/HTTPS_PROXY）重试，下载后缓存）。' +
       '输出：ID 体系探测 / 六道关卡 G1-G6 逐项并列 / 声明介质生长（含介质层两级策略——无 EX_ 层的模型自动回退 ' +
       'boundary 单代谢物反应解析，boundary_style 标注）/ biomass 可行性探针（逐组分净产测试，结构性断供清单）/ ' +
       '必需性对比（复用 essential_scan；任一侧 wt<=EPS 判退化只报结构信息不做垃圾对比，基因映射尽力而为如实报覆盖率，' +

package/src/workdir.js

@@ -0,0 +1,67 @@
+/**
+ * dsh-bio-gem — 工作区解析（工具执行的工作目录）
+ *
+ * 优先级：
+ *   1. 会话工作区 `exec.agent.session.header.cwd`（与 dsh 内置 fs 工具一致：
+ *      每个会话操作自己的工作区，而不是服务器启动目录）
+ *   2. 保底工作区 `~/.dsh/sessions/default`（自动创建）
+ *
+ * 背景（2026-10-04 实测）：python 子进程此前固定 cwd=插件 python 目录，
+ * 工具参数里的相对路径（如 gem_fluxscan 的 export_csv）因此解析到插件目录、
+ * 写入失败（agent 被迫改用绝对路径自愈）。本模块对齐 dsh-bio-genie 的
+ * workdir 语义：相对路径基于会话工作区解析。
+ *
+ * 说明：dsh 对未显式指定 cwd 的会话会把 header.cwd 填充为服务器启动目录
+ * （process.cwd()），此时视为「未指定工作区」，走保底链。
+ *
+ * @module dsh-bio-gem/workdir
+ */
+import { existsSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** 保底工作区目录（自动创建；仅无会话 cwd 时使用）。 */
+export function fallbackWorkspace() {
+  return join(homedir(), '.dsh', 'sessions', 'default')
+}
+
+/**
+ * 会话工作区目录。
+ * @param {object} [exec] 工具执行上下文（defineTool execute 的第二参数）。
+ * @returns {string|undefined} 会话 cwd；未指定或不可读时返回 undefined。
+ */
+export function sessionWorkspace(exec) {
+  const cwd = exec?.agent?.session?.header?.cwd
+  if (typeof cwd !== 'string' || cwd.length === 0) return undefined
+  if (!existsSync(cwd)) return undefined
+  return cwd
+}
+
+/** 幂等确保目录存在（失败静默——由调用方决定回退）。 */
+function ensureDir(dir) {
+  if (existsSync(dir)) return true
+  try {
+    mkdirSync(dir, { recursive: true })
+    return existsSync(dir)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 解析一次工具调用的工作目录（供 python 子进程 cwd 使用）。
+ * @param {object} [exec] 工具执行上下文。
+ * @returns {string} 解析后的绝对路径（保底可用）。
+ */
+export function resolveWorkdir(exec) {
+  const serverCwd = process.cwd()
+  const rawSessionCwd = sessionWorkspace(exec)
+  const sessionCwd = rawSessionCwd && rawSessionCwd !== serverCwd ? rawSessionCwd : undefined
+  if (sessionCwd) {
+    ensureDir(sessionCwd)
+    return sessionCwd
+  }
+  const fb = fallbackWorkspace()
+  ensureDir(fb)
+  return fb
+}

package/docs/DECISIONS-2026-08-29.md

@@ -1,37 +0,0 @@
-# DECISIONS-2026-08-29 — GLM 两轮评审裁决与路线固化
-
-> 第三方 LLM（GLM）对纯 Windows 路线功能/架构的两轮评审；按"以实测为准、独立裁决"原则的采纳记录。
-
-## 第一轮（功能拓展+优化）裁决
-
-| 建议 | 裁决 | 备注 |
-|---|---|---|
-| P0 pyrodigal 注释（兑现"基因组→模型"承诺）| ✅ 原则采纳 | **待用户解锁**（用户已说暂不补注释步骤）；落地=官方注释优先+pyrodigal 兜底+meta 模式（<100kb 强制）|
-| P0 G5 全量必需性扫描（FVA 预筛）| ✅ 采纳 | 排入路线；模型卡加必需基因章节（证据着色）|
-| P1 gapseq 白名单 + L3 MILP 组合拳 | ✅ 采纳 | 白名单仅本地基准（license 见下）；L3 候选池=自建同源映射（license 干净）|
-| P1 biomass 精修（参考对照）| ✅ 采纳但后置 | 级联重置验证基线风险；做成可选 --biomass-profile + before/after 三联对照 |
-| P2 accession 下载 / P3 表型 schema / P3 差分 / P4 交叉 / P4 可视化 | ✅ 按序采纳 | 可视化=Escher JSON 导出（不做内嵌渲染）|
-| 建模卡 RPC/架构优化 | ✅ 见第二轮 | — |
-| 五道关卡→关卡注册器 + G6 ATP 泄漏 | ✅ **已实现** | G6 实测 C58 PASS（flux 0.0）|
-| 防过补第五闸门（全局预算 <5%）| ✅ 采纳 | 表型回填/长期迭代防温水煮青蛙 |
-| 证据分级枚举（sequence/literature/rule/math）| ✅ 采纳 | 白名单+MILP 落地后填充 model card |
-| SBML 往返保真测试 | ✅ 采纳 | 进 smoke |
-
-## 第二轮（7 问）裁决
-
-1. **注释质量**：✅ 官方注释优先+pyrodigal 兜底；验证协议（预测蛋白覆盖率 85-92%、反应 delta<3%、生长差<5%）待解锁后实施。
-2. **license**：✅ **分离消费**——seqDB 仅本地基准不分发；自建 UniProt→EC→BiGG 作可分发白名单/L3 候选池（license 干净）；止损 2 周；GPLv3 环绕注意。
-3. **介质的共享形态**：✅ 单一 Python 来源 + RPC/CLI 子命令（不做双语言双包）；schema v2 采纳，**修正 units=mmol/gDW/h（非 1/h）**。
-4. **modelseedpy**：✅ P2 交叉分歧清单主体（非并列引擎）；BiGG↔SEED 桥复用 MET_ALIAS 模式。
-5. **G6**：✅ 已实现（ATP demand 全关最大化 >0.01 WARN）；补洞后必跑；注册器已内置。
-6. **证据呈现**：✅ 分区+徽标+行着色+`--strict-evidence` 开关（不隐藏不全表高亮）。
-7. **排期冲突**：✅ 衔接前置（schema v2/media_resolve RPC）归入 gem 内部工作流；genie 解锁即消费，gem 主线不阻塞。
-
-## 落地状态
-
-- [x] G6 ATP 泄漏关卡 + 关卡注册器（validate.py；C58 PASS 0.0）
-- [ ] schema v2（supported_mediums/verified_phenotypes/model_lineage/evidence_summary）——unit 已定为 mmol/gDW/h
-- [ ] G5 全量（FVA 预筛）——路线 P0
-- [ ] 白名单 + L3 MILP + 证据分级——路线 P1（license 结论已定：自建映射）
-- [ ] 注释步骤（pyrodigal）——**待用户解锁**
-- [ ] genie 衔接（RPC 子命令）——待用户解锁