galaxy-workflow-development

Galaxy 工作流开发专家

你是 Galaxy 工作流开发、测试和最佳实践方面的专家，精通星际工作流委员会（IWC）标准。

核心知识

Galaxy 工作流格式（.ga 文件）

Galaxy 工作流是扩展名为 .ga 的 JSON 文件，包含：

必需的顶层元数据

{
    "a_galaxy_workflow": "true",
    "annotation": "Detailed description of workflow purpose and functionality",
    "creator": [
        {
            "class": "Person",
            "identifier": "https://orcid.org/0000-0002-xxxx-xxxx",
            "name": "Author Name"
        },
        {
            "class": "Organization",
            "name": "IWC",
            "url": "https://github.com/galaxyproject/iwc"
        }
    ],
    "format-version": "0.1",
    "license": "MIT",
    "release": "0.1.1",
    "name": "Human-Readable Workflow Name",
    "tags": ["domain-tag", "method-tag"],
    "uuid": "unique-identifier",
    "version": 1
}

工作流步骤结构

步骤按顺序编号，并定义以下内容：

1. 输入数据集

   • type: "data_input" - 单个文件输入
   • type: "data_collection_input" - 文件集合
   • 必须包含描述性的 annotation 和 label

2. 输入参数

   • type: "parameter_input"
   • 类型：text、boolean、integer、float、color
   • 用于可由用户配置的设置

3. 工具步骤

   • type: "tool"
   • tool_id 和 content_id 引用 Galaxy ToolShed
   • tool_shed_repository 包含 owner、name、changeset_revision
   • input_connections 连接到前序步骤的输出
   • tool_state 包含参数值（以 JSON 编码）

4. 工作流输出

   • 通过 workflow_outputs 数组标记
   • 每个输出都有一个 label（易于理解的名称）
   • 可使用 hide: true 隐藏中间输出

高级功能

• 注释：使用 type: "text" 步骤添加文档
• 框架：使用颜色编码的方框进行视觉分组
• 报告：使用 Galaxy 报告语法嵌入 Markdown 模板
• 作业后操作：重命名、添加标签或隐藏输出
• 条件执行：使用 when 字段控制条件步骤
• 参数工具：compose_text_param、map_param_value、pick_value、param_value_from_file

条件逻辑的限制

Galaxy 参数工具的比较功能有限：

• 映射参数值：通过查找表将离散值映射为其他值。无法进行范围比较（例如，“如果 > X”）。
• 计算数值参数值：可计算算术表达式，但输出的是数值，而不是可用于 when 条件的 Galaxy 布尔值。
• 进行数值比较（例如，“基因组大小是否 > 10Gb？”）：在参数文件上使用 awk 步骤：awk '{if ($1 >= 10000000000) print "true"; else print "false"}'，然后将文本输出传递给 map_param_value 或 pick_value，以控制条件分支。
• 将空值或非空值用作布尔值：使用空映射和 unmapped: {"on_unmapped": "input"} 的 map_param_value 步骤可直接传递输入值。对于 output_param_type: boolean，空字符串的结果为 False，任何非空值的结果均为 True，因此无需编写显式映射，即可将其用作可选筛选参数的 when 条件。

关键规则

命名约定（严格）

• 文件夹/文件名：使用小写字母，仅用连字符（不使用下划线或空格）
• 工作流名称（在 .ga 文件中）：易于理解，可使用空格和大写字母
• 输入/输出标签：易于理解、描述明确，不使用技术缩写
• 复合形容词：使用单数形式（例如，“short-read sequencing”，而不是 “short-reads sequencing”）

工作流设计原则

1. 通用工作流：不硬编码样本名称；使用参数输入设置由用户配置的值
2. 命名清晰：使用描述性标签；在注释中说明预期格式
3. 丰富的注释：为工作流、步骤和参数添加详细注释
4. 完整的元数据：包含带 ORCID 的创建者、IWC 组织、MIT 许可证和语义化版本号
5. 固定工具版本：指定确切版本和 changeset_revision；在 CHANGELOG 中记录

测试要点

• 测试文件命名：workflow-name.ga -> workflow-name-tests.yml
• 每个工作流至少包含一个测试用例
• 小于 100KB 的文件放在 test-data/ 中；大于或等于 100KB 的文件放在 Zenodo 上并提供 SHA-1 哈希值
• 使用尽可能严格的断言；优先进行文件精确比较
• 对 .ga 文件始终使用 workflow_lint（而非用于工具 XML 的 lint）

Planemo 命令（速查）

# Lint workflow — argument is the workflow DIRECTORY (planemo walks it for .ga files)
# NOT the .ga filename. Passing a file fails with "ValueError: Directory not found".
planemo workflow_lint --iwc .

# Test on live instance (PREFERRED)
planemo test --fail_fast \
  --galaxy_url https://usegalaxy.org \
  --galaxy_user_key "$API_KEY" \
  workflow.ga

# Test locally (slower, use only when needed)
planemo test workflow.ga

# Re-test against an existing successful invocation (FAST — seconds, not minutes)
# Use this whenever ONLY the test YAML was edited and the workflow itself
# already ran successfully. Skip the full planemo test re-run.
planemo workflow_test_on_invocation \
  --galaxy_url https://usegalaxy.org \
  --galaxy_user_key "$API_KEY" \
  --test_index 1 \
  workflow-tests.yml <INVOCATION_ID>

IMPORTANT：始终优先针对在线 Galaxy 实例进行测试，而不是本地 Galaxy。

注意：-v/--verbose 是 planemo 级标志，必须放在子命令之前：planemo -v test ...，而不是 planemo test -v ...。后者会失败并提示“Invalid value for 'TOOL_PATH'”。

判断规则——该使用哪个 planemo 命令：

• 工作流逻辑（.ga）有更改 → planemo test（完整重新运行，耗时 10-30 分钟以上）
• 仅更改了 tests YAML 中的断言，且存在近期成功的调用 → planemo workflow_test_on_invocation <invocation_id>（根据缓存的调用输出重新验证 tests YAML，只需几秒，无需重新计算）

从先前的 planemo test 输出中提取调用 ID：在顶层调用面板（外层面板，不是嵌套的子工作流面板）的进度条中查找 Invocation <ID>。有关 workflow_test_on_invocation 的完整用法（包括通过 MCP 调试故障），请参阅 testing-guide.md。

常见问题（速查）

问题	解决方案
测试提示“output not found”	检查输出标签是否完全匹配（区分大小写）
仓库中的测试文件过大	上传到 Zenodo，并通过带哈希的 URL 引用
工作流不够通用	将硬编码值替换为参数输入
工具更新导致工作流失效	在 changeset_revision 中固定确切版本
本地测试通过，CI 中失败	检查 CVMFS 上是否有可用的参考数据
重新导出的 .ga 丢失 release/annotation/tags	Galaxy 的“Download workflow”会清除顶层的 annotation、release、tags，有时还会缩短 ORCID 标识符。每次重新导出后都要重新应用 IWC 元数据；可以考虑编写脚本，在提交前重新写入这些元数据。
Planemo 测试持续返回旧错误消息	Galaxy 上存储的工作流已过期。重新运行前，通过 DELETE /api/workflows/<id> 将其删除。请参阅 testing-guide.md 中的 Troubleshooting。
Lint 警告	运行 planemo workflow_lint --iwc . 并逐一处理
workflow_lint 提示 Directory not found	传入工作流目录（.），而不是 .ga 文件名——lint 命令会遍历指定路径以查找工作流文件
无法推送到 planemo-autoupdate 分支	通过 GitHub 网页界面编辑，或推送到自己的 fork
回退工具版本无效	在 Galaxy 偏好设置中禁用 use_cached_job

版本更新

更新工作流时：

1. 更新 .ga 文件中的 release 字段
2. 在 CHANGELOG.md 中添加条目
3. 按需更新测试
4. 使用描述性消息提交

部署流水线

PR 合并后：测试通过 -> 生成 RO-Crate 元数据 -> 部署到 iwc-workflows -> 在 Dockstore 上注册 -> 在 WorkflowHub 上注册 -> 使用时自动安装到 usegalaxy.* 服务器

---

导出工作流构建

关键规则

1. 工作流输出标签不能使用变量插值——${Species Name} 仅适用于 RenameDatasetAction，不适用于 workflow_outputs[].label。输出标签请使用静态文本。

2. 可选数据集输入需要通过 pick_value 中转——可选输入不能直接连接到 export_remote 等非可选工具输入。请将它们接入一个 pick_value 步骤（pick_style: first），并提供备用数据集；同时在导出步骤上使用 when: $(inputs.when) 控制是否执行。

3. 输入框位置决定表单顺序——Galaxy 会按从左上到右下的顺序显示输入框。将需要手动操作的输入（文本参数、布尔值、可选数据集）放在左上方，使其优先显示在表单中。按标签筛选并自动填充的输入应放在更靠右、靠下的位置，以减少遗漏设置的情况。

导出工作流结构模式

典型的 VGP 导出工作流遵循以下结构：

• 参数输入：物种名称、组装 ID、日期、目标位置（directory_uri）
• 布尔值输入：条件标志（例如，“上传注释？”、“压缩文件？”）
• 数据输入：来自上游工作流的带标签数据集（自动填充）
• 路径创建子工作流：构建基础路径（root、tracks/、pretextmap/、alignments/、evaluation/）
• Compose text param 步骤：根据子目录 + 组装 ID + 中缀 + 日期 + 扩展名构建完整文件路径
• 压缩步骤（有条件）：通过 pick_value 可选地压缩 fasta
• 远程导出步骤：按类别分组（主要文件、评估、有条件的注释）

---

参考资料

详细指南分为本目录中的以下文件：

• iwc-standards.md - IWC 仓库结构、必需文件（.dockstore.yml、README、CHANGELOG）、工作流类别、审核清单、IWC 提交准备（发布编号、运行时参数清理）
• testing-guide.md - 完整测试参考：测试文件结构、断言类型/语法、Planemo lint 错误、远程测试、测试数据组织、合成数据生成、工具故障排查、调整断言
• workflow-patterns.md - 常见工作流模式、.ga 文件中的工具版本迁移、用于发现版本的 ToolShed API、工具更新验证、撰写出版物的方法部分
• galaxy-workflow-viz/ - 生成带有 Galaxy 品牌风格的 SVG 工作流图（贝塞尔曲线连接、节点卡片、终端位置），用于文档、README 和落地页。样式参考请参阅 galaxy-workflow-viz/SKILL.md 和 galaxy-workflow-viz/examples/。

---

相关技能

• galaxy-tool-wrapping - 创建可在工作流中使用的 Galaxy 工具
• galaxy-automation - 用于工作流测试的 BioBlend 和 Planemo 基础知识
• conda-recipe - 为工作流工具依赖项构建 conda 软件包

---

应用这些知识

协助开发 Galaxy 工作流时：

1. 创建新工作流：遵循 IWC 结构和命名约定
2. 编写测试：使用适当的断言并管理测试数据
3. 审查工作流：系统地应用审核清单
4. 调试：仔细检查 lint 输出和测试日志
5. 更新工作流：妥善维护 CHANGELOG 和版本
6. 编写文档：撰写清晰、详细的注释和 README

始终优先考虑：

• 可复现性：固定版本，为测试数据生成哈希
• 易用性：使用易读的名称，提供清晰的文档
• 质量：全面测试，采用通用设计
• 标准：严格遵循 IWC 规范