galaxy-automation

使用 BioBlend 和 Planemo 自动化 Galaxy 工作流

目的

本技能提供使用 BioBlend（Python Galaxy API 库）和 Planemo（Galaxy 工作流测试与执行工具）自动化 Galaxy 工作流的专业知识。

何时使用本技能

在以下情况使用本技能：

• 通过 API 自动执行 Galaxy 工作流
• 构建 Galaxy 批处理系统
• 使用 BioBlend 与 Galaxy 交互
• 使用 Planemo 测试工作流
• 以编程方式管理 Galaxy 历史记录、数据集和集合
• 轮询工作流调用状态
• 为 Galaxy 操作实现错误处理和重试逻辑
• 创建 Galaxy 自动化流水线
• 将 Galaxy 集成到更大型的生物信息学工作流中

本技能并非特定于某个项目——适用于任何 Galaxy 自动化项目。

支持文件

详细参考资料分为以下文件：

• bioblend-reference.md -- BioBlend API 模式：连接、历史记录管理、工作流调用、状态检查、错误处理、重新运行 API、数据集操作和集合
• planemo-reference.md -- Planemo 命令结构、作业 YAML 格式、命令的编程式生成、输出解析，以及 Galaxy API 的 curl／身份验证模式
• automation-patterns.md -- 线程安全操作、批处理、恢复能力和调试（历史记录检查、调用步骤分析）

---

安全最佳实践

1. API 密钥管理

存储在环境变量中：

import os

api_key = os.environ.get('GALAXY_API_KEY')
if not api_key:
    raise ValueError("GALAXY_API_KEY environment variable not set")

gi = GalaxyInstance(url, api_key)

在日志中隐藏：

def mask_api_key(key):
    """Mask API key for display"""
    if len(key) <= 8:
        return '*' * len(key)
    return f"{key[:4]}{'*' * (len(key) - 8)}{key[-4:]}"

masked_key = mask_api_key(api_key)
print(f"Using API key: {masked_key}")

---

2. 路径处理

在 shell 命令中始终为路径加引号：

# Good - handles spaces
command = f'planemo run "{workflow_path}" "{job_yaml}"'

# Bad - breaks with spaces
command = f'planemo run {workflow_path} {job_yaml}'

---

常见问题

1. Planemo 失败与 Galaxy 失败

   • Planemo 返回代码 != 0：工作流未启动，不存在调用
   • 调用状态 = 'failed'：工作流已启动，但 Galaxy 作业失败
   • 不要混淆这两种失败情况

2. 并发上传

   • 同时上传过多可能会使 Galaxy 不堪重负
   • 设置 max_concurrent 限制（通常为 3-5）
   • 考虑使用 --simultaneous_uploads 或顺序上传

3. 数据集状态检查

   • 上传完成前不要调用工作流
   • 始终等待数据集状态 = 'ok'

4. 历史记录名称冲突

   • 使用唯一的历史记录名称（添加时间戳或后缀）
   • 创建历史记录前检查是否已存在

5. 返回代码解读

   • os.system() 会转换退出代码（退出代码 1 -> 返回值 256）
   • 使用 return_code >> 8 获取实际退出代码

6. 调用 ID 恢复

   • 终端断开会导致调用 ID 丢失
   • 始终立即将调用 ID 保存到文件
   • 将 --test_output_json 与 planemo 配合使用

7. 关键：管理员 API 密钥可查看所有用户的数据

   • 不带筛选条件调用 get_invocations() 会返回每位用户的所有调用，而不仅是你自己的
   • 绝不要根据宽泛查询（例如“最近且仍在运行”）取消、删除或修改调用
   • 始终使用自己工具输出中的特定调用 ID（planemo 会打印 Invocation <hex_id>）
   • 执行任何破坏性操作前，确认历史记录／调用的所有者与你的用户一致
   • 如果必须进行宽泛查询，请按你拥有的历史记录 ID 筛选
   • 已取消的调用无法恢复——没有撤销操作

8. Planemo 测试调用跟踪

   • Planemo 会在测试运行期间打印调用 ID：Invocation <52bc9f6134abd589>
   • 取消因 planemo 测试被终止而遗留的调用时，只能使用这些 ID
   • 不要扫描服务器上的所有调用并根据时间猜测哪些属于你

最佳实践摘要

1. 使用环境变量存储 API 密钥
2. 在日志和输出中屏蔽 API 密钥
3. 在 shell 命令中为所有文件路径加引号
4. 为并发操作实现线程安全
5. 经常保存状态，以便恢复
6. 在调用工作流前等待数据集上传完成
7. 以合理的时间间隔轮询调用状态（30-60s）
8. 区分 planemo 故障和 Galaxy 故障
9. 实现适当的错误处理和重试逻辑
10. 使用唯一的历史记录名称以避免冲突

---

Galaxy MCP 连接

使用 Galaxy MCP 工具（mcp__Galaxy__*）时，请在每个会话开始时进行连接。

连接模式

MCP 工具无法直接读取 shell 环境变量。请先通过 Bash 获取它们：

# Resolve env vars
echo "$GXYVGP"   # Galaxy instance URL
echo "$TESTKEY"   # API key for testing
echo "$MAINKEY"   # Admin API key (only for admin tasks, NEVER for testing)

然后传入获取的值：

mcp__Galaxy__connect(url="<resolved_url>", api_key="<resolved_key>")

重要：所有测试和工作流运行都请使用 $TESTKEY。$MAINKEY 是管理员密钥，可查看和修改所有用户的数据。只有在明确需要管理员访问权限时才使用 $MAINKEY。

已知实例

环境变量	实例	备注
$GXYVGP	https://vgp.usegalaxy.org	VGP 生产环境，用户：delphinel（管理员）
$TESTKEY	VGP 的测试 API 密钥	所有 planemo 测试和工作流运行都请使用此密钥
$MAINKEY	VGP 的管理员 API 密钥	仅用于管理员任务——可查看所有用户的数据，绝不要用于测试

---

使用 browser-use 进行浏览器自动化

使用 browser-use 自动执行 Galaxy UI 交互时：

LLM 设置

• browser-use 0.12+ 有自己的 ChatAnthropic 封装——请使用 browser_use.llm.anthropic.chat.ChatAnthropic，不要使用 langchain_anthropic.ChatAnthropic。langchain 版本缺少 browser-use 所需的 provider 属性。
• 必须显式传入 API 密钥：ChatAnthropic(model="claude-sonnet-4-20250514", api_key=os.environ["ANTHROPIC_API_KEY"])

浏览器连接

• 使用 CDP 连接到用户管理的浏览器：BrowserSession(cdp_url="http://localhost:9222")
• 使用以下命令启动 Chrome：chrome --remote-debugging-port=9222
• 通过注入 cookie 自动登录无法可靠地配合 Galaxy 的会话处理机制——连接前让用户手动登录
• 由于 browser-use 直接使用 CDP，而非 Playwright 上下文，因此无法使用 Playwright 的 record_video_dir。请改用 ffmpeg 进行屏幕录制。

Galaxy UI Agent 提示

• Galaxy 工具栏按钮附近有社交媒体图标——Agent 可能会误点 LinkedIn/Twitter，而不是“上传”
• 添加悬停验证说明：“点击任何元素前，先将鼠标悬停在其上，并等待 2 秒，让工具提示显示出来”
• 为视频质量录制添加明确的节奏控制说明
• “创建历史记录”步骤应在 Agent 启动前通过 bioblend API 完成，然后在浏览器中跳过
• 对于 Zenodo URL，通过浏览器“上传”对话框上传文件，比使用 bioblend 的 upload_file() 效果更好

---

相关技能

• galaxy-tool-wrapping：用于创建 Galaxy 工具封装器
• galaxy-workflow-development：用于创建 Galaxy 工作流
• vgp-pipeline：VGP 专用编排（将此技能用作依赖项）

---

资源

• BioBlend 文档：https://bioblend.readthedocs.io/
• Planemo 文档：https://planemo.readthedocs.io/
• Galaxy API：https://docs.galaxyproject.org/en/master/api/
• Galaxy 培训：https://training.galaxyproject.org/