@dsh-bio/dsh-bio-gem 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-bio-gem contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# dsh-bio-gem
+
+**基因组尺度代谢模型（GEM）构建插件**：输入细菌全基因组（支持多质粒/多染色体），自动构建 → 验证 → 补洞 → 出报告（标准 SBML + 模型卡），产出后可由 dsh-bio-genie 现有消费工具（FBA / 基因必需性 / 生产包络线 / 模型管理面板）直接加载使用。
+
+Genome-scale metabolic model builder for dsh: genome in, validated SBML out.
+
+## 📦 安装
+
+本插件以 **GitHub 源**分发（纯 ESM，无构建步骤，可直接加载）；npm 包尚未发布。
+
+### 0. 环境要求
+
+| 组件 | 要求 | 用途 |
+|------|------|------|
+| dsh 引擎 | 0.1.x（`npx -y @deepseek-ai/dsh --version` 可查） | 宿主 |
+| Node.js | ≥ 22.19 或 ≥ 24（见 `package.json` 的 `engines`） | 宿主 |
+| Python | 3.10+，且装 **`cobra`** | 分析/验证/补洞/账本/基准/导出 —— 除 `gem_build` 外的 19 个工具 |
+| `pyrodigal` | 装在同一个 Python 环境（可选但建议） | 裸基因组自动注释兜底（`gem_annotate` / fna 输入） |
+| **CarveMe** | 独立 venv `~/.dsh/dsh-bio-gem/venv-carveme`，含 `carve.exe` + **`diamond.exe`** | `gem_build`（carveme 引擎） |
+| WSL2 + gapseq | 可选，按本机拓扑（见第 4 节） | `gem_build`（gapseq 引擎） |
+
+> **与 dsh-bio-genie 的差别**：genie 首次运行会自动引导隔离 Python 环境（uv + venv + Biopython）；本插件**不自动引导**——`gem_build` 依赖 CarveMe 和 `diamond` 两个外部重依赖，请在部署时按下面第 2、3 步一次性准备。**只做分析（不建模型）也需要第 2 步**：除 `gem_build` 外的工具都要求一个装了 `cobra` 的 Python。
+
+### 1. 安装插件
+
+```sh
+# 从 GitHub 安装（推荐）
+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 CLI，把 `npx -y @deepseek-ai/dsh` 换成 `dsh` 即可。
+- `--profile <name>` 是**必填选项**（不传报 `required option '--profile <name>' not specified`）；Web 端固定用 `web`。
+- 安装完**重启 dsh web 服务**（关掉原窗口，重新双击启动入口）。
+
+验证插件层已生效（不用启动服务）：
+
+```sh
+npx -y @deepseek-ai/dsh --profile web --dump-config | grep dsh-bio-gem
+```
+
+### 2. 准备分析用 Python（cobra）
+
+```sh
+# 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` → 本机开发默认路径 → PATH 中的 `python` 顺序探测，落到没有 cobra 的解释器上时工具会直接报 `ModuleNotFoundError: cobra`。`GEM_PYTHON` 是 **dsh 进程的环境变量，必须在启动 dsh 之前设置**：
+
+```bat
+:: cmd（写进启动脚本即可）
+set GEM_PYTHON=%USERPROFILE%\.dsh\dsh-bio-gem\venv\Scripts\python.exe
+```
+
+```powershell
+# 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"
+```
+
+### 3. 准备 CarveMe（构建引擎）
+
+```sh
+# ① 独立 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 + `/opt/miniforge3` conda 环境 `gapseq` + 本地序列库），换机器需改 `python/gapseq_wsl.py` 顶部常量，故目前**视为实验性可选能力**。没有 WSL2 不影响其余 19 个工具与 carveme 构建。
+
+### 5. 自检（仓库源码目录内）
+
+```sh
+# 冒烟：不依赖 dsh，直测 Python 层 + 工具注册表
+# 断言锚定本机 C58 夹具路径（见 test/smoke.js 顶部常量），换机器先改路径
+GEM_PYTHON=<你的-cobra-python> node test/smoke.js --skip-build   # 跳过 ~70s 的 build 单测
+GEM_PYTHON=<你的-cobra-python> node test/smoke.js                # 含 build 单测
+```
+
+### 6. 与 dsh-bio-genie 协同
+
+两个插件职责互补、可同时安装（各自独立 bundle patch 行，互不冲突）：
+
+| 插件 | 职责 |
+|------|------|
+| **dsh-bio-gem**（本插件） | **造模型**：基因组 → 构建 → 验证 → 补洞 → 模型卡 |
+| dsh-bio-genie | **用模型**：FBA / 基因必需性 / 生产包络线 / 模型管理面板，外加全量生信分析工具 |
+
+装好 genie 后，其 agent 常驻 persona 已内置 GEM 能力域路由，「建模型 / 建模 / 补洞」类需求会自动转给 `gem_*` 工具。
+
+### 7. 卸载
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile web remove dsh-bio-gem
+```
+
+运行时数据都落在 `~/.dsh/dsh-bio-gem/`（`models/` 模型、`ledger/` 预测账本、`jobs/` 构建任务、`venv*` 环境），**卸载不会删除**，需要清理请手动删除该目录。
+
+### Installation (English quickstart)
+
+```sh
+# 1) install the plugin into the web profile, then restart dsh
+npx -y @deepseek-ai/dsh plugin --profile web add github:moonbowterfly/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 19 tools need nothing but a `cobra`-enabled Python.
+
+## 工具（20）
+
+| 工具 | 作用 | 状态 |
+|---|---|---|
+| `gem_report` | 模型摘要（基因/反应/区室/复制子分布）+ 预测账本基率摘要（ledger_summary）| ✅ |
+| `gem_validate` | 六道关卡 G1-G6（加载/元素平衡/生长真实性/表型(条件)/必需性抽检(条件)/ATP 泄漏）| ✅ |
+| `gem_gapfind` | 缺口分级诊断（L1 缺交换 / L2 缺转运 / L3 内部路径）| ✅ |
+| `gem_gapfill` | 规则级补洞（L1/L2 自动，provenance 打标，防过补四闸门）| ✅ |
+| `gem_l3_fix` | L3 内部路径补洞（L3a 连通性/L3b 白名单+BiGG 反应式；证据分级 + 防过补第五闸门）| ✅ C58 阿拉伯糖 0→0.851 |
+| `gem_biomass` | biomass 精修（inspect 组分/对照参考；apply 覆盖表+三联对照+回滚）| ✅ 复位 delta 0.0 |
+| `gem_phenotype` | 表型回填迭代（G4 sole 检测 → L1/L2 修复 → L3 报告 → 匹配率对比）| ✅ |
+| `gem_essentiality` | 全量必需基因扫描（FVA 预筛 + 手工敲除）| ✅ C58: 必需 155 |
+| `gem_annotate` | 基因组→蛋白（官方优先 + pyrodigal 兜底，纯 Windows）| ✅ pyrodigal 5330 |
+| `gem_build` | CarveMe/gapseq 双引擎构建（fna/faa；后台 job + 进度；M9 或目标介质验证闭环）| ✅ carveme 70s / fna 全链 63.5s / gapseq 实测中 |
+| `gem_gapseq` | gapseq 原子四步（WSL 可选：setup/launch/status/fetch）| ✅ 本机全通 |
+| `gem_media_resolve` | 跨引擎介质解析 RPC（自然名→EX ID；消费侧统一入口）| ✅ AB→20 EX |
+| `gem_fluxscan` | 通量区间制（FVA 区间+pFBA 点值；条件对比区间分离判定，overlap=伪影禁止引用）| ✅ C58 AB 0.519981 / 蔗糖 supplement 0.97077 |
+| `gem_sensitivity` | 结构性灵敏度（GAM×biomass 22 组合全量+稳定性三分类+单组分漂移+模型卡鲁棒性 v3）| ✅ C58 基准复现 155 |
+| `gem_ledger` | 预测账本（essentiality/phenotype 自动登记；幂等；list/query/update；基率追踪）| ✅ C58 155+19 条幂等复跑 |
+| `gem_benchmark` | 通用基准对比（两模型六关并列/生长/biomass 断供探针/必需性对比[退化护栏]/表型/账本回填；介质层两级策略；支持 bigg:&lt;id&gt; 下载）| ✅ B1 自检 C58 vs C58_P1；B2 C58 vs iNX1344_v4；B3 bigg:iML1515 |
+| `gem_secretion` | 可分泌代谢物谱（production envelope 扫描；边界声明=纯拓扑 LP；wt<=EPS 退化护栏）| ✅ C58: 182 候选 85 可分泌 |
+| `gem_double_knockout` | 双敲 v1 合成致死（GPR 穷尽先验+全扫预算；假设生成声明内置）| ✅ C58: Atu3364↔Atu4682 对应命中 |
+| `gem_enrichment` | 必需基因通路富集（超几何+BH FDR；通路源=SBML groups；无注释诚实兜底）| ✅ C58: 388 通路 55 显著 |
+| `gem_targets` | 靶点清单规范导出（账本三类 -> 锁定 schema CSV/JSON；计数闭合）| ✅ C58: 258 行三类闭合 |
+
+架构/决策见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)、[docs/DECISIONS-2026-08-29.md](docs/DECISIONS-2026-08-29.md)。
+
+## 开发速查
+
+```bash
+# 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](LICENSE)）；引擎 CarveMe/gapseq 以独立子进程调用分发，版本记录入模型卡，自带许可边界。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-bio-gem bundle patch: inserts the plugin row over whatever profile it
+# is stacked on. Applied AFTER @deepseek-ai/dsh-base (which supplies the
+# `tools` service this plugin injects).
+
+- insert:
+    - id: dsh-bio-gem
+      name: '@dsh-bio/dsh-bio-gem'

package/docs/ARCHITECTURE.md

@@ -0,0 +1,116 @@
+# dsh-bio-gem — 架构文档（M1 定稿 2026-08-29）
+
+## 1. 定位一句话
+
+dsh 平台的 **GEM 构建侧插件**：输入细菌全基因组（支持多质粒/多染色体），自动构建→验证→补洞→出报告（标准 SBML + 模型卡），产出后可被 dsh-bio-genie 现有消费工具（FBA/必需性/生产包络线/模型面板）直接加载使用。
+
+硬性原则（沿袭 bio-genie）：**用户零手动安装、零自愈、通用化（不可本机特化）、结论可溯源**。
+
+## 2. 决策记录（为什么这么设计）
+
+| 日期 | 决策 | 依据 |
+|---|---|---|
+| 08-28 | 插件名 dsh-bio-gem；资产盘点：消费侧已就绪、补构建侧闭环 | 用户拍板 |
+| 08-29 | 引擎路线：**任务门槛路由**（不是简单 auto）；落地节奏 **M1 CarveMe+补洞 → M2 gapseq WSL 桥 → M3 双引擎交叉** | 第三方 GLM 独立评估 + 本机实测（CarveMe AB 不生长=补洞是生存线；WSL 桥显著降级交付风险；Docker 非 WSL 替代）|
+| 08-29 | MVP 工具集：gem_build / gem_validate（G1G2G3 必做，G4 条件、G5 抽检）/ gem_gapfind（L1L2L3）/ gem_gapfill（L1L2 规则自动）/ gem_report（薄版模型卡）；**gem_essentiality 不进首版** | 消费侧 bio_gene_knockout 已存在，避免重复实现 |
+| 08-29 | 修正 GLM 建议：弃 μ 判据用 FBA 通量判据；pyrodigal 注释前端降 backlog；测试矩阵首版收敛 C58+2 公开株 | 本机输出口径为 objective_value；默认输入是带注释基因组 |
+
+**裁决原则**：GLM 分析质量高但缺本机上下文（输出单位、输入形态、部署面=本机为主的现实），凡冲突处以本机实测与产品原则为准。
+
+## 3. 工具契约（20 工具 ↔ Python 层；19 op + build CLI）
+
+| 工具 | Python 层 | 阶段 |
+|---|---|---|
+| gem_build | build.py CLI（CarveMe M9 gapfill；fna 自动注释）| ✅ M1+模块 DONE（C58 63-70s）|
+| gem_validate | op validate（G1-G6 + GATE_REGISTRY）| ✅ M1 DONE |
+| gem_gapfind | op gapfind（L1-L3 分级 + 跨引擎介质归一化）| ✅ M1 DONE |
+| gem_gapfill | op gapfill（L1/L2 规则 + provenance）| ✅ M1 DONE |
+| gem_phenotype | op phenotype_fix（表型回填迭代）| ✅ A3 DONE |
+| gem_essentiality | op essential_scan（FVA 预筛 + 手工敲除；预测自动入账本）| ✅ P0 DONE |
+| gem_annotate | op annotate（官方优先 + pyrodigal）| ✅ P0 DONE |
+| gem_gapseq | op gapseq（WSL 原子四步，可选项）| ✅ 桥全通 |
+| gem_l3_fix | op l3_fix（L3 补洞：L3a 连通性 + L3b 白名单/BiGG；证据分级 + 预算闸门 + G6 回滚）| ✅ B' DONE（C58 Arabinose 0→0.851）|
+| gem_report | op model_info（+ ledger_summary 基率摘要）| ✅ DONE |
+| gem_media_resolve | op media_resolve（介质解析 RPC，消费侧统一入口）| ✅ DONE |
+| gem_biomass | op biomass_inspect / biomass_apply（inspect 组分+对照参考；apply 覆盖表+三联对照+原文件不动回滚）| ✅ Q2 DONE（复位 delta 0.0）|
+| gem_fluxscan | op fluxscan（通量区间制：FVA 区间+pFBA 点值+条件对区间分离判定，overlap=伪影禁止引用）| ✅ 阶段A-M1 DONE（C58 AB 0.519981 / 蔗糖 supplement 0.97077）|
+| gem_sensitivity | op sensitivity（GAM×biomass 22 组合全量+稳定性三分类+单组分漂移；模型卡 robustness v3）| ✅ 阶段A-M2 DONE（基准复现 155）|
+| gem_ledger | op ledger（prediction ledger：list/query/update；幂等追加式账本）| ✅ 阶段A-M3 DONE（C58 155+19 条幂等复跑）|
+| gem_benchmark | op benchmark（通用基准对比：六关并列/生长[介质层两级策略]/biomass 探针/必需性对比含退化护栏/表型/账本回填/md 落盘；model 参数支持 bigg:<id> 下载）| ✅ 阶段B-B1/B2/B3 DONE |
+| gem_secretion | op secretion（可分泌谱：production envelope；边界声明内置；wt<=EPS 退化护栏不登记）| ✅ 阶段C-C1 DONE（C58 85 可分泌）|
+| gem_double_knockout | op double_knockout（双敲 v1：GPR 穷尽先验+全扫 max_pairs 预算；假设声明内置）| ✅ 阶段C-C2 DONE（Atu3364↔Atu4682 对应命中）|
+| gem_enrichment | op enrichment（必需基因通路富集：超几何+BH FDR；无注释 annotation_unavailable 兜底）| ✅ 阶段C-C3 DONE（C58 55 条 FDR 显著）|
+| gem_targets | op targets（靶点规范导出：11 字段锁定 schema；账本计数闭合；引物设计不做）| ✅ 阶段C-C4 DONE（258 行三类闭合）|
+
+> Python 分发器 `gem_ops.py` 共 **19 个 op**（model_info/validate/gapfind/gapfill/gapseq/phenotype_fix/essential_scan/annotate/media_resolve/l3_fix/biomass_inspect/biomass_apply/fluxscan/sensitivity/ledger/benchmark/secretion/double_knockout/enrichment/targets）；`gem_build` 不经分发器，由 `build.py` CLI 直接调用（长任务，jobs.js 拉起）。工具数（20）= op 数（19）+1（gem_biomass 一工具映射两 op）（biomass 一工具映射两 op，build 走 CLI 不占 op）。附模型卡统一写入 `python/model_card.py`（lineage/verified_phenotypes/essential_genes/robustness v3）与往返保真自检 `python/roundtrip_check.py`；预测账本 `python/ledger.py`（一个模型一个账本：`~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl`，按模型 basename 分，显式 ledger_path 可覆盖；无参查询=聚合全局视图；旧全局 predictions.jsonl 已迁移为 legacy）。**生长/通量数值口径（阶段A-M4）**：所有产出生长/通量数值的工具输出均带 `units: mmol/gDW/h` 与单点 FBA 声明；条件间通量对比一律走 gem_fluxscan 区间分离判定（overlap=伪影禁止引用）。
+
+## 4. 引擎路线（M1→M2→M3）
+
+- **M1（已完成 08-29，C58 实测）**：CarveMe 纯 Windows（独立 venv ~/.dsh/dsh-bio-gem/venv-carveme + diamond PATH 注入）。输入（protein.faa）→ carve -g M9（54s）→ 精确 M9 介质（media_db 提取）G3 PASS（C58 测 0.782）→ 用户目标介质 resolve（跨引擎自然名）→ G3 FAIL 时 L1/L2 规则补洞 → 模型卡。**CarveMe 模型实测：M9 可生长；AB 目标介质 FAIL 且为 L3 内部路径（L1/L2 规则不可修）——诚实报告为已知边界（研究设计既有结论：CarveMe M9 补洞局限）。**
+- **M2（2026-08-29 代码完成，doall 实测进行中）**：gapseq WSL2 桥（`python/gapseq_wsl.py`）。能力探测四件套（wsl/发行版/gapseq 版本/序列库注册 up-to-date——防假已装 UniProt 灾难）；新版 wsl.exe 输出 UTF-8（旧版 UTF-16LE，双解码兼容）；doall 哨兵文件轮询（30-60min，每 2min 进度 + 日志尾部旁观）；产物拷回 → 目标介质验证（AB 自然名）→ L1/L2 补洞闭环 → 模型卡。gem_build `engine` 参数（carveme|gapseq）+ 60min 超时。分发时采用**私有发行版**（wsl --import 自包含 bundle：R+gapseq+序列库 v1.5+哈希校验，版本钉死）。任务分步化（draft/build/transport/fill/adjust 每步落盘 → 断点续跑）待做。
+- **M3**：双引擎交叉验证，产出**分歧清单**（两引擎不一致反应/基因 = 低置信区，需文献/实验校验）而非平均；可选集成 gemsembler（先验证成熟度）；所有比对按**反应级等价类**而非基因级（引擎 GPR 粒度不同）。
+
+## 5. 五道验证关卡规格（HANDOFF-03 产品化）
+
+| 关卡 | 内容 | 首版 | 判定线 |
+|---|---|---|---|
+| G1 | 加载统计 + 多复制子 locus_tag 唯一性 + GPR 覆盖 | ✅ | 可加载；无重复 ID；GPR 覆盖率报告 |
+| G2 | 内部反应元素平衡（EX/DM/SK/boundary 排除）| ✅ | C/N/P/S 不平衡=0（FAIL/WARN），H/charge 单独报告；公式覆盖率先报 |
+| G3 | 生长真实性（声明培养基）| ✅ | 有碳源 objective_value>0；无碳 <1e-6；全关=0；与参照值比值≥99% 判 PASS |
+| G4 | 底物表型对照 | 条件 | 有参照表才跑（内置 C58 39 底物作回归锚），不设阻塞阈值 |
+| G5 | 必需基因抽检（≤30 基因）| 条件 | 有参照集才跑；映射覆盖 <80% 时 SKIP(WARN) |
+
+关卡 fail-fast 排序 G1→G3→G2（便宜的先行）；gem_validate 保持**无状态**，同 run 可双跑（补洞前后 diff 写进模型卡）。
+
+**判据口径**：FBA objective_value（mmol/gDW/h），不用 μ（h⁻¹）——模型输出单位即通量；C58 回归锚：gapseq AB=0.519981；补洞后 CarveMe 目标 ≥0.1 为软目标。
+
+## 6. 缺口分级（gapfind/gapfill）
+
+- **L1 缺交换**：培养基成分表 vs 模型 EX_ 列表的集合差 → 修复=补 EX_ 反应（完善环境定义，最安全）
+- **L2 缺转运**：e0↔c0 区室连通性（代谢物在胞外存在但无转运反应入胞）→ 修复=补转运（GPR 可空，标注未表征）
+- **L3 内部路径**：底物有交换+转运却无法达中心代谢 → 需文献反应（M1 报告清单，不自动补）
+
+已知规律（P1 实测）：多数"不能利用某碳源"缺口是 L1/L2 而非 L3。
+
+**防过补四闸门**：分级规则优先于 MILP（M1 不做 MILP）；新增反应数封顶（max_add=20）；逐条 provenance 打标（来源/原因/是否借自模板）；修复后强制重验 G3 + 生长值合理性上限告警（>1.0 时 WARN 过补嫌疑）。
+
+## 7. 模型卡（sidecar JSON，与 SBML 同目录同名 .card.json）
+
+```
+{ engine, engine_version, db_version, command, started, finished,
+  memote_like: {g1..g5}, gapfixes: [{type, reaction, reason, source}],
+  growth: {medium, before, after}, mapping_coverage,
+  replicons, warnings }
+```
+写盘用 cobra.io.write_sbml_model（cobra 0.32.1 无 Model.save_model——坑位记档）。
+
+## 8. 后台任务（M1 基建，约 30% 工程量）
+
+job 化 + 进度事件（粒度 ≤5s）+ 分步 checkpoint（每步落盘，可断点续跑）+ 结果可重入。引擎无关，M2 gapseq 直接复用。
+
+## 9. 与 bio-genie 衔接
+
+- 产出 SBML 落 `~/.dsh/dsh-bio-gem/models/<name>.xml`；模型卡同目录；
+- bio-genie 模型面板/消费工具读取同一模型库（路径注册另议：复用 dsh-bio-genie 的 /metabolic-models 上传入口或直接注册目录）。
+
+## 10. 验收（M1 最小可用判定线）
+
+零手动干预下：**基因组进 → 四个消费工具（FBA/必需性/包络线/面板）不经修改即可用的 SBML 出**，且模型在声明培养基上生长为正；C58 端到端演示通过（build→面板可见→FBA 可跑→必需性可跑）；模型卡齐全（引擎/版本/补洞记录/验证结果，同输入重跑一致）；5-6 Mb 基因组 p95 ≤ 20 min。
+
+## 附录 A：性能基准（阶段 A-M6，2026-08-30 本机实测，独占运行）
+
+分析 Python 3.13.13 / cobra 0.32.1 / GLPK；C58=gapseq 2485 反应/1084 基因；iNX1344_v4=1441 反应/1344 基因。
+
+| 项目 | C58 | iNX1344_v4 |
+|---|---|---|
+| model_info（读模+摘要） | 6.6s | 3.7s |
+| validate G1-G6 | 7.9s（G3 PASS 0.519981） | 3.7s（G3 WARN，介质层不兼容见 M5） |
+| essential_scan 全量（FVA 预筛+手工敲除） | ~50s（FVA 32.3s + 敲除 16.8s，818 候选） | ~30s（FVA 11.9s + 敲除 16.8s，1066 候选） |
+| fluxscan 1 条件（读模+FBA+FVA+pFBA） | ~31s（FVA 24-42s 为主） | ~14s（FVA ~12s） |
+| fluxscan 2 条件 1 对 | 63-72s | 28.5s |
+| fluxscan 3 条件 3 对 | 123.3s | 未跑（介质层不兼容，点值无意义） |
+| sensitivity 22 组合全量（每组合 wt+必需性重扫） | 2094.8s（~35min；grid 22×~95s） | 732.0s（~12min；grid 689s） |
+| 单组分 ±25% 灵敏度 | 75 组分×2=150 次 FBA，54.4s | 47 组分×2=94 次 FBA，7.9s |
+| 必需性漂移 top10（含生长探针） | 522.0s（含 7 刚性对跳过探针） | 33.8s（20/20 全部"不生长跳过"） |
+
+> 注：FVA 占单条件耗时 ~75%；sensitivity 线性于组合数（每组合 fresh 读模+FVA+敲除循环）。GLPK 对个别扰动 LP 有病态停摆前科，sensitivity 内置 LP_TIMEOUT_S=30 护栏（见 docs/DECISIONS-阶段A.md M2-5）。

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

@@ -0,0 +1,37 @@
+# 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 子命令）——待用户解锁

package/docs/DECISIONS-/351/230/266/346/256/265A.md

@@ -0,0 +1,67 @@
+# DECISIONS — 阶段 A：可信度内核六批次（2026-08-30）
+
+> 记录阶段 A（M1 fluxscan / M2 sensitivity / M3 ledger / M4 消费方升级 / M5 iNX1344 前哨 / M6 基准与文档）的每个设计决策与依据。背景：L1/L2 已做到行业上游，短板在 L3（通量分布）/L4（定量速率）呈现——单点 FBA 通量取决于求解器顶点，跨条件点值 diff 是伪影。本阶段让 L3 通量一律区间制、L2 必需性变稳定性谱、所有预测进账本可追踪。
+
+## M1 gem_fluxscan（通量区间制）
+
+| # | 决策 | 依据 |
+|---|---|---|
+| M1-1 | **语义按 bsp 锁稿一字不改**（fva_min/fva_max/pfba 三件套；区间分离判定公式；overlap=伪影禁止引用） | 任务书明确"语义已锁定，建议写报告由 bsp 裁决" |
+| M1-2 | **fraction_of_optimum 默认 0.9999 而非 1.0** | 1.0 时数值噪声会使个别区间变空/变窄（求解器在最优面顶点的抖动）；0.9999 留 0.01% 最优性余量换区间稳健性，对生长影响 <0.01% |
+| M1-3 | **tolerance 默认 1e-6 mmol/gDW/h** | 与必需性判定 EPS 同量级；区间间隙须 > 容差才判分离——防止把求解器噪声当成"硬结论"。判定公式 `ua+tol<lb → b_higher; ub+tol<la → a_higher; 否则 overlap` |
+| M1-4 | **判定与输出/CSV 同用 6 位舍入值**（而非 raw 值判定、展示舍入） | 自洽性：用户可从展示值直接复核判定。6 位舍入误差（≤5e-7）< 容差（1e-6），不改变科学结论。若 bsp 偏好 raw 判定，改一行 |
+| M1-5 | **每 condition 独立 `silent_read_sbml` 重读模型**，不用 cobra Model 深拷贝 | 深拷贝共享底层求解器状态有交叉污染风险；读模仅 4s，22 组合级成本可忽略（M2 实测 fresh 模型还规避了 GLPK 病态停摆，见 M2-5） |
+| M1-6 | **`reactions` 子集仅收窄 comparisons/summary 且两者同口径**；FVA/pFBA 恒全模型 | 任务书明确"禁止 summary 全模型 vs comparisons 子集矛盾"；FVA 全模型算一次，子集只是输出过滤，无性能收益可图 |
+| M1-7 | **only_diff 只过滤 comparisons，summary 仍全口径计数** | summary 的 total/overlapping 描述整个 scope 才有意义；任务书未明说，按"summary 与 scope 同口径"原则实现并报告 |
+| M1-8 | **conditions.name 唯一校验（重复直接报错）** | 任务书锁定要求；pairs 引用条件名，重名会使引用歧义 |
+| M1-9 | **任务书容差单测第 5 组与锁定公式矛盾——按公式实现，差异上报** | 公式 `ua+tol<lb` 要求间隙>tol；样例 `[1.0,1.0000005] vs [1.000001,2.0]` 间隙 5e-7 < tol 1e-6，公式判 overlap 而任务书写"分离"。公式是保守科学语义（防噪声造假硬结论），判"分离"需要反语义的 `ua<lb+tol`（会让"接触"样例变 b_higher，与第 2 组矛盾）。已按公式实现并双容差断言（1e-6→overlap；1e-7→b_higher 证明容差机制生效）。**待 bsp 裁决** |
+
+## M2 gem_sensitivity（结构性灵敏度）
+
+| # | 决策 | 依据 |
+|---|---|---|
+| M2-1 | **GAM 载体探索结论：C58 载体在 biomass 方程 bio1 内部**（81 组分中 ATP 水解 stub 五元组：ATP -40.165476 / H2O -34.922907 / ADP +40.0 / Pi +39.992706 / H+ +40.0，GAM_ORIG=40.0 以 ADP 系数为净水电解量），非独立 ATPM（全模型无 lb>0 维持反应） | 公式级（元素组成）识别跨命名空间通用（ModelSEED/BiGG/MetaCyc 都适用），不依赖 id 约定 |
+| M2-2 | **正交化实现**：biomass 组分缩放排除 5 元 GAM stub 与 Biomass 产物（连接 objective 的汇组分）；GAM 网格只动 stub（等比缩放 X/GAM_ORIG，保留 stub 内部记账不对称如 ATP-40.165 vs ADP+40） | 任务书要求"biomass 变体与 GAM 网格正交不混淆"；等比缩放保持 gapseq stub 的内部比例，可逆、可解释 |
+| M2-3 | **biomass 组分缩放语义 = 75 个原料/副产系数 ×f，Biomass 产物系数保持 +1.0** | 若把产物也缩放，growth 恰好等比缩放（平凡结论）；保持产物=1 才是真正的"组成不确定→生长响应"问题，且与 GAM 轴正交 |
+| M2-4 | **网格 = 3 biomass 档 × 7 GAM 档 = 21 扫点 + 1 基准（不扰动）= 22 组合**；每组合 wt growth + 必需性重扫（复用 essential_scan 拆出的 `setup_model_medium`/`scan_essentiality`） | 任务书锁定；基准与 essential_scan 完全同参数 → **实测精确复现 155（155 vs 155 EXACT MATCH）**；(1.0, gam=40) 扫点与基准互证（0.519981/155 双一致，stub×40/40=1.0 无扰动的数学必然） |
+| M2-5 | **GLPK 病态停摆护栏 LP_TIMEOUT_S=30**（optlang configuration.timeout）+ 扰动后不生长的组分跳过必需性漂移 | 实测两次全量扫描卡死于特定扰动 LP（GLPK 单纯形停摆）；30s 上限对正常 <0.05s 的 LP 是 600× 余量，永不误伤。刚性组分对（ACP↔apo-ACP 等 7 个）任一 ±25% 使 biomass 方程不可满足 → growth=0 → 必需性判定退化为"全候选必需"，漂移无意义 |
+| M2-6 | **CSV 导出容错**（跳过行无 essential_count 的 KeyError 曾致 45min 全量在导出步崩溃） | 教训：长任务的所有输出步骤必须 try/except 或缺省键兼容，不能让已完成 95% 的计算死在最后一行 |
+| M2-7 | **稳定性三分类**：always（22/22 组合必需）/ conditionally / never；基准 155 ⊆ always∪conditional 硬断言 | 任务书锁定断言（基准在网格内故必成立）；C58 实测 always=155 / conditional=0 / never=929——必需集对该网格完全鲁棒 |
+| M2-8 | **模型卡 robustness 章节 = schema v3**（v2 + robustness 字段，只增；`_ensure_v2` 接受 v3 不降级）；无 card 不造卡 | 向后兼容：读卡方按 JSON 字段访问，v2 消费方忽略 robustness 即可；C58/C58_P1 无卡 → card_robustness_written=false 如实报告 |
+
+## M3 gem_ledger（prediction ledger）
+
+| # | 决策 | 依据 |
+|---|---|---|
+| M3-1 | **追加式 JSONL**（`~/.dsh/dsh-bio-gem/ledger/predictions.jsonl`，目录不存在则创建）+ 幂等哈希去重（model+condition+type+content 的 sha256） | 任务书锁定；幂等使"每次扫描自动登记"可安全重复执行（实测 155 条复跑 appended=0/skipped=155） |
+| M3-2 | **evidence_tier 取支撑反应 evidence 集合中最高者，优先级 literature > sequence > rule > math；无标注默认 EVIDENCE_rule 并注明** | 任务书锁定优先级。注意与插件既有分级的表述差异：l3_fix 语境里 sequence（白名单直接对应）> math；ledger 的序以任务书为准，且 C58 实测全部默认 EVIDENCE_rule（l3_fix 数学连接反应无 GPR，不落入必需基因的支撑集），差异未实际生效 |
+| M3-3 | **update 重写文件但逐行保留（坏行原样写回，不删行）** | 任务书"全部只读/追加/更新，不删行"+ 完整性要求；重写时先按行解析，解析失败的行原样保留 |
+| M3-4 | **gem_report 增加 ledger_summary{total,by_status,by_type,corrupt_rows} + ledger_context 基率披露** | 基率披露措辞（zcode 建议稿，供裁决）："预测账本共 N 条（其中 M 条 unverified）：全部为模型推导预测（essentiality/phenotype 等），实验或文献兑现前不应当作事实引用；状态分布即预测可信度基率，回填后 by_status 向 literature_supported/experimentally_verified 迁移。" |
+| M3-5 | **gem_ledger 与 gem_report 均支持 `ledger_path` 覆盖默认路径** | 任务书明确（测试用临时路径不必写用户目录）；生产默认路径不变 |
+
+## M4 消费方升级（声明式，非自动区间化）
+
+| # | 决策 | 依据 |
+|---|---|---|
+| M4-1 | **声明式升级而非自动区间化**：既有工具输出加 `units` + `point_value_note` 声明（指向 gem_fluxscan），而不把每个工具的内部计算改成区间制 | 任务书锁定"严格只增不改"；自动区间化会改变所有既有输出的形状/成本（FVA 是 pFBA 的 25 倍耗时），且各工具的定位（验证/补洞/必需性）本就不是条件对比。取舍：声明在输出侧、区间化集中在 fluxscan 一个工具 |
+| M4-2 | 声明覆盖面：validate G3/G4 每行、l3_fix before/after/l3a/l3b、biomass apply 三联对照 growth、essentiality wt_growth 输出字段；tools.js 七个产出生长数值的工具 description 追加统一句 | 任务书 6 条清单 + "各工具 description"按产出生长数值者解释（validate/gapfind/build/phenotype/essentiality/l3_fix/biomass；新三工具 M1-M3 出生即带） |
+| M4-3 | skill 硬规则 #6「通量区间制：无区间不点数」+ 决策树补 gem_fluxscan/gem_sensitivity/gem_ledger 三行 | 决策树此前 6/12 覆盖的选型断层教训（D2）；工具数增至 15 后决策树全量同步 |
+
+## M5 iNX1344_v4 前哨（阶段 B 前哨，不做正式基准对比）
+
+| # | 决策/发现 | 依据 |
+|---|---|---|
+| M5-1 | **路径确认**：`F:/A_NGJ plan/Zcode/models/` 下修复链 `iNX1344_fixed.xml → v2 → v3 → v4.xml`（终点 1.9MB）；原始发布 `iNX1344_raw/mpp13032-sup-0009-DataS1.xml` cobra 直接加载失败（CobraSBMLError） | 任务书要求先 ls 确认真实路径再引用 |
+| M5-2 | **v4 状态**：1441 反应 / 1344 基因 / 1106 代谢物；MetaCyc 风格 `RnxatuXXXX`/`M00XXX_c` ID + Atu 基因座；objective=Rnxatu0132（52 组分 biomass，即 biomass 本体）；区室 c/e（名字为空）；756/1106 代谢物有名 | 任务书要求确认可加载/ID 体系/计数/biomass 状态 |
+| M5-3 | **GAM 检测适配**：v4 的 GAM 载体实际在 biomass 内（ATP -25.633 / ADP+Pi+H+ 各 +24.78，GAM_ORIG=24.78），但 H2O（M00001_c）公式缺失 → 公式级检测漏判 → 误落独立载体分支且谷氨酰胺合成酶（含额外底物的 ATP 水解反应）误命中。修复：h2o 量级回退（与 GAM 净水电解量差 <5% 的未分类能量级组分补判）+ 独立载体判据收紧为"反应内全部代谢物均为能量 stub 角色"（纯 ATPM） | 适配进 `find_biomass_gam`（C58 锚点不受影响——其 h2o 公式命中）；两个误判模式都记档 |
+| M5-4 | **核心发现：v4 交换层与介质机制不兼容**——全部 1441 反应 `Rnx` 前缀、无 EX_/DM_/SK_ 体系，交换由 161 个 boundary 单代谢物反应承担；`build_ex_index`（EX_ 前缀）索引为空 → 任何自然名/预设介质 0 解析 → 全交换清零后 growth 恒 0 | fluxscan AB vs M9 实测：两条件各 20 项全 unresolved、growth 0/0、pair 全 overlap（1441 行）。工具本身跑通无崩溃， medium 契约（EX_ 中心）是跨模型边界 |
+| M5-5 | **根因诊断：v4 结构性不生长**——161 个 boundary 全开放（lb=-1000）FBA 仍为 0；逐组分 demand 探针定位 5 个不可净产的 biomass 组分：M02908_c / M01051_c / M00342_c(Sn-Glycero-3-phosphoethanolamine，脂质) / M00336_c / M00155_c（多为无名无公式代谢物，脂质/聚合物家族；与原始模型"脂质 μ_max=0"诊断一致） | 全 boundary 开放 + 逐组分 demand 可行性测试（work/m5_probe_inx4.py 可复核） |
+| M5-6 | **必需性退化警示**：v4 essential_scan wt=0 → 1066/1066 候选全判"必需"（判定式 v<EPS 在 wt=0 时恒真）。sensitivity 增加 `baseline_growth_degenerate` 字段 + WARN：基准 wt≤0 时 essential 集无生物学意义，结果仅证明工具跑通 | 前哨发现的工具层固化：防止阶段 B 拿退化基线做对比 |
+| M5-7 | **M5 定位 = 前哨不修复**：发现清单进阶段 B 建议（交换层规范化/5 组分补路径/ID 桥），不实现 | 任务书"范围外：正式 iNX1344 基准对比表"；避免在共享介质代码上做临时特化 |
+
+## M6 基准与文档
+
+| # | 决策 | 依据 |
+|---|---|---|
+| M6-1 | 性能基准表口径：stderr/日志分段计时 + 整段 wall time；同机独占运行（避免后台任务竞争 skew） | 见报告性能基准表 |
+| M6-2 | 文档纪律校验以 grep 计数为准（ctx.tools.register / OPS 键 / 决策树覆盖 / README 工具表 / smoke 断言数） | 三轮验证方法论：文档计数漂移是常态，逐项点数核对 |

package/docs/DECISIONS-/351/230/266/346/256/265E.md

@@ -0,0 +1,56 @@
+# DECISIONS-阶段E — genie 接入期（E4 弹性批次）实测结论与决策
+
+> 2026-08-31 阶段 E「genie 接入 gem + 全面实战验证」弹性批次。执行与证据：`D:/Program/Zcode/gem-verify/work/e/`。
+
+## E4a 引擎对照（CarveMe vs gapseq，同基因组 C58）— 正式归因
+
+benchmark 全量对比（AB，essential_full=true，231.3s，export_md 落盘 `e4a_benchmark_report.md`）：
+
+| 维度 | CarveMe (C58_carveme_test.xml) | gapseq (C58.xml) |
+|---|---|---|
+| 规模 | 1495 基因 / 3109 反应 / 1981 代谢物 | 1084 基因 / 2485 反应 / 2062 代谢物 |
+| AB 生长 | 0.624132 | 0.519981（锚点精确复现） |
+| biomass 结构 | `Growth` 显式 57 组分，GAM=53.95（in-biomass），断供 0 | `bio1` 81 组分，GAM=40.0，**断供 7**（cpd00166/01997/03422/11493/12370/15665/15666） |
+| 必需性（全量） | 90/1276 | 155/818 |
+| 表型（19 底物 sole） | 11/19 = 57.9% | 11/19 = 57.9%（**Arabinose 双双失败**——两引擎独立重建同缺 L3 阿拉伯糖分解路径） |
+
+必需性差异分解（identity+gene.name 映射，覆盖 88.89%）：intersection 68 / a_only 12 / b_only 87。
+**归因**：差异主体不是命名空间映射噪声，而是两引擎的通路覆盖与 biomass 结构差异（gapseq bio1 更大更严——
+81 组分含 7 个模型内不可净产前体，敲除网络对前体供给更敏感→必需集更大）。
+
+## E4b 跨命名空间基因映射桥 — 原型结论（不并入插件）
+
+前提修正：任务书设定"覆盖率从 0 提升"，实测 identity+gene.name 已达 **88.89%**（80/90）——前提过时。
+EC 等价类桥原型（`work/e/e4b_ec_bridge_probe.py` + `e4b_bridge_crossref.py`）：
+
+- gapseq 侧 EC 索引 848 个（反应 id/annotation 提取）
+- 10 个未映射必需基因中 6 条 EC→gapseq-essential 命中；**唯一靶规则**（多候选拒绝）下可信桥 2 条：
+  NC_003062_2_847→NC_003063_2_595（4 EC 同靶）、NC_003063_2_888→NC_003062_2_1639
+- 覆盖率 0.8889 → **0.9111**（+2.2pp）；剩余未映射多为模型内容差（gapseq 无对应基因），非命名空间问题
+
+**决策**：不并入 benchmark 映射层。理由：收益 ≤2pp、EC→多候选歧义需二次证据消歧、错误映射会污染必需性对比结论。
+原型脚本留存可复跑；若未来接入 Atu 旧 locus 桥（GFF/tbl 资产），应与本 EC 桥合并为"二级映射策略"并带 evidence 标注。
+
+## E4c 双敲全扫先验排序 — 已实现（v0.1.1）
+
+见 commit 8736690。诚实结论：C58 上全部 18 对 SL 均为 GPR 穷尽型同工酶对（先验区），扫描区排序无可测收益；
+改动是其他模型的期望改进（共享反应数降序=冗余暴露先验），零回归（18/18 集合一致）。
+
+## E4d iNX1344_v4 断供 5 组分诊断深化 — 可行性报告（不修模型）
+
+demand 探针（全交换开放 lb=-10）复现 5 断供前体：**M00155_c / M00336_c / M00342_c / M01051_c / M02908_c**。
+
+关键事实（`work/e/e4d_inx_probe.py` + `e4d_inx_neighborhood.py`）：
+
+1. 仅 M00342（Sn-Glycero-3-phosphoethanolamine，C5H14NO6P）在模型内有 name+formula；
+   其余 4 个是**裸 MetaCyc M-ID**（无 name/formula/annotation）——修复前必须先做化合物身份解析（外部证据，不可臆造）。
+2. 邻域分析：5 个断供物由 Rnxatu0461-0470/Rnxatu0577（反应名内嵌 MetaCyc R0xxxxx id）连成**内部互连的孤岛子网络**——
+   断供根因是孤岛与核心代谢之间缺上游供给连接，不是 biomass 化学计量错误。
+3. 修复路径可行性 = 中：①MetaCyc 身份解析（4 个裸 ID）；②孤岛边界死端代谢物定位；③按 MetaCyc 通路补连接反应（需文献证据分级）。
+   属"补路径"而非"补公式"；G6 能量泄漏哨兵必须随补随测。
+
+## 接入记录（genie 侧）
+
+genie preset persona.md 增代谢模型能力域路由段（commit e38c561）+ docs/plugin-integration.md 契约 v1（64dae29）+
+bio_python 桥 exitCode 校验（06c8c05，genie 0.6.25）。路由生效、契约传导（prediction_id/status 引用与账本 grep 一致）
+经真实 agent 会话验证，详见 `D:/Program/Zcode/gem-verify/phaseE-report.md`。

package/index.js

@@ -0,0 +1,5 @@
+/**
+ * dsh-bio-gem — 入口。
+ * 转发到 src/index.js 的 Cordis 插件模块。
+ */
+export * from './src/index.js'

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dsh-bio/dsh-bio-gem",
+  "version": "0.1.1",
+  "description": "基因组尺度代谢模型（GEM）构建插件：输入细菌全基因组（蛋白FASTA，支持多质粒/多染色体），自动构建+验证+补洞+出报告（SBML + 模型卡），供 dsh-bio-genie 消费工具加载使用 | Genome-scale metabolic model builder for dsh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moonbowterfly/dsh-bio-gem.git"
+  },
+  "homepage": "https://github.com/moonbowterfly/dsh-bio-gem",
+  "bugs": {
+    "url": "https://github.com/moonbowterfly/dsh-bio-gem/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "src/**/*.js",
+    "python/**/*.py",
+    "skills/**/*.md",
+    "docs/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["dsh", "deepseek-harness", "dsh-plugin", "metabolic-model", "GEM", "SBML", "carveme", "cobra", "bioinformatics"],
+  "license": "MIT",
+  "engines": { "node": "^22.19 || >=24" },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "smoke": "node test/smoke.js"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": { "optional": true }
+  }
+}