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

package/skills/gem-expert.md

@@ -12,7 +12,8 @@ language: mixed
 |---|---|
 | 已有 SBML 模型文件，想知道概要（基因/反应/复制子）| `gem_report`（model 参数=绝对路径）|
 | 验证模型质量（五道关卡：加载/元素平衡/生长真实性/表型/必需性抽检）| `gem_validate`（model + medium）|
-| 模型在目标培养基不长，想知道为什么 | `gem_gapfind`（model + medium + substrates）|
+| 模型质量审计（对标 MEMOTE 维度：blocked 反应/环路/元素平衡/孤儿与死端/覆盖率/连通性 + 启发式质量分）| `gem_quality`（model + 可选 medium；分项与 failed_checks 为准，quality_index 仅速览）|
+| 模型在目标培养基不长，想知道为什么 | `gem_gapfind`（model + medium + substrates）**；先跑 `gem_precursor_scan` 确认阻塞层次**——它报「卡在哪个前体」（可生长即返无阻塞），比缺口清单更贴近根因 |
 | gapfind 判 L3（内部路径）后自动补洞（白名单/MILP）| `gem_l3_fix`（model + medium + substrates；allow_math=true 才放数学连接；补后自动跑 G6 防能量循环）|
 | 看/改 biomass（FBA 目标函数）| `gem_biomass`（action=inspect 只读组分/对照参考；apply 显式 profile + 三联对照，原文件不动可回滚）|
 | 按缺口自动补洞（缺交换/转运规则修复）| `gem_gapfill`（model + medium）→ 补完重跑 `gem_validate` |
@@ -20,6 +21,7 @@ language: mixed
 | 只有裸基因组 .fna，先要蛋白序列 | `gem_annotate`（fna → faa；官方优先 + pyrodigal 兜底）|
 | 需要模型的全量必需基因清单 | `gem_essentiality`（FVA 预筛 + 手工敲除；medium 推荐 AB）|
 | 跨条件通量对比（哪个反应真变了）| `gem_fluxscan`（区间制：FVA 区间+pFBA 点值，区间分离=硬结论，overlap=伪影禁止引用）|
+| 通量分布采样（反应合理取值范围、稳态分布）| `gem_sample`（model + n + growth_floor_fraction；默认全空间采样，看近最优生长态传 0.9）|
 | 量化模型不确定性（biomass/GAM 扰动下预测稳不稳）| `gem_sensitivity`（22 组合网格+稳定性三分类+单组分漂移；action=probe 秒级探测）|
 | 查询/更新模型预测（必需性/表型预测追踪与实验兑现）| `gem_ledger`（list/query/update；预测默认 unverified，兑现后回填状态）|
 | 两个模型规范对比（论文级基准表）| `gem_benchmark`（model_a+model_b：六关并列/生长/biomass 断供探针/必需性对比[退化侧只报结构]/表型/账本回填；export_md 落盘）|

package/src/capabilities.js

@@ -0,0 +1,152 @@
+// dsh-bio-gem — capabilities 单源（single source of truth for tool manifest & capability metadata）
+//
+// 目的（外部评审共识，2026-09-21 裁决 §3.3）：
+//   1. 工具清单/能力分级/成本与副作用元数据集中一处，供 integration API（/v1/capabilities）
+//      与 genie 宿主侧动态消费——消灭「工具数变化需同步 ≥12 处」的手工漂移。
+//   2. 校验脚本 scripts/check-capabilities.mjs 强制本 MANIFEST 与 tools.js 真实注册集合一致；
+//      文档计数（README/persona/面板）另有 count-audit 校验。
+//
+// 同步纪律：新增/删除工具时同步本文件（对应 category / capability / cost_class / network /
+// mutability / summary），否则 check-capabilities 会报红。
+//
+// cost_class:  light  (<10s)  | medium (10s–2min) | heavy (>2min)
+// network:     none | optional | required
+// mutability:  read_only | writes_output | model_mutating
+// status:      ready | experimental | data-not-initialized  （依赖级状态由 integration 动态覆盖）
+// requires:    动态依赖 id 列表（对齐 integration status 的 check id；缺省即 ready）
+
+export const TOOLS_MANIFEST = [
+  // ---- build ----
+  { name: 'gem_build', capability: 'gem.build.genome-to-model', category: 'build',
+    cost_class: 'heavy', network: 'optional', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra', 'runtime.carveme'],
+    summary: '基因组→GEM 构建（CarveMe 自动自举 / gapseq WSL 档）；后台 job + 进度' },
+  { name: 'gem_annotate', capability: 'gem.build.annotate', category: 'build',
+    cost_class: 'medium', network: 'none', mutability: 'writes_output', status: 'ready',
+    summary: '基因组注释→蛋白 FASTA（官方优先 + pyrodigal 兜底，纯 Windows）' },
+  { name: 'gem_gapseq', capability: 'gem.build.gapseq-wsl', category: 'build',
+    cost_class: 'heavy', network: 'none', mutability: 'writes_output', status: 'experimental',
+    requires: ['runtime.gapseq'],
+    summary: 'gapseq 引擎原子四步（setup/launch/status/fetch，WSL2 依赖，实验性）' },
+
+  // ---- validate ----
+  { name: 'gem_validate', capability: 'gem.validate.six-gate', category: 'validate',
+    cost_class: 'medium', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '六道验证关卡 G0-G6（加载/平衡/生长/表型/必需性/ATP 泄漏）' },
+  { name: 'gem_quality', capability: 'gem.validate.quality-report', category: 'validate',
+    cost_class: 'medium', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '模型质量报告（gem-qi-v1：blocked/环路/平衡/孤儿/覆盖/连通性 + 启发式聚合分）' },
+
+  // ---- repair ----
+  { name: 'gem_gapfind', capability: 'gem.repair.gap-diagnose', category: 'repair',
+    cost_class: 'medium', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '缺口分级诊断 L1 缺交换 / L2 缺转运 / L3 内部路径' },
+  { name: 'gem_gapfill', capability: 'gem.repair.gap-fill', category: 'repair',
+    cost_class: 'medium', network: 'none', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra'],
+    summary: 'L1/L2 规则级自动补洞（provenance 打标 + 防过补四闸门）' },
+  { name: 'gem_l3_fix', capability: 'gem.repair.l3-pathway', category: 'repair',
+    cost_class: 'heavy', network: 'none', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra'],
+    summary: 'L3 内部路径补洞（白名单 + BiGG 反应式移植 + 证据分级 + G6 回滚）' },
+  { name: 'gem_precursor_scan', capability: 'gem.repair.precursor-scan', category: 'repair',
+    cost_class: 'medium', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '阻塞前体分析（不生长时逐前体移除测试定位阻塞点）' },
+  { name: 'gem_phenotype', capability: 'gem.repair.phenotype-calibrate', category: 'repair',
+    cost_class: 'heavy', network: 'none', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '表型回填迭代（Biolog/文献表校准 + L1/L2 自动修复 + 匹配率对比）' },
+  { name: 'gem_biomass', capability: 'gem.repair.biomass-refine', category: 'repair',
+    cost_class: 'heavy', network: 'none', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra'],
+    summary: 'biomass 精修（inspect 组分对照 / apply 覆盖表 + 三联对照 + 回滚）' },
+
+  // ---- analysis ----
+  { name: 'gem_essentiality', capability: 'gem.analysis.essentiality', category: 'analysis',
+    cost_class: 'heavy', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '全量必需基因扫描（FVA 预筛 + 手工敲除；带 GPR 覆盖警告）' },
+  { name: 'gem_fluxscan', capability: 'gem.analysis.flux-interval', category: 'analysis',
+    cost_class: 'heavy', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '通量区间制（FVA 区间 + pFBA 点值；条件对比只认区间分离）' },
+  { name: 'gem_sensitivity', capability: 'gem.analysis.sensitivity', category: 'analysis',
+    cost_class: 'heavy', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '结构性灵敏度（GAM×biomass 网格 + 稳定性三分类）' },
+  { name: 'gem_secretion', capability: 'gem.analysis.secretion', category: 'analysis',
+    cost_class: 'medium', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '可分泌代谢物谱（production envelope 扫描；纯拓扑边界声明）' },
+  { name: 'gem_double_knockout', capability: 'gem.analysis.double-knockout', category: 'analysis',
+    cost_class: 'heavy', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '双敲合成致死（GPR 穷尽先验 + 全扫预算）' },
+  { name: 'gem_enrichment', capability: 'gem.analysis.enrichment', category: 'analysis',
+    cost_class: 'light', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '必需基因通路富集（超几何 + BH FDR；通路源 = SBML groups）' },
+  { name: 'gem_sample', capability: 'gem.analysis.sampling', category: 'analysis',
+    cost_class: 'heavy', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '通量空间采样（ACHR/OptGP；growth_floor 受限空间；边界声明）' },
+
+  // ---- export ----
+  { name: 'gem_targets', capability: 'gem.export.targets', category: 'export',
+    cost_class: 'light', network: 'none', mutability: 'writes_output', status: 'ready',
+    summary: '靶点清单规范导出（11 字段锁定 schema；计数闭合）' },
+
+  // ---- assets ----
+  { name: 'gem_media_resolve', capability: 'gem.asset.medium-resolve', category: 'assets',
+    cost_class: 'light', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '介质解析（自然名 → EX ID；跨引擎命名空间）' },
+  { name: 'gem_ledger', capability: 'gem.asset.ledger', category: 'assets',
+    cost_class: 'light', network: 'none', mutability: 'writes_output', status: 'ready',
+    summary: '预测账本（list/query/update；幂等；基率追踪）' },
+  { name: 'gem_benchmark', capability: 'gem.asset.benchmark', category: 'assets',
+    cost_class: 'heavy', network: 'optional', mutability: 'writes_output', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '两模型基准对比（六关并列/生长/必需性/表型/账本回填；支持 bigg: 下载）' },
+  { name: 'gem_report', capability: 'gem.asset.report', category: 'assets',
+    cost_class: 'light', network: 'none', mutability: 'read_only', status: 'ready',
+    requires: ['python.cobra'],
+    summary: '模型摘要 + 账本基率' },
+]
+
+export const CONTRACT_VERSION = '1'
+
+/** 组装 capabilities 报告（静态 manifest + 动态依赖状态覆盖）。 */
+export function buildCapabilitiesReport({ pluginVersion, checks = [] } = {}) {
+  const checkStatus = new Map(checks.map((c) => [c.id, c.status]))
+  const tools = TOOLS_MANIFEST.map((t) => {
+    const missingDeps = (t.requires ?? []).filter((id) => {
+      const st = checkStatus.get(id)
+      return st !== undefined && st !== 'ok'
+    })
+    const effectiveStatus = missingDeps.length > 0 ? 'unavailable' : (t.status ?? 'ready')
+    return {
+      name: t.name,
+      capability: t.capability,
+      category: t.category,
+      cost_class: t.cost_class,
+      network: t.network,
+      mutability: t.mutability,
+      status: effectiveStatus,
+      summary: t.summary,
+      ...(t.requires ? { requires: t.requires } : {}),
+      ...(missingDeps.length > 0 ? { missing_dependencies: missingDeps } : {}),
+    }
+  })
+  return {
+    contract_version: CONTRACT_VERSION,
+    plugin_id: 'dsh-bio-gem',
+    plugin_version: pluginVersion,
+    tool_count: tools.length,
+    tools,
+  }
+}

package/src/index.js

@@ -2,11 +2,21 @@
 // 注入 tools（5 语义化工具：gem_report/validate/gapfind/gapfill/build）+ skills（gem-expert）。
 import { registerTools } from './tools.js'
 import { registerSkills } from './skills.js'
+import { registerIntegrationRoutes, createIntegrationService } from './integration.js'
 
 /** Cordis 插件名（cordis.patch.yml row id 同名）。 */
 export const name = 'dsh-bio-gem'
 
-/** 需要的服务。M1：tools + skills（无浏览器半/无 server 路由）。 */
+/**
+ * 静态注入只列**必选**服务（数组形式是 cordis 唯一支持的「服务名列表」写法；
+ * `{ required, optional }` 的对象形式会被 cordis 当成「服务名 → 配置」字典，
+ * 导致插件永远 pending —— 实测：dsh boot 报
+ * `@dsh-bio/dsh-bio-gem: pending (waiting for services: required, optional)`）。
+ *
+ * `webServer` 是**可选**服务（非 web 部署不提供），改用 apply 内的动态注入
+ * `ctx.inject(['webServer'], cb)`（官方 dsh 插件同款模式）：服务可用时注册
+ * 只读 integration 路由，不可用时 23 个工具与 skill 照常注册。
+ */
 export const inject = ['tools', 'skills']
 
 /**
@@ -16,4 +26,13 @@ export const inject = ['tools', 'skills']
 export function apply(ctx) {
   registerTools(ctx)
   registerSkills(ctx)
-}
+
+  const service = createIntegrationService()
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(() => registerIntegrationRoutes(webCtx, { service }), 'dsh-bio-gem: integration API routes')
+    // 延迟预热（**不在插件加载期**执行，不阻塞启动）：启动 ~8s 后后台跑一次只读探测，
+    // 让面板首次打开即命中 60s 缓存，避免首次冷探测（含 WSL 探测）被消费端超时截断。
+    const warmup = setTimeout(() => { void service.status().catch(() => {}) }, 8_000)
+    webCtx.effect(() => () => clearTimeout(warmup), 'dsh-bio-gem: runtime probe warm-up')
+  })
+}