scientific-agent-skills 实战指南：用 Nextflow 可复现地运行 nf-core 与自定义流水线

scientific-agent-skills 实战指南：用 Nextflow 可复现地运行 nf-core 与自定义流水线

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本指南以仓库scientific-agent-skills中 nextflow 技能包 的 running-pipelines.md 为核心，系统讲解如何查找、启动、配置与排错 nf-core 流水线及自定义 Nextflow 工作流。读完你将掌握：标准运行模式（test冒烟测试 + 正式运行）、samplesheet 输入约定、-params-file参数管理、容器与 profile 选择、iGenomes 参考基因组、机构级配置、离线/隔离环境运行，以及基于.nextflow.log、-resume与报告文件的监控排错方法。

从哪开始：在 nf-core 生态中查找流水线

nf-core 是一个社区维护的 Nextflow 流水线仓库，提供了大量面向生物学与生信分析的生产级工作流。运行任何流水线之前，第一步是找到合适的流水线并了解其参数契约。nf-core tools（v3+ 将子命令分组在pipelines/modules/subworkflows下）提供了专门的检索命令：

nf-core pipelines list # 列出全部 nf-core 流水线，按活跃度排序 nf-core pipelines list rna # 按关键词搜索（如 rna） nf-core pipelines info rnaseq # 查看某条流水线的详细信息

nf-core pipelines list支持--json输出与--sort排序；每条流水线的官方页面会文档化其参数、samplesheet 格式与输出目录。在本仓库中，tests/skill-requirements.toml 的[skills.nextflow]一节声明了packages = ["nf-core"]，意味着该技能运行环境的基准依赖就是 nf-core 工具链；完整的nf-coreCLI 参考（包括pipelines create/launch/download/lint/schema、modules install/create/test、subworkflows install等命令）见 nf-core-tools.md。

标准运行模式：从冒烟测试到正式运行

无论运行哪条 nf-core 流水线，都遵循同一个两步模式：

第 1 步：用内置小数据集冒烟测试环境。testprofile 附带微型测试数据，用于快速验证 Nextflow 引擎、容器引擎与网络通路是否正常：

nextflow run nf-core/rnaseq -r 3.14.0 -profile test,docker --outdir test_results

第 2 步：正式运行。固定版本（-r）、选择容器引擎、提供 samplesheet：

nextflow run nf-core/<pipeline> \ -r <version> \ # 固定 release，保证可复现 -profile docker \ # 或 singularity / conda --input samplesheet.csv \ # 要处理的样本 --outdir results \ # 结果输出目录（nf-core 强制要求） -resume # 重跑时复用缓存

要点说明：

• nextflow run nf-core/rnaseq会自动从 GitHub 拉取流水线到~/.nextflow/assets（即$NXF_HOME/assets）。也可以先用nextflow pull nf-core/rnaseq预取/更新，再用-r固定到某个 tag。
• -profile（单横线）选择配置文件，--input/--genome/--outdir（双横线）是流水线自身参数，二者含义不同。本技能的 SKILL.md 中同样强调：容器/基础设施类 profile（docker、singularity、conda）互斥，一次只能选一个。
• -resume复用上一次运行的缓存结果；-r <version>固定 release 以实现可复现。

交互式命令构建器：nf-core pipelines launch

与其手工拼接长命令，不如让工具按 schema 逐项引导。nf-core pipelines launch会遍历流水线的每一个参数（依据其nextflow_schema.json校验），并写出可复用的nf-params.json：

nf-core pipelines launch nf-core/rnaseq nextflow run nf-core/rnaseq -profile docker -params-file nf-params.json

从源码结构看，该命令由nextflow_schema.json驱动——nextflow_schema.json是描述流水线全部参数的 JSON-Schema 文件，它同时支撑 CLI/-params-file校验（经由nf-schema插件）、nf-core pipelines launch的图形化引导与自动文档生成（见 developing.md）。

Samplesheets：流水线的输入契约

nf-core 流水线通过--input接收一个CSV samplesheet，而不是零散文件——这让样本元数据显式化、可审计。具体列名因流水线而异（以各流水线文档为准），典型 RNA-seq 表：

sample,fastq_1,fastq_2,strandedness CONTROL_REP1,s3://.../ctrl_1.fastq.gz,s3://.../ctrl_2.fastq.gz,auto TREAT_REP1,/data/treat_1.fastq.gz,/data/treat_2.fastq.gz,auto

约定与行为：

• 单端数据将fastq_2留空即可。
• 路径可以是本地路径，也可以是远程 URI（S3/GCS/https），Nextflow 会自动 stage 数据。
• 校验由nf-schema/nf-validation插件完成，列或值错误时会快速失败并给出清晰报错。在开发侧，samplesheet 本身由流水线assets/目录下的 schema（如assets/schema_input.json）约束（见 developing.md）。

参数与 params 文件：让命令行可复现、可评审

参数有三种传递方式，后者覆盖前者：config 文件 → -params-file → --cli 标志。凡是稍微复杂的运行，都建议用params 文件——它可复现、可评审、可纳入版本控制：

nf-core pipelines create-params-file nf-core/rnaseq # 生成带文档注释的 YAML nextflow run nf-core/rnaseq -profile docker -params-file params.yml --outdir results

# params.yml input: samplesheet.csv outdir: results genome: GRCh38 aligner: star_salmon

配套背景：在 configuration.md 中，nextflow.config的加载与合并遵循递增优先级——$NXF_HOME/config（~/.nextflow/config）→ 项目目录的nextflow.config→ 启动目录的nextflow.config→ 每个-c custom.config（可重复），而 CLI--param/-params-file覆盖 config 中的参数；如果改用-C file则只加载该文件、忽略其他所有来源。这一优先级模型解释了为何-params-file天然拥有高于 config 的覆盖权。

Profiles 与容器：环境选择的原则

• 容器引擎只选一个：-profile docker（本地/CI）、-profile singularity（HPC）、-profile conda（最后手段）。
• testprofile：内置小数据集，必须与某个引擎组合使用，例如-profile test,docker。
• profile 可以逗号分隔组合，顺序有影响（后者生效）；再用-c custom.config叠加站点级配置，用withName选择器做单进程微调（详见 configuration.md）。

本技能包对容器引擎的取舍有更系统的说明（containers.md）：Docker 适合本地开发/CI；Singularity/Apptainer 适合无 root、共享文件系统的 HPC 集群（学术圈最常见）；Conda/Mamba 是最不具可复现性的方案（求解器漂移、无 OS 隔离），发布科研成果时优先用容器。同时务必注意两个常见陷阱：同时启用两个引擎会报错或产生意外行为；Docker 产生 root 属主输出文件时需设置runOptions = '-u $(id -u):$(id -g)'。

参考基因组与 iGenomes：用与不用

许多流水线接受--genome <KEY>（如GRCh38、GRCm38、R64-1-1），并自动从 AWS iGenomes 拉取参考数据。备选方案：

• 自行提供参考：显式传入--fasta、--gtf、--star_index等参数——为了控制和可复现性，这是推荐做法；加--save_reference可保留构建好的索引供复用。
• 本地镜像 iGenomes：设置--igenomes_base指向本地路径，用于离线使用。
• 彻底关闭 iGenomes 逻辑：--igenomes_ignore。

陷阱提示：AWS iGenomes 的注释数据明显过时（人类 GTF 大约停留在 Ensembl release 75 / 2015 年），且其 GRCh38 来自NCBI，而非软屏蔽（soft-masked）的 Ensembl 组装。若要使用最新或软屏蔽参考，请自行提供--fasta/--gtf。

机构级配置：直接对接 HPC 与云

nf-core/configs 为许多 HPC 系统和云环境提供了现成 profile（executor、队列、容器缓存、资源限制）。使用方式：

nextflow run nf-core/rnaseq -profile crick,singularity

Nextflow 会从中心仓库自动拉取该机构配置。自定义机构配置的完整选项参考本仓库的 configuration.md——其中 executors 一节覆盖了local（默认）、slurm、sge/uge、lsf、pbs/pbspro、awsbatch、google-batch、azurebatch、k8s等平台，并给出 SLURM 示例（process.executor = 'slurm'+queue+clusterOptions，以及executor.queueSize/submitRateLimit节流参数）。若要指向本地或私有配置仓库（离线场景），用--custom_config_base。

离线 / 隔离（air-gapped）环境运行

在无外网的科学计算环境（如涉密或内网 HPC）运行流水线，需要预先打好"流水线 + 配置 + 容器"三件套：

# 在有网的机器上：打包流水线、配置与容器 nf-core pipelines download nf-core/rnaseq \ --revision 3.14.0 \ --container-system singularity \ # 预先将镜像转为 SIF --compress none \ --outdir nf-core-rnaseq # 传输整个目录后，在离线机器上： export NXF_OFFLINE=true export NXF_SINGULARITY_CACHEDIR=/shared/sif nextflow run nf-core-rnaseq/3_14_0 -profile singularity --input ... --outdir results

更精细的做法（避免把镜像复制进包内，改而共享镜像缓存）：设置$NXF_SINGULARITY_CACHEDIR并传--container-cache-utilisation amend。同时还应：预置参考基因组并设置对应--*_index/igenomes_base参数、固定所有插件版本、export NXF_OFFLINE=true。与离线相关的环境变量在 configuration.md 中有完整清单（NXF_OFFLINE=true禁用网络调用、NXF_SINGULARITY_CACHEDIR/NXF_APPTAINER_CACHEDIR指定 SIF 缓存目录、NXF_CONDA_CACHEDIR缓存 conda 环境）。在 HPC 上务必设置共享的NXF_SINGULARITY_CACHEDIR，让所有作业复用镜像拉取，避免"拉取风暴"与配额爆掉。

监控与排错：一次失败运行的标准处置流程

• 日志：每次运行会在终端打印实时的任务表（live task table）；完整的.nextflow.log位于启动目录。任务失败时，错误信息会给出该任务的工作目录（work dir），进入其中检查.command.sh、.command.out、.command.err与.exitcode四个文件即可定位失败原因。
• Resume：修复问题后加-resume重跑，跳过已成功的任务。其缓存机制是：每个任务对输入（文件内容/元数据）、脚本文本、容器与关键指令求哈希，哈希未变则复用缓存输出（详见 configuration.md 的缓存调试章节，可用nextflow log <run> -f hash,name,status,workdir检查任务，或对比两次运行的cache hash）。
• 报告：加-with-report -with-trace -with-timeline分别产出资源占用 HTML 报告、逐任务 tab 分隔 trace、执行时间线，用于画像资源用量并合理调整请求（各观测 flag 见 configuration.md）。
• 常见失败：
  • 内存不足（exit 137）→ 通过withName/withLabel或自定义 config 提高内存；
  • 缺少输入列 → 修正 samplesheet；
  • 容器拉取失败 → 检查引擎/profile 与缓存目录；
  • Java/Nextflow 版本不对 → 设置NXF_VER并用nextflow info核对。Nextflow 需要Java 17+（17–25 受支持），安装与版本固定方式见 SKILL.md。
• Seqera Platform：以-with-tower（配合TOWER_ACCESS_TOKEN）运行即可获得 Web 监控面板，或直接从 Seqera Platform 启动流水线。

把运行经验沉淀为本仓库技能的一部分

本仓库将该指南封装为nextflow技能包（skills/nextflow），其文档矩阵分工明确：本文对应的 running-pipelines.md 覆盖"运行现有流水线"；编写/修改.nf脚本与 DSL2 语言见 language.md；nextflow.config、profiles、executors、缓存与 CLI 见 configuration.md；容器引擎选型见 containers.md；开发 nf-core 风格流水线/模块见 developing.md；nf-test 测试见 testing.md；nf-coreCLI 完整参考见 nf-core-tools.md。

综合来看，一条可复现的流水线运行应当满足四个习惯：先跑-profile test冒烟、全部版本固定（-r、NXF_VER、镜像 tag）、用 samplesheet + params 文件而非散乱参数、失败后依据 work dir 与报告文件定向修复并-resume。这套工作流让任何 AI Agent 都能像一名熟练的生信工程师一样，把 nf-core 生态与自定义 Nextflow 流水线稳定地跑在笔记本、HPC 与云端。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills