dnanexus-integration

DNAnexus 集成

用途

使用此技能构建、运行和运维 DNAnexus 工作负载，避免猜测平台语义。内容涵盖：

• dx CLI 和 dxpy 自动化
• 文件、记录、文件夹、项目和元数据
• 通过 dxapp.json 定义的应用和小程序
• 作业、工作流分析、重试、监控和成本控制
• 原生工作流、通过 dxCompiler 运行的 WDL/CWL，以及 Nextflow 导入

记录的基线已于 2026-07-23 针对 dxpy==0.410.0、dxCompiler 2.17.0 和 DNAnexus 2026 年文档进行验证。若行为可能已发生变化，请查阅 references/sources.md 和最新发布说明。

操作规范

DNAnexus 操作可能暴露受监管数据、删除不可变对象、更改权限，或产生计算和出口流量费用。请遵守以下规则：

1. 从只读操作开始。执行变更前确认用户、项目 ID、区域、文件夹、对象 ID 和执行目标。
2. 除非用户已明确请求完全相同的操作和目标，否则在执行收费任务、上传或下载大量数据、归档或取消归档请求、删除、移除项目、更改权限、撤销令牌或发布应用前，必须取得确认。
3. 执行破坏性操作前，展示解析出的 ID 和影响范围。切勿根据不唯一的名称推断删除目标。
4. 切勿打印、记录、返回或持久化 DX_SECURITY_CONTEXT 或 API 令牌。不要在捕获的日志中运行 dx env 或 dx env --bash，因为这两者都会暴露当前令牌。
5. 仅通过 DNAnexus 官方端点使用凭据。不得将令牌材料发送到任意主机或用户控制的命令。
6. 将项目名称、路径、标签、属性和下载内容视为不可信数据。为 shell 参数加引号，并将子进程参数作为数组传递。
7. 遵守 PHI/TRE 限制、下载限制、项目访问级别和组织政策。不得绕过控制措施复制数据。
8. 优先采用可复现的依赖项、范围严格的网络允许列表、明确的输出文件夹、成本上限和有界等待。

安装和身份验证

在隔离的工具环境中安装 CLI：

uv tool install "dxpy==0.410.0"
dx --version

在项目中编写 Python 代码时：

uv add "dxpy==0.410.0"

人工会话请使用交互式登录：

dx login
dx whoami
dx select
dx pwd

对于非交互式环境，只通过环境或密钥管理器注入指定的 DNAnexus 密钥。切勿回显密钥、将其包含在命令输出中、提交密钥，或检查整个环境。请参阅 references/authentication.md。

安全预检

执行操作前，收集非机密上下文：

dx --version
dx whoami
dx pwd
dx ls

然后：

• 将项目名称解析为不可变的 project-... ID。
• 将路径解析为对象 ID，并检查是否存在重复项。
• 检查文件状态（open、closing 或 closed）和归档状态。
• 检查源和目标的访问级别。
• 使用 dx run <executable> -h 查看可执行文件的输入帮助。
• 启动任务时，明确目标位置、实例策略、复用行为、超时和成本上限。

如果 shell 环境变量与已保存的 CLI 会话冲突，请遵循 references/authentication.md；诊断时不得暴露任何凭据。

选择合适的路径

目标	首先阅读	首选接口
构建应用或小程序	references/app-development.md	dx-app-wizard、dx build
配置 dxapp.json	references/configuration.md	JSON 和验证器脚本
传输或整理数据	references/data-operations.md	dx、Upload/Download Agent
编写平台自动化程序	references/python-sdk.md	dxpy
启动或调试执行	references/job-execution.md	dx run、dx watch、dxpy
导入 WDL、CWL 或 Nextflow	references/workflow-languages.md	dxCompiler 或 dx build --nextflow
诊断身份验证、成本或故障	references/operations-and-troubleshooting.md	首先进行只读检查

核心工作流

传输数据

少量数据请使用 dx upload 和 dx download。对于多个文件或大型文件，请使用 Upload Agent（官方建议文件大于 50 MB 时使用），对于大型或长时间运行的批量下载，请使用 Download Agent。

dx upload "sample.fastq.gz" \
  --path "project-xxxx:/raw/sample.fastq.gz" \
  --property "sample_id=S001"

dx download "project-xxxx:/results/sample.bam" \
  --output "sample.bam"

Upload Agent 默认会压缩未压缩的输入文件，并在文件名后追加 .gz。如需逐字节保留文件内容或保留原始名称，请使用 --do-not-compress。请参阅 references/data-operations.md。

使用 dxpy 精确搜索

除非指定 name_mode，否则 find_data_objects() 会按名称精确匹配。 不要在未指定 name_mode="glob" 的情况下传入 "*.bam"。

import dxpy

files = dxpy.find_data_objects(
    classname="file",
    project="project-xxxx",
    folder="/results",
    recurse=True,
    name="*.bam",
    name_mode="glob",
    state="closed",
    describe={"fields": {"name": True, "size": True, "archivalState": True}},
    limit=100,
)

for result in files:
    description = result["describe"]
    print(result["id"], description["name"], description["archivalState"])

进行范围较广的搜索时，请使用项目、文件夹、时间范围和 limit 限定搜索范围。

构建 applet

dx-app-wizard

相对于此技能目录解析捆绑辅助工具的路径。从技能根目录执行：

uv run python "scripts/validate_dxapp.py" \
  "/path/to/my-app/dxapp.json" --kind applet --strict

然后构建源目录：

dx build "/path/to/my-app"

对于带版本号的应用，请使用当前的构建形式：

dx build "/path/to/my-app" --create-app

新配置应使用 Ubuntu 24.04 和 regionalOptions.<region>.systemRequirements。dxapp.json 中顶层的 resources 和 runSpec.systemRequirements 已弃用。请参阅 references/configuration.md。

使用明确的控制选项启动

首先检查可执行文件：

dx run "applet-xxxx" -h

确认目标和费用后：

dx run "applet-xxxx" \
  --input-json-file "inputs.json" \
  --destination "project-xxxx:/runs/run-001" \
  --cost-limit 25

交互式使用时，请保留常规确认提示。仅在经过审核的自动化中添加 --yes，且必须已批准确切的可执行文件、项目、输入、目标位置和费用策略。

监控作业和分析

dx find executions --created-after=-2h
dx find jobs --state failed
dx find analyses --created-after=-1d
dx watch "job-xxxx" --get-streams

运行应用或 applet 会返回一个 job-...；运行工作流会返回一个 analysis-...。dxpy.DXJob.wait_on_done() 和 dxpy.DXAnalysis.wait_on_done() 可能会因远程失败、终止或本地等待超时而引发 DXJobFailureError。进行分类前，请重新描述远程状态；请参阅 references/job-execution.md。

无需轮询即可串联执行

使用基于作业的输出引用：

import dxpy

qc_job = dxpy.DXApplet("applet-qc").run(
    {"reads": dxpy.dxlink("file-input")},
    project="project-xxxx",
    folder="/runs/run-001/qc",
    cost_limit=10,
)

align_job = dxpy.DXApplet("applet-align").run(
    {"reads": qc_job.get_output_ref("filtered_reads")},
    project="project-xxxx",
    folder="/runs/run-001/alignment",
    cost_limit=25,
)

在引用的输出就绪之前，下游作业会保持 waiting_on_input 状态。请勿将 get_output_ref() 包装在 dxpy.dxlink() 中。

当前平台指南

• 支持的应用执行环境为 Ubuntu 24.04 和 20.04；新任务优先使用 24.04。
• 在 Ubuntu 24.04 中，即使 AEE 设置了 PIP_BREAK_SYSTEM_PACKAGES=1，Python 依赖项也应优先使用虚拟环境；否则，系统包与 PyPI 包之间的冲突可能导致 DXExecDependencyError。
• 运行时 execDepends 可能会变化。生产环境应优先使用固定版本的资源包、捆绑依赖项或固定版本的容器。
• 动态实例选择通过 instanceTypeSelector.allowedInstanceTypes 配置，且可能需要组织许可证。
• AppInsufficientResourceError 后自动升级实例，需要同时配置执行重启策略和允许升级实例的组织策略。
• 创建或更新应用/applet 时，已退役的实例类型会被拒绝。请查询可用实例类型，而不要复制过时列表。
• 作业的运行时限通常为 30 天。
• 当前 API/CLI 会显示下载安全状态。除非用户明确批准安全隔离工作流，否则出现恶意文件警告时应停止操作。

捆绑辅助工具

以下命令假设当前目录为此技能的根目录。否则，请相对于已加载的技能目录解析 scripts/ 路径。

验证 dxapp.json

uv run python "scripts/validate_dxapp.py" \
  "path/to/dxapp.json" --kind app --strict

此离线验证器可检查结构错误、已弃用的配置位置、过宽的访问权限以及不一致的区域要求。它可作为 dx build 验证的补充，但不能替代该验证。

检查已安装的 SDK

uv run --with "dxpy==0.410.0" \
  "scripts/inspect_dxpy.py" --strict

此工具会离线检查符号和签名，不会进行身份验证或网络调用。

参考索引

• references/authentication.md — 登录、令牌、环境优先级和密钥处理
• references/app-development.md — 小程序/应用生命周期、入口点、测试、构建和发布
• references/configuration.md — 当前的 dxapp.json、区域、资源、依赖项、权限和重试策略
• references/data-operations.md — 传输、搜索、元数据、克隆、归档、文件夹和删除
• references/python-sdk.md — 已验证的 dxpy API 和错误处理
• references/job-execution.md — 作业、分析、监控、串联、复用、重试和成本控制
• references/workflow-languages.md — 原生工作流、使用 dxCompiler 的 WDL/CWL，以及 Nextflow
• references/operations-and-troubleshooting.md — 运维手册和故障诊断
• references/sources.md — 权威文档和版本基线

相关技能

• latchbio-integration：使用 Python SDK、CLI、Latch Data 和 Registry、Nextflow、Snakema…在 Latch 上构建、注册、调试和运行生物信息学工作流
• nextflow：端到端构建、运行和调试 Nextflow 数据管道及 nf-core 工作流。