create-workflow

Nextflow 工作流编写器

通过组合来自 Nextflow Registry 的已验证模块，创建完整的 Nextflow 工作流。

模块以命名空间形式发布（例如 nf-core/fastqc），这些技能可组合来自任意命名空间的模块。

需要 Nextflow 26.04 或更高版本（用于验证期间使用的 nextflow module 命令）。包含工作流模块需要 Nextflow 26.10 或更高版本。

Registry 模块分为两种（由 nextflow module view 显示为 Kind:）：

• 流程模块 — 一个工具，例如 nf-core/star/align
• 工作流模块 — 可复用的子工作流，可串联多个模块，例如 nf-core/fastq_align_star（STAR 比对 + samtools 排序/索引/统计）

绝不要仅为了运行/测试单个模块而编写包装工作流。

❌ 错误 — 编写工作流来运行一个模块：

// DO NOT DO THIS - not even when a module run fails!
include { FASTQC } from 'nf-core/fastqc'
workflow { FASTQC(Channel.fromPath('data/*.fq.gz')) }

✅ 正确 — 使用 run-module 技能：

Skill(skill="run-module")

run-module 技能：

• 使用 nextflow module search/view 查找模块并获取正确的输入/参数
• 直接通过 nextflow module run <namespace>/<module> 运行模块
• 无需包装工作流

⚠️ 模块运行因缺少参数而失败时：

• 不要编写包装工作流来“修复”
• 应运行 nextflow module view <module> 获取正确的参数
• 修正命令行参数，然后直接重新运行

仅在步骤 4 中编写工作流，用于组合多个已验证的模块。

创建工作流的 4 步流程

创建新工作流时，始终遵循此结构化流程：

步骤 1：确定模块并提出计划

1. 使用 nextflow module search <term> 查找每个处理步骤所需的 Registry 模块
2. 查找已涵盖一系列步骤的工作流模块。 nextflow module search 很少会将它们排得足够靠前，因此请使用 kind=Workflow 筛选条件查询 Registry 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"]]'
   

   如果某个工作流模块符合计划中的步骤链，请使用它，而不要手动连接相同的流程模块。
3. 使用 nextflow module view <name> 了解每个模块的输入/输出（对于工作流模块，按调用顺序查看其 take: 输入和 emit: 输出）
4. 向用户展示计划，包括：
   • 已识别模块的列表，并标明每个模块是流程模块还是工作流模块
   • 处理顺序（哪个模块先运行、其次运行等）
   • 模块间的数据流（输出 → 输入）

停止并等待用户批准后再继续。

步骤 2：用户同意

• 等待用户审阅并批准所提计划
• 回答用户的问题或处理其要求的修改
• 只有在用户明确同意后才能继续

步骤 3：逐个验证模块（必须执行）

绝不要跳过此步骤。 用户同意后：

1. 确定适用于验证的测试数据
2. 对计划中的每个模块，依次执行：
   • 安装并使用测试数据运行：调用 Skill(skill="run-module")
   • 验证输出 — 确认已生成预期数据
   • 只有当前模块成功后，才能继续下一个模块
   • 未类型化的工作流模块（大多数 nf-core 模块）运行 nextflow module run 时会报错“无法直接执行，因为它没有类型定义”。这是预期情况，不是需要修复的故障：不要为此编写包装工作流，也不要停下来询问用户。在验证日志中记录为“已在步骤 4 中验证”，然后继续。它将在步骤 4 的端到端运行中得到验证。
3. 将所有模块运行命令及其输出记录到带有 .modules-validation- 前缀的调试文件中
4. 如果命令失败，请停止并向用户展示所用命令及生成的输出，然后再尝试其他操作

注意：run-module 技能使用 nextflow module 命令进行发现、配置和执行 — 模块会即时安装。

在所有模块都已单独验证之前，不要继续执行步骤 4。

步骤 4：组合最终工作流

只有在所有模块都成功运行后：

1. 使用 Wave + Conda 配置 nextflow.config：

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

2. 编写工作流脚本，组合所有已验证的步骤，使用 Nextflow 管理的模块（不加 ./ 前缀 — Nextflow 会自动从 Nextflow Registry 下载并安装这些模块）：

   include { MODULE_A } from 'nf-core/module_a'
   include { MODULE_B } from 'nf-core/module_b'
   
   workflow {
       MODULE_A(input_ch)
       MODULE_B(MODULE_A.out.results)
   }
   

   工作流模块使用相同的 include 语法（include { FASTQ_ALIGN_STAR } from 'nf-core/fastq_align_star'），并按照 take: 中列出的顺序，使用位置参数调用。对于未类型化的工作流模块，nextflow module view 中的输入描述仅供参考。请阅读已安装的 modules/<namespace>/<name>/main.nf，了解每个输入传递给哪个进程，并构造该进程所需的通道形状（例如 [meta, index] 元组）。首次运行时，Nextflow 会将每个模块安装到 modules/<namespace>/<name>/ 下，并将其依赖项放在嵌套的 modules/ 目录中。请将 modules/ 目录提交到代码库，并与流水线一同维护。

3. 使用相同的测试数据运行完整工作流，进行端到端验证。对于步骤 3 中跳过的任何未类型化工作流模块，这是必要的验证步骤。

关键指南

命令执行

• 适当时使用 -resume 标志，以利用缓存结果
• 使用绝对路径，绝不使用相对路径

文件处理

• 指定多个文件时，使用逗号分隔并用双引号括起来：--input "file1.fq,file2.fq"
• 运行前，始终将通配符展开为以逗号分隔的文件列表
• 根据标准输出中的任务 ID，在工作目录中查找输出文件

模块包含语法

• include { MOD } from 'nf-core/module' — Nextflow 管理的模块（默认）。Nextflow 会自动从 Nextflow Registry 下载并安装该模块。始终优先使用这种形式。（这里的 nf-core 是命名空间；请替换为所用模块的实际命名空间。）
• include { MOD } from './modules/nf-core/module/main.nf' — 本地文件路径，相对于工作目录解析。仅在引用本地修改过的模块时使用。

模块选择

• 优先使用现有工作流模块，而不是手动串接它已组合的进程模块
• 通过注册表 API 的 kind=Workflow 筛选条件查找工作流模块（参见步骤 1）；nextflow module search 很少能找到这些模块
• 不要编写包装工作流来测试单个模块 — 改用 Skill(skill="run-module")
• 使用 nextflow module search 查找模块，然后使用 nextflow module view 查看详情

调试流程

1. 使用标准输出中的任务 ID 检查任务工作目录
2. 检查 .command.log、.command.err 和 .command.out 文件
3. 确认输入文件存在且可访问
4. 确认资源需求（内存、CPU）与可用资源相符

技能委派（重要）

使用 Skill 工具将特定于模块的任务委派给专门技能：

任务	调用技能
安装、运行或测试模块	Skill(skill="run-module")

何时委派

• 步骤 3（验证模块）：对每个模块的验证都使用 run-module 技能

示例：步骤 3 验证

对于计划中的每个模块：

1. Invoke: Skill(skill="run-module") → install, run with test data, and verify outputs
2. Only proceed to next module after success

这些技能包含针对特定任务的详细说明，可确保执行模式一致。

快速参考

Step 1: Identify process + workflow modules → Propose plan to user
Step 2: Wait for user agreement
Step 3: Validate ALL modules ONE BY ONE with test data (untyped workflow modules: defer to Step 4)
Step 4: Compose final workflow (only after Step 3 succeeds)