TBtools CLI

Turn legacy bioinformatics tools into Agent-callable, verifiable workflows.

294 Agent-facing tools · 59 FULL contracts · 129 schema-capable · Agent Protocol v1.0

将 TBtools-II 及传统生信工具转换为 Agent 可发现、可调用、可验证的接口层。

把 TBtools-II（2.535+）的全部功能封装成命令行，Linux/WSL 下免 GUI 直接使用。 294 Agent-facing tools(注册): Fully Agent-ready 59 | Schema-capable 129 | Registered 294(doctor --json 实时统计)——底层能力: 200+ 绘图/分析 + 180+ RPC + 80+ CLI 工具 + 110+ Java 桥 + 引擎反射(逃生舱)。 分级定义: FULL=契约完整(inputs+outputs+parameters+capabilities+stable);PARTIAL=部分契约;LEGACY=仅注册。核心竞争力不是包装数量,而是把传统生信工具转换成机器可理解/可验证/可组合的工具契约。 数字权威源: tbtools version --json / docs/_generated/counts.md / docs/_generated/tool-readiness.md(自动生成防漂移)。

---

📺 Demo

10 秒演示: tbtools version → doctor → search volcano → volcano 实跑出图。 (docs/images/demo.cast 为 asciinema 原始录制,可 asciinema play 播放。)

# 本地播放
asciinema play docs/images/demo.cast
# 或上传 asciinema.org 网页播放(asciinema upload)

🤖 Agent 接口(结构化调用, AI 可用)

统一命令模型 + 结构化 JSON 输出,Agent 可程序化发现/预检/执行/验证:

能力	命令	说明
1 Discover	tbtools search <任务> --json	工具发现(多词/反向/能力;不做规划)
2 Describe	tbtools tool-describe <命令> --json	命令 schema(列名/参数/依赖/关系/platforms)
3 Plan	tbtools workflow-plan <目标> --json	规划(决策层): 目标→工具链(relations/capability 推导)
4 Validate	tbtools tool-validate <命令> <输入...> --json	执行前检查(存在性/格式/列名契约)
5 Execute	tbtools tool-run <参数...> --json / tool-submit	同步执行 / 异步 job(状态机)
6 Observe	tbtools job-status/result <job_id>	长任务观测(running→succeeded/failed/cancelled/timed_out)
7 Artifact	tbtools artifact inspect <产出> --json	Artifact 语义验证(type/format/sha256/validation)
8 Provenance	tbtools tool-provenance <产出> / provenance-graph	溯源/DAG

# Agent 调用链示例
tbtools search "gene structure" --json        # 发现
tbtools tool-describe genestructure --json    # 理解 schema
tbtools tool-validate genestructure in.gff ids.txt --json   # 预检
tbtools tool-run seq genestructure in.gff ids.txt out.svg --json  # 执行
tbtools tool-provenance out.svg               # 溯源验证

📑 Table of Contents

• Demo
• Quick Start
• Features
• Documentation
• Installation
• Example Outputs
• Plotting Engines (200+)
• RPC Data Tools
• CLI Tools
• Any Engine Reflection
• Project Structure
• 兼容层退役计划
• Naming Convention
• Known Limitations
• FAQ
• Credits
• License

🎯 这是什么

生物信息学积累了大量成熟工具,但多为人工 GUI/CLI 设计,参数/格式/依赖复杂。tbtools-cli 将 TBtools-II 及传统生信工具转换为 Agent 可发现、可调用、可验证的接口层——人类用 CLI,AI Agent 用同一套接口(搜索/元数据/RPC/结构化输出)。

        Agent / 用户 / Shell
                 │
        ┌────────┴────────┐
        ↓                 ↓
      CLI              RPC(JSON)
        │                 │
        └────────┬────────┘
                 ↓
    统一注册层(metadata 单一数据源, 数量见 counts.md)
                 ↓
  ┌────────┬─────────┬─────────┐
  ↓        ↓         ↓         ↓
 Bridge   Direct    Tool     Engine
(118)   Engine    (82)     Reflection
                 ↓
         TBtools-II / 系统工具
                 ↓
           产物 SVG/TSV/图

典型工作流(Common Workflows)

• 基因家族分析(GRAS 实测): FASTA → muscle/trimal → iqtree → motif → genestructure(DEG 表 ± volcano)
• RNA-seq: counts → tpmCalc → pca → heatmap → volcano(DEG)
• 比较基因组学: GFF → mcscanx → dualsyn → dotplot
• 系统发育: FASTA → msa → trimal → one-step(IQ-TREE)→ tree draw
• Agent 调用: tbtools search <任务> → version --json / rpc <method> → 结构化结果

🤖 MCP Server(Claude/Cursor 即插即用)

tbtools mcp    # stdio MCP server

MCP 客户端配置示例(Claude Desktop / Cursor):

{"mcpServers": {"tbtools": {"command": "tbtools", "args": ["mcp"]}}}

MCP 暴露 9 个稳定编排原语(不是 200+ 工具): search / tool_describe / tool_validate / tool_run / workflow_plan / job_submit / job_status / job_result / tool_provenance——Agent 怕 2000 个工具;8 原语 ↓ 294 领域能力,自动发现、自动调用,零提示词。协议规范见 docs/agent-protocol.md。

🧭 按任务找命令(What do you want to do?)

你手上的数据	想做什么	命令链
FASTA(蛋白/核酸)	比对→修剪→建树	muscle → trimal → iqtree → tree
FASTA	Motif 发现/可视化	memerun → memeViz / motif
counts + 基因长度	RNA-seq 差异分析	tpmCalc → pca → heatmap → volcano
DEG 表(GeneID/Log2FC/pvalue)	火山图/分布图	volcano / dehist
表达矩阵	聚类/热图/PCA	hclust(三列距离)/ heatmap / pca
GFF3 + 基因 ID	基因结构图	genestructure
GFF + BLAST	共线性分析	mcscanx → dualsyn / dotplot / msy
基因列表	韦恩/UpSet	venn2 / venn3 / upset
GFF/PEP	GO/KEGG 富集	goEnrich / keggEnrich → barplot
FASTA	BLAST 同源搜索	blastp / blastn / recipBlast
peak 坐标	ChIP-seq 峰值/TSS	peaktss / peakanno
Newick	树定根/重命名	treeRooting / newickRename
Agent/AI	按任务自动发现	tbtools search <任务> --json → tool-describe → tool-run

🚀 Quick Start

最小示例数据（新人入门防格式坑）: 本仓库 examples/data/ 为官方数据,git clone 或直接下载: git clone --depth 1 https://github.com/qby1613527176-cmd/tbtools-cli → examples/data/ 即可复现本文所有命令。

tbtools version          # 查看版本（动态统计）
tbtools doctor           # 环境诊断（检查 Java/JAR/xvfb/依赖）
tbtools list              # 列出全部绘图/分析命令
tbtools list tools        # 列出全部命令行工具
tbtools help volcano      # 快捷帮助（自动定位分组）
tbtools rpc start         # 启动 RPC 服务器（188 方法；pid 文件+健康检查，死亡后 call/methods 自动拉起）
tbtools rpc status        # 查看 RPC 状态；rpc stop 停止
bash examples/scripts/run_examples.sh     # 一键验证（8 项核心功能）

配置文件

# ~/.config/tbtools-cli/config.toml
jar = "/path/to/TBtools_JRE1.6.jar"
[defaults]
threads = 4
format = "svg"
# preset = "nature"    # 取消注释启用默认预设

Bash Completion（tab 补全）

source scripts/tbtools-completion.bash   # 临时启用
# 或永久安装:
cp scripts/tbtools-completion.bash ~/.local/share/bash-completion/completions/tbtools

Man Page

man -l scripts/tbtools.1              # 查看 man page
# 或安装到系统:
sudo cp scripts/tbtools.1 /usr/local/share/man/man1/

stdin/stdout 管道（CLI 工具层）

# stat-fasta 支持 stdin
 ./tbtools tool stat-fasta /dev/stdin /dev/stdout < seqs.fa
# ⚠️ 大部分 Java 引擎不认 /dev/stdin，管道支持有限

✨ Features

能力	状态	说明
绘图引擎 CLI	✅	200+ 个（无头 SVG/PNG 输出,Linux 需 xvfb）
RPC 数据工具	✅	180+ 方法,自愈服务器（pid+健康检查+自动重启）
管道（stdin/stdout）	⚠️	仅部分 tool 层命令;绘图命令需真实文件路径
Windows 绘图	⚠️	基本可用;无 xvfb 时部分绘图受限
联网命令（NCBI/API）	⚠️	srr2ena/pubmed/seqfetch 等需外网,被墙环境请配代理
中文路径	✅	已实测支持
并发/高吞吐	✅	1.2GB FASTA 23.9s 线性

Layer	Capability	Entry
🎨 绘图引擎	200+ 个（基因结构/Motif/热图/树/共线性/韦恩/ChIP-seq/柱图/环形图/标记设计/eFP 等）	tbtools <plotName>
📊 RPC 数据工具	180+ 个（FASTA/GFF/表达/Blast/富集/建树/引物等）	tbtools rpc <method> '<json>'
🛠️ 命令行工具	80+ 个（extractFasta/statFasta/rpkmCal/tpmCalc/mimicVqsr 等）	tbtools tool <name>
🔬 任意引擎反射	万能兜底（任意 TBtools 引擎类）	tbtools engine <class> key=value
🧩 插件命令	12 个 CLI 化插件（GSEA/Notung reconcile/植物 TF motif 偏移/MEME 可视化/kallisto 定量/HMMer 全库扫描/MCScanX 加速/Newick 重命名/基因组 dot plot/diamond 蛋白注释/SMART 域注释/FIMO motif 扫描）	tbtools table gsea / tbtools tree notung 等

All engines are driven headlessly (via xvfb on Linux/WSL), no GUI needed. Verified with real biological data (oil-Camellia GRAS gene family etc).

📖 Documentation

每次调用前先查 docs/COMMAND_REFERENCE.md（命令参考手册,自动生成命令清单见 docs/_generated/commands.md）——每个命令的输入格式、参数、示例、已知坑都在里面。

文档	内容
docs/COMMAND_REFERENCE.md	命令参考手册：200+ 个命令（用法表+详细注释）+ 80+ 个 CLI 工具（18 类功能分组）+ 110+ 个桥 Javadoc（输入格式权威来源）+ 46 条实测坑位 + engine 反射 + RPC 指引
docs/rpc_methods_reference.md	RPC 180+ 方法参考（参数/返回值,自动生成）

# 快速查用法（不用翻手册）：
tbtools --help              # 绘图命令一屏预览
tbtools list tools          # CLI 工具列表
tbtools rpc methods         # RPC 方法列表
java -cp $TBTOOLS_JAR <引擎类>  # 无参运行 → 打印完整 [Usage] 参数表（含默认值）

---

📦 Installation

推荐路径: pip install tbtools-cli（见 0;受限环境加 --user 或 venv）; 备用路径: git clone + install.sh（见 1）。其余方式为历史兼容。

0. pip 安装（推荐，Python 包入口）

⚠️ Windows 用户注意: 绘图类命令在无 xvfb 时部分受限（工具类/RPC 全可用）;WSL2 推荐。详见 FAQ。 系统 Python 受 PEP 668 保护时（Debian/Ubuntu 23+），先建虚拟环境或加 --user： python3 -m venv ~/.venv && source ~/.venv/bin/activate 或 pip install --user tbtools-cli

pip install .            # 或 pipx install . / pip install git+https://github.com/qby1613527176-cmd/tbtools-cli
# 安装后 `tbtools` 直接可用（console_script）；JAR 仍需就位（见下）

Requirements

• Linux / WSL2 / macOS（绘图需要 xvfb-run，可用 sudo apt install xvfb）
• Windows：支持工具类/RPC/表格类命令（Git Bash + TBtools-II/bin 加入 PATH）；绘图类命令受 xvfb 限制（部分可用）
• JDK 11+（java、javac）
• TBtools_JRE1.6.jar（TBtools-II 主 jar，~55MB）

1. Install（自动接入本机 TBtools）

git clone https://github.com/qby1613527176-cmd/tbtools-cli.git
cd tbtools-cli

三种接入方式，AI/脚本可按需选用：

# ① 自动搜索本机已有 TBtools jar 并配置（最常用）
tbtools setup --auto
#    → 自动扫描 ~/TBtools、~/Downloads、~/桌面、/mnt/*（WSL）、C:/TBtools（Git-Bash）、
#      /Applications（macOS）等常见位置，找到即写入 ~/.config/tbtools-cli/

# ② 知道 jar 路径，直接指定
tbtools setup /path/to/TBtools_JRE1.6.jar

# ③ 本机没有 jar？自动下载官方 portable 包并提取 jar（官方只发 zip，~300MB）
tbtools fetch-jar
#    → 自动查询最新含 portable 的 release，下载 → 提取 TBtools_JRE1.6.jar → 配置
#    可选: tbtools fetch-jar --version 2.475

手动方式（无 tbtools 时）：

./install.sh --jar /path/to/TBtools_JRE1.6.jar
# 或
export TBTOOLS_JAR=/path/to/TBtools_JRE1.6.jar
export PATH="$PWD/bin:$PATH"

2. Verify

tbtools doctor      # 一键检查 Java/jar/xvfb/可选依赖；jar 缺失时给出可执行指引
tbtools version     # 实时统计命令/桥/坑位数量

3. Auto-verify（一键回归，8 项核心功能示例图）

bash examples/scripts/run_examples.sh   # 运行 8 个代表性引擎 → examples/output/ 下生成示例图

---

🖼️ Example Outputs

Heatmap	Venn / UpSet

Phylogenetic tree	Synteny (MCScanX + dot plot)	Grouped bar + significance

全部由本仓库 examples/fulltest 合成数据实测生成（docs/images/，SVG 可放大无损）。 复现: bash examples/scripts/run_examples.sh。

🎨 Plotting Engines (218)

Gene structure / Motif / Sequence logo

# Gene structure (exons/UTR from GFF)
tbtools seq genestructure <input.gff> <mRNA_ids.txt> <out.svg> [genome.fa] [w] [h]
# Motif distribution (MEME XML)
tbtools seq motif <meme.xml> <idList.txt> <out.svg> [w] [h]

更多命令见 docs/_generated/commands.md 或 tbtools list plots

Expression / Statistics

# Volcano plot (DEG: GeneID Log2FC pvalue)
tbtools volcano <deg.txt> <out.svg> [pvalCutoff] [fcCutoff] [w] [h]
# Expression level calculators (counts+len → RPKM/TPM; FPKM → TPM)
tbtools tool rpkmCal    --countsTable counts.tsv --lenInfo gene_len.tsv --outTable RPKM.out.tsv

更多命令见 docs/_generated/commands.md 或 tbtools list plots

Phylogeny / Tree

# Tree + annotation tracks (TextAnno/HeatMap/BarPlot/Tile/StackBar/Domain...)
tbtools tree draw <treeMeta.cfg> <out.svg> [pad]
# Hclust → Newick
tbtools expr hclust <distance_matrix.tsv> <out.nwk>

更多命令见 docs/_generated/commands.md 或 tbtools list plots

Genomic location / Circos / Synteny

# Gene chromosome location (GFF + IDs)
tbtools gxf genelocgff <gff3> <ids.txt> <out.svg> [--chrLen l.tsv --pairs p.tsv ...]
# Gene location (native CLI)
tbtools genelocation --ChrLen <chrlen.tsv> --FeaturePos <pos.tsv> --OutGraph <out.svg>

更多命令见 docs/_generated/commands.md 或 tbtools list plots

Venn / Sets

# Venn 2/3/4 (native ArgsParser CLI)
tbtools sets venn2 --List1 a.txt --List2 b.txt --label1 A --label2 B --graph out.svg --prefix out
tbtools sets venn3 --List1 a.txt --List2 b.txt --List3 c.txt --label1 A --label2 B --label3 C --graph out.svg --prefix out
tbtools sets venn4 --List1 a.txt --List2 b.txt --List3 c.txt --List4 d.txt --label1 A --label2 B --label3 C --label4 D --graph out.svg --prefix out

更多命令见 docs/_generated/commands.md 或 tbtools list plots

ChIP-seq / Others

# Peak-TSS heatmap
tbtools chipseq peaktss <gxf> <macs2_peak.xls> <out.svg> [--dist N]
# Peak chromosome distribution
tbtools chipseq peakdist <chrLen.tsv> <macs2_peak.xls> <out.svg> [--width W --height H]

更多命令见 docs/_generated/commands.md 或 tbtools list plots

📊 RPC Data Tools (188 methods)

tbtools rpc start                       # 启动 RPC 服务器 (port 8765)
tbtools rpc methods                     # list all RPC methods
tbtools rpc FastaStat.process '{"inputPath":"in.fa","outputPath":"out.xls"}'
tbtools rpc OneStepBuildATree.process '{"inputPath":"seqs.fa","outputPath":"outdir","options":{"ultraFastBS":true}}'

全部 188 方法见 docs/rpc_methods_reference.md 或 tbtools list rpc

🛠️ CLI Tools (82)

tbtools tool <name> [args...]      # run any CLI tool; full help: tbtools list tools

# --- Fasta / Fastq ---
tbtools tool statFasta             # sequence statistics
tbtools tool extractFasta          # extract/filter FASTA by ID list

全部工具见 docs/COMMAND_REFERENCE.md 或 tbtools list tools(数量见 counts.md)

🔬 Any Engine Reflection (universal fallback)

tbtools engine <full.class.Name> key=value [--call method]
# example: QuickStatFasta
tbtools engine biocjava.bioIO.FastX.FastaIndex.QuickStatFasta inFile=seqs.fa --call stat

---

📁 Project Structure

tbtools-cli/
├── bin/
│   ├── tbtools            # unified entry (bash 兼容层，转发 python -m tbtools_cli.cli)
│   ├── tbplot.sh          # plotting engines（兼容层，逐步退役为转发）
│   ├── tbtools_rpc.sh     # RPC server & calls
│   └── tbcli.py           # 旧工具入口（已由 cli_tools_registry 替代，保留兼容）
├── tbtools_cli/           # ✅ Python 包（真正的入口）
│   ├── cli.py             # click 主 CLI（全命令注册 + rpc 自愈 + 纠错）
│   ├── auto_commands.py   # ENGINE_REGISTRY 表驱动命令工厂(命令数以 `tbtools version` 为准)
│   ├── cli_tools_registry.py  # CLI 工具共享注册表
│   ├── command_metadata.json  # 命令元数据（gen_metadata 从 CommandSpec 生成,唯一数据源）
│   ├── core.py            # run_java 包装 + 输入保护 + PITFALL_HINTS(46)
│   ├── presets.py / scenarios.py / config.py
├── pyproject.toml         # ✅ pip 安装（tbtools console_script）
├── bridges/               # 118 Java bridge sources
├── build/                 # compiled bridges (auto-generated)
├── config/config.sh       # unified config (TBTOOLS_JAR etc.)
├── scripts/               # tbtools-completion.bash + tbtools.1 + 工具脚本
├── examples/              # example data + scripts
├── scripts/               # rpc_regression_linux.sh 等工具脚本
├── tests/                 # pytest（83 passed：框架/命令/防漂移/输入保护）
├── docs/                  # detailed documentation
│   ├── COMMAND_REFERENCE.md  # 📖 命令参考手册（218 命令+82 工具+118 桥+46 坑位）
│   └── rpc_methods_reference.md  # RPC 188 方法参考
├── install.sh             # one-command installer
└── README.md

---

🛠️ 兼容层退役计划

bin/tbplot.sh / bin/tbengine.sh / bin/tbcli.py / bin/tbtools_rpc.sh 为旧入口兼容层（已打印 deprecation 警告）。 计划 v2.0.0 移除。新用法一律走 tbtools（Python 入口）;.bashrc 如引用了旧入口请迁移。

🏷️ Naming Convention

• 规范命令名是小写 camelCase：tableCast / tableMelt / recipBlast（分组命令）
• 个别工具层保留旧大写注册名作别名：TableCast 与 tableCast 指向同一引擎（tool TableCast 兼容旧写法）
• 新旧入口并存是过渡设计，规范入口见 tbtools list

🖥️ 平台支持矩阵

能力	Linux	WSL2	macOS	Windows
CLI/Tool/RPC	✅	✅	✅	✅
绘图(SVG)	✅(xvfb)	✅	✅	⚠️ 部分受限
MCP	✅	✅	✅	✅
Workflow/Job	✅	✅	✅	⚠️ 进程组操作受限
外部二进制依赖	✅	✅	部分	部分

⚠️ Known Limitations

Engine	Status
MicroGenomeViz	doesn't handle join(complement(...))
UnrootedTreeViz	hardcoded demo main
geneOnGenome CLI	jar compile-level bug
PhyloTreeView	needs TreeTab format (not pure Newick)
DualSyn	old JJplot2 framework; plot() works but save limited (window traversal fails)
FindBlockDual/Multiple	requires real genome data; synthetic small data triggers ArrayList.get OOB
peakAnno	small coordinates (<10kb) trigger GxFOverlapIndexer bin boundary bug; use real genome scale
MountainPlot/StackMotif	empty shell in TBtools jar (no implementation)
DistanceAdvanced	pure calculation, no plotting (use distance command instead)

---

❓ FAQ

Java 版本要求? 需要 JRE 8+（推荐 11/17;引擎为 Java 8 编译,JDK 9+ 移除部分 javax.xml 类,--verbose 报 ClassNotFoundException 时见 docs/_worklog 修复记录）。tbtools doctor 会自动检测。

Windows 支持? 双击/终端可用（v2.475 实测）;绘图命令在 Windows 无 xvfb 时部分受限（见「Known Limitations」）。WSL2 经 /mnt/d 挂载 JAR 亦可。

xvfb 是什么? Linux 无头绘图必须的虚拟显示层。sudo apt install xvfb。doctor 会提示缺失。

stdin/stdout 管道支持? 仅 tool 层部分工具支持（/dev/stdin）;绘图命令需真实文件路径（Java 引擎不认 /dev/stdin）。

为什么命令有大小写混用? 小写 camelCase 为规范名,旧大写名作兼容别名（见 Naming Convention）。

如何升级? git pull && pip install -e .（源码安装）;JAR 用 tbtools fetch-jar --yes 更新。

🙏 Credits

• TBtools — the underlying toolkit by Chengjie Chen
• This project is an independent CLI wrapper, not affiliated with TBtools

📄 License

This CLI wrapper is released under the MIT License (see LICENSE): you may use, copy, modify, and distribute it freely, provided the copyright notice and this permission notice are preserved in all copies or substantial portions.

The underlying TBtools toolkit is also MIT-licensed by its author Chengjie Chen. This project is an independent wrapper and is not affiliated with TBtools.

文档以英文版为准;命令帮助信息以 tbtools <cmd> --help 输出为准。