bioinformatics-on-healthomics

AWS HealthOmics 上的生物信息学分析

用于在 AWS HealthOmics 上创建、部署和运行生物信息学工作流的端到端技能。面向可能不太熟悉技术的用户——Agent 会清楚地解释每个决定，并全程引导。

---

回复结构

引导用户完成 HealthOmics 生物信息学工作流时，请按以下顺序进行：

1. 明确分析目标 — 确认分析类型、物种和数据格式
2. 推荐工具 — 提出一套流程并说明理由；征求用户确认
3. 选择工作流语言 — 根据复杂度选择 WDL 或 Nextflow
4. 设置基础设施 — 容器（ECR 拉取透传）、S3、IAM、运行缓存
5. 生成工作流代码 — 注册前先进行 lint 检查
6. 注册并运行 — 部署、启动运行、监控进度
7. 处理失败 — 使用 MCP 工具诊断问题，并通过缓存迭代
8. 交付结果 — 指明输出位置，并提出优化建议

---

心智模型

AWS HealthOmics 是一项全托管服务，可运行基因组学工作流。你需要提供：

1. 工作流定义（Nextflow 或 WDL）
2. ECR 中的容器映像（通过拉取透传缓存从公共注册表拉取）
3. S3 中的输入数据
4. IAM 服务角色

HealthOmics 会处理计算资源预置、调度和输出收集。

关键限制

• 所有容器都必须位于私有 ECR 中（公共映像需使用拉取透传缓存）
• 所有输入／输出数据都必须位于与工作流相同区域的 S3 中
• 必须提供信任策略适用于 omics.amazonaws.com 的服务角色
• 支持的区域：us-east-1、us-east-2、us-west-2、eu-west-1、eu-west-2、 eu-central-1、ap-southeast-1、ap-northeast-1、ap-northeast-2、il-central-1

---

先决条件

开始之前，请确认：

1. 已配置 AWS 凭证，且所在区域受 HealthOmics 支持
2. 已安装 AWS CLI v2
3. HealthOmics MCP 服务可用且已启用（使用 aws-healthomics power）
4. 可使用 RODA MCP 来发现测试数据（可选，但建议使用）

---

阶段 1：了解用户的分析需求

询问用户想要完成什么任务。常见分析类型：

分析类型	常用工具	输入	输出
质量控制	FastQC、MultiQC、fastp	FASTQ	QC 报告、剪切后的 FASTQ
比对	BWA-MEM2、STAR、minimap2、bowtie2	FASTQ + 参考序列	BAM/CRAM
变异检测	GATK HaplotypeCaller、DeepVariant、Strelka2、FreeBayes	BAM + 参考序列	VCF/gVCF
结构变异	Manta、DELLY、LUMPY、Sniffles	BAM + 参考序列	VCF
RNA-Seq	STAR + featureCounts、Salmon、kallisto	FASTQ + 参考序列／索引	计数矩阵
甲基化	Bismark、bwa-meth	FASTQ + 参考序列	甲基化检测结果
变异注释	VEP、SnpEff、ANNOVAR	VCF + 数据库	已注释的 VCF
联合分型	GATK GenomicsDBImport + GenotypeGVCFs	gVCF	联合 VCF
体细胞变异检测	Mutect2、VarScan2、Strelka2-somatic	肿瘤／正常 BAM	体细胞 VCF

推荐引擎

根据用户说明的目标，推荐一套工具流程。组合示例：

全基因组测序（生殖系）：

1. fastp（质量控制 + 剪切）→ BWA-MEM2（比对）→ GATK MarkDuplicates → GATK HaplotypeCaller → VCF 过滤

RNA-Seq 差异表达：

1. fastp（质量控制）→ STAR（比对）→ featureCounts（定量）

靶向面板／外显子组：

1. fastp → BWA-MEM2 → GATK MarkDuplicates → GATK HaplotypeCaller（使用区间）→ VQSR 或硬过滤

始终解释推荐每种工具的原因，并在继续之前征求用户确认。

---

阶段 2：选择工作流语言

询问用户的偏好：

• WDL（推荐给大多数用户）——语法更清晰，输入／输出定义明确，更适合线性流程
• Nextflow——更适合包含多个分支点的复杂数据驱动型流程

如果用户没有偏好，简单流程默认使用 WDL 1.1；复杂的多样本 scatter-gather 模式默认使用 Nextflow DSL2。

---

阶段 3：容器镜像源

对于工作流中的每个工具，按以下优先级查找容器镜像：

1. quay.io/biocontainers/ — 首选，经过筛选的生物信息学容器
2. public.ecr.aws/ — AWS 托管的公共镜像
3. Docker Hub（registry-1.docker.io）— 镜像丰富，但存在速率限制

搜索策略

对于每个工具，搜索最新的稳定镜像：

• quay.io：quay.io/biocontainers/<tool>:<version>--<hash>
• ECR Public：public.ecr.aws/biocontainers/<tool>:<version>
• Docker Hub：broadinstitute/gatk:<version>、staphb/<tool>:<version>

设置 ECR 拉取直通缓存

HealthOmics 要求容器存放在私有 ECR 中。使用拉取直通缓存自动镜像公共镜像。

使用 HealthOmics MCP CreatePullThroughCacheForHealthOmics 工具：

• 将 upstream_registry 指定为 docker-hub、quay 或 ecr-public
• 可选择设置 ecr_repository_prefix
• 对于 quay 和 ecr-public：无需凭证
• 对于 docker-hub：必须提供 credential_arn（见下文）
• 该工具会自动创建缓存规则、更新 HealthOmics 的注册表权限，并创建具有正确权限的存储库创建模板

Docker Hub 身份验证（docker-hub 拉取直通缓存必需）

Docker Hub 会限制匿名拉取的速率。要通过拉取直通缓存使用 Docker Hub，请将凭证存储在 Secrets Manager 中，并将 ARN 作为 credential_arn 传入：

1. 创建 KMS 密钥：aws kms create-key → 保存 ARN
2. 存储凭证：aws secretsmanager create-secret --kms-key-id <KEY> --secret-string '{"username":"...","password":"..."}' → 保存密钥 ARN
3. 将 credential_arn 传给 CreatePullThroughCacheForHealthOmics

如果用户没有 Docker Hub 账户，优先使用 quay.io/biocontainers（无需身份验证）。

要验证设置，请使用 ValidateHealthOmicsECRConfig，它会检查所有拉取直通缓存规则、注册表权限和存储库模板。

要列出现有规则及其对 HealthOmics 的可用性，请使用 ListPullThroughCacheRules。

验证容器可用性

使用 HealthOmics MCP CheckContainerAvailability 工具，并将 initiate_pull_through: true 设为启用，以确认每个容器均可访问。此操作会验证镜像是否存在、检查 HealthOmics 访问权限，并可触发首次拉取直通。

要将特定镜像从上游注册表复制到具有 HealthOmics 权限的私有 ECR，请使用 CloneContainerToECR，并提供源镜像引用（支持 Docker Hub 简写、quay.io 和 public.ecr.aws 格式）。

容器注册表映射

对于引用公共注册表 URI 的工作流，请创建容器注册表映射，以便 HealthOmics 将拉取请求重定向到你的私有 ECR。

使用 HealthOmics MCP CreateContainerRegistryMap 工具：

• 将 include_pull_through_caches: true 设为启用，以自动发现可供 HealthOmics 使用的缓存
• 可选择提供 additional_registry_mappings 或 image_mappings 进行覆盖
• 输出可通过 container_registry_map 参数直接传给 CreateAHOWorkflow，也可保存到 S3，并通过 container_registry_map_uri 引用

---

阶段 4：工作流生成

根据选定的工具和语言生成工作流定义。请遵循 HealthOmics Power 中的指导文档最佳实践。

WDL 结构

workflow/
  main.wdl          # Top-level workflow
  tasks/
    fastqc.wdl      # Individual task definitions
    bwa_mem2.wdl
    gatk_hc.wdl
  structs/
    sample.wdl      # Struct definitions
  parameters.json   # Example parameters
  README.md         # Documentation

Nextflow 结构

workflow/
  main.nf           # Entry point
  nextflow.config   # Configuration
  modules/
    fastqc.nf       # Process definitions
    bwa_mem2.nf
    gatk_hc.nf
  conf/
    healthomics.config  # HealthOmics-specific config
  nextflow_schema.json  # Input schema (nf-schema)
  parameters.json       # Example parameters
  README.md             # Documentation

HealthOmics 兼容性关键规则

1. 每个任务/进程都必须声明 CPU、内存和容器
2. 每个任务至少使用 2 个 CPU 和 4 GB 内存
3. 所有最终输出都必须在工作流级别声明
4. 对于 Nextflow：publishDir 必须使用 /mnt/workflow/pubdir 作为基础路径
5. 对于 WDL：使用 ~{var} 插值和 <<< >>> 命令分隔符
6. 在所有命令块中使用 set -eu

部署前进行检查

对于 WDL/CWL 工作流，请使用 HealthOmics MCP LintAHOWorkflowDefinition 或 LintAHOWorkflowBundle 工具，在部署前进行验证。

---

阶段 5：基础设施设置（仅首次使用）

首次使用时，设置所需的 AWS 基础设施。逐项询问用户，或主动创建。

5A：S3 存储桶

创建一个 S3 存储桶，用于工作流输入、输出和可选的调用缓存：

aws s3 mb s3://<BUCKET_NAME> --region <REGION>

此存储桶用于：

• 输入文件（FASTQ、BAM、VCF、参考文件）
• 工作流输出（HealthOmics 写入的结果）
• 调用缓存（可选，用于恢复中断的运行）

5B：IAM 服务角色

为 HealthOmics 创建服务角色：

# Create the role with HealthOmics trust policy
aws iam create-role \
    --role-name <ROLE_NAME> \
    --assume-role-policy-document '{
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "omics.amazonaws.com"},
        "Action": "sts:AssumeRole"
      }]
    }'

该角色需要：

• 针对 omics.amazonaws.com 的信任策略
• S3：对存储桶授予 s3:GetObject、s3:PutObject、s3:ListBucket、s3:GetBucketLocation 权限
• ECR：授予 ecr:BatchGetImage、ecr:GetDownloadUrlForLayer、ecr:BatchCheckLayerAvailability 权限
• Logs：对 /aws/omics/* 授予 logs:CreateLogGroup、logs:CreateLogStream、logs:PutLogEvents 权限

5C：运行缓存设置

询问用户是否需要调用缓存。说明调用缓存可让 HealthOmics 跳过输入未变化的任务，无需重新运行；这在迭代开发工作流时尤其有用，例如对齐等部分步骤已成功，但变异调用等后续步骤仍需调整。

询问用户偏好的缓存行为：

• CACHE_ON_FAILURE（开发时推荐）——运行失败时缓存已成功任务的结果。下次运行时，输入相同的任务将被跳过。适用于迭代开发：修复失败步骤后重新运行，只有已更改或失败的任务会再次执行。上游已成功的步骤将从缓存中读取。

• CACHE_ALWAYS——无论运行结果如何，都会缓存每次运行的结果。适用于生产流水线：在新样本上重新运行同一工作流时，可跳过输入恰好相同的任务（例如参考索引）。

使用 CreateAHORunCache 创建运行缓存：

• cache_behavior——用户在上述选项中的选择
• cache_s3_location——用于存储缓存的 S3 前缀（例如，s3://<BUCKET>/healthomics-cache/）
• name——描述性名称（例如，“dev-cache”或“production-cache”）

保存返回的 cache_id，供运行时使用。

5D：配置文件

将设置保存到 .healthomics/config.toml：

omics_iam_role = "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
run_output_uri = "s3://<BUCKET>/healthomics-outputs/"
run_storage_type = "DYNAMIC"
cache_id = "<CACHE_ID>"
cache_behavior = "CACHE_ON_FAILURE"  # or "CACHE_ALWAYS"
cache_s3_location = "s3://<BUCKET>/healthomics-cache/"
aws_region = "<REGION>"

---

阶段 6：工作流注册

使用 MCP 工具打包工作流并将其部署到 HealthOmics：

1. 打包工作流——使用 PackageAHOWorkflow：

   • 将 main_file_content 设为主工作流文件的路径（例如，./workflow/main.wdl）
   • 相应地设置 main_file_name（例如，main.wdl 或 main.nf）
   • 通过 additional_files 提供所需的导入文件或模块（文件名 → 文件路径的字典）

2. 注册工作流——使用 CreateAHOWorkflow：

   • 为工作流设置 name
   • 将 definition_source 设为本地 ZIP 路径，或传入 PackageAHOWorkflow 返回的 base64 输出
   • 将 engine 设为 WDL、NEXTFLOW 或 CWL
   • 可选择提供 container_registry_map 或 container_registry_map_uri
   • 可选择提供 description 和 storage_type（默认值为 DYNAMIC）

3. 验证注册——使用 GetAHOWorkflow 确认状态为 ACTIVE

示例流程：

PackageAHOWorkflow(main_file_content="./workflow/main.nf", additional_files={"modules/bwa.nf": "./workflow/modules/bwa.nf", ...})
  → CreateAHOWorkflow(name="my-pipeline", definition_source=<zip_path>, engine="NEXTFLOW")
  → GetAHOWorkflow(workflow_id=<id>)  # verify ACTIVE

---

阶段 7：准备输入参数

帮助用户确定输入文件。

在 S3 中查找文件

使用 HealthOmics MCP 的 SearchGenomicsFiles 工具，在已配置的 S3 存储桶中查找 FASTQ、BAM、VCF 或参考文件。

使用 RODA 测试数据

如果 RODA MCP 可用，使用它查找用于测试的公开数据集：

• 搜索相关数据集（例如，“1000 genomes”、“giab”、“clinvar”）
• 预览数据集结构
• 确定合适的测试文件

常见测试数据集：

• GIAB（Genome in a Bottle）——用于验证变异调用的真值集
• 1000 Genomes——大规模人群 WGS 数据
• ClinVar——具有临床相关性的变异注释
• ENCODE——功能基因组学数据

构建 parameters.json

创建与工作流参数模板匹配的参数文件：

{
  "input_fastq_r1": "s3://bucket/data/sample_R1.fastq.gz",
  "input_fastq_r2": "s3://bucket/data/sample_R2.fastq.gz",
  "reference_fasta": "s3://bucket/references/GRCh38.fasta",
  "sample_name": "NA12878",
  "output_prefix": "results"
}

---

阶段 8：运行工作流

启动一次运行

使用 HealthOmics MCP StartAHORun 工具：

• workflow_id — 来自注册步骤
• role_arn — 来自 .healthomics/config.toml（omics_iam_role）
• name — 描述性运行名称
• output_uri — 来自 .healthomics/config.toml（run_output_uri）
• parameters — 工作流参数（来自 parameters.json）
• storage_type — 来自配置（默认值为 DYNAMIC）
• cache_id — 自动解析（见下文）
• cache_behavior — 来自 .healthomics/config.toml（CACHE_ON_FAILURE 或 CACHE_ALWAYS）

解析运行缓存

用户不应需要记住或指定缓存 ID。请自动解析：

1. 检查 .healthomics/config.toml — 如果已设置 cache_id，直接使用。
2. 检查会话历史记录 — 如果本次会话中较早时创建了缓存，使用该缓存 ID。
3. 如果两者都不可用，调用 ListAHORunCaches 查找现有缓存：
   • 如果恰好有 一个 缓存 → 自动使用。
   • 如果有 多个 缓存 → 向用户展示列表（包含名称、行为和创建日期），并请用户选择一个。
   • 如果没有缓存 → 提示用户创建一个（见阶段 5C）。
4. 解析完成后，将 cache_id 保存到 .healthomics/config.toml，以便后续运行使用，无需再次询问。

只要有可用的运行缓存，就始终传入 cache_id 和 cache_behavior。 在迭代开发期间，这样可以避免重新运行之前已成功完成的耗时任务（例如比对或重复标记）。

监控运行

使用 HealthOmics MCP 工具进行监控：

• GetAHORun — 检查总体状态、耗时和失败原因
• ListAHORunTasks — 查看各个任务的进度和状态
• GetAHORunLogs — 查看工作流执行的高级事件
• GetAHORunEngineLogs — 查看引擎的标准输出／标准错误日志以进行调试
• GetAHOTaskLogs — 查看特定任务的日志
• GetAHORunManifestLogs — 查看包含资源指标的工作流摘要

处理失败

如果运行失败：

1. 使用 DiagnoseAHORunFailure 获取全面诊断信息，包括：
   • 失败原因
   • 引擎日志
   • 失败任务的日志
   • 可执行的建议
2. 常见问题：
   • 未找到 S3 对象 — 确认输入路径存在
   • 容器拉取失败 — 检查 ECR 权限和拉取透传缓存
   • 内存不足 — 增加工作流定义中的任务内存
   • 超时 — 增加任务超时时间，或检查是否存在无限循环
3. 修复工作流，并通过 CreateAHOWorkflowVersion 创建新版本
4. 使用新版本重新运行

---

阶段 9：结果和后续步骤

成功完成后：

• 输出位于 S3 输出位置
• 使用 GetAHORun 查找确切的 runOutputUri
• 如需优化性能，使用 AnalyzeAHORunPerformance
• 如需可视化，使用 GenerateAHORunTimeline

---

失败处理指南

症状	解决方法
"HealthOmics is not available"	使用受支持的区域
容器拉取失败	使用 CreatePullThroughCacheForHealthOmics 修复 PTC 规则
访问 S3 时遭拒	使用正确的存储桶 ARN 更新 IAM 角色策略
工作流卡在 CREATING 状态	最多等待 10 分钟；大型工作流需要时间
注册表映射不匹配	映射更新后重新注册工作流
参数验证错误	检查工作流参数模板中的名称／类型是否匹配

---

关键规则

1. 始终使用 HealthOmics MCP 工具——绝不使用原始 AWS CLI 调用 HealthOmics。
2. 容器优先级：quay.io/biocontainers → public.ecr.aws → Docker Hub。
3. 必须使用拉取穿透缓存——使用 CreatePullThroughCacheForHealthOmics。
4. 区域一致性：S3、ECR 和 HealthOmics 必须位于同一区域。
5. 部署前进行 lint：注册前，使用 LintAHOWorkflowDefinition 验证 WDL/CWL。
6. 配置文件：读取 .healthomics/config.toml 获取已保存的偏好设置。
7. 测试数据：询问用户是否上传之前，先检查 RODA MCP 中的公共数据集。
8. 解释每个步骤，并在执行破坏性操作前进行确认。
9. 默认使用 DYNAMIC 存储以提高成本效益。
10. 诊断：发生故障时使用 DiagnoseAHORunFailure，进行优化时使用 AnalyzeAHORunPerformance。
11. 调用缓存：开发环境默认使用 CACHE_ON_FAILURE。自动从配置中解析缓存 ID——仅在存在多个缓存时才提示用户。