tbtools-cli 1.2.0__py3-none-any.whl

tbtools_cli/cli_load.py

@@ -0,0 +1,352 @@
+"""cli_load.py — 动态命令注册（架构重构批次 B：从 cli.py 拆分）
+
+CATEGORY_MAP/GROUPS 分组映射 + _load_auto_commands/_load_dynamic_commands +
+_make_passthrough（metadata 驱动）+ ToolGroup 兜底注册。
+由 cli.py 在 cli 定义后调用 build_and_load(cli) 完成装配。
+"""
+import difflib
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+import click
+
+from tbtools_cli import auto_commands as _ac
+from tbtools_cli.core import ROOT, _, check_input_format, get_pitfall_hint, validate_file
+from tbtools_cli.presets import PRESETS, apply_preset
+
+
+# ---- 动态加载剩余命令 ----
+# ---- 命令分类映射 ----
+CATEGORY_MAP = {
+    "sixframe": "seq",  # GUI 逆向：六框翻译
+    "longestorf": "seq",  # GUI 逆向：最长 ORF 预测
+    "protparam": "seq",  # GUI 逆向：蛋白理化性质
+    "genomefilter": "seq",  # GUI 逆向：序列长度过滤
+    "seqpattern": "seq",  # GUI 逆向：序列模式定位
+    "bed2gff3": "gxf",  # GUI 逆向：BED→GFF3
+    "careclassify": "seq",  # GUI 逆向：PlantCARE 元件分类
+    "protsim": "seq",  # GUI 逆向：蛋白相似度矩阵
+    "xml2blasttab": "blast", "xml2pairwise": "blast",  # GUI 逆向：BLAST XML 转换
+    "fa2tab": "seq", "tab2fa": "seq",  # GUI 逆向：FASTA↔表
+    "muscle": "seq",  # GUI 逆向：MUSCLE 比对（系统二进制）
+    "trimal": "seq",  # GUI 逆向：trimAl 修剪
+    "gblocks": "seq",  # GUI 逆向：Gblocks 修剪
+    "bestid": "blast",  # GUI 逆向：最优 ID 转换
+    "fasplit": "seq", "famerge": "seq",  # GUI 逆向：FASTA 拆/合
+    "clearchar": "table",  # GUI 逆向：非法字符清理
+    "getseqdb": "blast",  # GUI 逆向：BLAST 库提序列
+    "gb2fa": "seq",  # GUI 逆向：GenBank→FASTA
+    "findhomolog": "blast",  # GUI 逆向：最优同源
+    "taxparse": "table",  # GUI 逆向：物种分类解析
+    "srr2ena": "table",  # GUI 逆向：SRR→ENA 链接
+    "sraxml2tab": "table",  # GUI 逆向：SRA XML→表
+    "sranum2info": "table",  # GUI 逆向：SRR 信息表
+    "blat": "blast",  # GUI 逆向：BLAT 比对
+    "seqrecommend": "engine",  # GUI 逆向：测序量推荐
+    "seqfetch": "seq",  # GUI 逆向：NCBI 序列下载
+    "pubmed": "table",  # GUI 逆向：PubMed 检索
+    # 序列/结构/域
+    "genestructure": "seq", "motif": "seq", "msa": "seq", "seqlentrack": "seq",
+    "amazingmeta": "seq", "cddmotif": "seq", "pfammotif": "seq", "memerun": "seq",
+    "mastrun": "seq", "mastExtract": "seq", "mast2tab": "seq", "pep2codon": "seq",
+    "simplehmmscan": "seq", "gel": "seq", "gfa": "seq", "gfa2fa": "seq",
+    # 表达/统计
+    "pca": "expr", "hclust": "expr", "qpcr": "expr", "qpcrExp": "expr",
+    "groupedbar": "expr", "dehist": "expr", "barplot": "expr", "barplotter": "expr",
+    "layoutheatmap": "expr", "cubeheatmap": "expr", "violin": "expr",
+    "colorscheme": "expr", "distance": "expr", "mountain": "expr",
+    "tauIndex": "expr", "exprCorr": "expr", "groupCol": "expr",
+    "kaks": "tree",  # GUI 逆向：成对 Ka/Ks
+    "subtree": "tree",  # GUI 逆向：子树提取
+    "iqtree": "tree",  # GUI 逆向：IQ-TREE 建树
+    # 树/进化
+    "phylotree": "tree", "unrooted": "tree", "treeRooting": "tree",
+    "onesteptree": "tree", "degramdom": "tree", "findpath": "tree",
+    "nwAlign": "tree",
+    # 共线性/基因组
+    "circos": "syn", "supercircos": "syn", "circlegene": "syn", "dotplot": "syn",
+    "microsyn": "syn", "msy": "syn", "multisyn": "syn", "dualsyn": "syn",
+    "pafviz": "syn", "pafcomp": "syn", "pafref": "syn",
+    "mcscanx": "syn", "collinearRegion": "syn",
+    "findblockdual": "syn", "findblockmultiple": "syn", "visualizeblock": "syn",
+    "conflictpaf": "syn", "partitionconflict": "syn",
+    "microgenome": "syn",
+    # 集合/ChIP
+    "venn2": "sets", "venn3": "sets", "venn4": "sets",
+    "venn5": "sets", "venn6": "sets", "upset": "sets",
+    "peaktss": "chipseq", "peakdist": "chipseq", "peakanno": "chipseq",
+    "pileup": "chipseq",
+    # 组装/注释
+    "ctgGroup": "asm", "homoPhase": "asm", "sepChr": "asm",
+    "bamMerge": "asm", "bamindex": "asm", "bamsort": "asm", "bamstate": "asm",
+    "hicEnzyme": "asm", "virusRecomb": "asm", "preparespecies": "asm",
+    "gxfRename": "gxf", "gxfStat": "gxf", "gxfAppend": "gxf", "gxfGenepos": "gxf",
+    "gxfSplit": "gxf", "gxfIdAppender": "gxf",
+    "gxfRegion": "gxf", "gxfFix": "gxf", "gxfOverlap": "gxf", "gxfRepIDs": "gxf",
+    "gxfRepGXF": "gxf", "gxfMatch": "gxf", "gxfRecall": "gxf",
+    "regionAnno": "gxf", "annocompare": "gxf", "genedensity": "gxf",
+    "genelocation": "gxf", "genelocgff": "gxf", "gxfSort": "gxf",
+    # miRNA
+    "mirnatarget": "mirna", "mirnaTarget2": "mirna", "mirnaIdentify": "mirna",
+    # GO/表格
+    "levelGo": "table", "goParse": "table", "batchReplace": "table",
+    "goAnno": "table",  # GUI 逆向：GO 注释管道
+    "goEnrich": "table", "keggEnrich": "table",
+    "tableCollapse": "table", "tableColSelect": "table", "tableAppend": "table",
+    "tableMelt": "table", "tableColSel": "table", "tableCast": "table",
+    "tableUniq": "table", "tableTranspose": "table", "tableSplit": "table",
+    "tableMerge": "table",
+    # BLAST/比对
+    "recipBlast": "blast", "filterCScore": "blast", "quickFamily": "blast",
+    "twoSeqBlast": "blast",
+    # FASTQ
+    "fqTrim": "fastq", "fqfaConv": "fastq", "fastaSubseq": "fastq",
+    "fastaExtract": "fastq",
+    # HMM
+    "hmmExtract": "hmm", "hmmsearch": "hmm",
+    "gxfAttr": "gxf", "gdensity": "gxf",
+    "notung": "tree",
+    "newickRename": "tree",
+    "hmmerSearch": "hmm",
+    "memeViz": "seq",
+    "gsea": "table", "gbar": "expr", "golevel": "table", "sricher": "table",
+    "tfbsShift": "seq",
+    "kallisto": "expr",
+    "mcscanxd": "syn",
+    "qdot": "syn",
+    "quickAnno": "blast",
+    "smart": "seq",
+    "fimo": "seq", "meme": "seq", "mast": "seq", "meme2tab": "seq", "makemotif": "seq", "mpattern": "seq",
+    # GWAS
+    "mimicVqsr": "gwas", "vcfAddID": "gwas",
+    # 通用
+    "generic": "engine", "efpHeat": "expr", "multiEfp": "expr",
+    "plotrna": "seq", "rnaplot": "seq",
+}
+
+# 分组定义
+GROUPS = {
+    "seq": "序列/结构/域",
+    "expr": "表达/统计",
+    "tree": "树/进化",
+    "syn": "共线性/基因组",
+    "sets": "集合/韦恩",
+    "chipseq": "ChIP-seq",
+    "asm": "组装/注释",
+    "gxf": "GXF/表格",
+    "mirna": "miRNA",
+    "table": "GO/表格",
+    "blast": "BLAST/比对",
+    "fastq": "FASTQ/FASTA",
+    "hmm": "HMM",
+    "gwas": "GWAS",
+    "engine": "通用",
+}
+
+# 全局分组表（build_and_load → _ensure_groups(cli) 填充；cli.py/list 等 import 使用）
+_groups: dict[str, click.Group] = {}
+def _load_auto_commands():
+    """从 auto_commands.py 加载所有命令到对应分组（弥补 tbplot.sh 遗漏的命令）"""
+    skip = {"seqlogo", "msa", "motif", "genestructure",  # seq manual
+            "volcano", "heatmap2", "pca", "hclust", "dehist",  # expr manual
+            "tree", "unrooted", "treeRooting", "onesteptree",  # tree manual
+            "version", "doctor", "examples", "list", "presets",  # top commands
+            "seq", "expr", "tool",  # group names
+            "chipseq", "sets", "syn", "asm", "gxf", "mirna", "table",
+            "blast", "fastq", "hmm", "gwas", "engine"}
+    for name in sorted(dir(_ac)):
+        if name.startswith('_') and name.endswith('_impl') and not name.startswith('__'):
+            cmd = name[1:-5]
+            if cmd in skip:
+                continue
+            cat = CATEGORY_MAP.get(cmd, "engine")
+            target = _groups.get(cat)
+            if target and cmd not in target.commands:
+                _make_passthrough(cmd, target)
+
+def _load_dynamic_commands():
+    """从 tbplot.sh 动态生成 click 命令，按分类注册到 group"""
+    tbplot_sh = os.path.join(ROOT, "bin", "tbplot.sh")
+    if not os.path.isfile(tbplot_sh):
+        return
+    with open(tbplot_sh) as f:
+        content = f.read()
+    cmds = set(re.findall(r'^  ([a-zA-Z][a-zA-Z0-9]+)\)$', content, re.MULTILINE))
+    # 已迁移命令的原始名（不动态转发）——用 tbplot.sh 里的原始命令名
+    # 只排除真正有 @xxx.command 手动注册的命令 + group 名
+    registered = {"seqlogo", "msa", "motif", "genestructure",  # seq
+                  "volcano", "heatmap2", "pca", "hclust", "dehist",  # expr
+                  "tree", "unrooted", "treeRooting", "onesteptree",  # tree
+                  "version", "doctor", "examples", "seq", "expr", "tool",
+                  "chipseq", "sets", "syn", "asm", "gxf", "mirna", "table",
+                  "blast", "fastq", "hmm", "gwas", "engine"}
+    for cmd_name in sorted(cmds - registered):
+        cat = CATEGORY_MAP.get(cmd_name, "engine")
+        _make_passthrough(cmd_name, _groups[cat])
+
+    # 给所有分组加未知子命令纠错（ToolGroup/rpc 已有自己的 resolve_command）
+    def _smart_resolve(self, ctx, args):
+        try:
+            return click.Group.resolve_command(self, ctx, args)
+        except click.UsageError:
+            if not args:
+                raise
+            name = args[0]
+            cmds = list(self.commands.keys())
+            # 前缀优先（venn2 案例：get_close_matches n=3 按相似度排序会挤掉正确建议）
+            prefix_hits = [c for c in cmds if c.startswith(name)]
+            close = prefix_hits[:5] or difflib.get_close_matches(name, cmds, n=3, cutoff=0.6)
+            if close:
+                click.echo(_("❌ '{n}' 不是 '{g}' 分组内的命令", "❌ '{n}' is not a command in group '{g}'").format(n=name, g=self.name), err=True)
+                click.echo(f"   你是不是想用: {' / '.join(close)}?", err=True)
+            else:
+                click.echo(_("❌ '{n}' 不是 '{g}' 分组内的命令", "❌ '{n}' is not a command in group '{g}'").format(n=name, g=self.name), err=True)
+                click.echo(f"   查看: tbtools {self.name} --help", err=True)
+            ctx.exit(2)
+    for gname, g in _groups.items():
+        if gname in ("tool", "rpc"):
+            continue
+        if not hasattr(g, "resolve_command") or g.__class__.__name__ == "Group":
+            g.resolve_command = _smart_resolve.__get__(g, type(g))
+
+_META_JSON = None
+def _load_meta_json():
+    """懒加载 command_metadata.json（N33: 143 命令完整 help，含 150 可选位）"""
+    global _META_JSON
+    if _META_JSON is None:
+        try:
+            import json as _json
+            _p = os.path.join(ROOT, "tbtools_cli", "command_metadata.json")
+            _META_JSON = _json.load(open(_p, encoding="utf-8")) if os.path.isfile(_p) else {}
+        except Exception:
+            _META_JSON = {}
+    return _META_JSON
+
+def _parse_auto_metadata(name):
+    """从 auto_commands.py 解析命令元数据（docstring + 坑位）"""
+    impl = _ac._IMPL_REGISTRY.get(name) or getattr(_ac, f'_{name}_impl', None)  # 显式注册表优先(第四轮评审)
+    doc = (impl.__doc__ or "").strip() if impl else ""
+    # N33: 优先 command_metadata.json 完整 help（含可选位；docstring 常被表驱动截断）
+    _meta = _load_meta_json().get(name)
+    if _meta and _meta.get("help"):
+        usage = _meta["help"]
+    elif ':' in doc:
+        usage = doc.split(':', 1)[1].strip()
+    else:
+        usage = f"{name} [参数...]"
+    pitfall = get_pitfall_hint(name)
+    return {'impl': impl, 'usage': usage, 'pitfall': pitfall}
+
+def _make_passthrough(name, group=None):
+    """生成元数据驱动的 click 命令（help + 校验 + 预设 + 直调 Java）"""
+    meta = _parse_auto_metadata(name)
+    impl = meta['impl']
+    usage = meta['usage']
+    pitfall = meta['pitfall']
+    
+    help_text = usage
+    if pitfall:
+        help_text += f"\n\n⚠️ {pitfall}"
+    
+    _target = group  # 调用方总传 group
+    
+    def _cmd_impl(ctx, verbose, quiet, fmt, preset, height, width, threads):
+        args = list(ctx.args)
+        
+        # 输入校验：第一个非选项参数通常是输入文件（mcscanxd/kallisto 首参为工作目录/自定义路径，跳过校验）
+        if args and not args[0].startswith('-') and name not in ("mcscanxd", "kallisto", "famerge", "getseqdb", "seqrecommend", "pubmed", "tableMerge", "generic", "preparespecies", "marker", "markertools", "venn5", "venn6"):
+            ok, msg = validate_file(args[0], f"{name} 输入文件")
+            if not ok:
+                print(msg, file=sys.stderr)
+                sys.exit(2)
+            # C2: 早期格式不匹配警告（不阻断，仅提示）
+            warn = check_input_format(name, args[0])
+            if warn:
+                print(f"⚠️ 格式提醒: {warn}", file=sys.stderr)
+                print("   （继续执行；如确认无误可忽略）", file=sys.stderr)
+        if preset:
+            p = apply_preset(preset, width=width, height=height)
+            if not p:
+                print(f"❌ 未知预设: {preset}", file=sys.stderr)
+                print(f"   可用: {', '.join(PRESETS.keys())}", file=sys.stderr)
+                sys.exit(1)
+            if 'width' in p and not width:
+                width = p['width']
+            if 'height' in p and not height:
+                height = p['height']
+        
+        # 格式覆盖：替换输出文件扩展名
+        if fmt:
+            for i in range(len(args) - 1, -1, -1):
+                if args[i].endswith(('.svg', '.png', '.pdf')):
+                    base = os.path.splitext(args[i])[0]
+                    args[i] = f"{base}.{fmt}"
+                    break
+        
+        # 追加 width/height 到参数末尾（大多数命令接受 [w] [h] 位置参数）
+        if width:
+            args.append(str(width))
+        if height:
+            args.append(str(height))
+        
+        # 调用 impl 或回退到 bash tbplot.sh
+        if impl:
+            ec = impl(args, verbose=verbose, quiet=quiet)
+        else:
+            # 兜底走 bash tbplot.sh（Windows 需 Git Bash；无 bash 时报清晰错误）
+            bash_bin = shutil.which("bash")
+            if bash_bin:
+                bash_args = [bash_bin, os.path.join(ROOT, "bin", "tbplot.sh"), name] + list(ctx.args)
+                ec = subprocess.run(bash_args).returncode
+            else:
+                print(f"❌ {name} 需要 bash 兜底（tbplot.sh），但未找到 bash（Windows 请装 Git Bash）", file=sys.stderr)
+                ec = 1
+        sys.exit(ec)
+    
+    # 先设置 docstring，再装饰
+    _cmd_impl.__doc__ = help_text
+    _cmd_impl = click.pass_context(_cmd_impl)
+    for opt_args, opt_kwargs in [
+        (("--verbose", "-V"), {"is_flag": True, "default": False, "help": "显示完整堆栈"}),
+        (("--quiet", "-q"), {"is_flag": True, "default": False, "help": "静默模式"}),
+        (("--format", "-f", "fmt"), {"default": None, "help": "输出格式: svg|png|pdf"}),
+        (("--preset", "-p"), {"default": None, "help": "出版预设: nature|cell|plant_journal|wide|poster"}),
+        (("--height", "-H"), {"type": int, "default": None, "help": "画布高度"}),
+        (("--width", "-W"), {"type": int, "default": None, "help": "画布宽度"}),
+        (("--threads", "-t"), {"type": int, "default": None, "help": "线程数"}),
+    ]:
+        _cmd_impl = click.option(*opt_args, **opt_kwargs)(_cmd_impl)  # type: ignore[arg-type]
+    
+    # 提取 click.option 装饰器注册的参数（__click_params__）
+    params = getattr(_cmd_impl, '__click_params__', [])
+    params = params[::-1]  # click 处理顺序是反的
+    
+    cmd = click.Command(name=name, callback=_cmd_impl, params=params,
+        context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+        help=help_text)
+    _target.add_command(cmd)
+
+
+def build_and_load(cli):
+    """组装: 建 groups → 动态注册 auto_commands + tbplot.sh 遗留 → 返回 groups dict"""
+    _ensure_groups(cli)
+    _load_auto_commands()
+    _load_dynamic_commands()
+    return _groups
+
+
+def _ensure_groups(cli):
+    """按 GROUPS 定义补齐分组（复用装饰器已创建的；原地填充保持 _groups 引用不变）"""
+    global _groups
+    _groups.clear()
+    for key, desc in GROUPS.items():
+        if key in cli.commands:
+            _groups[key] = cli.commands[key]
+        else:
+            g = click.Group(name=key, help=desc)
+            cli.add_command(g, name=key)
+            _groups[key] = g
+    # 子命令纠错绑定在 _load_dynamic_commands 尾部完成（_smart_resolve）

tbtools_cli/cli_rpc.py

@@ -0,0 +1,303 @@
+"""cli_rpc.py — RPC 服务器管理（架构重构批次 B：从 cli.py 拆分）
+
+rpc 分组 + N34/N35 自愈基础设施（pid 文件/健康探针/自动拉起）+ N38 错误兜底。
+由 cli.py 以 `cli_rpc.build_rpc_group()` 注册。
+"""
+import json
+import os
+import subprocess
+import sys
+import time as _t
+import urllib.request
+
+import click
+
+from tbtools_cli.core import JAR
+from tbtools_cli.core import _ as _tr
+
+@click.group('rpc')
+def rpc_group():
+    """RPC 服务器管理（188 方法）"""
+
+# ---------- RPC 自愈基础设施（N34/N35 批次 2）----------
+# 症状：引擎进程内存/空闲期自发死亡；代理层把死亡伪装成 502；CLI 无感知、无自愈。
+# 方案：pid 文件 + 健康探针（system.listMethods）+ call/methods 前 ensure 自动拉起。
+# 注意：urllib 必须绕过代理（N41：HTTP_PROXY 注入会让 127.0.0.1 请求走代理转发失败）。
+
+def _rpc_state_dir():
+    d = os.environ.get(
+        "TBTOOLS_RPC_DIR",
+        os.path.join(os.path.expanduser("~"), ".config", "tbtools-cli"),
+    )
+    os.makedirs(d, exist_ok=True)
+    return d
+
+def _rpc_pid_file(port):
+    return os.path.join(_rpc_state_dir(), f"rpc-{port}.pid")
+
+def _rpc_log_file(port):
+    return os.path.join(_rpc_state_dir(), f"rpc-{port}.log")
+
+def _rpc_ping(port, timeout=5):
+    """健康探针：POST system.listMethods。绕过代理。返回 True/False"""
+    try:
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        req = urllib.request.Request(
+            f"http://127.0.0.1:{port}/rpc",
+            data=json.dumps({"jsonrpc": "2.0", "method": "system.listMethods",
+                             "params": {}, "id": 1}).encode(),
+            headers={"Content-Type": "application/json"})
+        resp = opener.open(req, timeout=timeout)
+        result = json.loads(resp.read())
+        return "result" in result
+    except Exception:
+        return False
+
+def _rpc_read_pid(port):
+    """读 pid 文件；进程不存在或与 RPC 无关则清理并返回 None"""
+    pid_file = _rpc_pid_file(port)
+    try:
+        with open(pid_file) as f:
+            pid = int(f.read().strip())
+    except Exception:
+        return None
+    try:
+        os.kill(pid, 0)
+    except (ProcessLookupError, PermissionError, OverflowError, ValueError):
+        _rpc_remove_pid(port)
+        return None
+    # Linux 下确认 cmdline 是 RPC server（防 pid 复用误杀）
+    cmdline = f"/proc/{pid}/cmdline"
+    if os.path.isfile(cmdline):
+        try:
+            with open(cmdline, "rb") as f:
+                if b"biocjava.rpc.RpcServer" not in f.read():
+                    _rpc_remove_pid(port)
+                    return None
+        except Exception:
+            pass
+    return pid
+
+def _rpc_write_pid(port, pid):
+    with open(_rpc_pid_file(port), "w") as f:
+        f.write(str(pid))
+
+def _rpc_remove_pid(port):
+    try:
+        os.remove(_rpc_pid_file(port))
+    except OSError:
+        pass
+
+def _rpc_launch(port, mem):
+    """拉起 RPC 服务器（detached，OOM 崩溃转储，日志落盘）。返回 Popen"""
+    if not JAR or not os.path.isfile(JAR):
+        raise FileNotFoundError(
+            "TBtools jar 未找到。请设置 TBTOOLS_JAR 环境变量或放入常见位置")
+    log_path = _rpc_log_file(port)
+    log_fh = open(log_path, "ab", buffering=0)
+    args = [
+        "java", f"-Xmx{mem}",
+        # N35: OOM 时宁可崩溃（可自愈拉起）也不要僵尸悬挂；同时留堆转储供排查
+        "-XX:+CrashOnOutOfMemoryError",
+        "-XX:+HeapDumpOnOutOfMemoryError",
+        f"-XX:HeapDumpPath={_rpc_state_dir()}",
+        "-cp", JAR, "biocjava.rpc.RpcServer",
+    ]
+    proc = subprocess.Popen(
+        args, stdout=log_fh, stderr=log_fh, start_new_session=True)
+    _rpc_write_pid(port, proc.pid)
+    return proc
+
+def _ensure_rpc(port, mem="4g", wait_s=30, quiet=False):
+    """ensure 逻辑（同交付包 run_p*.py 的 ensure_srv）：
+    健康 → True；不健康/死亡 → 清 stale pid → 拉起 → 轮询健康。"""
+    if _rpc_ping(port):
+        return True
+    old_pid = _rpc_read_pid(port)
+    if old_pid:
+        if not quiet:
+            click.echo(f"⚠️ 检测到旧 RPC 进程 (PID {old_pid}) 无响应，终止后拉起新实例...", err=True)
+        try:
+            os.kill(old_pid, 15)
+        except OSError:
+            pass
+        _rpc_remove_pid(port)
+        _t.sleep(1)
+    elif not quiet:
+        click.echo(_tr("⚠️ RPC 服务器不可达（端口 {p}），自动拉起...", "⚠️ RPC server unreachable (port {p}) — auto-restarting...").format(p=port), err=True)
+    try:
+        _rpc_launch(port, mem)
+    except FileNotFoundError as e:
+        click.echo(f"❌ {e}", err=True)
+        return False
+    for _ in range(wait_s):
+        _t.sleep(1)
+        if _rpc_ping(port):
+            return True
+    click.echo(_tr("❌ RPC 服务器 {s}s 内未就绪，日志: {log}", "❌ RPC server not ready within {s}s, log: {log}").format(s=wait_s, log=_rpc_log_file(port)), err=True)
+    return False
+
+@rpc_group.command('start')
+@click.option('--port', '-p', type=int, default=8765, help='RPC 端口')
+@click.option('--mem', '-m', default='4g', help='Java 堆内存')
+@click.option('--force', '-f', is_flag=True, help='强制重启（杀掉已有实例）')
+def rpc_start(port, mem, force):
+    """启动 RPC 服务器（pid 文件 + 健康检查；已在跑则幂等返回）"""
+    if _rpc_ping(port):
+        if not force:
+            pid = _rpc_read_pid(port)
+            click.echo(_tr("✅ RPC 服务器已在运行（端口 {p}, PID {pid}）", "✅ RPC server already running (port {p}, PID {pid})").format(p=port, pid=pid or '?'))
+            return
+        old = _rpc_read_pid(port)
+        click.echo(f"🔄 --force：终止旧实例 (PID {old or '?'})...")
+        if old:
+            try:
+                os.kill(old, 15)
+            except OSError:
+                pass
+        _rpc_remove_pid(port)
+        _t.sleep(1)
+    else:
+        # 清 stale（引擎自发死亡残留）
+        old = _rpc_read_pid(port)
+        if old:
+            click.echo(f"⚠️ 旧 RPC 进程 (PID {old}) 无响应，终止...")
+            try:
+                os.kill(old, 15)
+            except OSError:
+                pass
+            _rpc_remove_pid(port)
+        _t.sleep(1)
+    click.echo(_tr("🚀 启动 RPC 服务器（端口 {p}，堆 {m}）...", "🚀 Starting RPC server (port {p}, heap {m})...").format(p=port, m=mem))
+    try:
+        proc = _rpc_launch(port, mem)
+    except FileNotFoundError as e:
+        click.echo(f"❌ {e}", err=True)
+        sys.exit(1)
+    for _ in range(30):
+        _t.sleep(1)
+        if _rpc_ping(port):
+            click.echo(f"✅ RPC 服务器就绪 (PID {proc.pid})")
+            click.echo(f"   pid 文件: {_rpc_pid_file(port)}")
+            click.echo(f"   日志: {_rpc_log_file(port)}")
+            click.echo(f"   测试: curl -X POST http://127.0.0.1:{port}/rpc -H 'Content-Type: application/json' -d '{{\"method\":\"system.listMethods\",\"params\":{{}},\"id\":1}}'")
+            return
+    click.echo(f"❌ 启动超时（30s），日志: {_rpc_log_file(port)}", err=True)
+    sys.exit(1)
+
+
+@rpc_group.command('logs')
+@click.option('--tail', 'n', type=int, default=50, help='显示末尾 N 行(0=全部)')
+@click.option('--port', default=8765, help='RPC 端口')
+def logs(n, port):
+    """查看 RPC 服务器日志(尾部 N 行;0=全部)"""
+    import os as _os
+    log = _rpc_log_file(port)
+    if not _os.path.isfile(log):
+        click.echo(f"❌ 无日志文件(服务器未启动过?): {log}", err=True)
+        sys.exit(1)
+    if n <= 0:
+        click.echo(open(log, encoding="utf-8", errors="replace").read())
+    else:
+        lines = open(log, encoding="utf-8", errors="replace").read().splitlines()
+        click.echo("\n".join(lines[-n:]))
+
+@rpc_group.command('stop')
+@click.option('--port', '-p', type=int, default=8765, help='RPC 端口')
+def rpc_stop(port):
+    """停止 RPC 服务器"""
+    pid = _rpc_read_pid(port)
+    if not pid:
+        click.echo(f"RPC 服务器未在运行（端口 {port}）")
+        _rpc_remove_pid(port)
+        return
+    try:
+        os.kill(pid, 15)
+        click.echo(_tr("✅ 已发送 SIGTERM (PID {p})", "✅ SIGTERM sent (PID {p})").format(p=pid))
+    except OSError as e:
+        click.echo(f"❌ 终止失败: {e}", err=True)
+        sys.exit(1)
+    _rpc_remove_pid(port)
+
+@rpc_group.command('status')
+@click.option('--port', '-p', type=int, default=8765, help='RPC 端口')
+def rpc_status(port):
+    """查看 RPC 服务器状态"""
+    pid = _rpc_read_pid(port)
+    healthy = _rpc_ping(port)
+    if healthy:
+        click.echo(f"✅ 运行中（端口 {port}, PID {pid or '?'}）")
+    elif pid:
+        click.echo(f"⚠️ 进程存在 (PID {pid}) 但健康检查失败（可能正在启动或假死）")
+        sys.exit(2)
+    else:
+        click.echo(f"❌ 未运行（端口 {port}）。启动: tbtools rpc start")
+        sys.exit(1)
+
+@rpc_group.command('methods')
+@click.option('--port', '-p', type=int, default=8765, help='RPC 端口')
+@click.option('--mem', '-m', default='4g', help='--autostart 时的 Java 堆内存')
+@click.option('--autostart', is_flag=True, help='服务不可达时自动拉起(默认不启动进程——发现操作应 side-effect free)')
+def rpc_methods(port, mem, autostart):
+    """列出全部 188 RPC 方法（默认静态发现, 不启动服务器; --autostart 时自动拉起）"""
+    if autostart and not _ensure_rpc(port, mem):
+        click.echo("   手动启动: tbtools rpc start", err=True)
+        sys.exit(1)
+    try:
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        req = urllib.request.Request(
+            f"http://127.0.0.1:{port}/rpc",
+            data=json.dumps({"jsonrpc": "2.0", "method": "system.listMethods", "params": {}, "id": 1}).encode(),
+            headers={"Content-Type": "application/json"})
+        resp = opener.open(req, timeout=15)
+        result = json.loads(resp.read())
+        res = result.get('result', [])
+        methods = res.get('methods', res) if isinstance(res, dict) else res
+        click.echo(f"RPC 方法（{len(methods)} 个）：")
+        for m in methods:
+            click.echo(f"  {m}")
+    except Exception as e:
+        click.echo(f"❌ RPC 调用失败: {e}", err=True)
+        click.echo("   引擎可能已死，尝试: tbtools rpc start --force", err=True)
+        sys.exit(1)
+
+@rpc_group.command('call')
+@click.argument('method')
+@click.argument('params', required=False)
+@click.option('--port', '-p', type=int, default=8765, help='RPC 端口')
+@click.option('--mem', '-m', default='4g', help='自动拉起时的 Java 堆内存')
+@click.option('--timeout', '-t', type=int, default=300, help='调用超时（秒）')
+@click.option('--no-autostart', is_flag=True, help='禁用在不可达时自动拉起')
+def rpc_call(method, params, port, mem, timeout, no_autostart):
+    """调用 RPC 方法（服务不可达时自动拉起）"""
+    params_obj = json.loads(params) if params else {}
+    if not no_autostart and not _ensure_rpc(port, mem):
+        click.echo("   手动启动: tbtools rpc start", err=True)
+        sys.exit(1)
+    try:
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        req = urllib.request.Request(
+            f"http://127.0.0.1:{port}/rpc",
+            data=json.dumps({"jsonrpc": "2.0", "method": method, "params": params_obj, "id": 1}).encode(),
+            headers={"Content-Type": "application/json"})
+        resp = opener.open(req, timeout=timeout)
+        result = json.loads(resp.read())
+        if result.get('error'):
+            # N38: 引擎错误 message 空/占位符时补友好提示（GffReconstructorBatch 等家族）
+            err = result['error']
+            msg = str(err.get('data', {}).get('message') if isinstance(err.get('data'), dict) else err.get('data') or err.get('message') or '')
+            if not msg.strip() or msg.strip() == '===== See Following Info =====' or msg.startswith('Something Error'):
+                msg = '引擎内部错误且未提供消息（N38 家族，GffReconstructorBatch/BestIdConverter/ReciprocalBlast 已知）'
+                click.echo(f"❌ RPC 错误 [{err.get('code')}]: {msg}（原始: {json.dumps(err, ensure_ascii=False)[:200]}）", err=True)
+            else:
+                click.echo(f"❌ RPC 错误 [{err.get('code')}]: {msg}", err=True)
+            sys.exit(1)
+        click.echo(json.dumps(result.get('result', ''), indent=2, ensure_ascii=False))
+    except Exception as e:
+        click.echo(f"❌ RPC 调用失败: {e}", err=True)
+        sys.exit(1)
+
+
+def build_rpc_group():
+    """构建 rpc 分组（由主 CLI 注册）"""
+    return rpc_group