usgs-water-iv-fetch

用途

本技能用于检索 USGS WaterServices 的瞬时站点观测数据（instantaneous station observations）。它通过天工 CLI 中由 CLI 拥有的 usgs.water-instantaneous-values 能力完成实际数据获取。技能本身只负责意图路由与结果使用边界；源发现、输入/输出模式、HTTP 行为、限制、校验和回执均由 CLI 负责。

主要能力

支持按一个有界数值区域（boundingBox）或一份明确的站点列表（siteNumbers）进行空间选择。
支持按一个有时限的时间段（period）或一对显式的 start/end 时间窗口进行时间选择。
可指定参数代码（parameterCodes）、站点类型（siteType）和站点状态（siteStatus）。
输出为 tiangong.data.run-result.v1 信封，包含契约、警告、错误和回执。

使用方式

运行前需先读取 references/tiangong-data-requirement.json，并使用调用方或工作区解析出的稳定 CLI。该需求文件声明兼容的能力与操作契约主版本，但不选择包构建。

先运行 data describe，仅当能力 ID 与所需契约主版本匹配时才继续，并将该响应中当前的能力/操作版本复制到运行请求中。随后运行默认的静态 doctor；除非用户明确要求探测提供方，否则不要添加 --live。

tiangong-ai data describe usgs.water-instantaneous-values --json
tiangong-ai data doctor usgs.water-instantaneous-values --json

使用返回的 Discovery Metadata 确认当前源覆盖范围、新鲜度、退役状态、限制、provides 与 doesNotProvide。若任务需要超出旧版服务生命周期的操作，优先使用现代 USGS Water Data 能力。USGS 目前警告称，在计划于 2027 年第一季度退役之前，2026 年下半年为退役做准备期间可能包含有意的降级或中断；应将此类失败视为提供方接口可用性问题，而非水观测数据不存在的证据。

构造 tiangong.data.run-request.v1 信封，并用同一 data describe 响应中的确切版本替换两个版本占位符。在 input 下，空间选择器（boundingBox 或 siteNumbers）只能选一个，时间选择器（period 或成对的显式 start/end 窗口）也只能选一个：

{
  "schemaVersion": "tiangong.data.run-request.v1",
  "capabilityId": "usgs.water-instantaneous-values",
  "capabilityVersion": "<describe.manifest.capabilityVersion>",
  "operationId": "fetch",
  "operationVersion": "<describe.manifest.operations[0].operationVersion>",
  "input": {
    "boundingBox": {
      "minLongitude": -77.3,
      "minLatitude": 38.8,
      "maxLongitude": -77.0,
      "maxLatitude": 39.1
    },
    "period": "P1D",
    "parameterCodes": ["00060", "00065"],
    "siteType": "ST",
    "siteStatus": "active"
  }
}

使用同一 data describe 响应返回的操作输入模式来获取当前字段语义与限制。保留站点和参数标识符中的前导零。不要从地名推断站点编号，不要在未经用户意图的情况下扩大区域或时间范围，也不要混用模式声明为互斥的选择器。经审查的契约最多接受 100 个精确站点 ID、一个坐标跨度乘积不超过 25 平方度的 bbox，以及 1 至 8 个参数代码。period 必须是正的 ISO-8601 时长；不要使用零时长、不要附加空的 T，也不要将周表示法与其他时长分量混用。

运行：

tiangong-ai data run usgs.water-instantaneous-values fetch \
  --input /absolute/path/to/request.json --json

该命令输出 tiangong.data.run-result.v1 信封。将结果交给其他工作流时，需连同数据一起保留其契约、警告、错误和回执。

结果边界

将限定符 P 和 provisional: true 视为提供方警告，表示数值可能变化；在任何下游使用中保留限定符。
将 partial 视为归一化覆盖不完整，并报告受影响的序列或值路径。不要将缺失或无效观测转换为零。
将 blocked 视为无可用业务结果，并呈现结构化错误，而不是静默扩大查询或绕过限制。
报告记录数限制导致的截断；不要暗示截断结果是详尽的时间序列。
零结果或稀疏的提供方结果可能反映选择器选择、活动状态、站点/参数覆盖、中断或本地数据保留限制；它不能证明河流流量、水位变化或洪水影响不存在。一些未经质量保证的业务参数（如温度或降水）可能被负责的 USGS 中心限制为 120 天或更短。
不要从原始站点观测推断洪水水位、重现期、警报状态、危害、原因或政策含义。
跨源比较和研究证据采纳属于调用方或 Auto Research，而非此原子技能。

参考

references/tiangong-data-requirement.json：稳定的能力需求；它不是包锁。

技能介绍

用途

主要能力

使用方式

结果边界

参考