地球科学数据下载技能

概述

本技能指导 AI Agent 使用本仓库中的下载脚本获取地球科学数据。

环境要求

• Conda 环境：earthkit
• 执行方式：所有 Python 脚本通过 conda run -n earthkit python <脚本路径> 执行
• 数据根目录：仓库根目录（即本项目所在目录）

数据集注册表

根据用户请求的数据类型，先读取对应的详细指南文件，再构造命令执行。

仅人工获取的数据集：仓库中另有 8 个数据目录（DTU_SeaIceDrift、ICESat-2、FAO_DesertLocust、MOSAiC_TSX、NE_Greenland_S1、CNECT、ETOPO、HWSD）为人工获取的数据，无下载脚本，不在本技能管理范围内。

工作流程

1. 识别数据集：根据用户消息中的关键词匹配上表中的数据集
2. 读取详细指南：用 view 工具读取本技能目录下对应的 .md 文件
3. 确认参数：如用户未指定年份、月份、变量等关键参数，主动询问
4. 构造命令：按照详细指南中的参数格式和示例构造下载命令
5. 执行下载：通过 bash 工具运行命令，监控输出

重要约定

• 下载任务通常耗时较长，使用 bash 的 mode="sync" 执行，设置合理的 initial_wait
• 除 Climate_Indices 外，所有脚本支持断点续传（task_state*.json），中断后重新运行会跳过已完成的文件
• 状态文件存储位置：状态文件保存在各数据集脚本所在目录下，命名规则因脚本而异：
  • ERA5：ERA5/task_state.json（单文件，所有任务共用）
  • OSISAF：OSISAF/task_state.json（单文件，按 产品/年/月/文件 键区分）
  • CMIP6：CMIP6/task_state_{model}_{experiment}.json（按模型+实验组合隔离）
  • GLDAS：GLDAS/task_state_{dataset}.json（按数据集隔离）
  • MODIS：MODIS/task_state_{dataset}.json（按数据集隔离）
  • GLASS：GLASS/task_state_{product}_{sensor}_{resolution}.json（按产品+传感器+分辨率组合隔离）
• ERA5 下载需要 CDS API 凭据（ERA5/api.json），首次使用需提示用户配置
• 除 Climate_Indices 外，所有脚本均支持 --progress 参数显示 tqdm 进度条与预估完成时间（仅供终端手动运行）

代理与网络

本机长期运行系统代理（通过 HTTP_PROXY / HTTPS_PROXY 环境变量），但数据下载通过代理转发不稳定（长连接易断、SSL 中间人错误）。因此所有下载脚本默认绕过系统代理直连数据源。

• 所有脚本均提供 --proxy 参数：不加时绕过代理直连，加上后走系统代理
• Agent 调用下载脚本时，禁止添加 --proxy 参数，始终使用默认直连
• 新增下载脚本时必须遵循此约定（详见 add-new-dataset.md）

Agent 调用规则

• Agent 调用下载脚本时，禁止添加 --progress 参数。 进度条和 ETA 仅供人类在终端直接运行时使用；Agent 通过日志输出监控进度即可。
• Agent 调用下载脚本时，禁止添加 --proxy 参数。 始终使用默认直连模式。
• 当用户在终端手动运行脚本、或明确要求看到进度条时，才建议加上 --progress。

变量与产品开放性

• ERA5：脚本接受 CDS API 支持的任意单层变量名（通过 JSON 配置文件的 variables 字段传入）。技能文档中列出的变量仅为常用推荐，不构成硬性限制。用户如需其他变量，直接填入配置即可。
• OSISAF：脚本通过产品注册表（PRODUCTS 字典）管理已支持的产品 ID。当前已注册 10 个产品，覆盖密集度、漂移、边缘、类型四大类。新增产品需在代码中添加 ProductSpec 条目。
• GLDAS：数据集（-d）、变量和年份均为必填参数，不设默认值。可用 --list-datasets 查看 18 个数据集，--list-variables -d <数据集> 查看变量。空间范围可选，不指定时下载完整覆盖范围。
• MODIS：数据集（-d）和年份为必填参数，不设默认值。可用 --list-datasets 查看 12 个 CMG 0.05° v061 产品，覆盖植被指数、地表温度/发射率、反照率/BRDF、土地覆盖四大类。每个产品下载完整 HDF4 粒度，不支持变量或空间子集。
• CMIP6：支持 CMIP6 项目下任意模型/实验/变量组合。6 个发现命令（--list-models / --list-experiments / --list-frequencies / --list-variants / --list-variables / --list-grids）可逐级浏览可用数据。3 个可选过滤器（--activity / --table / --institution）进一步约束查询范围。下载时模型、实验、变量、集合成员、频率均为必填。