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

package/python/sampling.py

@@ -0,0 +1,269 @@
+"""Flux-space sampling primitives for the ``sample`` gem operation."""
+import contextlib
+import hashlib
+import io
+import os
+import time
+
+import numpy as np
+from cobra.sampling import ACHRSampler
+from cobra.util.solver import linear_reaction_coefficients
+
+from gapfind import expand_medium, resolve_medium
+from silentio import silent_read_sbml
+
+
+EX_PREFIXES = ("EX_", "DM_", "SK_")
+FLUX_TOLERANCE = 1e-9
+MIN_SAMPLES = 10
+MAX_SAMPLES = 20000
+
+
+def _model_hash(path):
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()[:16]
+
+
+def _is_boundary(reaction):
+    return reaction.boundary or reaction.id.startswith(EX_PREFIXES)
+
+
+def _configure_medium(model, medium):
+    """Apply only an explicitly supplied medium; preserve SBML defaults otherwise."""
+    if medium is not None and not isinstance(medium, dict):
+        raise ValueError("medium must be an object when provided")
+
+    expanded, preset = expand_medium(medium)
+    resolved, unresolved = resolve_medium(model, expanded) if expanded else ({}, [])
+    if medium is not None:
+        for reaction in model.reactions:
+            if _is_boundary(reaction):
+                reaction.lower_bound = 0.0
+        for reaction_id, lower_bound in resolved.items():
+            model.reactions.get_by_id(reaction_id).lower_bound = lower_bound
+    return {"preset": preset, "resolved_exchanges": len(resolved)}, unresolved
+
+
+def _require_int(name, value, minimum=None, maximum=None):
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an integer")
+    if minimum is not None and value < minimum:
+        raise ValueError(f"{name} must be >= {minimum}")
+    if maximum is not None and value > maximum:
+        raise ValueError(f"{name} must be <= {maximum}")
+    return value
+
+
+def _growth_reaction(model):
+    """Select the strongest positive linear objective reaction deterministically."""
+    coefficients = linear_reaction_coefficients(model)
+    if not coefficients:
+        raise ValueError("model needs a linear objective to identify the growth reaction")
+
+    candidates = [(reaction, float(coefficient)) for reaction, coefficient in coefficients.items()]
+    positive = [(reaction, coefficient) for reaction, coefficient in candidates if coefficient > 0]
+    pool = positive or candidates
+    reaction, _coefficient = sorted(pool, key=lambda item: (-abs(item[1]), item[0].id))[0]
+    return reaction
+
+
+def _describe(values):
+    values = np.asarray(values, dtype=float)
+    return {
+        "median": float(np.quantile(values, 0.5)),
+        "mean": float(np.mean(values)),
+        "min": float(np.min(values)),
+        "max": float(np.max(values)),
+        "q05": float(np.quantile(values, 0.05)),
+        "q25": float(np.quantile(values, 0.25)),
+        "q75": float(np.quantile(values, 0.75)),
+        "q95": float(np.quantile(values, 0.95)),
+    }
+
+
+def _reaction_stats(values):
+    values = np.asarray(values, dtype=float)
+    return {
+        "median": float(np.quantile(values, 0.5)),
+        "q05": float(np.quantile(values, 0.05)),
+        "q95": float(np.quantile(values, 0.95)),
+        "sign_probability": float(np.mean(values > FLUX_TOLERANCE)),
+        "near_zero_fraction": float(np.mean(np.abs(values) <= FLUX_TOLERANCE)),
+    }
+
+
+def _selected_reactions(samples, growth_reaction_id, reactions):
+    if reactions is not None:
+        if not isinstance(reactions, list) or any(not isinstance(item, str) for item in reactions):
+            raise ValueError("reactions must be an array of reaction IDs")
+        selected = []
+        for reaction_id in reactions:
+            if reaction_id not in samples.columns:
+                raise ValueError(f"reaction not found in model: {reaction_id}")
+            if reaction_id not in selected:
+                selected.append(reaction_id)
+        return selected
+
+    iqr = samples.quantile(0.75) - samples.quantile(0.25)
+    ranked = sorted(
+        (reaction_id for reaction_id in samples.columns if reaction_id != growth_reaction_id),
+        key=lambda reaction_id: (-float(iqr[reaction_id]), reaction_id),
+    )
+    return [growth_reaction_id] + ranked[:20]
+
+
+def _validate_requested_reactions(model, reactions):
+    """Reject malformed target lists before expensive ACHR warmup starts."""
+    if reactions is None:
+        return
+    if not isinstance(reactions, list) or any(not isinstance(item, str) for item in reactions):
+        raise ValueError("reactions must be an array of reaction IDs")
+    for reaction_id in reactions:
+        if reaction_id not in model.reactions:
+            raise ValueError(f"reaction not found in model: {reaction_id}")
+
+
+def _method(method):
+    if method is None:
+        method = "auto"
+    if not isinstance(method, str):
+        raise ValueError("method must be one of auto, achr, optgp")
+    normalized = method.lower()
+    if normalized not in {"auto", "achr", "optgp"}:
+        raise ValueError("method must be one of auto, achr, optgp")
+    if normalized == "auto":
+        return "achr"
+    if normalized == "optgp" and os.name == "nt":
+        # OptGP creates a worker pool.  gem_ops is deliberately import-safe,
+        # but this operation must never expose Windows callers to an accidental
+        # spawn loop until that execution route has its own verified harness.
+        raise ValueError("method 'optgp' is not supported on Windows; use 'achr' or 'auto'")
+    return normalized
+
+
+def sample_fluxes(
+    model_path,
+    medium=None,
+    n=1000,
+    method="auto",
+    thinning=100,
+    growth_floor_fraction=None,
+    reactions=None,
+    seed=42,
+    export_csv=None,
+):
+    """Sample a model's feasible flux space with a deterministic ACHR default."""
+    if not model_path or not os.path.isfile(model_path):
+        raise ValueError(f"model file not found: {model_path}")
+    n = _require_int("n", n, MIN_SAMPLES, MAX_SAMPLES)
+    thinning = _require_int("thinning", thinning, 1)
+    seed = _require_int("seed", seed)
+    if export_csv is not None and not isinstance(export_csv, str):
+        raise ValueError("export_csv must be a path string when provided")
+    if growth_floor_fraction is not None:
+        if isinstance(growth_floor_fraction, bool) or not isinstance(growth_floor_fraction, (int, float)):
+            raise ValueError("growth_floor_fraction must be a number strictly between 0 and 1")
+        growth_floor_fraction = float(growth_floor_fraction)
+        if not 0.0 < growth_floor_fraction < 1.0:
+            raise ValueError("growth_floor_fraction must be strictly between 0 and 1")
+
+    method_used = _method(method)
+    started = time.perf_counter()
+    base_model = silent_read_sbml(model_path)
+    configured_model = base_model.copy()
+    medium_summary, unresolved_medium = _configure_medium(configured_model, medium)
+
+    growth_reaction = _growth_reaction(configured_model)
+    fba_solution = configured_model.optimize()
+    if fba_solution.status != "optimal":
+        raise ValueError(f"FBA under the selected medium is not optimal: {fba_solution.status}")
+    max_growth = float(fba_solution.fluxes[growth_reaction.id])
+
+    # Every sampling run gets an independent model copy.  The growth-floor
+    # branch therefore cannot leak modified bounds into the caller or a retry.
+    sampling_model = configured_model.copy()
+    if growth_floor_fraction is not None:
+        if max_growth <= FLUX_TOLERANCE:
+            raise ValueError("cannot apply growth_floor_fraction because maximum growth is not positive")
+        sampling_growth = sampling_model.reactions.get_by_id(growth_reaction.id)
+        sampling_growth.lower_bound = growth_floor_fraction * max_growth
+
+    _validate_requested_reactions(sampling_model, reactions)
+
+    # The only fully supported execution route for the Windows target is ACHR.
+    # A non-Windows future caller can still ask for OptGP explicitly.
+    # Sampling libraries can emit backend diagnostics.  Keep them off stdout so
+    # gem_ops retains its one-JSON-object protocol.
+    with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+        if method_used == "achr":
+            sampler = ACHRSampler(sampling_model, thinning=thinning, seed=seed)
+        else:
+            from cobra.sampling import OptGPSampler
+
+            sampler = OptGPSampler(sampling_model, thinning=thinning, processes=1, seed=seed)
+        samples = sampler.sample(n, fluxes=True)
+    runtime_s = time.perf_counter() - started
+    if len(samples) != n:
+        raise RuntimeError(f"sampler returned {len(samples)} rows for n={n}")
+
+    validation_codes = sampler.validate(samples.to_numpy())
+    n_valid = int(np.sum(validation_codes == "v"))
+    selected = _selected_reactions(samples, growth_reaction.id, reactions)
+    reaction_summary = {
+        reaction_id: _reaction_stats(samples[reaction_id].to_numpy())
+        for reaction_id in selected
+    }
+    growth_summary = _describe(samples[growth_reaction.id].to_numpy())
+
+    if export_csv:
+        samples.to_csv(export_csv, index=False)
+
+    if growth_floor_fraction is None:
+        boundary_space = "full_feasible_space"
+        floor_note = "未施加 growth floor。"
+    else:
+        boundary_space = "growth_floor_constrained_space"
+        floor_note = (
+            f"已在独立 model.copy() 上将 {growth_reaction.id} 的下界设为 "
+            f"{growth_floor_fraction:.6g} × 当前 FBA 最大生长。"
+        )
+
+    boundary_note = (
+        "全空间均匀采样 ≠ 生物学上有意义的活跃状态；关心近最优生长态请传 "
+        "growth_floor_fraction（如 0.9）。"
+        f"当前介质下 {growth_reaction.id} 的 FBA 最大生长为 {max_growth:.9g}。{floor_note}"
+    )
+    feasibility_note = (
+        "n_valid 为 cobra sampler.validate 返回 'v'（同时满足稳态、上下界）的样本数；"
+        "validation_failures 为其余 l/u/e 代码的样本数。"
+    )
+    if unresolved_medium:
+        feasibility_note += " 未解析的介质成分未施加：" + ", ".join(sorted(unresolved_medium)) + "。"
+
+    return {
+        "model": model_path,
+        "model_hash": _model_hash(model_path),
+        "method_used": method_used,
+        "n_requested": n,
+        "n_samples": int(len(samples)),
+        "thinning": thinning,
+        "seed": seed,
+        "runtime_s": runtime_s,
+        "growth_reaction": growth_reaction.id,
+        "growth": growth_summary,
+        "reactions": reaction_summary,
+        "feasibility": {
+            "n_valid": n_valid,
+            "validation_failures": int(len(samples) - n_valid),
+            "note": feasibility_note,
+        },
+        "boundary": {
+            "space": boundary_space,
+            "growth_floor_fraction": growth_floor_fraction,
+            "note": boundary_note,
+        },
+        "medium": medium_summary,
+    }

package/python/sensitivity.py

@@ -7,7 +7,7 @@
 #   产物（目标汇连接组分），GAM 网格只动 stub（等比缩放 X/GAM_ORIG）。
 # 锚点: 基准组合与 essential_scan 完全同参数 -> 必须精确复现 155；且 155 全部在
 #   always_essential ∪ conditionally_essential（基准在网格内故断言必成立）。
-# 生长/通量数值口径: 单点 FBA objective_value（mmol/gDW/h）；区间制对比请用 gem_fluxscan。
+# 生长数值口径: 单点 FBA objective_value = 比生长速率（1/h，biomass 归一化口径）；区间制对比请用 gem_fluxscan。
 import os
 import sys
 import csv
@@ -391,7 +391,7 @@ def sensitivity(model_path, medium=None, biomass_scales=None, gam_grid=None,
         "component_sensitivity": {"top_sensitive": top_sensitive, "rows": comp_rows},
         "component_essentiality_drift": drift,
         "card_robustness_written": card_written,
-        "units": "mmol/gDW/h",
+        "units": "1/h",
         "timing_seconds": round(time.time() - t_start, 1),
     }
     try:

package/python/validate.py

@@ -1,6 +1,6 @@
 # validate.py — dsh-bio-gem 五道验证关卡（M1）
 # G1 加载统计 / G2 内部反应元素平衡 / G3 生长真实性 / G4 底物表型(条件) / G5 必需基因抽检(条件)
-# 规格: docs/ARCHITECTURE.md §5；判据口径 = FBA objective_value（mmol/gDW/h，不用 μ）
+# 规格: docs/ARCHITECTURE.md §5；判据口径 = FBA objective_value（biomass 归一化 → 比生长速率 μ，单位 1/h）
 # 实现从 HANDOFF-03 五道关卡协议产品化（农杆菌项目验证过的逻辑）
 import re
 import os
@@ -197,7 +197,7 @@ class Validator:
             "ratio_vs_reference": round(ratio, 4) if ratio is not None else None,
             "checks": {"medium>0": ok_grow, "no_carbon==0": ok_noc, "closed==0": ok_closed},
             # 阶段A-M4 口径声明（只增）：单点 FBA 值非硬结论
-            "units": "mmol/gDW/h",
+            "units": "1/h",
             "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定",
         }
         return rep
@@ -313,7 +313,7 @@ class Validator:
             results.append({"substrate": sub, "published": int(pub), "predicted": int(pred),
                             "growth": round(g, 6), "exchange": exid or None, "match": bool(ok),
                             # 阶段A-M4 口径声明（只增）：每底物 growth 为单点 FBA 值
-                            "units": "mmol/gDW/h",
+                            "units": "1/h",
                             "point_value_note": "单点 FBA 值，非解空间硬结论；条件对比请用 gem_fluxscan 区间分离判定"})
         rep = {
             "status": "PASS" if rows and matched / len(rows) >= 0.8 else ("WARN" if rows else "SKIP"),
@@ -373,7 +373,7 @@ class Validator:
         medium, _preset = expand_medium(medium)
         resolved_med, unresolved = resolve_medium(self.m, medium) if medium else ({}, [])
         report = {"model": self.path,
-                  "units": {"growth": "mmol/gDW/h", "note": "objective_value 是 FBA 通量（mmol/gDW/h），不是比生长速率 μ（h⁻¹）"},
+                  "units": {"growth": "1/h", "note": "growth 为比生长速率 μ：biomass 反应归一化到 1 gDW 时其通量数值等于 μ（标准 GEM 约定）；非归一化模型的 growth 应以 mmol/gDW/h 解读"},
                   # G0 模型数据质量前置诊断：未映射前体等数据问题会让 G2/G3 与 gapfind 的
                   # 结论失真（实测 iNX1344_v3：gapfind 报的 5 个 L3 缺口实为未映射前体所致）
                   "g0": model_coherence(self.m),

package/skills/gem-expert.md

@@ -12,6 +12,7 @@ language: mixed
 |---|---|
 | 已有 SBML 模型文件，想知道概要（基因/反应/复制子）| `gem_report`（model 参数=绝对路径）|
 | 验证模型质量（五道关卡：加载/元素平衡/生长真实性/表型/必需性抽检）| `gem_validate`（model + medium）|
+| 模型质量审计（对标 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 + 三联对照，原文件不动可回滚）|
@@ -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

@@ -15,7 +15,7 @@ export const name = 'dsh-bio-gem'
  *
  * `webServer` 是**可选**服务（非 web 部署不提供），改用 apply 内的动态注入
  * `ctx.inject(['webServer'], cb)`（官方 dsh 插件同款模式）：服务可用时注册
- * 只读 integration 路由，不可用时 21 个工具与 skill 照常注册。
+ * 只读 integration 路由，不可用时 23 个工具与 skill 照常注册。
  */
 export const inject = ['tools', 'skills']