@dsh-bio/dsh-bio-gem 0.1.1

package/src/tools.js

@@ -0,0 +1,545 @@
+// dsh-bio-gem — 工具层（defineTool 注册，20 语义化工具，2026-08-30 阶段C-C4 起）
+// 全部执行走 python/gem_ops.py（JSON stdin 协议）或 build.py CLI（gem_build 长任务）。
+// op 与工具对照：19 op（含 fluxscan/sensitivity/ledger/benchmark/secretion/double_knockout/enrichment/targets）+ build CLI；详见 docs/ARCHITECTURE.md §3。
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { join } from 'node:path'
+import { dirname, isAbsolute } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
+import { callGem, pythonExe, PYTHON_DIR } from './python.js'
+import { startBuild, jobStatus } from './jobs.js'
+
+const PY = pythonExe()
+
+/** 校验输入存在（绝对路径或用户给定路径）。 */
+function requirePath(v, label) {
+  if (!v) throw new Error(`${label} required`)
+  if (!isAbsolute(v)) throw new Error(`${label} 必须是绝对路径: ${v}`)
+  return v
+}
+
+/** gem_ops 通用工具工厂（同步 op：report/validate/gapfind/gapfill）。 */
+function gemTool(opts) {
+  return defineTool({
+    name: opts.name,
+    description: opts.description,
+    parameters: opts.parameters,
+    timeoutMs: opts.timeoutMs ?? 300_000,
+    output: {
+      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 })
+    },
+  })
+}
+
+/** gem_build：spawn build.py（可 60-120s），await 完成返回 {model, card, ...}。 */
+function buildTool() {
+  return defineTool({
+    name: 'gem_build',
+    description:
+      '从细菌全基因组构建基因组尺度代谢模型（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 → 模型拷回 → 目标介质验证，' +
+      '约 30-60 分钟（后台进度日志旁观，不要误判超时）。' +
+      '输出标准 SBML（fbc v2）+ 模型卡（sidecar JSON：引擎版本/验证结果/补洞记录）。' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：构建代谢模型、基因组转模型、建GSMM、carveme 建模、gapseq 建模。',
+    parameters: {
+      input: {
+        type: 'string', required: true,
+        description: '输入绝对路径：engine=carveme 用蛋白 FASTA（*.faa）；engine=gapseq 用核苷酸 FASTA（*.fna）。',
+      },
+      name: { type: 'string', description: '模型命名（如 C58），缺省用文件名' },
+      engine: { type: 'string', enum: ['carveme', 'gapseq'], description: '构建引擎：carveme（默认，纯 Windows 快出稿）或 gapseq（WSL2，质量档 30-60min）' },
+      out_dir: { type: 'string', description: '输出目录，缺省 ~/.dsh/dsh-bio-gem/models' },
+      target_medium: {
+        type: 'object', additionalProperties: true,
+        description: '目标培养基：可传 {"medium_name": "AB"/"M9"}（内置完整成分）或自然名成分字典 {"D-Glucose": -5, "NH3": -10, ...}。跨引擎自动解析。',
+      },
+    },
+    timeoutMs: 3_600_000,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args) {
+      requirePath(args.input, 'input')
+      const job = startBuild({
+        input: args.input,
+        name: args.name,
+        engine: args.engine,
+        medium: args.target_medium,
+        outDir: args.out_dir,
+      })
+      // 轮询进度直到 done（build.py 内部已写 result.json）
+      const deadline = Date.now() + 3_540_000
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 2000))
+        const st = jobStatus(job.jobId)
+        if (st.done) {
+          const d = st.detail ? ` | detail=${JSON.stringify(st.detail)}` : ''
+          if (st.error) throw new Error(`gem_build failed: ${st.error}${d}`)
+          if (!st.result || st.result.ok === false || st.result.result == null) {
+            throw new Error(`gem_build failed: ${st.result?.error_hint ?? st.error ?? 'result missing'}${d}`)
+          }
+          return st.result.result
+        }
+      }
+      throw new Error('gem_build timeout (840s)')
+    },
+  })
+}
+
+export function registerTools(ctx) {
+  const disposers = []
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_report',
+    description:
+      '读取 SBML 代谢模型文件，输出模型摘要：基因/反应/代谢物/区室/复制子分布（多质粒/多染色体分离统计）、交换数。' +
+      '用于快速检查模型文件是否可加载、规模、是否为多复制子。模型文件不存在或非有效 SBML 会明确报错。' +
+      '输出含 ledger_summary（预测账本基率摘要：total/by_status/by_type/by_model；一个模型一个账本——' +
+      '传本工具 model 时读该模型自己的账本，own_model_entries=本模型条目数=账本总数，不再混其他模型预测；' +
+      '可选 ledger_path 指向自定义账本）与基率披露语境。' +
+      '触发词：看模型信息、模型摘要、有多少基因。',
+    parameters: { model: { type: 'string', required: true, description: 'SBML 文件绝对路径' }, ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 ~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl）' } },
+    op: 'model_info',
+  })))
+
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_validate',
+    description:
+      '对 SBML 代谢模型执行五道验证关卡：G1 加载统计（+多复制子 ID 检查 + GPR 覆盖）、' +
+      'G2 内部反应元素平衡（C/N/P/S 必须为 0，H/O 单独报告）、G3 生长真实性（声明培养基上有碳源>0、无碳=0、全关=0）、' +
+      'G4 底物表型对照（需 phenotype_table 路径，条件执行）、G5 必需基因抽检（需 essential_test 基因列表，条件执行）。' +
+      'medium 用自然名成分（如 D-Glucose/NH3/O2），跨引擎自动解析。G2 的已知生物质方程簿记偏差（如 bio1）报 WARN 不阻塞。' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：验证模型、质量检查、五道关卡。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：可传 {"medium_name": "AB"}（推荐，内置完整 AB 成分含金属）或自然名成分字典 {"D-Glucose": -5, "NH3": -10, ...}' },
+      reference_growth: { type: 'number', description: '回归锚：已知野生型生长值（用于 G3 ratio 判定）' },
+      phenotype_table: { type: 'string', description: '可选：底物表型 TSV（substrate<TAB>published 0/1）' },
+      essential_test: { type: 'array', items: { type: 'string' }, description: '可选：抽检基因 ID 列表' },
+      carbon_mode: { type: 'string', enum: ['supplement', 'sole'], description: 'G4 语义（默认 supplement=基准+底物）' },
+    },
+    op: 'validate',
+    timeoutMs: 300_000,
+  })))
+
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_gapfind',
+    description:
+      '代谢模型缺口分级诊断：L1 缺胞外交换（培养基成分无对应 EX）、L2 缺转运（e0 代谢物无入胞出口）、' +
+      'L3 内部路径（有交换+转运但 FBA 不生长）。输出分级缺口清单 + 每条是否规则可修（fixable）。' +
+      '已知规律：多数「不能利用某碳源」缺口是 L1/L2 而非 L3。medium 支持自然名（跨引擎解析）。' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：诊断缺口、为什么不能用这个碳源、gapfind。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：可传 {"medium_name": "AB"}（推荐，内置完整 AB 成分含金属）或自然名成分字典 {"D-Glucose": -5, "NH3": -10, ...}' },
+      substrates: { type: 'array', items: { type: 'string' }, description: '可选：待检底物名列表（如 Sucrose）' },
+    },
+    op: 'gapfind',
+  })))
+
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_gapfill',
+    description:
+      '按 gapfind 分级结果自动补洞：L1 补胞外交换（EX_ 反应 + 胞外代谢物）、L2 补转运（e0→c0，GPR 留空标注）。' +
+      '每条新增反应打 provenance 标记（source=gem-gapfill + 原因）；max_add 封顶防过补；out 缺省生成 <model>_gf.xml（原文件不覆盖，' +
+      '就地覆盖才备份 .bak）。L3 内部路径不自动补（需文献反应）。补洞后建议重跑 gem_validate 确认生长恢复。' +
+      '触发词：补洞、修复缺口、gapfill、加交换。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：可传 {"medium_name": "AB"/"M9"}（内置完整成分）或自然名成分字典' },
+      substrates: { type: 'array', items: { type: 'string' }, description: '可选：要支持的底物名列表' },
+      max_add: { type: 'integer', description: '单次最多新增反应数（默认 20）' },
+      out: { type: 'string', description: '输出模型路径（缺省 <model>_gf.xml）' },
+    },
+    op: 'gapfill',
+  })))
+
+  disposers.push(ctx.tools.register(buildTool()))
+
+  // gem_gapseq：gapseq 引擎原子步骤（agent 编排 setup->launch->status*->fetch）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_gapseq',
+    description:
+      'gapseq 引擎（WSL2）原子步骤工具——长任务由 agent 按编排推进：\n' +
+      'action=setup：能力探测（wsl/发行版/gapseq 版本/序列库注册）→ capability OK 才能继续。\n' +
+      'action=launch：输入核苷酸 FASTA（*.fna 绝对路径）→ 后台启动 gapseq doall（30-60min），立即返回工作目录；不要等它完成。\n' +
+      'action=status：查 doall 状态 → {state: running|done|failed, log_tail}；running 时 2-5 分钟后再查，可多轮。\n' +
+      'action=fetch：done 后把产物（XML/faa.gz/tbl/日志）拷回 Windows 输出目录 → {model}。\n' +
+      '编排模式：setup → launch →（循环 status 直到 done）→ fetch → 对 model 跑 gem_validate/缺口补洞。' +
+      '失败时（failed/COPY_FAIL）根据 hint 自纠后重试 launch。触发词：gapseq 建模、doall、质量重建。',
+    parameters: {
+      action: { type: 'string', enum: ['setup', 'launch', 'status', 'fetch'], required: true, description: '原子步骤' },
+      input: { type: 'string', description: 'launch 用：核苷酸 .fna 绝对路径' },
+      name: { type: 'string', description: '模型名（产物 basename），缺省 model' },
+      out_dir: { type: 'string', description: '产物输出目录，缺省 ~/.dsh/dsh-bio-gem/models' },
+    },
+    op: 'gapseq',
+    timeoutMs: 180_000,
+  })))
+
+  // gem_phenotype：表型回填迭代（G4 驱动，路线 A3）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_phenotype',
+    description:
+      '表型回填迭代：对模型跑 G4 表型对照（phenotype_table：substrate<TAB>published 0/1，如 Biolog/文献表），' +
+      '对「应生长但模型不长」的底物逐个 gapfind 分级 → L1/L2 交换/转运规则自动补洞（累积修复）→ L3 内部路径列候选清单 → 重跑 G4 对比匹配率。' +
+      'medium 推荐 {"medium_name": "AB"}。输出 before/after 匹配率 + 修复清单 + L3 待处理项。' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：表型回填、提高表型匹配、Biolog 校准、为什么这个底物不长。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径（将基于副本修复，原文件不动）' },
+      phenotype_table: { type: 'string', required: true, description: '表型表 TSV 绝对路径：substrate<TAB>published(0/1)' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：{"medium_name": "AB"} 或自然名成分字典' },
+      max_add: { type: 'integer', description: '每底物最多新增反应数（默认 20）' },
+      out: { type: 'string', description: '修复后模型输出路径（缺省 <model>_pf.xml）' },
+    },
+    op: 'phenotype_fix',
+    timeoutMs: 300_000,
+  })))
+
+  // gem_essentiality：G5 全量必需基因扫描（FVA 预筛 + 手工敲除）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_essentiality',
+    description:
+          '对代谢模型做全量必需基因扫描：FVA（全范围）预筛出可通量反应关联基因（死基因免敲，通常省 30-50% 计算），' +
+          '再对候选逐一手工敲除（with m: 循环）判定是否必需（敲除后生长<1e-6）。' +
+          'medium 推荐 {"medium_name": "AB"}。输出必需基因列表 + 数量 + wt 生长 + 耗时统计。' +
+          '若提供 gene_table（gem_annotate 返回的 <base>.gene_table.tsv），输出额外含 essential_gene_details（' +
+          '每必需基因带 locus_tag/product 功能注释——坐标型基因 ID 无此表时是不可解读的）。' +
+          '结果可用于模型卡"必需基因"章节（对照文献/实验必需基因集即召回率）。' +
+          '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+          '触发词：必需基因扫描、全量必要基因、essentiality scan、敲除全扫。',
+        parameters: {
+          model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+          medium: { type: 'object', additionalProperties: true, description: '培养基：{"medium_name": "AB"} 或自然名成分字典' },
+          gene_subset: { type: 'array', items: { type: 'string' }, description: '可选：只扫描指定基因（限制范围）' },
+          gene_table: { type: 'string', description: '可选：gem_annotate 返回的基因注释表 TSV（<base>.gene_table.tsv），提供则 essential_gene_details 带 locus_tag/product' },
+        },
+    op: 'essential_scan',
+    timeoutMs: 600_000,
+  })))
+
+  // gem_annotate：基因组注释（纯 Windows；官方优先 + pyrodigal 兜底）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_annotate',
+    description:
+      '把细菌基因组核苷酸 FASTA（.fna）转成蛋白 FASTA（.faa），供 gem_build(CarveMe) 使用。' +
+      '优先级：同目录 *_protein.faa（官方蛋白）→ 同目录 cds_from_genomic.fna 直译 → 同目录 *.gff 解析翻译 → pyrodigal 预测（兜底）。' +
+      '返回 {faa, source, stats}；GFF 路径额外产出 gene_table（<base>.gene_table.tsv：坐标ID→locus_tag/product 基因注释表），' +
+      '传给 gem_essentiality 的 gene_table 参数即可让必需基因结果带功能注释。' +
+      '触发词：注释、基因组转蛋白、建蛋白序列、pyrodigal。',
+    parameters: {
+      fna: { type: 'string', required: true, description: '基因组核苷酸 fasta 绝对路径（.fna）' },
+      out: { type: 'string', description: '输出蛋白 fasta 路径（缺省同目录 <base>.gem_annot.faa）' },
+    },
+    op: 'annotate',
+    timeoutMs: 300_000,
+  })))
+
+  // gem_media_resolve：跨引擎介质解析 RPC（genie 消费侧统一入口；防介质语义漂移三次假象重演）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_media_resolve',
+    description:
+      '把自然名培养基（如 {"medium_name": "AB"} 或 {"D-Glucose": -5, "NH3": -10, ...}）解析到指定模型的实际交换反应（EX ID 列表）。' +
+      '这是全插件统一的介质解析入口——任何消费方（包括 dsh-bio-genie 的 FBA 等）应通过本工具/同款解析层获得交换 ID，' +
+      '不要自行实现介质名匹配（已因三次"模型不生长假象"加固）。返回 {resolved_exchanges, unresolved, medium_preset}。' +
+      '触发词：介质解析、培养基转交换、media resolve。',
+    parameters: {
+      model: { type: 'string', required: true, description: '目标模型 SBML 绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '自然名培养基（medium_name 或成分字典）' },
+    },
+    op: 'media_resolve',
+    timeoutMs: 120_000,
+  })))
+
+  // gem_l3_fix：L3 内部路径补洞（B' 后半：L3a 模型内连通性 + L3b 白名单/BiGG 反应式 + 证据分级）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_l3_fix',
+    description:
+      'L3 内部路径补洞（两级，白名单驱动）：对 gapfind 判为 L3 的底物（有交换+转运但不生长）做修复。\n' +
+      'L3a 模型内连通性：先全内部反应放开方向做 LP 预检（快速判"是否纯连通性问题"），可行才用 MILP 取最小放宽集（改 bounds，不复制反应）。\n' +
+      'L3b 白名单+反应式：diamond 白名单命中集（EC/名字桥接 iML1515 反应式移植到本模型命名空间；无匹配不强补）；' +
+      'allow_math=true 时允许纯数学连接（MILP 决策，证据最弱）。PTS 型反应一律排除（PTS-less 机体守则）。\n' +
+      '证据分级：EVIDENCE_sequence（白名单直接对应）> EVIDENCE_math（数学连接，附 sequence_hint 表示有序列线索的间接桥）；' +
+      '防过补第五闸门：历史累计新增 ≤ max(5, 5%·总反应)，超限返回 confirm_required 需显式 confirm_budget=true。\n' +
+      '补后自动 validate G1-G6 全跑，G6（ATP 泄漏哨兵）非 PASS 自动回滚本批改动。' +
+      '返回每底物 before/after sole 生长 + verdict（fixed/not_fixable + 不可补证据链）。\n' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：补内部路径、L3 补洞、白名单补反应、为什么补了交换还是不长。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径（原文件不动，修复写到 out）' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：可传 {"medium_name": "AB"}（推荐，内置完整成分含金属）或自然名成分字典' },
+      substrates: { type: 'array', items: { type: 'string' }, required: true, description: 'L3 底物名列表（gapfind 报 L3 的底物，如 Arabinose/Mannitol）' },
+      allow_math: { type: 'boolean', description: '是否允许纯数学连接（EVIDENCE_math；默认 false=只用白名单序列证据池）' },
+      confirm_budget: { type: 'boolean', description: '第五闸门超限时显式确认继续（默认 false）' },
+      whitelist: { type: 'string', description: '白名单命中集 JSON 路径（缺省用 ~/.dsh/dsh-bio-gem/whitelist/ 缓存或现场跑 diamond）' },
+      faa: { type: 'string', description: '目标物种蛋白 fasta（白名单未缓存时现场构建用）' },
+      out: { type: 'string', description: '修复后模型输出路径（缺省 <model>_l3.xml）' },
+    },
+    op: 'l3_fix',
+    timeoutMs: 900_000,
+  })))
+
+  // gem_biomass：biomass 精修（Q2：inspect 只读 / apply 显式覆盖表 + 三联对照）
+  disposers.push(ctx.tools.register(defineTool({
+    name: 'gem_biomass',
+    description:
+      'biomass（FBA 目标函数）精修工具，action 两步：\n' +
+      'action=inspect（只读，无副作用）：解析 biomass 反应 → 组分表（met_id/name/coeff/compartment/类别）+ 摘要' +
+      '（组分个数、原子总量、类别分布：氨基酸/核酸/脂质/辅因子/金属/其他）；reference 可选 iML1515/both 对照' +
+      '（含 iNX1344_v4 按代谢物名同义尽力翻译，翻不了明示 unmapped N 个，不强行全翻）。\n' +
+      'action=apply（显式修改）：必须给 biomass_profile 覆盖表 [{"met_id","coeff","op":"set|add|remove"}]，' +
+      '基于副本替换 biomass → 强制 G1-G6 重验 + 三联对照（生长率/表型匹配率/必需基因 delta，单位 mmol/gDW/h）' +
+      '→ 输出 before/after 对照 + 新模型（原文件不动=天然可回滚）+ 模型卡 lineage 追加（有 card 时）。' +
+      '生长变差 WARN 不阻塞；默认不应用任何 profile。' +
+      '生长/通量数值为单点 FBA 值（非硬结论）；条件间对比用 gem_fluxscan（区间制）。' +
+      '触发词：biomass 精修、看生物质组成、改 biomass 系数、目标函数调整。',
+    parameters: {
+      action: { type: 'string', enum: ['inspect', 'apply'], required: true, description: 'inspect=只读诊断；apply=显式应用覆盖表' },
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      biomass_profile: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'apply 用：覆盖表 [{"met_id","coeff","op":"set|add|remove"}]（set 沿用原符号；必须显式提供，缺省报错）' },
+      reference: { type: 'string', enum: ['iML1515', 'iNX1344_v4', 'both'], description: 'inspect 用：参考模板对照' },
+      medium: { type: 'object', additionalProperties: true, description: '对照验证用培养基：{"medium_name": "AB"/"M9"} 或自然名字典' },
+      phenotype_table: { type: 'string', description: 'apply 三联对照用：底物表型 TSV（substrate<TAB>published 0/1）' },
+      out: { type: 'string', description: 'apply 输出模型路径（缺省 <model>_bm.xml）' },
+      essential_sample: { type: 'integer', description: 'apply 必需基因对照抽样数（默认 40，确定性步进抽样）' },
+      note: { type: 'string', description: 'apply 备注（写入模型卡 lineage detail）' },
+    },
+    timeoutMs: 900_000,
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args) {
+      const op = args.action === 'apply' ? 'biomass_apply' : 'biomass_inspect'
+      return callGem(op, args, { timeoutMs: 900_000 })
+    },
+  })))
+
+  // gem_fluxscan：通量区间制（阶段A-M1：FVA 区间 + pFBA 点值 + 条件对区间分离判定）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_fluxscan',
+    description:
+      '通量区间制（fluxscan）：对同一模型在多个培养条件下做全模型 FVA（区间）+ pFBA（点值），' +
+      '每反应输出 fva_min/fva_max/pfba；条件对比消费区间分离判定——' +
+      '两条件区间分离 = 解空间无关硬结论（a_higher/b_higher），区间重叠（overlap）= 点值差异是求解器伪影，禁止引用。' +
+      '背景：单点 FBA 通量取决于求解器顶点（解空间退化），跨条件点值 diff 是伪影，条件比较必须用本工具的区间制。' +
+      '输入 conditions 数组（name 唯一；medium 支持 {"medium_name": "AB"}；substrates+carbon_mode=sole 对齐 G4 表型语义）；' +
+      '可选 reactions 关注子集（FVA/pFBA 仍全模型算，仅收窄输出口径）、pairs 显式比较对（缺省全唯一对）、' +
+      'only_diff 只看硬结论、export_csv 全量落盘。' +
+      '触发词：通量扫描、区间制、FVA 对比、为什么这个反应通量变了、哪些反应在两个条件下真变了。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      conditions: {
+        type: 'array', items: { type: 'object', additionalProperties: true }, required: true,
+        description: '条件数组，每项 {name(唯一), medium: {"medium_name": "AB"} 或自然名字典, substrates?: ["L-Arabinose"], carbon_mode?: "supplement"(默认)|"sole"}',
+      },
+      reactions: { type: 'array', items: { type: 'string' }, description: '可选：关注反应子集（FVA/pFBA 仍全模型计算；comparisons/summary 只含子集）' },
+      pairs: { type: 'array', items: { type: 'array', items: { type: 'string' } }, description: '可选：显式比较对 [[\"AB\",\"AB+Ara\"]]；缺省=conditions 全唯一对' },
+      fraction_of_optimum: { type: 'number', description: 'FVA 最优约束分数（默认 0.9999，避免 1.0 数值噪声致空/窄区间）' },
+      tolerance: { type: 'number', description: '区间分离容差 mmol/gDW/h（默认 1e-6；分离要求区间间隙 > 容差）' },
+      only_diff: { type: 'boolean', description: 'true=只输出 hard_conclusion 反应（默认 false）' },
+      export_csv: { type: 'string', description: '全量结果 CSV 落盘路径（所有反应×条件对×区间/点值/判定），返回文件路径' },
+    },
+    op: 'fluxscan',
+    timeoutMs: 900_000,
+  })))
+
+  // gem_sensitivity：结构性灵敏度（阶段A-M2：GAM×biomass 网格 22 组合 + 稳定性三分类 + 单组分漂移）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_sensitivity',
+    description:
+      '结构性灵敏度（sensitivity）：把"模型不确定"量化——biomass 组分系数 ×{0.75,1.0,1.25} × GAM {1,5,10,20,30,40,50} ' +
+      '= 21 扫点 + 1 基准组合（不扰动）= 22 组合全量（不抽样），每组合 wt 生长 + 必需性重扫（复用 essential_scan 的 ' +
+      'FVA 预筛+手工敲除逻辑）；输出稳定性三分类（always/conditionally/never essential）+ 单组分 ±25% 灵敏度 top10 ' +
+      '+ top10 必需性漂移（哪些基因从必需变非必需/新增必需）+ 模型卡"鲁棒性"章节（schema v3，无 card 不造卡）。' +
+      'GAM 载体自动定位（biomass 方程内 ATP stub 或独立 ATPM），biomass 扰动与 GAM 网格正交化。' +
+      '生长/必需性数值为单点 FBA 口径（mmol/gDW/h）；条件间通量对比用 gem_fluxscan（区间制）。' +
+      'action=probe 秒级只读探测（GAM 载体/组分计数）；缺省 full 全量约 35-45 分钟（后台长任务，耐心等待勿误判超时）。' +
+      '触发词：灵敏度分析、鲁棒性、GAM 扫描、biomass 不确定性、必需基因稳定性。',
+    parameters: {
+      action: { type: 'string', enum: ['probe', 'full'], description: 'probe=秒级只读（GAM 载体定位）；full=22 组合全量（默认缺省即 full，长任务）' },
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '培养基：{"medium_name": "AB"}（默认）或自然名成分字典' },
+      biomass_scales: { type: 'array', items: { type: 'number' }, description: 'biomass 组分缩放轴（默认 [0.75, 1.0, 1.25]）' },
+      gam_grid: { type: 'array', items: { type: 'number' }, description: 'GAM 网格（默认 [1,5,10,20,30,40,50] mmol ATP/gDW）' },
+      run_component_sensitivity: { type: 'boolean', description: '二级单组分 ±25% 灵敏度（默认 true，~114 次 FBA）' },
+      run_drift: { type: 'boolean', description: 'top 敏感组分必需性重扫（默认 true，20 次×~55s）' },
+      top_n: { type: 'integer', description: '敏感组分 top N（默认 10）' },
+      export_csv: { type: 'string', description: '全量结果 CSV 落盘路径' },
+      baseline_check_path: { type: 'string', description: '可选：essential_scan 基线必需集 JSON 文件路径（基准组合做精确复现断言）' },
+    },
+    op: 'sensitivity',
+    timeoutMs: 3_600_000,
+  })))
+
+  // gem_ledger：prediction ledger 预测账本（阶段A-M3：gem_essentiality/gem_phenotype 自动登记的预测可查询/更新/追踪）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_ledger',
+    description:
+      '预测账本（prediction ledger）：一个模型一个账本——账本文件按模型名分（ledger/<模型名>.jsonl），' +
+      'gem_essentiality（每必需基因一条）与 gem_phenotype（每底物一条 G4 结果）等自动登记到对应模型的账本（追加式 JSONL，幂等去重，' +
+      '同 model+condition+type+content 不重复入账）。' +
+      'action=list 分页列出（limit/offset，返回 total）；action=query 条件过滤（type/status/condition/model ' +
+      '前缀匹配，可组合；传 model 则定位到该模型自己的账本，不传则聚合所有模型账本=全局视图）；action=update 按 prediction_id 改 status（unverified/literature_supported/' +
+      'literature_contradicted/experimentally_verified）/source_refs/comparison_refs（维护 updated_at）。' +
+      '只读/追加/更新，不删行；损坏行跳过并报 corrupt_rows 不阻塞。' +
+      '账本预测默认 status=unverified——实验或文献兑现前不应当作事实引用（基率披露见 gem_report 的 ledger_summary）。' +
+      '生长/通量数值为单点 FBA 口径（mmol/gDW/h）；条件间通量对比用 gem_fluxscan（区间制）。' +
+      '触发词：预测账本、查询预测、更新预测状态、预测追踪、ledger。',
+    parameters: {
+      action: { type: 'string', enum: ['list', 'query', 'update'], required: true, description: 'list=分页列出；query=条件过滤；update=改状态/来源' },
+      limit: { type: 'integer', description: 'list/query 分页大小' },
+      offset: { type: 'integer', description: 'list/query 分页偏移（默认 0）' },
+      type: { type: 'string', description: 'query 用：类型前缀过滤（essentiality/phenotype/synthetic_lethal/secretion/other）' },
+      status: { type: 'string', description: 'query 用：状态前缀过滤（unverified/literature_supported/literature_contradicted/experimentally_verified）' },
+      condition: { type: 'string', description: 'query 用：条件前缀过滤（如 AB）' },
+      model: { type: 'string', description: 'query 用：模型路径前缀过滤' },
+      prediction_id: { type: 'string', description: 'update 用：预测 ID（如 P0001）' },
+      source_refs: { type: 'array', items: { type: 'string' }, description: 'update 用：文献/实验来源引用列表' },
+      comparison_refs: { type: 'array', items: { type: 'string' }, description: 'update 用：对照记录引用' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 ~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl）' },
+    },
+    op: 'ledger',
+    timeoutMs: 60_000,
+  })))
+
+  // gem_benchmark：通用基准对比（阶段B-B1：任何两个 GEM 的规范对比表，六关并列+生长+biomass 探针+必需性+表型+账本回填）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_benchmark',
+    description:
+      '通用基准对比（benchmark）：任何两个代谢模型跑规范对比表，产出论文级对比。model_a/model_b 支持本地 SBML 绝对路径' +
+      '或 "bigg:<model_id>" URI（如 bigg:iML1515，BiGG 静态库下载到 ~/.dsh/dsh-bio-gem/models/，直连失败自动走本机代理，下载后缓存）。' +
+      '输出：ID 体系探测 / 六道关卡 G1-G6 逐项并列 / 声明介质生长（含介质层两级策略——无 EX_ 层的模型自动回退 ' +
+      'boundary 单代谢物反应解析，boundary_style 标注）/ biomass 可行性探针（逐组分净产测试，结构性断供清单）/ ' +
+      '必需性对比（复用 essential_scan；任一侧 wt<=EPS 判退化只报结构信息不做垃圾对比，基因映射尽力而为如实报覆盖率，' +
+      'reference_essential 文献值仅标注不冒充模型输出）/ 表型对比（G4 sole）/ 可复现性评估 / 账本 comparison_refs ' +
+      '回填（update 语义幂等可重入）。export_md 落盘论文级 Markdown。' +
+      '生长/通量数值为单点 FBA 口径（mmol/gDW/h）；条件间通量对比用 gem_fluxscan（区间制）。' +
+      '触发词：模型对比、两个模型比较、基准、benchmark、跨模型校准。',
+    parameters: {
+      model_a: { type: 'string', required: true, description: '模型 A SBML 绝对路径' },
+      model_b: { type: 'string', required: true, description: '模型 B SBML 绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '对比介质（缺省 {"medium_name": "AB"}）' },
+      phenotype_table: { type: 'string', description: '可选：底物表型 TSV（substrate<TAB>published 0/1），提供则跑表型对比' },
+      reference_essential: { type: 'object', additionalProperties: true, description: '可选：文献必需基因集（如 {"b": [...]})，仅报告标注不参与计算' },
+      essential_full: { type: 'boolean', description: 'true=全量必需性对比（各 ~50s）；false=抽检 40（G5 口径，默认）' },
+      ledger_refs: { type: 'boolean', description: '对比后回填账本 comparison_refs（默认 true；幂等可重入）' },
+      export_md: { type: 'string', description: '论文级 Markdown 落盘路径' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 ~/.dsh/dsh-bio-gem/ledger/<模型名>.jsonl）' },
+    },
+    op: 'benchmark',
+    timeoutMs: 1_200_000,
+  })))
+
+  // gem_secretion：可分泌代谢物谱（阶段C-C1：production envelope 扫描，纯拓扑边界声明内置）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_secretion',
+    description:
+      '可分泌代谢物谱（secretion）：对模型在指定介质下做 production envelope 扫描——候选=介质层两级策略导出的' +
+      '交换反应（EX_ 型与 boundary 型模型都适用），固定生长分数 {0.25,0.5,0.75,0.9,0.99,1.0} 下最大化产物交换，' +
+      '任一分数下产物交换 >1e-6 判可分泌。**mode 默认 summary**：只返回 top20（按 max_prod）可分泌物 + 统计，' +
+      '不内联全量（防大输出被平台省略截断——不要在 summary 返回里找截断区数字）；' +
+      '完整 {met_id, name, max_prod, growth_at_max, feasible, envelope[...]} 请传 export_csv 落盘 CSV（返回里 full_data_file 指向该文件），' +
+      '或显式 mode=full（注意可能很大）。export_csv 全量落盘。**边界声明：未考虑毒性/渗透压/调控，纯拓扑/线性规划结果**——可分泌≠实际会分泌。' +
+      '被测模型 wt<=EPS（介质下不生长，如 AB 预设对非根瘤菌模型）→ degenerate=true 不扫描不登记，提示介质适配。' +
+      '每个可分泌代谢物自动登记账本 type=secretion（幂等）。' +
+      '生长/通量数值为单点 FBA 口径（mmol/gDW/h）；条件间通量对比用 gem_fluxscan（区间制）。' +
+      '触发词：可分泌谱、分泌能力、secretion、能产什么、代谢物分泌。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '分泌条件（缺省 {"medium_name": "AB"}）' },
+      fractions: { type: 'array', items: { type: 'number' }, description: '生长分数网格（默认 [0.25,0.5,0.75,0.9,0.99,1.0]）' },
+      mode: { type: 'string', enum: ['summary', 'full'], description: 'summary=默认，只返回 top20 可分泌物（防大输出省略）；full=全量含 envelope（可能被平台省略截断）；完整数据推荐 export_csv 落盘 CSV' },
+      export_csv: { type: 'string', description: '全量 envelope CSV 落盘路径（无论 mode 均写全量；返回 full_data_file 指向）' },
+      ledger_refs: { type: 'boolean', description: '可分泌代谢物登记账本（默认 true；幂等）' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 <模型名>.jsonl）' },
+    },
+    op: 'secretion',
+    timeoutMs: 900_000,
+  })))
+
+  // gem_double_knockout：双敲 v1 合成致死（阶段C-C2：GPR 穷尽先验 + FVA 预筛全扫，假设声明内置）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_double_knockout',
+    description:
+      '双敲 v1（合成致死预测）：候选池=①GPR 结构先验（纯 or 型且恰 2 基因的反应=穷尽型同工酶对，必做）+' +
+      '②FVA 预筛活性反应关联基因中共享反应的基因对（复用 essential_scan 预筛与敲除；全扫受 max_pairs 预算上限' +
+      '默认 5000，超限截断+报告）。判定：单敲双活（>1e-6）且双敲死（<=1e-6）→ 合成致死对。' +
+      '输出 {pair, single_a_growth, single_b_growth, double_growth, rationale（GPR先验/全扫）, source}。' +
+      '**假设声明：细菌双敲验证率无大规模实验数据支撑，本结果=假设生成，供实验设计参考非结论**。' +
+      '被测模型 wt<=EPS → degenerate=true 不扫描不登记（提示介质适配）。每对自动登记账本 type=synthetic_lethal（幂等）。' +
+      '生长/通量数值为单点 FBA 口径（mmol/gDW/h）；条件间通量对比用 gem_fluxscan（区间制）。' +
+      '触发词：双敲、合成致死、double knockout、基因对敲除、互补基因。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      medium: { type: 'object', additionalProperties: true, description: '判定条件（缺省 {"medium_name": "AB"}）' },
+      max_pairs: { type: 'integer', description: '全扫预算上限（默认 5000 对；超限截断并报告）' },
+      export_csv: { type: 'string', description: '合成致死对 CSV 落盘路径' },
+      ledger_refs: { type: 'boolean', description: '合成致死对登记账本（默认 true；幂等）' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 <模型名>.jsonl）' },
+    },
+    op: 'double_knockout',
+    timeoutMs: 1_200_000,
+  })))
+
+  // gem_enrichment：必需基因通路富集（阶段C-C3：超几何+BH FDR；通路源=SBML groups[MetaCyc PWY]）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_enrichment',
+    description:
+      '必需基因通路富集（enrichment）：对基因列表（缺省从账本读该模型 essentiality 预测）做通路超几何单侧富集检验' +
+      '+ Benjamini-Hochberg FDR 校正。通路注释源=模型的 SBML groups（gapseq 重建自带 MetaCyc PWY 分组）；' +
+      '模型无 groups 注释时按契约返回 annotation_unavailable（不伪造通路，附可补途径说明）；' +
+      '有效映射基因 <10 如实声明统计功效有限。输出 {pathway, genes_hit, background_hit, total_bg, p_value, fdr, ' +
+      'fold_enrichment, ...} 全表 + export_csv。统计描述性结果，不登记账本，不做跨模型对比。' +
+      '触发词：通路富集、必需基因富集、enrichment、哪些通路富集。',
+    parameters: {
+      model: { type: 'string', required: true, description: 'SBML 文件绝对路径' },
+      gene_list: { type: 'array', items: { type: 'string' }, description: '可选：基因列表（缺省从账本 essentiality 预测读取）' },
+      pathway_source: { type: 'string', description: '通路注释源（缺省 groups=SBML groups）' },
+      export_csv: { type: 'string', description: '富集表 CSV 落盘路径' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 <模型名>.jsonl；gene_list 缺省来源）' },
+    },
+    op: 'enrichment',
+    timeoutMs: 300_000,
+  })))
+
+  // gem_targets：靶点清单规范导出（阶段C-C4：账本三类预测 -> 锁定 schema，供下游引物/编辑工具直接输入）
+  disposers.push(ctx.tools.register(gemTool({
+    name: 'gem_targets',
+    description:
+      '靶点清单规范导出（targets）：把账本中的 essentiality/synthetic_lethal/secretion 预测汇总为下游' +
+      '引物/编辑工具可直接输入的规范 schema——每行锁定 11 字段：target_id(T0001 递增)/type/genes/met_ids/' +
+      'condition/rationale/evidence_tier/status/growth_or_maxprod/source(ledger:P####)/exported_at。' +
+      'essential 默认读账本不重扫；types 可筛选（essential=essentiality/全部）；可选 condition 过滤；' +
+      'export_format=csv（默认，utf-8-sig）/json；与账本计数闭合（exported==ledger per type）。' +
+      '引物/质粒设计本身不做（方案文件明确）。触发词：靶点清单、导出靶点、targets、基因编辑靶点、引物输入。',
+    parameters: {
+      model: { type: 'string', description: '可选：模型路径过滤（精确匹配优先，退化为文件名匹配）' },
+      types: { type: 'array', items: { type: 'string' }, description: '类型筛选（essential/synthetic_lethal/secretion；缺省全部三类）' },
+      condition: { type: 'string', description: '可选：条件过滤（精确匹配，如 AB）' },
+      export_format: { type: 'string', enum: ['csv', 'json'], description: '导出格式（默认 csv）' },
+      export_path: { type: 'string', description: '落盘路径（缺省 ~/.dsh/dsh-bio-gem/exports/targets_<ts>.<ext>）' },
+      ledger_path: { type: 'string', description: '可选：自定义账本 JSONL 路径（缺省=该模型的账本 <模型名>.jsonl）' },
+    },
+    op: 'targets',
+    timeoutMs: 120_000,
+  })))
+
+
+  return () => disposers.forEach((d) => d())
+}
+
+export const gemToolNames = ['gem_report', 'gem_validate', 'gem_gapfind', 'gem_gapfill', 'gem_build',
+  'gem_gapseq', 'gem_phenotype', 'gem_essentiality', 'gem_annotate', 'gem_media_resolve', 'gem_l3_fix',
+  'gem_biomass', 'gem_fluxscan', 'gem_sensitivity', 'gem_ledger', 'gem_benchmark', 'gem_secretion',
+  'gem_double_knockout', 'gem_enrichment', 'gem_targets']