企业官网建设流程全解析

scientific-agent-skills 中的 DNAnexus 数据操作实战：dx CLI 与 dxpy 的传输、检索、元数据与删除安全框架

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

本文基于 scientific-agent-skills 仓库中dnanexus-integration技能的核心参考文档># 独立 CLI 环境（推荐隔离安装） uv tool install "dxpy==0.410.0" dx --version # 项目内 Python 依赖 uv add "dxpy==0.410.0"

认证建议交互式使用dx login，自动化场景通过密钥管理器注入名为DX_SECURITY_CONTEXT的环境变量（其值必须是 JSON 文本，形如{"auth_token_type": "Bearer", "auth_token": "..."}），详见 authentication.md。配置解析优先级为：命令行覆盖 > 环境变量 >~/.dnanexus_config/environment.json> 内置默认值——这意味着残留的 shell 环境变量会覆盖后来的dx login，诊断时应只用dx whoami/dx pwd等非密命令。

动手前建议做只读预检（SKILL.md 中的 Safe Preflight 段落）：

dx --version dx whoami dx pwd dx ls

2. 安全模型：变更前的六步预检

DNAnexus 的数据对象存放在项目（project）或其他数据容器中。文档将“名字与路径只是人类友好的表示，不是不可变标识符；自动化必须用 ID”作为总原则，并要求任何变更前执行六步流程（data-operations.md）：

1. 将项目名解析为project-...形式的不可变 ID；
2. 将每个路径解析为对象 ID；
3. 检测重名（duplicate names）——同名不代表同一对象；
4. 检查对象状态（state）、归档状态（archivalState）、大小与相关元数据；
5. 确认源/目标的权限与限制（access level、下载限制、TRE 策略）；
6. 对删除、克隆、归档、数据外发（egress）等操作，向用户展示精确 ID 与影响面后再执行。

这条安全模型与 SKILL.md 的 Operating Contract 一致：从只读开始、对计费/破坏性操作先确认、绝不从非唯一名字推断删除目标、永不打印或记录DX_SECURITY_CONTEXT与 API token。

3. 对象生命周期：open → closing → closed

文件对象使用三态生命周期（data-operations.md）：

open → closing → closed

• open：分片/内容仍可上传；
• closing：收尾进行中，内容不可读不可写；
• closed：内容不可变，可下载/分享。

关键操作约束：

• 文件必须closed才能被读取或克隆。open/closing状态的文件可以作为 job 输入提交，但 job 会停留在waiting_on_input直到文件关闭。
• open/closing文件若约 24 小时无活动会被视为废弃，随后被平台删除——上传后不及时 close 是数据丢失的常见原因。
• 关闭时，内容连同 types、details/links、可见性一起固化；但用户可编辑的元数据（name、properties、tags）仍可按权限管理。
• Record可以在需要可变结构化 details 时有意保持 open，但文档强调这属于例外：open record 会削弱可复现性，必须在文档中声明该例外。

4. 传输工具选型

文档给出的选型矩阵（data-operations.md）：

官方建议在超过 50 MB 时使用 Upload Agent；凡是分片完整性校验与断点续传重要的场景，都应使用平台传输代理而非自己拼 HTTP 请求。

5. 小规模传输：dx upload / dx download

上传（附带属性与标签，见>dx upload "sample.fastq.gz" \ --path "project-xxxx:/raw/sample.fastq.gz" \ --property "sample_id=S001" \ --tag "raw"

下载：

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

三条实操纪律：

• 始终使用带引号的完整路径（project-xxxx:/folder/name）；名字不唯一时改用对象 ID。
• 脚本化场景使用--brief或机器可读输出，不要解析人类格式化的表格。
• 当前版本dx在下载（或生成下载 URL）指向被标记为恶意的文件时会发出警告。文档将其定义为停止条件：除非用户批准一套防止执行并保护本地系统的遏制流程，否则不要继续。这与 SKILL.md “Current Platform Guidance” 中“恶意文件警告视为停止条件”的表述一致，对应的平台能力是 2026-06-09 起文件下载 API 暴露securityStatus字段（见 sources.md 的基线变更列表）。

6. Upload Agent（ua）

Upload Agent 是可断点续传的并行连接上传器。文档列出的关键行为（data-operations.md）需要逐条理解：

• 未压缩文件默认会被压缩，远端文件名自动追加.gz；
• 已压缩输入不会被二次压缩；
• --do-not-compress保留原始字节与命名行为（字节级保真场景必须加）；
• 重复执行相同命令会续传匹配中的未完成传输——这就是“同一命令可重入”的幂等性；
• --wait-on-close阻塞直到上传的文件对象完成 close；
• 平台对每个分片校验Content-MD5。

标准示例：

ua \ --project "project-xxxx" \ --folder "/raw" \ --wait-on-close \ --progress \ "sample.fastq.gz"

必须原样保留字节与文件名（例如参考基因组）时：

ua \ --project "project-xxxx" \ --folder "/raw" \ --do-not-compress \ --wait-on-close \ "reference.fa"

两个安全要点：

1. 不要在捕获输出中运行ua --env，它会打印当前 token。同理，任何 Upload Agent 的--auth-token值与DX_SECURITY_CONTEXT都应按秘密处理（authentication.md 明确禁止打印/记录/提交 token 材料）。
2. --do-not-resume只应在你有意制造第二份副本时使用；否则应让代理自动续传中断的上传。

7. Download Agent

Download Agent 消费BZIP2 压缩的 JSON manifest。文档要求：manifest 由官方dnanexus/dxda发布包中的 manifest 生成工具产出，并在启动数据外发（egress）前审阅其解析出的文件集合。

凭据行为有一个容易混淆的点：Download Agent 检查秘密变量DX_API_TOKEN，缺失时回落到~/.dnanexus_config/environment.json。这是 Download Agent 专属变量，不要假设它能为 Upload Agent、dx或dxpy提供配置——dx/dxpy消费的是DX_SECURITY_CONTEXT（authentication.md 的“tool-specific variable names”一节给出了完整的变量名对照）。

dx-download-agent download "manifest.json.bz2" dx-download-agent progress "manifest.json.bz2" dx-download-agent inspect "manifest.json.bz2"

inspect会用 manifest 中的校验和重新验证已下载分片；若分片缺失或损坏，重跑download即可（可续传）。

大下载前的检查清单（文档原文六项，全部保留）：

• 确认本地可用磁盘空间；
• 确认数据外发的审批与费用；
• 确认下载限制 / TRE 策略；
• 确认所有文件为live且closed（归档或开放中的文件无法按预期下载）;
• 审阅 manifest 中是否有意外项目或 PHI 数据；
• 使用一个在预期传输时长内保持有效的 token（未显式设置过期的 token 默认一个月失效，且撤销 token 会立即终止其关联的进行中传输与 job）。

最后一条运维红线：不要把 API token 放进 Docker 命令行或已提交的 compose 文件。

8. Python 传输：dxpy 上传、下载与流式读取

完整示例（data-operations.md）：

from pathlib import Path import dxpy project_id = "project-xxxx" remote = dxpy.upload_local_file( "sample.fastq.gz", project=project_id, folder="/raw", properties={"sample_id": "S001"}, tags=["raw"], wait_on_close=True, show_progress=True, ) dxpy.download_dxfile( remote, str(Path("downloads") / "sample.fastq.gz"), project=project_id, show_progress=True, )

结合 python-sdk.md 中记录的 0.410.0 已验证签名，可以补充参数细节：

• upload_local_file(filename=None, file=None, media_type=None, keep_open=False, wait_on_close=False, use_existing_dxfile=None, show_progress=False, write_buffer_size=None, multithread=True, **kwargs)——filename与file二选一；wait_on_close=True在下一步依赖 closed 对象（如提交 job 输入、克隆）时尤其有用；
• 下载侧的project参数不只是路由提示，它影响计费/上下文归属：当同一文件在多个项目中存在副本、或计费上下文重要时必须显式传入。

流式读取远端文件：

import dxpy with dxpy.open_dxfile("file-xxxx", project="project-xxxx") as stream: first_chunk = stream.read(1024)

这里有一个历史陷阱值得强调：DXFile.open_file()不是当前 dxpy 的方法，必须使用dxpy.open_dxfile()。这一点在 sources.md 的“Corrected Legacy Patterns”表中被列为已修正的遗留模式，仓库还内置了离线自检脚本把它固化为检查项：

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

该脚本（inspect_dxpy.py）离线检查一组必需符号（含dxpy.upload_local_file、dxpy.download_dxfile、dxpy.open_dxfile、dxpy.find_data_objects等）与各 handler 关键方法（DXFile.clone、DXProject.list_folder等），并在--strict模式下于基线不满足时以非零码退出，报告中还包含DXFile.open_file的遗留探测项。它不认证、不发网络请求，适合在升级 dxpy 后先跑一遍再改代码（其报告整形与版本比较逻辑由 test_scripts.py 的单元测试覆盖）。

9. 搜索：dx find data 与 find_data_objects

9.1 CLI

dx find data \ --class file \ --path "project-xxxx:/results" \ --name "*.bam" \ --name-mode glob

当前安装的 toolkit 的过滤标志以dx find data --help为准——这是文档对版本漂移的明确免责声明。

9.2 dxpy

import dxpy results = dxpy.find_data_objects( classname="file", project="project-xxxx", folder="/results", recurse=True, name="*.bam", name_mode="glob", state="closed", archival_state="live", describe={ "fields": { "name": True, "size": True, "created": True, "archivalState": True, "properties": True, } }, limit=500, ) for result in results: print(result["id"], result["describe"]["name"])

python-sdk.md 中记录的find_data_objects已验证签名与文档的“Critical semantics”合起来给出六条必须牢记的语义：

• name_mode默认是"exact"——直接传"*.bam"而不加name_mode="glob"是最高频的错误；"glob"支持*与?；"regexp"只允许经过评审、边界受控的模式；
• 结果返回的是生成器，dxpy 内部处理 API 分页；不传limit时会一直翻页直到遍历完整结果集，宽泛搜索务必用项目/文件夹/时间范围/limit收敛；
• describe会额外消耗 API 调用且可能暴露元数据，只请求需要的字段（describe=True返回完整默认描述，字段映射更安全）；
• archival_state过滤要求 file 类对象并提供 project/folder 作用域；
• tags语义为“同时具有全部指定标签”，旧参数tag已弃用；
• 时间戳参数接受 epoch 毫秒、相对现在的负毫秒数、以及"-2d"、"-1w"形式的相对字符串。

服务限流方面，文档引用了平台文档的两个数字：API 默认每页最多1000条；账号级200 次 API 调用/秒的上限。因此批量脚本应实现有界并发与指数退避，而不是压垮服务。

10. 元数据：properties 与 tags

properties 是字符串键值对，tags 是字符串集合（data-operations.md）：

import dxpy file_obj = dxpy.DXFile("file-xxxx", project="project-xxxx") file_obj.set_properties( { "sample_id": "S001", "pipeline_version": "2.4.1", } ) file_obj.add_tags(["validated", "release-2026-07"]) file_obj.rename("S001.aligned.bam")

两条治理约束：

• 项目包含 PHI 时，避免在 tags/properties 中写入直接标识符，遵循组织批准的元数据模型；
• 元数据更新直接影响检索与溯源。set_properties/set_details是整体替换语义（replace，而非 merge），覆写前必须审阅，共享 open record 上避免读-改-写竞争（python-sdk.md 也重申了这一点）。

DXFile的set_properties、add_tags、rename、clone、move、close均在本仓库 inspect_dxpy.py 的METHOD_GROUPS中被列为基线必检方法，升级 SDK 后可用--strict模式确认这些方法仍然存在。

11. Records：不可变审计记录与可变状态记录

创建 closed 不可变记录（推荐默认）：

import dxpy record = dxpy.new_dxrecord( project="project-xxxx", folder="/metadata", name="run-001", types=["RunMetadata"], details={ "pipeline": "rna-seq", "pipeline_version": "2.4.1", }, close=True, )

仅在确实需要持续变更时才创建 open record：

record = dxpy.new_dxrecord( project="project-xxxx", name="mutable-status", details={"state": "queued"}, close=False, ) record.set_details({"state": "running"}) record.close()

close 之后 details 与 links 固化。对于 append-only 溯源场景，文档给出的最佳实践是：创建新的版本化记录，而不是变更共享的 open record——这与第 10 节的替换语义互相印证。

12. Folders：创建、列举与移动

import dxpy project = dxpy.DXProject("project-xxxx") project.new_folder("/analysis/run-001/results", parents=True) listing = project.list_folder( "/analysis/run-001", describe={"fields": {"name": True, "state": True}}, )

移动操作按精确 ID 进行：

project.move( "/analysis/run-001/final", objects=["file-xxxx", "record-yyyy"], )

纪律：在把文件夹列表与数量展示给用户之前，绝不执行宽泛的递归操作。DXProject的describe、list_folder、new_folder、move、remove_objects、remove_folder同样在 inspect_dxpy.py 的基线检查范围内。

13. 克隆：跨项目复制的权限与限制

import dxpy source = dxpy.DXFile("file-xxxx", project="project-source") clone = source.clone( project="project-destination", folder="/imports", ) print(clone.get_id())

文档列出的要求与陷阱（data-operations.md），每一条都对应一个真实失败场景：

• 源对象必须closed；
• 源项目需要VIEW及以上权限，目标项目需要UPLOAD及以上（权限等级定义见 authentication.md 的认证失败检查表）；
• 受限项目/TRE 可以禁止克隆；
• 数据库（database）不可克隆；
• 隐藏的 linked 对象可能随可见父对象一起被克隆——影响面比看到的更大；
• 归档状态迁移可能阻塞克隆；
• 跨billTo克隆归档数据要求对象为 live；
• 克隆是独立副本：删除源不影响克隆。

当文件夹结构是第一接口时，用dx cp做项目间复制：

dx cp \ "project-source:/results" \ "project-destination:/imports"

执行前先确认：源、目标、文件数量、计费实体。

14. 归档与解归档

dx archive/dx unarchive是计费/存储相关且可能耗时较长的操作：

dx archive "project-xxxx:/old-results/sample.bam" dx unarchive "project-xxxx:/old-results/sample.bam"

归档前检查三件事：活跃工作流/协作者/已发布产物是否还需要它；所有副本与计费行为；目标是文件还是预期文件夹。解归档前检查：取回费用与必须的完成时限；文件回到live之前不要启动依赖它的 job。

编程接口是dxpy.api.project_archive()与dxpy.api.project_unarchive()，但文档明确建议：一次性、需要人工审阅的操作优先用 CLI。

15. 删除：不可逆操作的安全序列

数据删除在平台侧不可逆，且删除可见对象可能连带删除孤立的 hidden linked 对象。文档给出的安全序列（data-operations.md）：

1. 列出精确 ID；
2. 逐个 describe 对象；
3. 确认项目、文件夹、大小、状态与 linked 对象影响；
4. 请求用户确认；
5. 按 ID 删除；
6. 验证对象不存在，并在被删数据之外记录审计条目。

项目级保护是独立于对象删除的三层控制：

• protected=true：项目内数据删除限定为项目管理员；false时 contributor 也可删除；
• destroyProtected=true：无论请求者权限如何，阻止整个项目被销毁，直到授权管理员清除；
• 项目销毁移除全部对象；有活跃 job 时会失败，除非terminateJobs=true强制终止它们。

文档特别警告：绝不把清除destroyProtected、设置terminateJobs=true或销毁项目当作对象删除请求的隐含延伸——每一项都需要在列出活跃 job、项目保护、计费上下文与总数据影响之后单独获得显式授权。

Python 删除 API：

import dxpy project = dxpy.DXProject("project-xxxx") project.remove_objects(["file-xxxx"], force=False)

递归文件夹删除：

project.remove_folder("/obsolete/run-001", recurse=True, force=False)

文档原文对它的定性是危险的：“递归删除/会删掉容器全部内容，永远不要生成或执行该操作。”另有一个容易被忽略的 API 限制：单次文件夹删除请求最多移除 10,000 个对象，不要自动循环“删一批”而不重新核对剩余范围。项目删除、权限变更与委托overrideProjectAccess删除同样需要单独的显式授权。python-sdk.md 还补充了一条工程准则：不要用force=True来掩盖目标解析错误。

16. 批量操作检查清单

文档收尾的清单（data-operations.md）是批量脚本的验收标准，十条全部保留：

• 限制结果数量与并发度；
• 变更前将目标 ID 列表物化并审阅；
• 保留机器可读的 manifest（源 ID 与目标位置）；
• 让操作可重启/幂等（Upload Agent 的同命令续传正是此原则的体现）;
• 不把重名当作同一对象；
• 上传后检查文件状态（是否已 closed）；
• 校验传输完整性（Upload Agent 的分片 Content-MD5、Download Agent 的inspect）；
• 捕获失败，但日志中不得出现凭据或敏感元数据；
• 对账：完成、跳过、失败三类 ID 分别核对；
• 尊重服务限制并使用指数退避。

17. 仓库内的验证资产

本篇引用行为均有仓库内证据链，可按路径继续深入：

升级 dxpy 前后的标准动作（来自 sources.md 的 Refresh Procedure）：核对 PyPI 版本 → 阅读平台发布说明 → 运行inspect_dxpy.py --strict→ 对比dx build/run/find的 help → 在沙盒项目实测代表性格式 → 更新日期与版本基线。不要仅凭记忆更新示例——这正是本仓库把基线日期、版本表和遗留模式修正表写入文档的原因。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills