gside：基因组物种鉴定引擎
独立 CLI：从组装 contigs 做多层物种鉴定，从 FASTQ reads 做宏基因组谱分析。
概述
gside 将标准生信工具（blastn、skani、mash、sourmash、GTDB-Tk、Kraken2、sylph）封装在数据驱动规则之后，跨方法仲裁，输出单一 JSON 判定。智能体优先设计：结构化错误字段、自动安装、MCP 服务器、机器可读数据库状态。
底层生信工具 blastn / skani / mash / sourmash / gtdbtk / kraken2 / sylph
↑
gside 物种鉴定引擎 + 宏基因组谱分析
物种鉴定层次
| 层次 | CLI mode | 底层引擎 | 原理 | 说明 |
|---|---|---|---|---|
| L3 | gtdbtk |
GTDB-Tk | 系统发育位置 | 最权威；外部数据库 |
| L2 | panel |
skani | ANI 精选面板（291 基因组） | 需 panel 层 |
| L2 | mash_refseq |
mash | MinHash 距离（RefSeq） | 需 mash 层 |
| L2 | sourmash |
sourmash | GTDB gather | 需 GTDB 库 |
| L1 | marker |
blastn | 靶基因规则（38 条，80 序列） | mini 层随包分发 |
| 仲裁 | all |
— | 全方法层级共识（L3 > L2 > L1） | 取最优 |
宏基因组谱分析
| 模式 | 引擎 | 输入 | 适用 |
|---|---|---|---|
kraken2 |
Kraken2 + Bracken | FASTQ / FASTA | 快速筛查、contig 支持、丰度 |
sylph |
sylph | 仅 FASTQ | ANI 精度、种级判定 |
all |
双引擎 | FASTQ / FASTA | 合并谱 |
快速开始
# 安装
pixi install
pip install -e .
# 物种鉴定（marker 模式开箱即用）
gside species contigs.fna
# 多方法鉴定 + 自动安装
gside species contigs.fna --mode all --auto-setup
# 并行批量处理
gside species *.fna --mode all -j 8 -t 4 -o results.tsv
# 宏基因组
gside meta reads_R1.fq reads_R2.fq --mode all
# 数据库管理
gside db status
gside db setup --tier all
智能体友好设计
- stdout 纯 JSON — species 恒 exit 0；单法错误在
methods.<mode>.error - 结构化缺库错误 —
suggested_command、missing_tier、estimated_size - 自动安装 —
--auto-setup安装缺失层级，进度走 stderr - 机器可读状态 —
db status --format json、db list --format json - MCP 服务器 —
gside mcp向 Claude Desktop / MCP 客户端暴露工具 - 流式输出 — tsv/md 逐输入即时写盘
输出
所有模式向 stdout 输出统一 JSON，顶层字段为 analysis_type、tool、version、
contigs、methods、verdict。详见
JSON 输出契约。
文档
License
MIT