air-chart

--- name: air-chart description: 查询全球城市空气质量（OpenAQ 监测数据）并生成高清 SVG 趋势图表。当用户要求"查看/对比某城市空气质量、PM2.5/PM10/臭氧等污染物走势、生成空气质量图表"时使用。支持单城趋势、多城对比（≤4 城）、单城多指标、同城多站点快照四种模式，自动优选活性政府参考级监测站，叠加 WHO 安全基准线，UTC 自动转站点当地时间。 --- # air-chart — 空气质量图表生成 Skill ## 能力概述 从自然语言查询到 SVG 图表的端到端闭环：城市解析 → OpenAQ 站点优选 → 数据清洗 → 矢量图表渲染。 零重型依赖：仅需 `bash`、`jq`、`awk`、`curl`（渲染器为纯 awk 实现，不依赖 Python/Node）。 ## 触发场景 用户提出以下意图时调用本 Skill： - "看看北京最近一周 PM2.5 走势" - "对比东京和首尔过去 7 天的空气质量" - "德里过去 30 天 PM10 日均值，和 WHO 标准对比出图" - "新加坡最近 48 小时臭氧和 PM2.5 的小时变化" - "生成某城市空气质量图表/折线图/对比图" ## 调用方式 ```bash scripts/air_chart.sh --city <城市> [--city <城市2> ...] [--param <指标>] [--period <跨度>] [选项] ``` ### 参数 | 参数 | 说明 | 取值 | | --- | --- | --- | | `--city, -c` | 城市名（内置约 200 个全球主要城市，支持大小写/别名模糊匹配），或直接传坐标 `"lat,lon"`。可重复，最多 4 个 | 如 `Beijing`、`New Delhi`、`39.9,116.4` | | `--param, -p` | 污染物指标，默认 `pm25`。单城可传多个，多城对比只能传一个 | `pm25` `pm10` `o3` `no2` `so2` `co` | | `--period, -t` | 时间跨度，默认 `7d`。`24h/48h` 按小时聚合，`7d/14d/30d` 按天聚合 | `24h` `48h` `7d` `14d` `30d` | | `--snapshot` | 快照模式：同城多个活性站点当前值横向柱状图（默认取前 6 个站点） | 开关 | | `--theme` | 图表主题 | `light`（默认）/ `dark` | | `--out, -o` | 输出 SVG 路径 | 默认 `./air-chart-<时间戳>.svg` | | `--demo` | 演示模式：使用内置模拟数据，无需 API Key，用于预览与联调 | 开关 | ### 模式自动判定 - 1 城市 × 1 指标 → 单城趋势折线图 - 多城市 × 1 指标 → 多城对比折线图（高对比度色板） - 1 城市 × 多指标 → 单城多指标折线图 - `--snapshot` → 同城多站点横向柱状图 ## 前置条件 需要 OpenAQ API Key（免费）：`https://explore.openaq.org/register` - 环境变量：`export OPENAQ_API_KEY="..."` - 或 x-cmd 钥匙串：`x keyring set openaq` 未配置时脚本以退出码 3 退出并输出注册引导，不会产生未捕获异常。 ## 输出解读（Agent 指引） 脚本 stdout 末尾输出 `[air-chart] 图表已生成: <路径>` 与数据摘要（站点名、参考级标记、n/min/max/avg、单位）。 Agent 应： 1. 向用户展示 SVG 文件路径（Markdown 中可内联引用该 SVG）。 2. 摘要数据以文本形式呈现，注明单位为**物理浓度**（µg/m³ 等），而非 AQI 指数。 3. 图表默认叠加 WHO 24 小时基准虚线（PM2.5=15、PM10=45、O3=100、NO2=25、SO2=40 µg/m³，CO=4 mg/m³），可据此说明达标/超标情况。 ## 异常与降级处理 | 情况 | 退出码 | 行为 | | --- | --- | --- | | 未配置 API Key | 3 | 输出注册引导链接与配置命令 | | 网络/API 异常、鉴权失败、限流重试耗尽 | 4 | 明确错误信息（含 HTTP 状态码） | | 城市不在内置库 | 2 | 输出相近候选城市列表，并提示可传坐标 | | 无活性站点 / 无有效数据 | 5 | 说明原因并建议更换城市/指标/时间范围 | | 24h 无活性站点 | — | 自动放宽到 72h 重试一次 | - 多城对比中个别城市失败时，其余城市正常出图，Agent 应告知用户哪个城市失败及原因。 - 请求具缓存（小时级 20 分钟、日级 2 小时，存于 `~/.cache/air-chart/`），重复查询秒级返回。 ## 实现要点（供维护者） - `scripts/geo_resolve.sh`：城市→坐标/时区（`data/top_cities.tsv`），坐标直传兜底。 - `scripts/openaq_client.sh`：API v3 封装（X-API-Key 鉴权、md5 缓存、429 指数退避重试、活性过滤、参考级站点优先）。 - `scripts/data_transform.awk`：负值/空值清洗、断点检测（缺口插入空行，折线断开而非插值）、min/max/avg 统计。 - `scripts/render_draw.sh`：纯 awk SVG 渲染（折线/柱状、WHO 虚线、图例、浅深主题）。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本