qweather
一个文档驱动、可自扩展的天气 skill，基于和风天气 API 提供稳定的最小可用能力，并允许在官方文档边界内持续扩展。
不可变原则
以下是这个 skill 的宪法，任何扩展和修改都不得违反。
- 文档驱动 — 一切能力以和风天气官方文档为准，不猜测 undocumented 接口，不依赖未公开行为。
- 最小可用基线 — 基础脚本（认证、城市解析、天气查询）是所有扩展的脚手架，不可删除，只可增强。
- 受控扩展 — 允许自我生长，但每次扩展必须完整走完：查文档 → 明确接口 → 测试通过 → 回写 SKILL.md。跳过任何一步都不算完成。
- 零泄露 — 发布版不包含任何私钥、KID、Project ID、API Host 等用户私密信息。
local/目录永远不进入发布版。 - 省额度 — 城市解析优先走离线数据（LocationList CSV），GeoAPI 仅作兜底。
当前能力
以下内容随扩展演化，每次新增能力后更新此节。
认证
- JWT（Ed25519），通过
scripts/gen-jwt.mjs生成，支持 token 缓存（local/jwt-cache.json） - 配置方式：环境变量 或
local/qweather.json，详见references/setup.md
城市解析
三级优先级链（零 API 消耗优先）：
local/cities.json— 用户自定义快捷映射local/China-City-List-latest.csv— 和风天气官方 LocationList 离线数据- 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 应主动完成以下流程，而不是把步骤列给用户：
- 告知用户需要在和风天气控制台获取三个值：KID、Project ID、API Host
- 等用户提供这三个值
- 生成 Ed25519 密钥对：询问用户希望存放的位置，如果用户不确定，默认存到
~/.ssh/下并以 skill 名命名（如qweather-ed25519-private.pem） - 提醒用户将公钥上传到和风天气控制台
- 自动创建
local/qweather.json - 自动执行
bash scripts/init.sh - 自动执行
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 尚不具备、但官方文档支持的能力时，例如：逐小时天气、天气预警、分钟级降水、空气质量、生活指数等。
扩展流程
- 查对应接口的官方文档
- 明确 endpoint、参数、认证方式、返回字段
- 判断是否属于高频能力（值得沉淀）还是一次性需求
- 复用现有的认证、请求（
api_get）、错误处理和输出模式 - 真实执行测试，确认通过
- 回写 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 缓存