dsh-bio-gem

基因组尺度代谢模型（GEM）构建插件：输入细菌全基因组（支持多质粒/多染色体），自动构建 → 验证 → 补洞 → 出报告（标准 SBML + 模型卡），产出后可由 dsh-bio-genie 现有消费工具（FBA / 基因必需性 / 生产包络线 / 模型管理面板）直接加载使用。

Genome-scale metabolic model builder for dsh: genome in, validated SBML out.

📦 安装

本插件已发布为 npm 包 @dsh-bio/dsh-bio-gem（纯 ESM，无构建步骤），也可直接从 GitHub 源或本地目录安装。

0. 环境要求

Python 环境从哪来（v0.1.4 起）：解释器探测顺序为 GEM_PYTHON → 宿主 dsh-bio-genie 的自举环境 → CONDA_PREFIX → PATH 中的 python， 且会逐个探测该解释器能否 import cobra（不盲选）。

因此：装了 dsh-bio-genie 就无需任何额外配置 —— genie 的自举环境自带 cobra （属它的第一层依赖），gem 直接复用。只有未装 genie 时才需要按第 2 步自备解释器。

gem_build（构建侧）另有重依赖（CarveMe + diamond，或 WSL2 + gapseq），见第 3、4 步， 这部分不与 genie 共享环境。

1. 安装插件

# 方式一：从 npm 安装（推荐，已发布预置包）
npx -y @deepseek-ai/dsh plugin --profile web add @dsh-bio/dsh-bio-gem

# 方式二：从 GitHub 安装（拉源码；本插件纯 ESM 无构建步骤，可直接加载）
npx -y @deepseek-ai/dsh plugin --profile web add github:moonbowterfly/dsh-bio-gem

# 方式三：从本地目录安装（本地源码）
npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-bio-gem

方式四：安装到 dsh 桌面端（0.2.0+，推荐）——桌面端内置 dsh 命令与 pnpm，无需另装 Node/pnpm：

1. 先启动一次桌面端（初始化 desktop profile），完全退出应用；
2. 用桌面端自带 CLI 安装（Windows 默认安装路径）：

& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add @dsh-bio/dsh-bio-gem

3. 重新打开桌面端生效（也可直接在桌面端内 「插件」页输入包名安装，无需退出应用）。

• 若已全局安装 dsh CLI，把 npx -y @deepseek-ai/dsh 换成 dsh 即可。
• --profile <name> 是必填选项（不传报 required option '--profile <name>' not specified）；Web 端固定用 web，桌面端固定用 desktop。
• 安装完重启对应的 dsh（web：重新双击启动入口；桌面端：重开应用）。
• 引擎兼容：0.1.x 侧经 dsh 0.1.5-rc.2 完整兼容核验与实机验证；0.2.0+（含官方桌面端）已于 2026-10-01 实测（工具全量注册 + gem_media_resolve 真实执行）。
• 版本刚发布时可能短时间拉不到：registry 首次分发有几分钟延迟，pnpm 还可能缓存住 404。遇到 ERR_PNPM_FETCH_404 ... is not in the npm registry 时等几分钟重试，或在命令末尾追加 --registry https://registry.npmjs.org/ 绕过缓存。

验证插件层已生效（不用启动服务）：

npx -y @deepseek-ai/dsh --profile web --dump-config | grep dsh-bio-gem

2. 准备分析用 Python（cobra）—— 装了 genie 就跳过

已安装 @dsh-bio/dsh-bio-genie 时本节可跳过：gem 自动复用 genie 的自举环境 （$DSH_HOME/dsh-bio-genie/python-env），其中 cobra 属 genie 的第一层依赖，无需任何配置。

未装 genie 时，自备一个装了 cobra 的解释器：

# uv 建独立 venv 并安装（推荐）
uv venv --python 3.11 "$HOME/.dsh/dsh-bio-gem/venv"
uv pip install --python "$HOME/.dsh/dsh-bio-gem/venv/Scripts/python.exe" cobra pyrodigal

用 GEM_PYTHON 指向它（dsh 进程的环境变量，必须在启动 dsh 之前设置）：

:: cmd（写进启动脚本即可）
set GEM_PYTHON=%USERPROFILE%\.dsh\dsh-bio-gem\venv\Scripts\python.exe

# PowerShell：永久（对之后新开的终端与快捷方式生效）
setx GEM_PYTHON "$env:USERPROFILE\.dsh\dsh-bio-gem\venv\Scripts\python.exe"

# 或临时（仅当前窗口）
$env:GEM_PYTHON = "$env:USERPROFILE\.dsh\dsh-bio-gem\venv\Scripts\python.exe"

插件不会盲选解释器：它按上述顺序逐个探测 import cobra，选中第一个可用的并缓存。 若候选全都不含 cobra，工具会显式报 ModuleNotFoundError: cobra 并附带候选探测结果， 而不是静默落到一个不可用的解释器上。

3. 准备 CarveMe（构建引擎）

# ① 独立 venv（勿并入系统 Python，也不要并入 dsh-bio-genie 的环境）
uv venv --python 3.11 "$HOME/.dsh/dsh-bio-gem/venv-carveme"
uv pip install --python "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/python.exe" carveme

# ② diamond 是 CarveMe 的外部分比对引擎，不在 Python 包里，必须单独放进来
curl -L -o diamond.zip https://github.com/bbuchfink/diamond/releases/latest/download/diamond-windows.zip
unzip -o diamond.zip diamond.exe -d "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/"

# ③ 验证（两个可执行文件应同在 venv 的 Scripts/ 下）
"$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/carve.exe" --version
"$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/diamond.exe" --version

两个实测坑（都真实踩到过）：

• 命令名是 carve，不是 carveme。
• 缺 diamond 不报错、不产文件：carve 只打一行 Unable to run diamond (make sure diamond is available in your PATH)，退出码 0、输出目录为空。构建失败又找不到原因时，先确认 diamond.exe 就在 carve.exe 旁边。
• 插件已把 venv 的 Scripts/ 注入子进程 PATH，无需激活 venv。

4.（可选）gapseq 引擎（WSL2）

gem_build 的 engine=gapseq 走 WSL2 桥（gem_gapseq 原子四步：setup / launch / status / fetch），质量档耗时 30-60 分钟/模型，非必需——默认的 engine=carveme 已能出可验证模型。桥按 WSL2 + conda 环境拓扑实现（默认路径见 python/gapseq_wsl.py 顶部常量，换机器需相应调整），故目前视为实验性可选能力。没有 WSL2 不影响其余 22 个工具与 carveme 构建。

能力探针只读检查 doall 使用的环境内 seq/Bacteria 元数据和 rev/rxn/unrev 文件，不请求 Zenodo。检查路径与当前固定的 conda 环境路径一致。

5. 自检（仓库源码目录内）

# 冒烟：不依赖 dsh，直测 Python 层 + 工具注册表
# 资产（C58 模型等）不在仓库内：用 --assets-root 或 DSH_BIO_GEM_ASSETS 指定；缺资产时相关检查 SKIP
GEM_PYTHON=<你的-cobra-python> node test/smoke.js --skip-build   # 跳过 ~70s 的 build 单测
GEM_PYTHON=<你的-cobra-python> node test/smoke.js                # 含 build 单测
# 托管领域扩展的只读 integration 协议（无需 dsh 实例）
node test/integration.js

6. 与 dsh-bio-genie 协同

两个插件职责互补、可同时安装（各自独立 bundle patch 行，互不冲突）：

装好 genie 后，其 agent 常驻 persona 已内置 GEM 能力域路由，「建模型 / 建模 / 补洞」类需求会自动转给 gem_* 工具。

托管领域扩展集成协议（v0.1.11+）

当 gem 与 BioGenie 运行在同一 dsh Web 实例时，gem 提供两个固定、只读、loopback-only 的端点：

GET /api/dsh-bio-gem/integration/health
GET /api/dsh-bio-gem/integration/v1/status

• 两端点统一返回 { ok: true, value } 或 { ok: false, code, message }；health 只声明插件身份与协议能力，绝不启动 Python 或写盘。
• status 返回模型/账本/导出的限量摘要、解释器与构建引擎的只读检查；state 仅为 ready 或 degraded。Python/cobra 仍在进程内短缓存；WSL/gapseq 则采用非阻塞 stale-while-revalidate：首次返回 available: null / probing 与 warn，后台完成后才转为 ok 或 missing，不会把 status 响应拖到超时。
• gapseq 成功结果缓存 5 分钟；失败或超时最多缓存 60 秒后自动重试。探测先用固定的 wsl.exe -l -q 预检目标发行版，再运行固定只读版本命令；插件在 webServer 出现约 8 秒后后台预热一次，加载期不探测、不阻塞启动。
• 非 loopback、跨站或 Origin/Host 不一致的请求一律得到 403；端点不返回 token、任意命令、任意 URL 或完整日志。修复建议只有受控 code + owner。
• 设置入口和五态显示属于 BioGenie 面板，gem 不注册自己的设置页。BioGenie 结合本地安装探测与上述端点显示 not-installed / legacy / installed-unavailable / incompatible / degraded / ready；旧 gem 仅有文件系统只读兼容视图。
• 本批不提供 job、安装、删除、配置或其他写 API；这些操作必须等后续的显式用户动作协议。

7. 卸载

npx -y @deepseek-ai/dsh plugin --profile web remove dsh-bio-gem

运行时数据都落在 ~/.dsh/dsh-bio-gem/（models/ 模型、ledger/ 预测账本、jobs/ 构建任务、venv* 环境），卸载不会删除，需要清理请手动删除该目录。

Installation (English quickstart)

# 1) install the plugin into the web profile, then restart dsh
npx -y @deepseek-ai/dsh plugin --profile web add @dsh-bio/dsh-bio-gem
# (or from source: github:moonbowterfly/dsh-bio-gem)
# desktop app (0.2.0+): use its bundled CLI with --profile desktop, e.g.
#   & "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add @dsh-bio/dsh-bio-gem

# 2) analysis Python needs cobra (+ pyrodigal for the annotation fallback)
uv venv --python 3.11 "$HOME/.dsh/dsh-bio-gem/venv"
uv pip install --python "$HOME/.dsh/dsh-bio-gem/venv/Scripts/python.exe" cobra pyrodigal
# point the plugin at it BEFORE starting dsh (dsh reads process env):
#   PowerShell: setx GEM_PYTHON "$env:USERPROFILE\.dsh\dsh-bio-gem\venv\Scripts\python.exe"

# 3) build engine: CarveMe in a dedicated venv + the external `diamond` binary
uv venv --python 3.11 "$HOME/.dsh/dsh-bio-gem/venv-carveme"
uv pip install --python "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/python.exe" carveme
curl -L -o diamond.zip https://github.com/bbuchfink/diamond/releases/latest/download/diamond-windows.zip
unzip -o diamond.zip diamond.exe -d "$HOME/.dsh/dsh-bio-gem/venv-carveme/Scripts/"

# 4) verify the plugin layer is registered (no server needed)
npx -y @deepseek-ai/dsh --profile web --dump-config | grep dsh-bio-gem

CarveMe + diamond are required only by gem_build; the other 22 tools need nothing but a cobra-enabled Python.

工具（23）

架构见 docs/ARCHITECTURE.md。

开发速查

# Python 层直测（需 Python + cobra，推荐显式指定解释器）
echo '{"op":"model_info","args":{"model":"path.xml"}}' | "$GEM_PYTHON" -I python/gem_ops.py
"$GEM_PYTHON" -u python/build.py --input proteins.faa --name X --progress p.jsonl --medium-json '{...}'

# 独立脚本模式（gapfind/gapfill）
"$GEM_PYTHON" -I python/gapfind.py payload.json
"$GEM_PYTHON" -I python/gapfill.py payload.json

依赖：cobra（分析，需装在插件探测到的 Python 里）；carveme + diamond（构建，独立 venv ~/.dsh/dsh-bio-gem/venv-carveme）。安装步骤见上文第 2、3 节。

验收（C58 回归锚）

• gem_validate 对 C58.xml：G1 PASS / G2 WARN(仅 bio1 已知边界) / G3 PASS(0.519981) / G4 PASS(17/19) / G5 PASS
• gapfind→gapfill 闭环：原版 C58.xml + 蔗糖培养基 → 自动补交换/转运 → 蔗糖生长 0.97077（与手工 P1 补洞一致）
• gem_build 端到端（C58 protein.faa）：carve M9 gapfill 54s → 精确 M9 介质 G3 PASS 0.782 → AB 目标介质 resolve 20/20，G3 FAIL（L3 内部路径，已记录为 CarveMe 已知边界）

许可

MIT（工程层，见 LICENSE）；引擎 CarveMe/gapseq 以独立子进程调用分发，版本记录入模型卡，自带许可边界。