@dsh-bio/dsh-bio-gem 0.1.12 → 0.1.13

package/docs/DECISIONS-2026-09-21.md

@@ -0,0 +1,76 @@
+# DECISIONS — 2026-09-21 升级批次（外部评审裁决后 Phase 1）
+
+> 本批决策依据：`D:\Program\dsh-plug-develop\21-gem升级-裁决与实施方案.md`（GPT/DS 双评审 + 本机 8 项实测核验）。
+> 记录本批次的**语义演进与架构决策**，供下游与后续批次参考。
+
+## D1. growth 单位演进：mmol/gDW/h → 1/h（数值不变）
+
+**决策**：growth / growth_rate / wt_growth / before-after 生长 等**比生长量**字段的单位标注由
+`mmol/gDW/h` 改为 `1/h`；反应通量类保持 `mmol/gDW/h`。
+
+**依据**（实测 + 社区约定）：
+- C58 的 bio1（Bacterial Gram-negative biomass reaction）产物系数 = 1.0 —— biomass 反应已按
+  **1 gDW 归一化**；此时其通量数值 = 比生长速率 μ（h⁻¹），这是 COBRA 社区的标准解读
+  （biomass flux through a normalized biomass reaction equals the specific growth rate）。
+- 外部评审（GPT）指出原标注 `mmol/gDW/h` 对 biomass 反应在语义上不准确 → 列为 P0。
+- straindesign 官方文档同样以 `growth rates above 0.5/h` 表述（旁证）。
+
+**边界**：对**未归一化**的 biomass 反应（产物系数 ≠ 1）growth 应以 mmol/gDW/h 解读——见
+validate 的 units.note 表述。数值本身在任何情况下不变，本决策只纠标注。
+
+**影响面**：python/ 12 个模块（23 处）+ src/tools.js（16 处口径文案统一）+ 本文档；
+`model_card.GROWTH_UNITS` 同步演进（旧卡兼容：growth_units 字段照读，数值口径不变）。
+
+## D2. 能力单源（capabilities.json → /v1/capabilities → 宿主动态消费）
+
+**决策**：工具清单与能力元数据（cost_class / network / mutability / requires）以
+`src/capabilities.js` 的 `TOOLS_MANIFEST` 为**唯一事实源**：
+- integration API 新增 `GET /v1/capabilities`（features 声明 `capabilities`）；
+- 宿主 dsh-bio-genie 的 `handleDomainRequest` 在对方声明该 feature 时拉取并透传
+  （失败静默降级到静态清单 `GEM_TOOLS`——它已降级为 fallback 视图）；
+- 机器门：`test/check-capabilities.mjs`（manifest ↔ 真实注册一致）+
+  `test/check-counts.mjs`（文档计数 ↔ manifest 一致）。
+
+**背景**：原「工具数变化需同步 ≥12 处」是两评审共同指出的工程债；本决策把它变成
+「单源 + 两道机器门」，文档数字仍手写但有门兜底。
+
+## D3. CarveMe 零手动部署（bootstrap_carveme.py）
+
+**决策**：`gem_build(engine=carveme)` 首次调用自动完成运行时部署（幂等）：
+uv venv（uv 探测链：`GEM_UV` → genie 自举 uv → PATH）→ `uv pip install carveme` →
+下载 GitHub 官方 diamond 二进制（**固定 v2.2.8**，3.4MB）→ deep smoke → manifest 记录。
+
+**关键设计**：
+- **快速路径**：`carve.exe + diamond.exe + manifest.json` 齐备时秒过（实测 0.34s，不做子进程冒烟）；
+- 部署与复验才做 deep smoke（实测全量部署 45s：venv 31s + diamond 下载数秒 + 冒烟）；
+- 下载通道：直连 → 环境代理（HTTPS_PROXY/HTTP_PROXY）→ 失败给可执行指引（含手动放置路径）；
+- 这就是 P0「装完插件 ≠ 构建可用」的根治：契约要求用户零手动安装。
+
+## D4. gem_sample 的边界设计（全空间 vs 受限）
+
+**决策**：默认采样**全 feasible space**（ACHR），但 `boundary` 字段**强制输出**边界声明；
+近最优生长状态必须显式传 `growth_floor_fraction`（如 0.9）。
+
+**依据**（本机实测）：C58 全空间采样 bio1 max ≈ 0.017 vs FBA 最优 0.7134（差 2 个数量级）——
+全空间均匀分布 ≠ 生物学上有意义的活跃状态；不声明边界就是「做了但没用」的典型。
+
+**Windows 约束**：默认 ACHR（无多进程依赖，实测 init ~172s、采样秒级）；OptGP 在 Windows
+下实验性——不可用时**显式安全拒绝**（不触发多进程陷阱）。
+
+## D5. quality_index（gem-qi-v1）不是 MEMOTE 分数
+
+**决策**：`gem_quality` 输出 `quality_index`（0-100 启发式聚合）+ 分项 raw_metrics +
+failed_checks + not_assessable_checks；**禁止**作为单一质量结论引用（notes 内置声明）。
+
+**依据**：两评审共识——MEMOTE 的价值在其可分解测试体系；聚合分容易被误用。
+评分规则（写死在 `python/quality.py` 常量）：见 WEIGHTS / 阈值常量与 note 输出。
+**不安装 MEMOTE 整体**（PyPI 0.17.0 仅声明兼容到 Py3.11；本机 Py3.13 风险）。
+
+## D6. 本批新增工具（2）
+
+| 工具 | capability | cost_class | 说明 |
+|---|---|---|---|
+| `gem_quality` | `gem.validate.quality-report` | medium | 质量审计（blocked/环路/平衡/孤儿/覆盖/连通性）|
+| `gem_sample` | `gem.analysis.sampling` | heavy | 通量空间采样（ACHR/OptGP；边界声明）|
+
+工具数 21 → 23；op 数 21 → 23。两门（check-capabilities / check-counts）同步更新。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-bio/dsh-bio-gem",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "基因组尺度代谢模型（GEM）构建插件：输入细菌全基因组（蛋白FASTA，支持多质粒/多染色体），自动构建+验证+补洞+出报告（SBML + 模型卡），供 dsh-bio-genie 消费工具加载使用 | Genome-scale metabolic model builder for dsh",
   "repository": {
     "type": "git",
@@ -40,8 +40,8 @@
   },
   "scripts": {
     "smoke": "node test/smoke.js",
-    "test": "node test/smoke.js --skip-build && node test/integration.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js",
-    "test:full": "node test/smoke.js && node test/integration.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js"
+    "test": "node test/smoke.js --skip-build && node test/integration.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js && node --import ./test/register-dsh-tools.mjs test/check-capabilities.mjs && node test/check-counts.mjs",
+    "test:full": "node test/smoke.js && node test/integration.js && node --import ./test/register-dsh-tools.mjs test/optional-injection.js && node --import ./test/register-dsh-tools.mjs test/check-capabilities.mjs && node test/check-counts.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-tools": "*"

package/python/benchmark.py

@@ -19,7 +19,7 @@ from sensitivity import find_biomass_gam
 from validate import Validator
 
 EPS = 1e-6
-UNITS_NOTE = "growth=mmol/gDW/h；必需判定=敲除生长<1e-6"
+UNITS_NOTE = "growth=1/h（比生长速率；biomass 归一化口径，数值 = μ）；必需判定=敲除生长<1e-6"
 DEG_MSG = "wt<=EPS：必需性判定恒真（v=0 使全部候选判'必需'），essential 集无生物学意义"
 
 
@@ -317,7 +317,7 @@ def write_md(path, out):
     L.append("\n## 3. 生长（声明介质，单点 FBA 口径）\n")
     for tag, name in (("a", "A"), ("b", "B")):
         g = out["growth"][tag]
-        L.append(f"- **{name}**: growth=**{g['growth']}** mmol/gDW/h, resolved={g['resolved_exchanges']}, "
+        L.append(f"- **{name}**: growth=**{g['growth']}** 1/h, resolved={g['resolved_exchanges']}, "
                  f"boundary_style={g['boundary_style']}, unresolved={g['unresolved']}")
         if g.get("resolved_display"):
             L.append(f"  - resolved_display: {g['resolved_display']}")
@@ -492,7 +492,7 @@ def benchmark(model_a, model_b, medium=None, phenotype_table=None, reference_ess
     for tag, path in (("a", model_a), ("b", model_b)):
         wt, resolved, unresolved, preset, bstyle = growth_on(path, medium)
         entry = {"growth": wt, "resolved_exchanges": len(resolved), "unresolved": unresolved,
-                 "medium_preset": preset, "boundary_style": bstyle, "units": "mmol/gDW/h",
+                 "medium_preset": preset, "boundary_style": bstyle, "units": "1/h",
                  "point_value_note": "单点 FBA 值，非解空间硬结论；条件间对比用 gem_fluxscan（区间制）"}
         if bstyle:
             entry["resolved_display"] = [ex_display_name(silent_read_sbml(path), rid)

package/python/biomass_tools.py

@@ -4,7 +4,7 @@
 # apply（显式）: biomass_profile 覆盖表（op=set|add|remove）→ 副本替换 biomass → 强制 G1-G6 重验
 #               + 三联对照（生长/表型/必需基因 delta）→ model_lineage 追加（有 card 时）
 # 原则: 默认不应用任何 profile；生长变差 WARN 不阻塞；C58 CarveMe AB 0.624 锚点保护（delta 如实报告）。
-# units: growth 一律 mmol/gDW/h。
+# units: growth 一律 1/h（比生长速率；biomass 反应 gDW 归一化口径，数值 = μ）。
 import os
 import re
 import sys
@@ -18,7 +18,7 @@ import cobra
 EX_PREFIX = ("EX_", "DM_", "SK_")
 DEFAULT_UNIVERSAL = r"D:\Program\hermes\temp\gem_universal\iML1515.xml"
 DEFAULT_INX = r"F:\A_NGJ plan\Zcode\models\iNX1344_v4.xml"
-GROWTH_UNITS = "mmol/gDW/h"
+GROWTH_UNITS = "1/h"
 EPS = 1e-6
 
 # 分类词表（name 规约匹配为主，id 规约为辅；覆盖 BiGG/ModelSEED/MetaCyc 常见命名）

package/python/bootstrap_carveme.py

@@ -0,0 +1,259 @@
+# bootstrap_carveme.py — CarveMe 运行时「零手动部署」（探测 → uv venv → carveme → diamond → 冒烟 → manifest）
+#
+# 产品原则：用户零手动安装。gem_build(engine=carveme) 首次调用时自动补齐运行时：
+#   1. 探测现有 venv（carve.exe + diamond.exe + 冒烟通过）→ 就绪则秒回
+#   2. 缺则部署：uv venv（uv 探测链见下）→ uv pip install carveme → 下载 diamond 官方二进制 → 冒烟
+#   3. 全过程写进度事件（progress.jsonl），失败给「可执行指引」而不是裸异常
+#
+# uv 探测链：GEM_UV env → genie 自举 uv（~/.dsh/dsh-bio-genie/bin/uv.exe）→ PATH uv
+# diamond 来源：GitHub release 固定版本（v2.2.8, diamond-windows.zip, 3.4MB 纯二进制）
+#   下载策略：直连 → 环境变量代理（HTTPS_PROXY/HTTP_PROXY）→ 失败给指引
+#
+# 幂等性：重复调用不重复部署；diamond 单独缺失时只补 diamond；manifest.json 记录版本与来源
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+import zipfile
+
+DEFAULT_CARVE_VENV = os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem", "venv-carveme")
+GEM_ROOT = os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-gem")
+DIAMOND_VERSION = "v2.2.8"
+DIAMOND_URL = f"https://github.com/bbuchfink/diamond/releases/download/{DIAMOND_VERSION}/diamond-windows.zip"
+GENIE_UV = os.path.join(os.path.expanduser("~"), ".dsh", "dsh-bio-genie", "bin", "uv.exe")
+
+VERIFY_TIMEOUT = 60
+DOWNLOAD_TIMEOUT = 300
+
+
+def _log(progress_path, event):
+    """进度事件（与 build.py 同格式；progress_path 为 None 时静默）。"""
+    if not progress_path:
+        return
+    try:
+        ev = {"ts": time.time(), **event}
+        with open(progress_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(ev, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def _run(cmd, timeout=VERIFY_TIMEOUT, env=None):
+    return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
+                          env=env, encoding="utf-8", errors="replace")
+
+
+def find_uv():
+    """uv 探测链：GEM_UV → genie 自举 → PATH。返回 (uv_path, source) 或 (None, None)。"""
+    env_uv = os.environ.get("GEM_UV")
+    if env_uv and os.path.exists(env_uv):
+        return env_uv, "env:GEM_UV"
+    if os.path.exists(GENIE_UV):
+        return GENIE_UV, "genie-bootstrap"
+    which = shutil.which("uv")
+    if which:
+        return which, "PATH"
+    return None, None
+
+
+def _carve_exe(venv=None):
+    return os.path.join(venv or DEFAULT_CARVE_VENV, "Scripts", "carve.exe")
+
+
+def _diamond_exe(venv=None):
+    return os.path.join(venv or DEFAULT_CARVE_VENV, "Scripts", "diamond.exe")
+
+
+def _probe(venv=None, deep=False):
+    """就绪探测。
+    deep=False（默认）：文件存在 + manifest 信任 —— 秒级（gem_build 每次调用的日常路径）；
+    deep=True：额外跑 diamond/carve 冒烟（部署完成后复验一次用）。
+    返回 (ok, detail)。"""
+    carve, diamond = _carve_exe(venv), _diamond_exe(venv)
+    if not os.path.exists(carve):
+        return False, {"missing": "carve.exe"}
+    if not os.path.exists(diamond):
+        return False, {"missing": "diamond.exe"}
+    if not deep and _read_manifest(venv):
+        return True, {"mode": "fast-manifest"}
+    try:
+        r1 = _run([diamond, "--version"])
+        if r1.returncode != 0:
+            return False, {"diamond_broken": (r1.stderr or r1.stdout or "")[:200]}
+        # carve 无 --version：用 -h 验证可启动（exit 0）
+        r2 = _run([carve, "-h"])
+        if r2.returncode not in (0, 1):  # argparse -h 正常为 0；某些版本非 0
+            return False, {"carve_broken": (r2.stderr or r2.stdout or "")[:200]}
+        return True, {"diamond": (r1.stdout or "").strip()[:80], "mode": "deep-smoke"}
+    except Exception as e:
+        return False, {"probe_error": f"{type(e).__name__}: {e}"}
+
+
+def _download(url, dest, progress_path=None):
+    """下载（直连 → 环境代理 → 抛错含指引）。返回使用的通道。"""
+    headers = {"User-Agent": "dsh-bio-gem-bootstrap/1.0"}
+
+    def _get(opener=None):
+        req = urllib.request.Request(url, headers=headers)
+        op = opener.open(req, timeout=DOWNLOAD_TIMEOUT) if opener else urllib.request.urlopen(req, timeout=DOWNLOAD_TIMEOUT)
+        with op as resp, open(dest, "wb") as f:
+            shutil.copyfileobj(resp, f)
+
+    try:
+        _get()
+        return "direct"
+    except Exception as e1:
+        _log(progress_path, {"event": "diamond_direct_failed", "err": str(e1)[:200]})
+    proxy = (os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
+             or os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy"))
+    if proxy:
+        try:
+            opener = urllib.request.build_opener(
+                urllib.request.ProxyHandler({"http": proxy, "https": proxy}))
+            _get(opener)
+            return f"proxy:{proxy}"
+        except Exception as e2:
+            _log(progress_path, {"event": "diamond_proxy_failed", "err": str(e2)[:200]})
+    raise RuntimeError(
+        f"无法下载 diamond（{url}）。可执行的手动方案：\n"
+        f"  1) 设置代理后重试：set HTTPS_PROXY=http://127.0.0.1:端口\n"
+        f"  2) 或手动下载 diamond-windows.zip，把解压出的 diamond.exe 放到：\n"
+        f"     {os.path.join(DEFAULT_CARVE_VENV, 'Scripts')}")
+
+
+def ensure_carveme(venv=None, progress_path=None, force_diamond=False):
+    """确保 CarveMe 运行时可用（幂等）。返回 dict：
+    {ready, action: already|deployed|repaired|failed, carve, diamond, version, note?, error?}
+    """
+    venv = venv or DEFAULT_CARVE_VENV
+    ok, detail = _probe(venv)
+    if ok and not force_diamond:
+        return {"ready": True, "action": "already", "carve": _carve_exe(venv),
+                "diamond": _diamond_exe(venv), "note": detail.get("diamond", "")}
+
+    _log(progress_path, {"event": "bootstrap_start", "venv": venv, "probe": detail})
+    os.makedirs(os.path.dirname(venv), exist_ok=True)
+
+    uv, uv_src = find_uv()
+    if not uv:
+        return {"ready": False, "action": "failed", "error":
+                "未找到 uv（探测链：GEM_UV env → ~/.dsh/dsh-bio-genie/bin/uv.exe → PATH）。"
+                "请安装 uv（https://docs.astral.sh/uv/）或安装宿主插件 dsh-bio-genie 以复用其自举 uv。"}
+
+    # ---- 1) venv + carveme（carve.exe 缺失或损坏时） ----
+    need_env = not os.path.exists(_carve_exe(venv))
+    if need_env:
+        _log(progress_path, {"event": "uv_venv", "uv": uv, "uv_source": uv_src})
+        try:
+            r = _run([uv, "venv", venv, "--python", "3.13"], timeout=300)
+            if r.returncode != 0 or not os.path.exists(os.path.join(venv, "Scripts", "python.exe")):
+                return {"ready": False, "action": "failed",
+                        "error": f"uv venv 创建失败 rc={r.returncode}: {(r.stderr or '')[-300:]}"}
+        except Exception as e:
+            return {"ready": False, "action": "failed", "error": f"uv venv 异常: {e}"}
+
+        py = os.path.join(venv, "Scripts", "python.exe")
+        _log(progress_path, {"event": "uv_pip_carveme", "detail": "uv pip install carveme"})
+        try:
+            r = _run([uv, "pip", "install", "--python", py, "carveme"], timeout=900)
+            if r.returncode != 0:
+                return {"ready": False, "action": "failed",
+                        "error": f"carveme 安装失败 rc={r.returncode}: {(r.stderr or '')[-400:]}"}
+        except Exception as e:
+            return {"ready": False, "action": "failed", "error": f"carveme 安装异常: {e}"}
+
+    # ---- 2) diamond（缺失/损坏时补） ----
+    if not os.path.exists(_diamond_exe(venv)) or force_diamond:
+        scripts_dir = os.path.join(venv, "Scripts")
+        os.makedirs(scripts_dir, exist_ok=True)
+        tmp_zip = os.path.join(venv, "diamond-download.zip")
+        _log(progress_path, {"event": "diamond_download", "url": DIAMOND_URL})
+        try:
+            channel = _download(DIAMOND_URL, tmp_zip, progress_path)
+        except RuntimeError as e:
+            return {"ready": False, "action": "failed", "error": str(e)}
+        try:
+            with zipfile.ZipFile(tmp_zip) as z:
+                names = z.namelist()
+                if "diamond.exe" not in names:
+                    return {"ready": False, "action": "failed",
+                            "error": f"diamond zip 内容异常: {names}"}
+                z.extract("diamond.exe", scripts_dir)
+        except Exception as e:
+            return {"ready": False, "action": "failed", "error": f"diamond 解压失败: {e}"}
+        finally:
+            try:
+                os.remove(tmp_zip)
+            except OSError:
+                pass
+        _log(progress_path, {"event": "diamond_ready", "channel": channel})
+
+    # ---- 3) 冒烟复验（deep：真跑 diamond/carve 一次） ----
+    ok2, detail2 = _probe(venv, deep=True)
+    version = _read_carve_version(venv)
+    manifest = {
+        "carve_version": version,
+        "diamond_version": DIAMOND_VERSION,
+        "diamond_url": DIAMOND_URL,
+        "uv_source": uv_src,
+        "installed_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+    }
+    try:
+        with open(os.path.join(venv, "manifest.json"), "w", encoding="utf-8") as f:
+            json.dump(manifest, f, ensure_ascii=False, indent=1)
+    except OSError:
+        pass
+
+    if not ok2:
+        return {"ready": False, "action": "failed",
+                "error": f"部署后冒烟未通过: {detail2}"}
+    action = "deployed" if need_env else "repaired"
+    _log(progress_path, {"event": "bootstrap_done", "action": action, "manifest": manifest})
+    return {"ready": True, "action": action, "carve": _carve_exe(venv),
+            "diamond": _diamond_exe(venv), "manifest": manifest}
+
+
+def _read_carve_version(venv=None):
+    py = os.path.join(venv or DEFAULT_CARVE_VENV, "Scripts", "python.exe")
+    if not os.path.exists(py):
+        return None
+    try:
+        r = _run([py, "-c",
+                  "import importlib.metadata as im; print(im.version('carveme'))"])
+        if r.returncode == 0:
+            return (r.stdout or "").strip()
+    except Exception:
+        pass
+    return None
+
+
+def carveme_status(venv=None):
+    """只读状态（供诊断/工具面板）。"""
+    ok, detail = _probe(venv)
+    return {"ready": ok, "venv": venv or DEFAULT_CARVE_VENV,
+            "carve": _carve_exe(venv), "diamond": _diamond_exe(venv),
+            "detail": detail, "manifest": _read_manifest(venv),
+            "uv": find_uv()[1]}
+
+
+def _read_manifest(venv=None):
+    p = os.path.join(venv or DEFAULT_CARVE_VENV, "manifest.json")
+    try:
+        with open(p, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+if __name__ == "__main__":
+    # CLI：python bootstrap_carveme.py [status|ensure]
+    action = sys.argv[1] if len(sys.argv) > 1 else "ensure"
+    if action == "status":
+        print(json.dumps(carveme_status(), ensure_ascii=False, indent=1))
+    else:
+        out = ensure_carveme()
+        print(json.dumps(out, ensure_ascii=False, indent=1))
+        sys.exit(0 if out.get("ready") else 1)

package/python/build.py

@@ -138,6 +138,14 @@ def build(input_spec, name=None, medium=None, venv=None, out_dir=None, progress_
     os.makedirs(out_dir, exist_ok=True)
     out_xml = os.path.join(out_dir, name + ".xml")
 
+    # 0) 运行时自举（零手动安装）：carve + diamond 缺失时自动部署（幂等，就绪时秒过）
+    from bootstrap_carveme import ensure_carveme
+    boot = ensure_carveme(venv=venv, progress_path=progress_path)
+    if not boot.get("ready"):
+        _log(progress_path, {"event": "bootstrap_failed", "error": boot.get("error")})
+        raise RuntimeError("CarveMe 运行时不可用：" + str(boot.get("error")))
+    _log(progress_path, {"event": "bootstrap_ok", "action": boot.get("action")})
+
     # 1) carve（自带 M9 gapfill，CarveMe 原生最小培养基）
     st = time.time()
     if not (os.path.exists(out_xml) and os.path.getmtime(out_xml) > os.path.getmtime(proteins)):
@@ -195,7 +203,7 @@ def build(input_spec, name=None, medium=None, venv=None, out_dir=None, progress_
     # 4) 模型卡（schema v2 起步：supported_mediums 由验证结果得出）
     supported = [
         {"medium_name": "M9", "ex_reactions": sorted(med_m9),
-         "growth_rate": g3_m9.get("growth_medium"), "units": "mmol/gDW/h",
+         "growth_rate": g3_m9.get("growth_medium"), "units": "1/h",
          "validation_status": "verified_G3" if g3_m9.get("status") == "PASS" else "unverified"},
     ]
     if target and target.get("g3") == "PASS":
@@ -204,7 +212,7 @@ def build(input_spec, name=None, medium=None, venv=None, out_dir=None, progress_
             tname = medium.get("medium_name") or "custom"
         supported.append({
             "medium_name": tname, "ex_reactions": target.get("resolved_exchanges"),
-            "growth_rate": target.get("growth"), "units": "mmol/gDW/h",
+            "growth_rate": target.get("growth"), "units": "1/h",
             "validation_status": "verified_G3_G4" if target.get("gapfixes_applied", 0) == 0 else "verified_G3_only",
         })
     # 模型卡（schema v2：init_card 统一基座 —— lineage v0.1.0 起始 + changelog=[build]）

package/python/double_knockout.py

@@ -63,7 +63,7 @@ def double_knockout(model_path, medium=None, max_pairs=5000, export_csv=None,
     log(f"[dk] {model_path} medium={medium} wt={wt} max_pairs={max_pairs}")
 
     out = {"model": model_path, "medium": medium, "medium_preset": preset,
-           "wt_growth": wt, "units": "mmol/gDW/h", "assumption_note": ASSUMPTION_NOTE,
+           "wt_growth": wt, "units": "1/h", "assumption_note": ASSUMPTION_NOTE,
            "max_pairs": max_pairs, "eps": EPS,
            "degenerate": wt <= EPS}
     if out["degenerate"]:

package/python/essential_scan.py

@@ -151,7 +151,7 @@ def essential_scan(model_path, medium=None, gene_subset=None, progress=None, led
         "medium_unresolved": unresolved,
         "note": "必需判定=A 培养基下敲除生长<1e-6；evidence 分级按基因支撑反应是否含 EVIDENCE_math（Q2）",
         # 阶段A-M4 口径声明（只增）：wt_growth 为单点 FBA 值
-        "units": "mmol/gDW/h",
+        "units": "1/h",
         "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
     })
     # 模型卡 schema v2 回写（产物旁已有 card 才写；无卡不凭空造卡）

package/python/gem_ops.py

@@ -309,6 +309,48 @@ def op_sensitivity(args):
         export_csv=args.get("export_csv"), baseline_check=baseline_check)}
 
 
+# ---------------------------------------------------------------------------
+# op: quality — gem-qi-v1 模型质量摘要（只读）
+# ---------------------------------------------------------------------------
+def op_quality(args):
+    from quality import quality_report
+    model = args.get("model")
+    if not model or not os.path.exists(model):
+        return {"ok": False, "error": f"model file not found: {model}"}
+    try:
+        result = quality_report(
+            model, medium=args.get("medium"), checks=args.get("checks"),
+            export_csv=args.get("export_csv"))
+    except (ValueError, OSError) as e:
+        return {"ok": False, "error": str(e)}
+    return {"ok": True, "result": result}
+
+
+# ---------------------------------------------------------------------------
+# op: sample — COBRA 通量空间采样（默认 Windows-safe ACHR）
+# ---------------------------------------------------------------------------
+def op_sample(args):
+    from sampling import sample_fluxes
+    model = args.get("model")
+    if not model or not os.path.exists(model):
+        return {"ok": False, "error": f"model file not found: {model}"}
+    try:
+        result = sample_fluxes(
+            model,
+            medium=args.get("medium"),
+            n=args.get("n", 1000),
+            method=args.get("method", "auto"),
+            thinning=args.get("thinning", 100),
+            growth_floor_fraction=args.get("growth_floor_fraction"),
+            reactions=args.get("reactions"),
+            seed=args.get("seed", 42),
+            export_csv=args.get("export_csv"),
+        )
+    except (ValueError, OSError) as e:
+        return {"ok": False, "error": str(e)}
+    return {"ok": True, "result": result}
+
+
 # ---------------------------------------------------------------------------
 # 分发器
 # ---------------------------------------------------------------------------
@@ -323,6 +365,8 @@ OPS = {
     "annotate": op_annotate,
     "media_resolve": op_media_resolve,
     "l3_fix": op_l3_fix,
+    "quality": op_quality,
+    "sample": op_sample,
 }
 
 
@@ -536,4 +580,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/python/l3_fix.py

@@ -417,7 +417,7 @@ def l3_fix(model_path, medium=None, substrates=None, out=None,
         if exid and exid in m.reactions and g < 1e-6:
             l3.append({"substrate": sub, "exchange": exid, "growth_sole_before": round(g, 6),
                        # 阶段A-M4 口径声明（只增）
-                       "units": "mmol/gDW/h",
+                       "units": "1/h",
                        "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"})
 
     # 第五闸门（入口预检: 每底物至少 1 条新增预估）
@@ -493,7 +493,7 @@ def l3_fix(model_path, medium=None, substrates=None, out=None,
                                     "evidence": "EVIDENCE_math"})
         growth_a = _growth_sole(cur, resolved_med, exid)
         l3a["growth_sole_after"] = round(growth_a, 6)
-        l3a["units"] = "mmol/gDW/h"
+        l3a["units"] = "1/h"
         l3a["point_value_note"] = "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"
         entry["l3a"] = l3a
 
@@ -556,12 +556,12 @@ def l3_fix(model_path, medium=None, substrates=None, out=None,
             _note(f"[l3b] {sub}: picked {len(picked)}, added {len(added_here)}")
         growth_b = _growth_sole(cur, resolved_med, exid)
         l3b["growth_sole_after"] = round(growth_b, 6)
-        l3b["units"] = "mmol/gDW/h"
+        l3b["units"] = "1/h"
         l3b["point_value_note"] = "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"
         l3b["added"] = added_here
         entry["l3b"] = l3b
         entry["growth_sole_after"] = round(max(growth_a, growth_b), 6)
-        entry["units"] = "mmol/gDW/h"
+        entry["units"] = "1/h"
         entry["point_value_note"] = "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"
         entry["verdict"] = "fixed" if growth_b > 1e-6 else "not_fixable"
         if entry["verdict"] == "not_fixable":

package/python/ledger.py

@@ -401,7 +401,7 @@ def register_phenotype(model_path, g4_results, condition=None, lineage_version=N
             "type": "phenotype",
             "content": (f"底物 {sub} 预测{'生长' if r.get('predicted') else '不生长'}"
                         f"（文献={r.get('published')}，匹配={r.get('match')}，"
-                        f"growth={r.get('growth')} mmol/gDW/h）"),
+                        f"growth={r.get('growth')} 1/h）"),
             "model": model_path,
             "model_lineage_version": lineage_version,
             "condition": condition,

package/python/model_card.py

@@ -3,14 +3,15 @@
 #       / set_verified_phenotypes（phenotype 结果）/ set_essential_genes（必需基因 + 证据分级）
 # 纪律: 各工具完成后**仅当产物模型旁已有 card** 才向后追加；无卡不动（不凭空造卡）。
 # 兼容: build.py 旧卡（无 schema 字段）读取时即时迁移到 v2（新增字段缺失不报错）。
-# units: growth_rate 一律 mmol/gDW/h（schema v2 规定，勿用 1/h）。
+# units: growth_rate 一律 1/h（比生长速率；biomass 反应 gDW 归一化口径，数值 = μ）。
+# 2026-09-21 由 mmol/gDW/h 演进为 1/h：数值不变、生物语义更准（外部评审 P0；schema 向后兼容，旧卡照读）。
 import os
 import json
 import time
 
 CARD_SUFFIX = ".card.json"
 SCHEMA = "v2"
-GROWTH_UNITS = "mmol/gDW/h"
+GROWTH_UNITS = "1/h"
 
 
 def _now():

package/python/precursor_scan.py

@@ -73,7 +73,7 @@ def scan_precursors(model_path, medium=None, max_precursors=200):
         "medium_applied_exchanges": medium_applied,
         "medium_unresolved": unresolved,
         "baseline_flux": round(baseline, 6),
-        "units": "mmol/gDW/h",
+        "units": "1/h",
         "point_value_note": "单点 FBA 值，非解空间硬结论",
         "blocking_precursors": [],
         "n_blocking": 0,