run-module

运行 Nextflow 模块

使用 nextflow module 命令原生运行 Nextflow Registry 中的模块。所有内容均为自包含，无需外部工具或 MCP。运行时会即时安装模块。

模块按命名空间发布（例如 nf-core/fastqc），nextflow module 命令适用于所有命名空间。

需要 Nextflow 26.04 或更高版本（以使用 nextflow module 命令）。工作流模块需要 Nextflow 26.10 或更高版本。

进程模块与工作流模块

模块有一个种类，nextflow module search 和 nextflow module view 会将其显示为 Kind:：

种类	说明	示例
Process	封装单个工具的进程	nf-core/star/align
Workflow	命名工作流（子工作流），用于串联多个模块；其依赖项会随之安装	nf-core/fastq_align_star（STAR + samtools sort/index/stats）

两种模块的搜索、查看、运行和引入方式相同。差异详见查找工作流模块和运行工作流模块。

⛔ 切勿编写包装工作流

如果模块因缺少参数或参数错误而运行失败：

❌ 错误 - 编写包装工作流：

// NEVER DO THIS - even if the module fails!
include { FASTQC } from 'nf-core/fastqc'
workflow { FASTQC(Channel.fromPath('*.fq.gz')) }

✅ 正确 - 使用 nextflow module view 获取正确的参数：

nextflow module view nf-core/fastqc

模块运行失败时：

1. 运行 nextflow module view <module> 获取命令模板
2. 根据模板修正参数
3. 使用 nextflow module run <module> ... 重新运行

切勿将创建包装工作流作为缺少参数的“修复”方案。

步骤 1：搜索模块

使用 nextflow module search 和自然语言词语进行搜索——它会对模块名称、描述和功能进行相似度搜索：

nextflow module search "quality control"
nextflow module search "alignment"
nextflow module search "variant calling"
nextflow module search "BAM statistics"

查找工作流模块

nextflow module search 对工作流模块的排序低于进程模块，因此它们很少出现在搜索结果中。当任务涉及多个步骤时（例如“使用 STAR 比对，然后排序并建立索引”），还应使用 kind=Workflow 过滤条件查询注册表 API：

curl -s "https://registry.nextflow.io/api/v1/modules?query=align%20reads%20STAR&kind=Workflow&limit=10" \
  | python3 -c 'import json,sys; [print(r["name"], "-", r["description"]) for r in json.load(sys.stdin)["results"]]'

将 query 中的空格 URL 编码为 %20。然后使用 nextflow module view 查看匹配项。

步骤 2：获取模块信息和运行模板

确定模块后，获取其详细信息和命令模板：

nextflow module view nf-core/fastqc

此命令会返回模块种类、描述、输入、参数和准确的运行命令模板。以此模板为基础编写运行命令。

对于工作流模块，输入是工作流的 take: 声明（按调用顺序排列），输出是其 emit: 声明。

步骤 3：替换模板值并运行

将模板中的占位值替换为用户提供的具体值（文件路径、参数），然后执行。无需显式安装——模块会即时获取：

nextflow module run nf-core/fastqc \
  --input "/path/to/sample.fq.gz" \
  --outdir results

使用 Wave + Conda 配置容器

模块需要容器来运行底层工具。配置 nextflow.config，使用 Wave + Conda，以便根据每个模块的 conda 软件包即时配置容器：

wave.enabled = true
wave.strategy = 'conda,container'
docker.enabled = true

这样就无需手动构建或拉取容器镜像——Wave 会根据模块声明的 conda 依赖项配置容器。

运行工作流模块

工作流模块使用相同的 nextflow module run 命令运行，但存在以下区别：

• 必须是类型化模块。 只有带有类型化 take: 输入的工作流模块才能直接运行。大多数 nf-core 工作流模块都没有类型，因此会运行失败：

  Workflow `FASTQ_ALIGN_STAR` cannot be executed directly because it is not typed
  

  nextflow module view 仍会为非类型化工作流模块打印用法模板，因此此错误就是判断信号。运行失败后，模块及其依赖项已经安装到 ./modules/ 下。这不是缺少参数的问题，也不是编写包装工作流的理由。如果是从 create-workflow 第 3 步调用，请遵循该技能的说明（转到其第 4 步）。否则，请停止并告知用户该工作流模块无法单独运行，然后提供以下选项：
  • 使用 nextflow module run 逐个运行其组成的流程模块。这些模块列在 ./modules/<namespace>/<name>/meta.yml 的 requires.modules 下；如果其中列出了工作流模块，则可通过其自身嵌套的 meta.yml 展开。或者
  • 通过 create-workflow 技能在管道中使用该模块。
• 通道输入需要样本表。 Channel<...> 输入接受 CSV、JSON 或 YAML 样本表路径；每一行都会成为一个通道项。Value<...> 输入接受单个值（例如文件路径）。
• 输出不会发布。 每个发出的输出都会报告其工作目录路径；不会有任何内容复制到 --outdir。

命令参考

命令	描述
nextflow module search <term>	按名称／描述／功能进行相似度搜索
nextflow module view <name>	查看模块的详细信息及运行方法
nextflow module run <name> [options]	运行模块（即时安装）
nextflow module list	列出已安装模块及其版本和类型

示例

单端 FASTQ 质量控制

# 1. Search
nextflow module search "quality control"

# 2. Get the template
nextflow module view nf-core/fastqc

# 3. Run with concrete values
nextflow module run nf-core/fastqc \
  --input "data/sample.fq.gz" \
  --outdir results_fastqc

双端比对

# 1. Search
nextflow module search "bwa alignment"

# 2. Get the template
nextflow module view nf-core/bwa/mem

# 3. Run with concrete values
nextflow module run nf-core/bwa/mem \
  --input "data/reads_1.fq.gz,data/reads_2.fq.gz" \
  --reference "data/genome.fa" \
  --outdir results_bwa

完整工作流：搜索 → 查看信息 → 运行

1. 搜索模块：

   nextflow module search "quality control for FASTQ"
   

2. 获取信息和运行模板：

   nextflow module view nf-core/fastqc
   

3. 替换模板占位符，填入用户数据中的实际值

4. 运行模块：

   nextflow module run nf-core/fastqc \
     --input "data/sample.fq.gz" \
     --outdir results
   

5. 处理输出——读取标准输出，总结关键结果，并向用户建议合理的下一步

关键规则

1. 先搜索——始终使用 nextflow module search 查找合适的模块
2. 获取模板——运行模块前，始终执行 nextflow module view
3. 替换模板值——将所有占位符替换为用户数据中的具体值
4. 绝不编写包装工作流——如果运行失败，使用 nextflow module view 获取正确参数
5. 绝不猜测参数——始终从信息模板中获取参数
6. 先展开通配符——使用 ls data/*.fq，然后用逗号分隔结果
7. 为多个文件的输入加引号——--input "file1,file2,file3"
8. 尽可能使用绝对路径
9. 始终处理标准输出——运行成功后，提供总结并建议合理的下一步
10. 检查类型——nextflow module view 会报告 Kind: Process 或 Kind: Workflow；对于多步骤任务，还应通过注册表 API 的 kind=Workflow 筛选条件查找工作流模块
11. 非类型化工作流模块无法直接运行——遇到“cannot be executed directly because it is not typed”错误时，请停止并提供运行工作流模块中的替代方案；绝不编写包装工作流

模块运行失败时

**不要编写包装工作流。**请改为：

1. 运行 nextflow module view nf-core/<module>
2. 将模板与命令进行比较，找出差异
3. 使用正确参数修正 nextflow module run 命令
4. 重新运行修正后的命令

第 4 步：处理运行输出（必须）

nextflow module run 命令会将其输出打印到 stdout。模块运行后，你必须：

1. 读取运行命令的 stdout 输出
2. 向用户清晰地总结结果——突出显示关键指标、状态以及任何警告或错误
3. 推断下一步——根据输出和运行的模块，建议用户接下来可以做什么。例如：
   • 在运行 fastqc 后：“质量分数看起来不错。你想继续使用 bwa/mem 进行比对吗？”
   • 在运行 bwa/mem 后：“比对已完成。你想使用 samtools/sort 对 BAM 进行排序，还是使用 samtools/stats 获取统计信息？”
   • 在运行 fastp 后：“剪切已完成。你想对剪切后的 reads 进行比对吗？”

始终将下一步建议表述为向用户提出的问题。

只有在模块或用户明确要求时，才列出或检查工作目录中的输出文件；默认情况下不要这样做。