⚡

Earth2Studio数据源创建与验证Skill earth2studio-create-datasource

该技能用于创建并验证 Earth2Studio 数据源包装器（DataSource、ForecastSource、DataFrameSource、ForecastFrameSource），帮助连接 S3、GCS、Azure、HTTP、HuggingFace 等远程数据存储，涵盖词表映射、异步获取、测试验证、文档注册及 PR 流程。关键词：Earth2Studio、Earth2、数据源、DataSource、ForecastSource、DataFrameSource、远程存储、fsspec、气候数据、数据验证、异步获取、数据集成、Earth-2、预测数据。

气候预测 0 次安装 0 次浏览 更新于 9/6/2026
名称 earth2studio-create-datasource
版本 0.16.0
开源协议 Apache-2.0 metadata:
作者 NVIDIA Earth-2 团队 agent-skills@nvidia.com tags: - earth2studio - earth2 - python - data-source - forecast-source - integration
描述 > 创建并验证 Earth2Studio 数据源包装器（DataSource、ForecastSource、DataFrameSource、ForecastFrameSource），用于连接远程数据存储。请勿用于使用现有数据源获取数据、模型推理或安装任务。 argument-hint: 远程数据存储的 URL 或描述（可选）

创建并验证数据源

目的

为新的 Earth2Studio 数据源包装器实现端到端工作流，将远程数据存储（S3、GCS、Azure、HTTP、HuggingFace）连接到 Earth2Studio 的异步数据获取基础设施——从分析到实现、测试、验证和 PR 提交。

先决条件

  • 具备 uv 的 Earth2Studio 开发环境（uv run python 必须可用）
  • 已配置 Git 的 fork（origin）和 upstream（upstream）远程仓库
  • 可访问目标远程数据存储（如果是私有存储则需要凭证）
  • Python 3.10+

工作区

使用包含 pyproject.toml 的目录。对于 Harbor 评估，写入 /workspace/output/ 并保留路径。切勿读取 evals/targets/。

说明

Python 环境： 始终使用 uv run python 或本地 .venv。切勿直接使用系统 Python。

按顺序遵循每个步骤。

[确认] 门控： 只有步骤 1（源类型）和步骤 12（合理性检查图）需要用户明确批准。所有其他 [确认] 标记仅供参考——可内联呈现决策并继续，无需阻塞。

先交付产品： 在深入探索、文档、注册、CHANGELOG 或 PR 工作之前，先编写源文件和测试文件（步骤 6–7）。当用户仅要求实现时，跳过步骤 8–14。

完成之前： 在仓库根目录运行验证命令，使结果出现在会话日志中：

uv run pytest test/data/test_<source>.py -x
make format && make lint

保持简洁： 避免冗长的架构报告；用几句话总结决策，然后继续写入文件。

卡住或用户反馈： 如果代理在此技能使用过程中卡住或用户提供了更正，保守地审查技能的相关部分并改进。保持简洁。

一次只处理一种源类型。 对于伴随类型请再次调用。

参考文件

在相关步骤中按需加载：

文件 内容 加载时机
references/implementation-guide.py 带有 FILL 注释的骨架源代码 步骤 3–10
references/testing-guide.py 带有 FILL 注释的测试骨架 步骤 11
references/validation-guide.md 绘图模板、PR 正文模板、Greptile 处理 步骤 12–14（可选，用于模板）

工作流概览

步骤 0: 获取参考 → 步骤 1: 确定类型 → 步骤 2: 依赖
→ 步骤 3: 添加依赖 → 步骤 4: 创建词表 → 步骤 5: 更新 vocab/schema
→ 步骤 6: 创建骨架 → 步骤 7: 实现源 → 步骤 8: 注册
→ 步骤 9: 文档 → 步骤 10: CHANGELOG → 步骤 11: 测试
→ 步骤 12: 验证与绘图（用户确认） → 步骤 13: PR + 合理性评论
→ 步骤 14: Greptile 审查

第 0 步 — 获取远程数据存储参考

如果提供了 $ARGUMENTS，请使用它（URL → WebFetch；文件路径 → 读取）。

如果为空，请询问：

请提供远程数据存储的 URL、API 文档链接或描述。这将用于了解存储格式、访问模式、变量清单、时间/空间分辨率。

第 1 步 — 确定源类型

协议 返回 是否有 lead_time？ 用途
DataSource xr.DataArray 否 网格分析/再分析
ForecastSource xr.DataArray 是 网格预报
DataFrameSource pd.DataFrame 否 稀疏/站点观测
ForecastFrameSource pd.DataFrame 是 稀疏预报观测

关键因素：网格化 vs 稀疏 → DataArray vs DataFrame；分析 vs 预报 → Source vs ForecastSource。

[确认 — 源类型]

展示推荐类型及理由。请求确认。

第 2 步 — 检查远程存储并建议依赖

分析： 存储后端、文件格式、身份验证、访问模式、时间/空间分辨率、变量清单。

优先使用 fsspec：

后端 首选 避免
AWS S3 s3fs（核心依赖） 直接使用 boto3
GCS gcsfs（核心依赖） google-cloud-storage
Azure adlfs azure-storage-blob
HTTP fsspec（核心依赖） requests
HuggingFace huggingface_hub（核心依赖） 自定义脚本

仅在 fsspec 无法访问该存储时，才回退到专用库。

检查 pyproject.toml —— 只建议尚不存在的包。核心依赖包括：s3fs、gcsfs、fsspec、zarr、netCDF4、h5py、pygrib、huggingface-hub、pandas、pyarrow。

[确认 — 依赖与访问模式]

展示：后端、fsspec 文件系统、新包（含许可证）、认证方法。

第 3 步 — 添加依赖

从这里到步骤 10，请加载 references/implementation-guide.py。

如果需要新包：

  1. uv add --extra data <package>
  2. uv lock
  3. 使用 OptionalDependencyFailure 模式添加可选依赖导入

第 4 步 — 创建词表类

创建 earth2studio/lexicon/<source_name>.py，包含：

  • metaclass=LexiconType
  • VOCAB: dict[str, str]，将 E2S 名称映射到远程键
  • get_item(cls, val) 返回 tuple[str, Callable]
  • 对结构化键使用 :: 分隔符

将远程变量映射到 E2STUDIO_VOCAB（earth2studio/lexicon/base.py 中的 282 个条目）。

[确认 — 词表与变量映射]

展示：类名、键格式、完整映射表、修饰符、参考 URL。

第 5 步 — 更新 E2STUDIO_VOCAB / SCHEMA（如需要）

  • 新词表：地面 = 描述性缩写；气压层 = {name}{level}
  • 新模式字段：仅限 DataFrame 源；检查 E2STUDIO_SCHEMA

[确认 — 词表与模式更新]

如无需更新则跳过。

第 6 步 — 创建数据源骨架文件

遵循规范方法排序：

  1. 类常量
  2. SCHEMA
  3. __init__
  4. _async_init
  5. __call__
  6. fetch
  7. _create_tasks
  8. fetch_wrapper
  9. fetch_array
  10. _validate_time
  11. 辅助函数
  12. cache 属性
  13. available 类方法

对于并行执行，使用异步任务 dataclass 模式。

[确认 — 骨架]

展示：类名、文件路径、骨架代码、任务 dataclass。

第 7 步 — 实现数据源与测试

测试文件是同等重要的交付物。 在源文件旁边创建 test/data/test_<filename>.py。为异步源添加 test_<source>_call_mock。

同步源： 使用 prep_data_inputs/prep_forecast_inputs，直接调用 __call__。

异步源： 参见 references/implementation-guide.py 中要求的模式：_sync_async、managed_session、gather_with_concurrency、async_retry、纯异步 I/O、try/finally 清理。构造函数参数：cache=True、verbose=True、async_timeout=600、async_workers=16、retries=3。DataFrame 源需额外指定 time_tolerance。

第 8 步 — 注册源

  • earth2studio/data/__init__.py — 按字母顺序导入
  • earth2studio/lexicon/__init__.py — 按字母顺序导入
  • 验证 pyproject.toml 依赖

第 9 步 — 更新文档

  • 添加到正确的 RST 文件（datasources_analysis.rst / _forecast.rst / _dataframe.rst）
  • 类 docstring：Parameters、Warning（下载大小）、Note（参考 URL）、Badges（最后）
  • 所有公共方法：NumPy 风格 docstring

第 10 步 — 更新 CHANGELOG.md

在当前未发布版本下添加条目。参见 references/implementation-guide.py 中的 REGISTRATION CHECKLIST 获取格式。

每个源一行。不要为词表增加单独条目。

第 11 步 — 验证风格并扩展测试

运行 make format && make lint && make license。加载 references/testing-guide.py 获取测试骨架。所需测试：test_<source>_fetch（慢）、_cache（慢）、_call_mock、_exceptions、_available。使用 --slow 目标 90%+ 覆盖率。

[确认 — 测试]

展示：测试文件、函数、覆盖率。

第 12 步 — 验证变量与合理性检查

  1. 对照真实数据验证所有词表变量（运行脚本，不要提交）
  2. 移除有效数据 < 10% 的变量
  3. 创建合理性检查图（网格或稀疏模板）
  4. 告知用户图路径并请求视觉确认

[确认 — 合理性检查图]

用户必须目视检查图表。未经确认不得继续。

第 13 步 — 分支、提交并打开 PR

  1. 创建分支 feat/data-source-<name>
  2. 提交（不要添加合理性检查脚本/图片）
  3. 推送到 fork
  4. gh pr create --repo NVIDIA/earth2studio
  5. 立即将合理性检查验证作为 PR 评论发布，包含：
    • 变量覆盖表（名称、计数、范围、单位）
    • 数据验证摘要（区域、风暴/站点、时间范围）
    • 关键发现（物理上合理的值、转换已确认）
    • 完整验证脚本放在 <details> 块中
    • 图片占位符：<!-- Drag and drop sanity-check image here -->

[确认 — 准备提交]

在创建 PR 前确认所有步骤已完成。

第 14 步 — 自动代码审查

  1. 轮询 Greptile 审查（5 分钟超时）
  2. 对反馈进行分类（bug/风格/性能/文档/建议/误报）
  3. 向用户展示分诊表
  4. 实现已接受的修复
  5. 回复 PR 评论
  6. 推送

[确认 — 审查分诊]

用户批准要处理的评论。

示例

用户：为 S3 上的 NOAA GFS 分析添加一个数据源
代理：[加载技能，完成步骤 0–14]

限制

  • 每次调用只处理一种源类型
  • 验证需要网络访问（步骤 12）
  • 所有文件均需 SPDX 许可证头

提醒

做： uv run python、loguru.logger、__init__.py/RST/CHANGELOG 中按字母顺序排列、规范方法排序、异步工具（managed_session、gather_with_concurrency、async_retry）、纯异步 I/O、docstring 中的参考 URL、try/finally 清理。

避免： asyncio.to_thread、裸 tqdm.gather、用于加载的 xarray、完整文件下载。

绝不： loop.set_default_executor()、提交密钥、提交合理性检查脚本/图片。