Skip to content
Skills Library
Science & research · Automation

environment-setup

/environment-setup

在真正开始下载之前,检查并引导用户配置 ResearchDataHub 数据源所需的依赖与凭证(如 CDS 的 CDSAPI_KEY、NCAR/NASA 的认证),全程由用户自己在终端完成配置,Agent 绝不索取或打印任何密码或令牌。当采集前需要"这台机器能不能跑通"的判断、出现 MISSING_CREDENTIAL 类阻断、或用户问"怎么配置 CDS/Earthdata 凭证"时使用。

Licence
MIT
Last repository change
06.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 06.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

在真正开始下载之前,检查并引导用户配置 ResearchDataHub 数据源所需的依赖与凭证(如 CDS 的 CDSAPI_KEY、NCAR/NASA 的认证),全程由用户自己在终端完成配置,Agent 绝不索取或打印任何密码或令牌。当采集前需要"这台机器能不能跑通"的判断、出现 MISSING_CREDENTIAL 类阻断、或用户问"怎么配置 CDS/Earthdata 凭证"时使用。

Triggers from the description

这台机器能不能跑通怎么配置 CDS/Earthdata 凭证
Original author description

在真正开始下载之前,检查并引导用户配置 ResearchDataHub 数据源所需的依赖与凭证(如 CDS 的 CDSAPI_KEY、NCAR/NASA 的认证),全程由用户自己在终端完成配置,Agent 绝不索取或打印任何密码或令牌。当采集前需要"这台机器能不能跑通"的判断、出现 MISSING_CREDENTIAL 类阻断、或用户问"怎么配置 CDS/Earthdata 凭证"时使用。

How it works

  1. 1. 何时使用
  2. 2. 前置条件
  3. 3. 工具调用序列
  4. 4. 状态语义(必须按此话术对用户解释)
  5. 5. 输出给用户的模板(怎么配 / 为什么 / 去哪拿 / 存到哪 / 怎么验证)
  6. 6. 失败分支与恢复动作
  7. 7. 禁止事项(本 Skill 的红线)
  8. 8. 黄金路径中属于本 Skill 的步骤(第 6–8 步)
Original SKILL.md headings · 143 lines, 595 words
SKILL.md preview
---
name: environment-setup
description: 在真正开始下载之前,检查并引导用户配置 ResearchDataHub 数据源所需的依赖与凭证(如 CDS 的 CDSAPI_KEY、NCAR/NASA 的认证),全程由用户自己在终端完成配置,Agent 绝不索取或打印任何密码或令牌。当采集前需要"这台机器能不能跑通"的判断、出现 MISSING_CREDENTIAL 类阻断、或用户问"怎么配置 CDS/Earthdata 凭证"时使用。
metadata:
  type: workflow
  version: "1.0.0"
  stage: "2/4"
  next-skill: data-acquisition
---

# environment-setup —— 环境检查与凭证配置引导

> 四段式流程的**第 2 段**:`data-discovery` → `environment-setup` → `data-acquisition` → `data-validation`
> 本段的目标是回答**一个**问题:**"这台机器现在能不能为该 Provider 真正执行采集?"**
> 不行时给出「配什么 / 为什么 / 去哪拿 / 存到哪 / 怎么验证」四要素引导。

## 1. 何时使用

- `data-discovery` 已确认方案,进入采集前;
- 上一次采集报 `source_unavailable` / `not_available` 类错误且与"缺凭证/缺依赖/端点不可达"有关;
- 用户主动问"我要用 CDS/NCAR/NASA,需要准备什么"。

**不适用**:本地文件分析、纯概念问答、用户已明确说"我配好了直接用"(仍要跑一次 `validate_environment` 作为证据)。

## 2. 前置条件

- `rdh-mcp` 已连接;`--root` 指向的状态根已初始化(`rdh db init`)。
- **你(Agent)不能**替用户输入密码、不能读任何认证文件内容、不能把凭证写进任何输出。
  → 本 Skill 的全部动作是"**检查 → 解释 → 引导用户自己做 → 复验**"。

## 3. 工具调用序列

```text
① check_environment(provider, checks?, timeout_seconds?)
② get_environment_requirements(provider)          # 仅当 ① 不可用(usable=false)时
③ (用户自己完成配置)
④ validate_environment(provider, require_network?, checks?, timeout_seconds?)
```

### 3.1 `check_environment`(必填 `provider`)

| 参数 | 类型 | 说明 |
|---|---|---|
| `provider` | string | 如 `cds` / `ncar` |
| `checks` | array of `dependencies` \| `credentials` \| `network` \| `disk` | 只跑指定检查项;省略=全部 |
| `timeout_seconds` | number 0.1–120 | 单次网络/磁盘检查超时,默认 5 s |

返回(关键字段):`status`(`ok` / `needs_configuration` / `unavailable`)、`usable`(bool)、`summary`、
`report.requirements[]`(每项含 `name` / `kind` / `status` / `required` / `guidance` / `help_url` / `observed`)、
`report.errors[]`。
**会发起真实网络请求**(端点可达性 HEAD),但**不下载数据**。

### 3.2 `get_environment_requirements`(必填 `provider`)

返回 `requirements`(依赖 / 凭证引用 / 端点声明)与 `guide`:

```
guide.provider, guide.summary,
guide.steps[] = { action, why, where, verify }
```

`guide.steps` 就是官方的四要素引导,**直接逐条讲给用户**,不要自己编:
- `action`:要做什么
- `why`:为什么需要
- `where`:去哪拿 / 存到哪(含真实 URL 与文件路径模板)
- `verify`:怎么验证生效(通常是一条可复制的命令)

`requirements[].reference` 只包含**凭证引用**(`kind`: `env` / `file` / `keyring`,`name`: 变量名或路径模板)——
**只有名字,没有值**。请原样转述名字,绝不索取值。

### 3.3 `validate_environment`(必填 `provider`)

| 参数 | 类型 | 说明 |
|---|---|---|
| `provider` | string | 同上 |
| `require_network` | bool | 是否必须联网通过才算可用,默认 `false` |
| `checks` | 同上 | 省略=全部 |
| `timeout_seconds` | number 0.1–120 | 默认 5 s |

返回:`usable`(bool)、`status`、`blocking[]`(每项 `name` / `kind` / `status` / `guidance`)、`report`。
**只有 `usable=true` 才允许进入 `data-acquisition`。**

## 4. 状态语义(必须按此话术对用户解释)

| `status` | 含义 | 你该说什么 |
|---|---|---|
| `ok` | 全部必需要求已就绪 | 「这台机器可以执行该数据源的采集,继续下一步。」 |
| `needs_configuration` | 缺**可修复**的东西(依赖没装 / 凭证没配 / 端点暂时不可达) | 「还差 N 项,按下面 4 条做完就能用」+ 逐条给四要素 |
| `unavailable` | **结构性**不可用(必需端点 5xx、平台不支持),或用户显式跳过必需修复项 | 「当前环境结构性不可用,原因:…;换源或换机器」 |

> 口径来自实现:`unknown` 状态一律降级为 `needs_configuration`(不允许被忽略);
> 必需端点的 5xx 视为结构性失败 → `unavailable`。

## 5. 输出给用户的模板(怎么配 / 为什么 / 去哪拿 / 存到哪 / 怎么验证)

```markdown
### 还差 2 项才能开始采集(数据源:cds)

**① 缺少凭证 `CDSAPI_KEY`**
- 配什么:环境变量 `CDSAPI_KEY`,或写进 `~/.cdsapirc` 的 `key:` 一行
- 为什么:CDS 的检索与下载接口需要你的个人访问令牌(PAT)
- 去哪拿:https://cds.climate.copernicus.eu/ → 登录 → 用户页面的 API 令牌区
- 存到哪:你自己终端里 `export CDSAPI_KEY="..."`(不要发给我),或按官网写入 `~/.cdsapirc`
- 怎么验证:`rdh config validate`,看到 PASS 即可

**② Python 依赖 `cdsapi` 未安装**
- 配什么:`pip install "researchdatahub[cds]"`
- 为什么:CDS 的异步提交/轮询走 `cdsapi` 客户端
- 存到哪:你当前项目的虚拟环境(`.venv`)
- 怎么验证:`python -c "import cdsapi"` 无报错

配完告诉我「配好了」,我会重新跑一次 validate_environment 复验。
```

**每条必须四要素齐全**(配什么 / 为什么 / 去哪拿或存哪 / 怎么验证),缺一不可。

## 6. 失败分支与恢复动作

| 情况 | Agent 动作 |
|---|---|
| `check_environment` 返回 `not_available`(`data.capability` 指向 `environment` 包) | 说明"环境检查组件未安装",提示 `pip install -e ".[dev]"` 或确认安装方式;**不要**假装环境没问题 |
| `status=needs_configuration` | 调 `get_environment_requirements`,按 `guide.steps` 逐条输出四要素 |
| `status=unavailable` | 说明结构性原因(看 `report.requirements[].observed` 里的 `status_code`),建议换源或换机器;**不要**反复重试 |
| `validate_environment` 仍 `usable=false` | 只对 `blocking[]` 里的项给出**具体**下一步;不要笼统说"再试一次" |
| 用户说"我把 token 发给你" | **拒绝**:「请不要把令牌发给我,也不需要贴进对话;请在你自己的终端/配置文件里设置,我只做检查」 |
| 用户贴出疑似密钥的字符串 | 不要复述、不要保存、提示其轮换该密钥 |
| 错误码 `invalid_arguments` | 按 hint 修正参数名/取值(schema 顶层禁止未知字段) |
| 错误码 `config_error` | 提示检查 `rdh config validate` 与 `--root` 指向 |

完整错误码表见 `skills/data-acquisition/SKILL.md` §7。

## 7. 禁止事项(本 Skill 的红线)

1. **绝不索取、打印、上传任何密码 / token / API Key / 私钥内容。**
2. **绝不读取认证文件内容**(`~/.cdsapirc`、`~/.netrc`、`~/.config/earthengine/credentials` 等)——只检查**存在性**与**权限**。
3. **绝不替用户执行 `export`/写配置文件**——配置由用户在自己终端完成。
4. 不得把 `needs_configuration` 说成"环境不可用",也不得把 `unavailable` 说成"配一下就好"。
5. 不得在 `usable=false` 时继续进入 `data-acquisition`。

## 8. 黄金路径中属于本 Skill 的步骤(第 6–8 步)

> 承接 `data-discovery` 第 5 步用户确认后的需求:
> ERA5 气压层 2015-01-01→2025-01-01,`[73,18,135,54]`,变量 `clwc/ciwc/t/u/v`,层 1000/850/500,→ `./data/raw`

| 步 | 工具 | 传什么 | 期望返回 | 用户看到什么 |
|---|---|---|---|---|
| 6 | `check_environment` | `{"provider":"cds","checks":["dependencies","credentials","network","disk"]}` | `status`、`usable`、`requirements[]` | 「环境检查:缺 CDSAPI_KEY 与 cdsapi」 |
| 7 | `get_environment_requirements` | `{"provider":"cds"}`(仅当上一步 `usable=false`) | `guide.steps[]` 四要素 | 「怎么配 / 为什么 / 去哪拿 / 怎么验证」清单 |
| 8 | `validate_environment` | `{"provider":"cds","require_network":true}` | `usable:true`、`blocking:[]` | 「✅ 环境就绪,可以开始采集」 |

若第 8 步仍 `usable=false` → **停在这里**,把 `blocking[]` 逐条转成四要素引导,等用户回话;不要跳步。

Versions

RepositoryScoreLicence
This page · Neiyako/ResearchDataHub100MIT
autohandai/community-skills100Apache-2.0
akillness/jeo-skills95MIT

Database snapshot: 13.11.2026 · package version 1a10d6eee0c6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100data-discovery
    把用户用自然语言描述的科学数据需求解析成结构化需求,并在 ResearchDataHub 中搜索、检视、比较候选数据集,产出对比表让用户确认。当用户提到要下载/采集 ERA5、再分析、云水、温度、风场等气候或地球科学数据,或问"有没有某个数据集""哪几个数据集能满足这个需求"时使用。
  • 100smap-fetch
    Fetch NASA SMAP Enhanced L3 (SPL3SMP_E) daily 9 km volumetric surface soil moisture for a region and short date range via NASA Earthdata, as a weather-skills Zarr. Needs an Earthdata login. Use when a task needs gridded soil-moisture observations, e.g. for drought or…
  • 100data-acquisition
    在 ResearchDataHub 中把已确认的数据需求估量、生成执行计划、向用户展示计划并取得明确确认(计划带一次性 approval_token),然后提交采集任务并轮询状态,失败时按错误码做重试或取消。当用户已确认数据集与参数、要真正开始下载/采集,或要"估算这次要下载多少""把任务跑起来""查进度""取消任务"时使用。
  • 100earth-data-discovery
    Runs a discovery-first check before building anything - finds candidate NASA Earthdata collections, verifies granule availability for the requested region and period, inspects variables, services, software and citation information with the Earthdata MCP tools, searches the…
  • 100imerg-fetch
    Fetch NASA IMERG daily precipitation (global 0.1° grid) for a date range from NASA GES DISC via Earthdata login, as a weather-skills Zarr. Serves the daily Late (GPM_3IMERGDL, about 2 days behind) and Final (GPM_3IMERGDF, gauge-adjusted research quality) files. Use when a task…
  • 100cds-design-to-code
    Turn Figma designs into CDS React (cds-web) or React Native (cds-mobile) code. Use when the user shares a Figma design URL (e.g. `figma.com/design/...?node-id=...`) or asks to "implement this design" or "build this from Figma" in a frontend project that is using Coinbase Design…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.