QWeather

Global weather queries powered by QWeather. Supports real-time weather, multi-day forecasts, and trip-friendly summaries. Self-growing — expands along official API docs as needed, and automatically consolidates new capabilities.

一个文档驱动、可自扩展的天气 skill，基于和风天气 API 提供稳定的最小可用能力，并允许在官方文档边界内持续扩展。

---

不可变原则

以下是这个 skill 的宪法，任何扩展和修改都不得违反。

1. 文档驱动 — 一切能力以和风天气官方文档为准，不猜测 undocumented 接口，不依赖未公开行为。
2. 最小可用基线 — 基础脚本（认证、城市解析、天气查询）是所有扩展的脚手架，不可删除，只可增强。
3. 受控扩展 — 允许自我生长，但每次扩展必须完整走完：查文档 → 明确接口 → 测试通过 → 回写 SKILL.md。跳过任何一步都不算完成。
4. 零泄露 — 发布版不包含任何私钥、KID、Project ID、API Host 等用户私密信息。local/ 目录永远不进入发布版。
5. 省额度 — 城市解析优先走离线数据（LocationList CSV），GeoAPI 仅作兜底。

---

当前能力

以下内容随扩展演化，每次新增能力后更新此节。

认证

• JWT（Ed25519），通过 scripts/gen-jwt.mjs 生成，支持 token 缓存（local/jwt-cache.json）
• 配置方式：环境变量 或 local/qweather.json，详见 references/setup.md

城市解析

三级优先级链（零 API 消耗优先）：

1. local/cities.json — 用户自定义快捷映射
2. local/China-City-List-latest.csv — 和风天气官方 LocationList 离线数据
3. GeoAPI /geo/v2/city/lookup — 兜底动态查询

歧义城市（如"朝阳"）列出候选，由用户选择。

天气查询

能力	端点	参数
实时天气	/v7/weather/now	--now
逐日预报	/v7/weather/3d /v7/weather/7d	--days 3|7（默认 3）

输出格式

脚本支持 --brief（默认）、--trip、--json 三种格式。

agent 向用户展示天气时，不要直接贴脚本输出，应重新组织为易读格式：

• 用天气 emoji 增强可读性：☀️ 晴、⛅ 多云、☁️ 阴、🌧 雨、🌨 雪、💨 大风、🌡️ 气温
• 每天一行，结构清晰：日期 + emoji + 天气 + 气温区间 + 风力 + 降水
• 出行场景补一句简短建议（🌂 带伞、🧥 防风、⚠️ 路滑等）
• 涉及未来出行时提醒预报会变化

首次使用引导

当用户首次使用此 skill（local/qweather.json 不存在）时，agent 应主动完成以下流程，而不是把步骤列给用户：

1. 告知用户需要在和风天气控制台获取三个值：KID、Project ID、API Host
2. 等用户提供这三个值
3. 生成 Ed25519 密钥对：询问用户希望存放的位置，如果用户不确定，默认存到 ~/.ssh/ 下并以 skill 名命名（如 qweather-ed25519-private.pem）
4. 提醒用户将公钥上传到和风天气控制台
5. 自动创建 local/qweather.json
6. 自动执行 bash scripts/init.sh
7. 自动执行 bash scripts/test.sh 验证

整个过程用户只需要提供 3 个值 + 上传一次公钥，其余 agent 全部自动完成。

推荐命令

# 初始化（首次使用）
bash ./scripts/init.sh

# 实时天气
bash ./scripts/qweather.sh 杭州 --now

# 3 天预报（默认）
bash ./scripts/qweather.sh 杭州

# 出行导向摘要
bash ./scripts/qweather.sh 杭州 --trip

# 7 天预报
bash ./scripts/qweather.sh 杭州 --days 7

# 直接用 LocationID
bash ./scripts/qweather.sh 101210101

扩展指南

触发条件

当用户提出当前 skill 尚不具备、但官方文档支持的能力时，例如：逐小时天气、天气预警、分钟级降水、空气质量、生活指数等。

扩展流程

1. 查对应接口的官方文档
2. 明确 endpoint、参数、认证方式、返回字段
3. 判断是否属于高频能力（值得沉淀）还是一次性需求
4. 复用现有的认证、请求（api_get）、错误处理和输出模式
5. 真实执行测试，确认通过
6. 回写 SKILL.md 当前能力表和文件清单

优先参考

• API 总文档: https://dev.qweather.com/docs/api/
• 认证文档: https://dev.qweather.com/docs/configuration/authentication/
• LocationList: https://github.com/qwd/LocationList
• GeoAPI: https://dev.qweather.com/docs/api/geoapi/

文件清单

scripts/

• gen-jwt.mjs — JWT 生成与缓存
• qweather.sh — 天气查询主入口
• init.sh — 初始化（下载 LocationList、验证配置）
• test.sh — 冒烟测试

references/

• setup.md — 配置说明
• publish.md — 发布注意事项

local/（不进入发布版）

• qweather.json — 认证配置
• cities.json — 用户自定义城市映射
• China-City-List-latest.csv — LocationList 离线数据
• jwt-cache.json — JWT 缓存