scientific-databases：按域聚合的科研数据库检索规程

目的

把用户的专业数据需求路由到 references/connectors.yaml 中登记的 connector（MCP server 或直连 HTTP API），执行检索，把结果统一为 PaperDocument（文献类）或结构化 JSON（数据类）落盘，供下游技能使用。

核心原则与 literature-search 一致：诚实路由、失败留痕。此外本技能多一条 硬约束——fail-closed 合规门禁：凡是 connectors.yaml 里没有登记、 或登记为 deferred 的 connector，一律不得使用；宁可停下来告诉用户 "这个源当前不可用及原因"，也不临时找表外替代品静默顶替。

前置检查

1. references/connectors.yaml 存在且可读；它是 connector 合规的唯一 权威清单。
2. 网络可用；离线时直接说明无法检索并终止。
3. 用户需求足够具体：若过于宽泛（如"查点材料数据"），先与用户收敛到 具体物质/指标/时间范围再执行。
4. 计算 slug：需求描述规范化（Unicode NFKC 规范化、转小写、去首尾空白、 连续空白折叠为单个空格）后取 sha1 十六进制摘要前 8 位。
5. 若需求实质是文献检索（找论文而非找数据），转交 literature-search，不在本技能内重复实现。

操作规程

1. license gate（任何检索之前必须执行）

• 在 references/connectors.yaml 中查找目标 connector 条目：
  • 表中没有该条目 → 停止。告知用户"该数据源未登记，按 fail-closed 原则不得使用"；如需新增，走 customize 流程先改表。
  • status: deferred → 停止。如实引用表中的 reason 字段说明暂缓 原因（如 KEGG 学术许可限制），不得尝试绕过或找镜像顶替。
  • status: needs-key → 检查对应 apiKeyEnv 环境变量是否已配置； 未配置则停止并给出配置指引（变量名、去哪申请），不替用户申请。
  • status: active → 放行。注意 tested: false 表示该条目尚未在本 仓库实测，首次使用应先小规模试运行（limit 调小），确认可用后再放量， 并把实测结果反馈给用户（建议其把 tested 改为 true）。
• license gate 的检查结果（哪个条目、哪个 status、放行还是停止）写入 manifest 的 license_gate 字段。

2. 路由：域 → 推荐 connector

路由决策与理由写入 manifest；用户也可直接指定 connector 跳过路由， 但 license gate 仍然必须过——指定表外 connector 与查不到条目同等处理。

3. politeness（礼貌访问）

• 请求速率 ≤ 2 req/s；批量任务在每次请求间至少间隔 0.5 秒。
• 遭遇 HTTP 429 / 503 时按指数退避重试（1s → 2s → 4s，最多 3 次）； 仍失败则记 rate_limited 留痕，不得当作"结果为 0"。
• 批量上限：单次任务默认 ≤ 50 条记录；需要更大批量时先向用户说明 数据源的速率政策并获确认（guardrail 第 8 条：联网批量下载属危险操作）。
• 带 User-Agent 发起直连 HTTP 请求；MCP server 类 connector 的速率由 其自身实现控制，但批量上限与危险操作确认规则同样适用。

4. 执行检索

• MCP 类 connector（paper-search / biomcp / open-meteo）：调用其暴露的 工具；工具不可用时（server 未启动、uvx 包不存在）如实记录错误，不伪装 成"无结果"。
• HTTP 类 connector（materials-project / fred / spaceweather / usgs-water）：按其官方 API 文档构造请求；接口字段以各官方文档为准， 解析失败按 upstream_changed 错误类型留痕。
• 逐源串行执行、逐源记录结果。

5. 失败结构化记录

任一 connector 返回错误或执行异常时：

• 在 manifest 的 errors 数组记录：connector、type（network / rate_limited / auth_missing / upstream_changed / parse）、 message；
• 回复中如实告知"X connector 本次失败及原因"；
• 查不到 ≠ 不存在：检索结果为 0 只说明"本次在该源未命中"，回复中 必须用这个措辞，不得推断"该物质/指标不存在"；
• 失败不静默：禁止产出空结果文件冒充成功。

6. 结果统一与落盘

• 文献类结果（biomcp、paper-search 返回的论文条目）：统一为 PaperDocument： {id, title, authors, year, venue, doi, url, abstract, source, retrieved_at} （source 为字符串数组）。
• 数据类结果（材料性质、经济序列、气象数据等）：保留该域原生结构， 包一层统一信封： {connector, query, domain, retrieved_at, records: [...]}。
• 落盘目录 output/scientific-databases/<slug>/latest/：
  • papers.json：文献类 PaperDocument 数组（有文献结果时）；
  • data.json：数据类结构化结果（有数据结果时）；
  • manifest.json：query、license_gate、路由决策、各源命中数、 errors、执行时间。
• 产物落盘后按工作区约定用 provenance-record 登记。

输出模板

data.json（数据类信封）

{
  "connector": "open-meteo",
  "query": "Beijing daily mean temperature 2020-2024",
  "domain": "气象",
  "retrieved_at": "2026-08-18T00:00:00+00:00",
  "records": [
    {"date": "2020-01-01", "tmean_c": -3.2}
  ]
}

manifest.json

{
  "query": "LiFePO4 band gap",
  "slug": "1a2b3c4d",
  "license_gate": {"connector": "materials-project", "status": "needs-key", "decision": "pass"},
  "routing": [{"connector": "materials-project", "reason": "材料计算性质"}],
  "hits": {"materials-project": 3},
  "errors": [{"connector": "fred", "type": "auth_missing", "message": "FRED_API_KEY 未配置"}],
  "executed_at": "2026-08-18T00:00:00+00:00"
}

本技能不做什么

• 不使用 connectors.yaml 之外的任何数据源（fail-closed）。
• 不绕过 deferred 条目的暂缓原因，不找镜像或替代品静默顶替。
• 不替用户申请或保管 API key；只检查环境变量是否已配置。
• 不做批量镜像式下载；超过批量上限的需求先确认再执行。
• 不把"检索结果为 0"表述为"数据不存在"，不把 connector 失败伪装成 "无结果"。
• 不做文献综述与论文级检索（交给 literature-search / literature-survey）。
• 不对数据做科学解释与结论判断；只负责取数与留痕。

收尾与下一步

1. 汇总：license gate 结果、各 connector 命中数、失败源及原因，5 行内 说明；结果为 0 的源用"本次未命中"措辞。
2. 指向 output/scientific-databases/<slug>/latest/ 下的产物文件。
3. 建议下一步：数据进 analysis 阶段处理；文献类结果可交给 literature-survey；needs-key 的源给出配置指引后等待用户配置。
4. 若全部 connector 均失败或被 gate 拦停，明确告知"本次检索整体未完成"， 不产出空文件冒充成功；需要新增 connector 时建议走 customize 流程 先更新 connectors.yaml。