液体活检方法顾问（中文）¶

方法顾问帮助用户针对数据集或研究问题选择液体活检分析工具，包括成熟工具、外部运行环境和明确标记的研究/观察列表方法。它不是黑箱分类器，而是比较检测到的输入文件、用户目标、本地依赖可用性、外部环境状态和安全内部回退路径。

项目范围内全部可调用内部工作流、编码器、外部运行环境、LLM 引擎和数据类型见能力矩阵。安装/冒烟/运行详情见外部工具运行环境。

当问题涉及分析方法、算法、外部工具，或片段组学、甲基化、拷贝数分析、变异检测、cfRNA、小 RNA、CTC 表和血浆蛋白组学等检测专用路径时使用。

使用方式¶

交互式 Shell：

/methods fragmentomics CNV methylation
/methods check low-pass cfDNA WGS copy number
/methods run which tools should I use for cfMeDIP and fragmentomics?

自然语言：

What mature tools should I consider for fragmentomics, methylation, and CNV in this dataset?

Check whether this folder is better suited for cfDNAPro, FinaleToolkit, WisecondorX, QSEA, Bismark, cfTools, or variant calling.

CLI：

liquid-agent methods --input <dataset_or_subdir> --query "fragmentomics CNV methylation"

写入 JSON 和 Markdown 报告：

liquid-agent methods \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output-dir <output_dir>

脚本形式：

python scripts/run_liquid_biopsy_method_advisor.py \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output_dir <output_dir>

Python API：

from liquidbiopsy_agent.methods import recommend_liquid_biopsy_methods, write_method_advice_report

advice = recommend_liquid_biopsy_methods(
    input_path="<dataset_or_subdir>",
    query="fragmentomics CNV methylation",
)
summary = write_method_advice_report(
    output_dir="<output_dir>",
    input_path="<dataset_or_subdir>",
    query="fragmentomics CNV methylation",
)

本地 Web API：

GET /api/methods?query=fragmentomics%20CNV%20methylation
POST /api/session/{session_id}/methods/advice

报告内容¶

顾问写入：

liquid_biopsy_method_advice.json
liquid_biopsy_method_advice.md

报告包含：

匹配方法名称和评分
每种方法的选择理由
预期输入文件
预期输出
本地依赖状态
缺失可选工具的安装提示
安全内部回退路径
每个方法家族的参考资料

输出属于建议。除非后续执行任务实际运行了外部方法，否则不声称它已经运行。

外部运行环境层¶

对于选定工具，方法顾问连接外部运行环境管理器。相同工具状态可通过以下命令查看：

liquid-agent tools status
liquid-agent tools status --tool purecn --json
liquid-agent tools install purecn --execute
liquid-agent tools smoke purecn

顾问在方法输出中使用这些运行环境状态：

external_runtime_ready：运行环境及所需资源存在
external_runtime_installed：运行环境、源码检出、可执行文件、Python 模块或 R 包在本地存在，当前未报告方法专用资源缺失
external_runtime_needs_resources：部分运行环境已安装，但真实分析仍需数据、模型、参考或工作流资源
missing_external_tools：无可调用运行环境
reimplementation_candidate：上游代码有用，但对普通用户过旧或不稳定；优先使用内部替代或维护中的现代工具

示例：

PureCN 和 FACETS core 可安装到隔离 R/conda 环境，但真实分析需要覆盖表、正常样本资源或 SNP pileup。
modkit 可通过纳米孔甲基化路径安装和调用，Dorado 碱基识别及 ONT 模型资源仍需用户显式提供。
CopywriteR 在 macOS arm64 环境中被列为重新实现候选，因为可用 conda 构建依赖旧 R/Bioconductor 栈，无法顺利解析；Liquid Agent 包含保守内部 copywriter-proxy，用于首轮非靶向区域/分箱计数 CNV 筛查。

支持的方法家族¶

家族	跟踪方法	典型输入	内部回退或当前项目路径
片段组学	FinaleToolkit, cfDNAPro, DELFI-style features, Griffin, LIQUORICE, LBFextract, cfDNAFE, cfDNAanalyzer, EMIT, DeepFRAG	双端 cfDNA WGS BAM/CRAM、片段文件、区域表、末端基序/片段长度矩阵	原始信号数值与可视化套件；适合时的 BED 队列流水线
广泛 cfDNA WGS/WGBS 工作流	cfDNApipe, cfDNA UniFlow	FASTQ/BAM 加参考资源	不需完整外部流水线时，使用模块化预处理、原始信号、CNV 和甲基化汇总
拷贝数	ichorCNA, QDNAseq, WisecondorX, HMMcopy readcount correction, CNVkit, Control-FREEC, CopywriteR, FACETS/facetsSuite, PureCN, BayesCNV	LPWGS/ULPWGS BAM、WIG/read-count 分箱、CNV 表、较高覆盖 WGS/WES/panel BAM	LPWGS 预处理、分段、染色体臂负荷、CNV 汇总，以及首轮非靶向区域/分箱计数筛查 `copywriter-proxy`
甲基化富集	QSEA, MEDIPS	cfMeDIP/MeDIP BAM、富集窗口、CpG 资源	表观基因组预处理、区域信号汇总、甲基化感知编码
亚硫酸氢盐 / EM-seq / 纳米孔甲基化	Bismark, MethylDackel, nf-core/methylseq, Dorado + modkit	FASTQ、已比对甲基化 BAM/CRAM、纳米孔 POD5/FAST5 或修饰碱基 BAM	外部检测后汇总生成的甲基化表
甲基化去卷积与高级模型	FinaleMe, cfTools/cfSort, MethylBERT, cfDecon, CelFiE-ISH, CelFEER, UXM, MethAtlas, cfNOMe, MetDecode, CpGPT, MethylGPT, MethFormer, cfMethylPre	WGBS/cfMethyl-Seq 甲基化结果、read 级甲基化模式、标志/参考图谱、甲基化矩阵	兼容外部输入就绪前，采用内部甲基化汇总和元数据感知审阅
ctDNA 变异	fgbio UMI consensus, Mutect2, LoFreq, VarDict	带 UMI 的 BAM/FASTQ、VCF、MAF、变异表	变异预处理、VAF 汇总，注释存在时的效应谱型聚合
cfRNA	Salmon, STAR, featureCounts	cfRNA FASTQ 或计数矩阵	方法指导与用户提供矩阵审阅
EV-miRNA / 小 RNA	sRNAbench, miRge-style routes	小 RNA FASTQ 或 miRNA 计数矩阵	方法指导与用户提供矩阵审阅
CTC 表	Scanpy, Seurat, CellTypist-style downstream analysis	CTC 计数表、标志物表、h5ad/RDS 输出	表格级汇总与专家指导解释
血浆或 EV 蛋白组学	DIA-NN, MaxQuant, OpenMS-style upstream workflows	mzML/厂商原始文件或丰度矩阵	输入矩阵汇总与元数据感知审阅

选择规则¶

顾问有意区分三个问题：

Liquid Agent 能否直接分析提供的文件？
哪些外部工具或研究方法适合更深入的检测专用分析？
外部依赖缺失时，现在应运行哪条安全内部路径？

这使自动运行保持实用。例如低深度 cfDNA WGS 文件夹未配置 ichorCNA 资源时，智能体仍可运行 LPWGS 预处理和 CNV 负荷汇总，将 ichorCNA 报告为推荐的深入后续，而不是假装已估算肿瘤比例。

智能体集成¶

助手可在三处纳入方法建议：

规划时：数据集包含相关液体活检文件类型
自动运行时：方法建议有用且报告尚不存在
审阅时：需要将已有输出与方法建议一起总结

端到端运行中，方法顾问不应阻塞可行内部分析。它应记录哪些方法成熟、哪些本地可用、缺什么，以及智能体改做了什么。

依赖语义¶

需求状态值按保守原则解释：

ready：必需外部工具本地可用
ready_with_optional_gaps：必需工具存在，可选辅助工具缺失
partial：至少一项需求可用，但方法尚未完全就绪
missing_external_tools：外部工具本地不可用
internal_or_guidance_only：建议条目不需要外部依赖
external_runtime_ready：外部运行环境包装器和所需资源全部存在
external_runtime_installed：外部包装器在本地存在，当前未报告方法资源缺失
external_runtime_needs_resources：外部包装器或源码检出存在，但方法资源仍不完整

缺少可选工具不视为失败，而是附安装提示和内部回退路径报告。

部分方法还需要参考 panel、模型文件或专用代码包等手动资源。用户显式配置前，顾问将其报告为不完整；不能仅因本地有 Java、R 或 Python 等通用运行环境就标记方法完全可运行。

跨语言执行约束¶

许多成熟液体活检工具不是 Python 包。因此，除非已有专用本地包装器，否则 Liquid Agent 将其视为外部运行环境。

PureCN、FACETS 等 R/Bioconductor 方法尽可能使用隔离 conda R 环境；QDNAseq、HMMcopy、QSEA、MEDIPS 和 cfTools 在添加专用包装器前仍属方法指导条目。
FinaleToolkit、CNVkit、modkit 等命令行工具与 Snakemake 工作流通过配置环境中的可执行文件发现来检查。
FinaleMe 等 Java 或手动下载方法，以及若干图谱/模型去卷积工具，需要显式 manual_resource 配置。
MethylBERT、CpGPT、MethylGPT、cfDecon、CelFEER、UXM、EMIT、DeepFRAG 等具有代码/模型检查点的研究模型，可以已有源码/运行包装器，但在检查点、图谱和输入格式资源就绪前仍为 ready=False。MethFormer 当前是模型资源指导，不是注册的可执行包装器。

这意味着智能体可以推荐 R、Java、Snakemake 或深度学习方法，但只有必需运行环境和方法资源存在、且执行任务实际调用后，才可声称已运行。检查失败时，应继续安全内部汇总，并将外部方法作为后续建议。