返回 Liquid Agent 首页使用文档

外部工具运行环境（中文）¶

Liquid Agent 现在可为不属于主 Python 内核的液体活检方法管理专门的外部工具层。此层有意与默认环境分离：严格固定版本的 Python 包、R/Bioconductor 包、Snakemake 工作流、仅有源码的研究代码和系统二进制尽可能在隔离运行环境中安装或检查。

当某个方法不只是建议，而需要确认 Liquid Agent 能否实际调用其运行环境时，使用本页。

CLI¶

显示全部注册外部运行环境：

liquid-agent tools status

以 JSON 显示单个运行环境：

liquid-agent tools status --tool purecn --json

常见稳定运行环境的一键准备：

liquid-agent tools bootstrap
liquid-agent tools bootstrap --execute

准备所有可自动安装运行环境：

liquid-agent tools bootstrap --profile all
liquid-agent tools bootstrap --profile all --execute

安装器试运行：

liquid-agent tools install purecn

执行安装器：

liquid-agent tools install purecn --execute

运行冒烟测试：

liquid-agent tools smoke purecn

通过包装器运行命令：

liquid-agent tools run cnvkit -- cnvkit.py --help
liquid-agent tools run purecn -- Rscript -e "library(PureCN); packageVersion('PureCN')"
liquid-agent tools run dorado_modkit -- modkit --version

写入状态报告：

liquid-agent tools status --output-dir <output_dir>

写入文件：

liquid_biopsy_external_tool_status.json
liquid_biopsy_external_tool_status.md

状态含义¶

字段	含义
`installed`	运行环境、源码检出、可执行文件、Python 模块或 R 包可通过 Liquid Agent 在本地调用。
`ready`	已安装运行环境，且所有数据专用资源已配置，包括模型检查点、参考 panel、清单或真实输入文件。
`auto_installable`	Liquid Agent 对当前运行环境类别有自动安装/准备路径。
`reimplementation_candidate`	原工具有价值但无法顺利安装；应优先小型内部替代或现代重新实现，而非让普通用户调试旧依赖。
`compatibility_proxy_*`	对适合在主 Python 运行时安全复现的实用子集，已有 Liquid Agent 内部实现。

运行环境可以 installed=True 且 ready=False，这很正常。例如 PureCN 可已安装并通过冒烟，但真实分析仍需要区间覆盖表和正常数据库资源。

用户无需手动激活隔离 conda 环境。Liquid Agent 从主进程通过 conda run -n liquid_tool_purecn ... 等包装器运行外部命令。

注册的运行环境类别¶

类别	示例	Liquid Agent 处理方式
隔离 Python 环境	MethylBERT, CNVkit, FinaleToolkit, MetDecode, BayesCNV, CpGPT, MethylGPT	创建专用 conda 环境，检查 Python 模块或 CLI 命令。
源码检出	cfDecon, CelFEER, UXM, MethAtlas, cfNOMe, cfDNAFE, EMIT, DeepFRAG	将源码克隆到 `~/.liquidbiopsy_agent/external_tools/src`，安全时运行注册的冒烟命令。
Snakemake 工作流	cfDNA UniFlow	克隆工作流，在隔离环境安装 Snakemake；真实运行需工作流配置和参考。
隔离 R/Bioconductor 环境	PureCN, FACETS core	创建专用 conda R 环境，验证 `Rscript` 和 R 包加载。
系统二进制包装器	纳米孔甲基化 modkit 路径	可用时安装/调用 modkit；Dorado 碱基识别仍需用户提供二进制/模型资源。
重新实现候选	macOS arm64 上的 CopywriteR	保持方法可见，记录旧安装失败原因，引导使用内部 CNV 替代或维护中的现代 CNV 方法。

当前高价值工具¶

信号	运行环境/工具	当前项目处理
片段组学	FinaleToolkit	隔离 Python CLI/运行环境。
片段组学	cfDNAFE	源码检出，兼容时可调用源码 CLI。
片段组学	cfDNA UniFlow	Snakemake 工作流包装器；真实运行需配置/参考资源。
片段组学	EMIT	源码/模型检出；真实运行需 EMIT 格式末端基序数据。
片段组学	DeepFRAG	源码检出；真实监督使用需标签、模型资源和验证设计。
甲基化	MethylBERT	隔离 Python 运行环境；真实使用需训练检查点和 read 级甲基化输入。
甲基化	cfDecon, CelFEER, UXM, MethAtlas, cfNOMe	源码检出；真实运行需图谱/标志物/参考资源。
甲基化	MetDecode	隔离 Python/源码环境；真实运行需标志区域甲基化/总 CpG 计数与参考 panel。
甲基化	CpGPT, MethylGPT	隔离 Python/源码环境；真实运行需兼容检查点与矩阵。
甲基化	Dorado + modkit	modkit 可安装/调用；Dorado 二进制/模型和纳米孔输入仍为明确前提。
CNV	CNVkit	隔离 Python CLI/运行环境。
CNV	PureCN	隔离 R/Bioconductor 环境；真实运行需覆盖度/正常样本/VCF 资源。
CNV	FACETS core	核心 FACETS 的隔离 R 环境；完整等位基因特异性工作流需 SNP pileup 或平台专用辅助工具。
CNV	BayesCNV	JAX/numpyro 组件的隔离 Python/源码环境。
CNV	CopywriteR	在 macOS arm64 上旧安装不可靠；列为重新实现候选，并提供内部 CopywriteR 类 CNV 替代。

内部兼容替代实现¶

部分有用研究工具绑定旧 Python、旧 R/Bioconductor 或平台特定运行假设。上游实现足够小、开源且算法明确时，Liquid Agent 可提供现代内部替代，而不要求用户修复旧环境。

当前替代：

liquid-agent copywriter-proxy \
  --input <interval_or_bin_dir> \
  --output-dir <output_dir> \
  --exclude-regions <targets_or_peaks.bed>

此替代用于首轮 CopywriteR 类非靶向区域/分箱计数 CNV 筛查，执行区间分箱、可选靶区/峰排除、深度标准化、稳健增益/缺失检测和简单分段汇总。它不是原始 CopywriteR 工作流的完整移植；发表级分析仍应对照原方法，或 CNVkit、PureCN、FACETS、LPWGS 专用路径等维护中的现代 CNV 工作流验证。

既有工具或旧 Python 工具¶

有用方法若依赖旧 Python、旧 R/Bioconductor 或平台专用二进制，Liquid Agent 会记录安装限制，并引导用户使用可用的内部替代或维护中的现代工具。替代命令会明确说明适用范围，不声称与上游完整实现完全等同。