Agent-native Scientific Data Acquisition Infrastructure 面向 AI Coding Agent 的科研数据获取基础设施 —— 自然语言 → 自动获取 → 验证 → 交付。
用户想拿到科研数据,通常要:查文档 → 读平台 API → 申请凭据 → 写脚本处理参数顺序/日期边界/变量映射 → 等排队 → 断点续传 → 核对文件是否完整 → 手工整理清单。每一步都容易出错,且过一年无法复现。
ResearchDataHub 把这件事变成一句话:
帮我获取 2015—2024 年中国区域的 ERA5 小时数据,包含温度、风场、云液态水和云冰水,保存到当前项目的
data/raw。
Coding Agent(Codex / Claude Code)通过 MCP 调用本系统,系统负责:
理解需求 → 发现数据源 → 检查数据集真实能力 → 检查环境与凭据 → 引导配置
→ 构建并校验请求 → 选择平台/节点/链路 → 真实下载 → 监控与重试
→ 完整性验证(六层)→ 交付到用户指定目录 → Manifest 与校验结果
边界很清楚:ResearchDataHub 只负责"把正确的数据取到正确的位置,并证明取数过程与结果可靠"。 拿到数据之后的 EDA、清洗、建模、绘图、论文撰写,不属于本项目,交给外部工具与 Agent。
从"CLI 数据采集框架"升级为 Agent-native 数据获取基础设施。以下每一项都已落地并有测试。
| 能力 | 说明 | 位置 |
|---|---|---|
| MCP Server + 18 工具 | 外部 Coding Agent 的唯一正式执行接口(stdio) | interfaces/mcp/ · docs/mcp.md |
| Agent Skills × 4 | data-discovery / environment-setup / data-acquisition / data-validation |
skills/ · docs/skills.md |
| 环境配置系统 | 5 个 Provider 的依赖/凭据/网络/磁盘检查 + 可操作引导 | environment/ · docs/environment-setup.md |
| 多节点 Worker 体系 | Worker 注册/心跳/健康、真实 Remote Worker 协议(7 端点,含 Range 回传) | network/ · docs/workers.md |
| 多链路 Route 选择 | 只凭实测性能打分;冷启动明说"无测量",禁止按地域推断速度 | ADR-0013 |
| Provider 契约 v1 | NASA Earthdata(CMR + EDL)、Copernicus Dataspace(STAC/OData + OAuth2) | providers/ |
| 需求级状态机 | 17 态覆盖 发现→评估→配置→计划→审批→执行→交付 | core/acquisition.py · ADR-0007 |
| 请求契约 v1.2 | 坐标顺序/日期边界/时区/频率/语义变量名→原生 ID 映射 | planner/request_v12.py · ADR-0012 |
| 交付到用户目录 | 数据落到用户指定的 ./data/raw,默认不覆盖 |
delivery/ · ADR-0015 |
| HMAC 审批令牌 | submit_acquisition 必须携带一次性、有期限、绑定计划指纹的令牌 |
interfaces/mcp/auth.py · ADR-0011 |
| # | 缺陷 | 严重性 |
|---|---|---|
| 1 | 交付路径缺失:数据只到 ~/.rdh/raw/,用户要求的 ./data/raw 从未被使用 |
🔴 功能性 |
| 2 | 签名凭据泄露到日志:CloudFront/S3 预签名 URL 的 Signature/token 被原样写入 transfer_logs 落盘 |
🔴 安全 |
| 3 | 认证头无法透传:RDH 无法下载任何需要 Bearer token 的科研数据(Earthdata 全部受保护资源) | 🔴 功能性 |
| 4 | 跨域重定向丢凭据:EDL 303 到签名地址后 401 | 🟠 功能性 |
| 5 | 审批闸门可绕过:PAUSED → QUEUED 能跳过 AWAITING_APPROVAL 直接入队 |
🔴 安全 |
| 6 | 科学校验从未生效:variable_present/time_coverage 因期望值不传而永远 SKIPPED |
🔴 可靠性 |
| 7 | 语义名↔原生名未桥接:声明 temperature 而文件是 t 时永远失败 |
🟠 功能性 |
| 8 | 规划器改写签名 URL:已完成的结果地址被改成 cds:// 模板 → 任务必然失败 |
🟠 功能性 |
| 9 | MCP 层 3 个 bug:协议帧写进 stderr / 令牌因 JSON 键序失效 / 幂等判断位置错误 | 🟠 可靠性 |
全部有回归测试锁定。逐条细节见 CHANGELOG。
完整报告:
docs/chain-speed-benchmark.md· 原始数据:benchmarks/speed/测于 2026-11-06,macOS arm64 / Python 3.13。对比对象是用户自己写的朴素下载脚本(不重试、不续传、不校验、不交付)。
| 链路 | 路径 | 样本 | 响应率 | 中位耗时 | P95 | 中位吞吐 |
|---|---|---|---|---|---|---|
| Earthdata(0.17 MB 受保护 granule) | baseline | 8 | 100% | 3.50 s | 7.62 s | 0.05 MB/s |
| RDH | 8 | 100% | 6.04 s | 6.77 s | 0.03 MB/s | |
| GEE(云端裁剪→Export→Drive) | baseline | 5 | 100% | 46.56 s | 75.34 s | 0.02 MB/s |
| RDH | 5 | 100% | 48.28 s | 85.49 s | 0.02 MB/s | |
| NCAR GDEX(58.3 MB NetCDF) | baseline | 8 | 88% | 15.75 s | 20.34 s | 3.53 MB/s |
| RDH | 8 | 100% ✅ | 14.18 s | 19.60 s | 3.92 MB/s |
- NCAR(大文件、CDN 有间歇断连):RDH 100% vs 88% —— 重试 +
.part三重自证续传把"从头再来" 变成"从断点继续",中位耗时反而更快。这是本项目最可复现、最有价值的提升。 - Earthdata(小文件):两者都 100%,RDH 慢 +2.5 s。这 2.5 s 是六层校验 + 原子提交 + 交付的 固定成本;换来的是"文件真的完整、有 SHA-256、有 Manifest 可回溯"。P95 反而更低(6.77 < 7.62), 说明框架开销稳定,而基线高分位由网络抖动主导。
- GEE(云端导出任务):瓶颈是 GEE 自己的排队(中位 46 s),RDH 只多 1.7 s(3.7%), 没有重复云端计算。
因此本项目不宣称"让下载变快"。它保证的是三件事: ① 失败能恢复(88%→100%)② 成功的数据经过验证(六层校验 + Manifest) ③ 固定成本可预期且随文件增大被摊薄。
签名凭据泄露到日志、认证头无法透传、跨域重定向丢凭据、规划器改写签名 URL —— 全部在真实链路跑测时暴露并修复(见 §1.5 表格 2/3/4/8)。
把下面这段整段复制给 Codex / Claude Code,它会自己完成安装和配置:
请帮我安装并配置 ResearchDataHub(科研数据获取基础设施):
仓库 https://github.com/Neiyako/ResearchDataHub
步骤:
1. git clone 到 ~/ResearchDataHub(若已存在则跳过),cd 进去
2. python3 -m venv .venv && .venv/bin/pip install -e ".[mcp,sci]"
3. 把 MCP Server 注册到你自己:
- Claude Code: claude mcp add researchdatahub -- <仓库绝对路径>/.venv/bin/rdh-mcp
- Codex: 在 ~/.codex/config.toml 加
[mcp_servers.researchdatahub]
command = "<仓库绝对路径>/.venv/bin/rdh-mcp"
4. bash scripts/install_skills.sh
5. 用 `.venv/bin/rdh version` 验证退出码为 0,然后告诉我 MCP 工具是否可见
注意:不要向我索要任何密码或 token;需要凭据时教我自己在终端 export。
装完后直接说需求即可,例如:
帮我获取 2015—2024 年中国区域的 ERA5 小时数据,包含温度、风场、云液态水和云冰水,保存到当前项目的
data/raw。
Agent 会按 Skill 自动走完:搜索数据源 → 检查数据集 → 检查环境 → 引导配置凭据 → 校验请求 → 生成计划 → 等你确认 → 下载 → 校验 → 交付路径与 Manifest。
git clone https://github.com/Neiyako/ResearchDataHub.git
cd ResearchDataHub
python3 -m venv .venv
.venv/bin/pip install -e ".[mcp,sci]" # mcp=Agent 接口, sci=NetCDF 校验
.venv/bin/rdh version # 退出码 0 即成功
bash scripts/install_skills.sh # 装 4 个 Skill需要 Python 3.12+(见 ADR-0010)。
cds依赖只在需要 CDS 取数时安装:pip install -e ".[cds]"。
cp configs/sources.example.yaml configs/sources.yaml
export CDSAPI_KEY="<你的 CDS 个人访问令牌>" # 凭据只以 env 引用出现,不写进 YAML
.venv/bin/rdh config validate # PASS,退出码 0
.venv/bin/rdh request validate examples/era5-request.yaml
.venv/bin/rdh plan create examples/era5-request.yaml
.venv/bin/rdh task run <plan_id> --max-tasks 1 --max-workers 1
.venv/bin/rdh report generate <request_id>需要凭据时,rdh 与 MCP 都会给出结构化、可操作的引导(配什么/为什么/去哪拿/存到哪/怎么验证),
见 docs/environment-setup.md。
本表是本项目唯一的能力口径。未验证的一律写
UNVERIFIED/NOT_RUN,不写进"已完成"。
| 能力 | 状态 | 证据 |
|---|---|---|
| MCP Server(stdio)+ 18 个工具 | ✅ | src/researchdatahub/interfaces/mcp/;tests/unit/test_mcp/ |
| 副作用授权(HMAC 审批令牌、一次性、防重放、指纹绑定) | ✅ | interfaces/mcp/auth.py;ADR-0011 |
结构化错误信封(code/hint/retryable) |
✅ | 同上 |
| Agent Skills × 4(discovery / env-setup / acquisition / validation) | ✅ | skills/;docs/skills.md |
| 在真实 Codex / Claude Code 会话中端到端验证 | NOT_RUN |
需用户本地安装后验证;工具协议层已由集成测试覆盖 |
| 平台 | 覆盖数据 | 状态 |
|---|---|---|
| Copernicus CDS | ERA5 / ERA5-Land / 气压层 / 单层 / 其他 CDS 集合 | ✅ 真实取数实测(2026-11-04,见 benchmarks/m6/);本轮未重测(ADR-0014:用户要求不做 cdsapi 抓取测试) |
| NSF NCAR GDEX (RDA) | 大气/气候/数值预报/地球系统科学 | ✅ 真实取数实测(1.13 GB 文件,10.5 MB/s) |
| NASA Earthdata (CMR) | MODIS / VIIRS / 对地观测 | 🟡 目录查询与能力声明已实现;真实下载 UNVERIFIED(需 EDL 账户) |
| Copernicus Data Space | Sentinel 系列(STAC / OData) | 🟡 目录查询与 OAuth2 已实现;真实下载 UNVERIFIED(需 CDSE 账户) |
| Google Earth Engine | 遥感影像 / 土地覆盖 / 植被指数 | ⬜ 未实现(需 GEE 项目权限;且只做筛选/裁剪/导出,不做分析) |
| NOAA / USGS / PANGAEA / Zenodo / AWS Open Data | — | ⬜ 未实现(Provider 架构已预留) |
| 能力 | 状态 | 说明 |
|---|---|---|
| 本地 Worker | ✅ | 适配既有调度器执行路径 |
| 远程 Worker 协议(7 端点,含 Range 回传) | ✅ 本机环回验证 | tests/integration/test_network_remote.py:真实子进程 + 真实 HTTP + 真实 sha256 |
| 真实公网远程节点 | NOT_RUN |
需要一台可部署的服务器 |
| 多链路 Route 选择(仅凭实测打分) | ✅ | ADR-0013;禁止按地域推断速度 |
| 故障转移 / 重试 / 取消 / 超时 | ✅ | network/routes/failover.py |
| HTTP / HTTP Range / S3 / CDS API 传输 | ✅(S3 端到端 NOT_RUN) |
transfer/ |
| FTP / SFTP / Globus / Zarr | ⬜ 未实现 | 不虚构路径规则 |
| 能力 | 状态 |
|---|---|
| 六层校验(存在/大小/SHA-256/格式/NetCDF/科学语义) | ✅ |
time_coverage(时间轴覆盖)与 variable_present(含语义名→原生名映射) |
✅ 本轮实现 |
断点续传(.part + 大小/校验器/来源身份三重自证) |
✅ |
| staging → raw 原子提交 + 隔离区(不删除坏文件) | ✅ |
| 交付到用户指定目录(默认不覆盖,冲突返回结构化选项) | ✅ 本轮实现,ADR-0015 |
| Manifest / 交付清单 / 采集报告 | ✅ |
| 场景 | 结果 |
|---|---|
A:ERA5 全链路(契约→计划→审批→下载→校验→交付 ./data/raw) |
✅ |
| B:NCAR 全链路(免认证→下载→验证→交付) | ✅ |
| C:缺凭据 → 引导配置 → 复验 → 继续 | ✅ |
| D:节点失败 → 明确失败(不产生文件记录、不冒充成功) | ✅ |
E:传输中断 → 续传(断言真实 Range 请求)→ 最终一致 |
✅ |
| F:目标已存在 → 不覆盖 → 用户选择 | ✅ |
┌─ Layer 1 Agent Integration ─────────────────────────────────┐
│ MCP Server (18 tools) · Tool Schemas · Agent Skills × 4 │
│ Environment Setup Guidance · Approval (HMAC) │
└───────────────────────────┬──────────────────────────────────┘
│ 只做入参校验 + 调 Core service
┌─ Layer 2 Acquisition Core ──────────────────────────────────┐
│ Discovery · Metadata · Assessment · Request Builder │
│ Validator · Planner · Provider/Route Selection · Verify │
└───────────────────────────┬──────────────────────────────────┘
│
┌─ Layer 3 Providers ────────┴────────────────────────────────┐
│ CDS · NCAR GDEX · NASA Earthdata · Copernicus Dataspace │
│ (每个 Provider 如实声明能力:支持什么、不支持什么) │
└───────────────────────────┬──────────────────────────────────┘
│
┌─ Layer 4 Execution Network ─────────────────────────────────┐
│ Worker Registry · Local/Remote Worker · Route Manager │
│ Scheduler · Transfer Engine · Retry · Task Queue │
└───────────────────────────┬──────────────────────────────────┘
│
┌─ Layer 5 Storage & Integrity ───────────────────────────────┐
│ SQLite Manifest · Task DB · Checksum · Manifest · Logs │
│ Credential References(只存引用,不存值) │
└──────────────────────────────────────────────────────────────┘
四条不可让步的约束:
| 约束 | 含义 | 决策 |
|---|---|---|
| Source ≠ Transport | 数据源知道"哪里有数据",传输层知道"怎么搬字节" | ADR-0002 |
| Manifest First | SQLite 是唯一事实来源,不靠扫目录判断进度 | ADR-0003 |
| Integrity Before Delivery | 未经校验不得标记完成 | ADR-0006 |
| Preserve Original Data | 原始数据只读,坏文件进隔离区而不是删除 | ADR-0005 |
Core 不依赖 LLM:Agent 负责理解自然语言,Core 只做真实执行。MCP 是唯一执行接口,Skill 是流程知识分发机制。
| 状态机 | 位置 | 描述什么 | 状态数 |
|---|---|---|---|
| 传输任务态 | core/state.py |
一个远端文件 → 一次字节搬运 + 校验 | 12 |
| 需求生命周期态 | core/acquisition.py |
一次用户请求:发现→评估→配置→计划→审批→执行→交付 | 17 |
二者并列不合并(ADR-0007):
一次需求在 PLANNING 后展开为 N 个传输任务,EXECUTING/TRANSFERRING/VERIFYING 段是聚合态。
需求级:CREATED → DISCOVERING → ASSESSING → VALIDATING → PLANNING
→ AWAITING_APPROVAL → QUEUED → EXECUTING → TRANSFERRING → VERIFYING → COMPLETED
异常态:NEEDS_CLARIFICATION / NEEDS_CONFIGURATION / PARTIALLY_SUPPORTED / FAILED / CANCELLED / PAUSED
任务级:PENDING → PLANNED → QUEUED → RUNNING → VERIFYING → COMPLETED
↘ RETRY_WAIT ↗ ↘ QUARANTINED
schema_version: "1.2"
dataset:
provider: cds
dataset_id: reanalysis-era5-pressure-levels
product_family: ERA5
selection:
variables:
- name: cloud_liquid_water # 语义名(CF 风格),不是平台变量 ID
units: kg m**-2
provider_native: {cds: clwc} # 显式映射槽;Provider 负责真实映射
temporal:
start: "2015-01-01"
end: "2024-12-31" # 纯日期 → 次日 00:00 UTC(闭开区间,包含 12-31 全天)
frequency: hourly
spatial:
type: bounding_box
bounds: [73, 18, 135, 54] # 固定顺序 W, S, E, N(CDS 是 N,W,S,E,转序集中在一处并强制测试)
output:
format: netcdf
destination: local
path: ./data/raw # 数据必须落在这里(ADR-0015)详见 ADR-0012 与 planner/request_v12.py。
- 凭据只以引用形式出现:
env:VAR/file:~/.cdsapirc/keyring:service/user。 - 任何 MCP 返回、日志、Manifest 都不含 secret:
environment包只返回present: true/false, 有 7 个 sentinel 专项用例断言 secret 不出现在任何序列化形式里。 - 不要求用户把 token 发到聊天窗口:Agent 引导用户在终端自行配置。
- 有副作用的操作需要审批令牌:
submit_acquisition必须携带由create_execution_plan签发的 HMAC 令牌(一次性、有期限、绑定计划指纹)。 - 默认不覆盖用户文件:冲突时返回
overwrite/skip/suffix三个选项由用户决定。
已知局限(如实声明):令牌机制保证"计划未被篡改且只执行一次",但无法在协议层证明 "用户确实点了确认"——真正的用户确认由 Skill 在提示词层强制。见 ADR-0011。
.venv/bin/python -m pytest -q # 1735 passed, 30 deselected(默认离线、可重复)
.venv/bin/python -m pytest -m network -q # 真实外网(需凭据,默认不跑)
.venv/bin/ruff check src tests
.venv/bin/ruff format --check src tests
.venv/bin/mypy src30 个 network 用例默认不跑:外网抖动算进 CI 红/绿会让"测试通过"失去意义。
EDA / 清洗 / 分析 / 可视化 / 机器学习 / 模型训练 / 科研结论推断 / 论文生成 / 独立聊天 Agent / 内置 LLM 推理 / 通用 Python 分析 SDK / 面向普通用户的 Web 下载平台。
也不引入 Redis / Kafka / Kubernetes / PostgreSQL —— 本地运行保持轻量,适配低内存设备。
| 文档 | 内容 |
|---|---|
| INSTALL_PROMPT.md | 给 Agent 的安装提示词(整段复制即可) |
| roadmap.md | 里程碑真实状态 + 未完成项与阻塞原因 |
| chain-speed-benchmark.md | 三条链路效率实测对比(Earthdata / GEE / NCAR) |
| repository-audit.md | M0 仓库审计:保留/修改/删除/新增判定 |
| decisions/ | 15 份 ADR(两层状态机、审批模型、请求契约、链路选择、交付路径…) |
| architecture.md | 主数据流、线程/事务边界、模块职责 |
| mcp.md | MCP Server 安装、18 个工具、错误码、审批流程 |
| skills.md | 四个 Agent Skills 的安装与使用 |
| environment-setup.md | 环境检查与配置引导 |
| workers.md | Worker/Route 部署、远程 Worker 协议 |
| data-contract.md | 契约模型、科学等价性、版本策略 |
| data-integrity.md | 六层校验、checksum 策略、原子提交 |
| recovery.md | 租约/心跳/崩溃恢复/对账 |
| operations.md | 部署、日常流程、故障处置 |
| testing-strategy.md | 测试分层、覆盖率、盲区 |
| M6-efficiency-benchmark.md | 效率基准(CDS / NCAR / 混合,实测) |
| adr/ | M0–M6 历史 ADR(0001–0006,仍然有效) |
ResearchDataHub/
├── src/researchdatahub/
│ ├── core/ # 契约层:models / errors / state(任务态)/ acquisition(需求态)/ ports
│ ├── interfaces/mcp/# MCP Server + 18 tools + 审批令牌
│ ├── environment/ # 依赖/凭据/网络/磁盘检查与配置引导
│ ├── providers/ # 数据集目录与能力层(Earthdata / Copernicus …)
│ ├── network/ # Worker 注册/心跳/健康、Remote Worker 协议、Route 选择
│ ├── planner/ # 需求 → 计划(含版本化请求契约 v1.2)
│ ├── sources/ # CDS / NCAR 资产发现适配器
│ ├── scheduler/ # 调度、租约、心跳、恢复
│ ├── transfer/ # http / s3 / cds_api 传输与续传
│ ├── integrity/ # 六层校验
│ ├── delivery/ # 交付到用户目录(不覆盖)
│ ├── storage/ # staging / raw / quarantine / archive
│ ├── manifest/ # SQLite 持久化
│ └── reporting/ # 交付清单与报告
├── skills/ # 四个 Agent Skills
├── configs/ examples/ scripts/ benchmarks/
├── docs/ # 架构、契约、决策、路线图
└── tests/ # unit / integration(1735 项)
- 许可证:MIT
- 引用:CITATION.cff
- 变更记录:CHANGELOG.md
本项目如实区分「已验证 / 未验证 / 未实现」三类状态;未测试的能力不会出现在"已完成"里。