QWeather

Global weather queries powered by QWeather. Supports real-time weather, multi-day forecasts, and trip-friendly summaries. Self-growing — expands along offici...

Security Scan

The skill is mostly what it claims (a QWeather wrapper) but it requires your QWeather credentials and private key, asks the agent to generate/store keys and run local scripts, and the registry metadata does not declare those secrets—these inconsistencies warrant caution before installing.

Purpose & Capability

The skill's description is a weather client for QWeather, which legitimately requires KID, Project ID, API Host, and a private key for JWT-based auth. However the registry metadata declares no required environment variables or primary credential even though the code and SKILL.md clearly require secrets (QWEATHER_KID, QWEATHER_PROJECT_ID, QWEATHER_PRIVATE_KEY_PATH, QWEATHER_API_HOST or local/qweather.json). This mismatch between declared requirements and actual needed credentials is incoherent and should be fixed or explained by the author.

Instruction Scope

SKILL.md instructs the agent to perform an interactive first-use flow: collect the three secret values from the user, generate an Ed25519 keypair (defaulting to ~/.ssh/ if user unsure), prompt the user to upload the public key, create local/qweather.json, and automatically run bash scripts (init.sh and test.sh). Those instructions give the agent broad permission to write files, execute local scripts, and (per the 'self-growing' language) to update SKILL.md and capabilities. While this is plausible for setup, it grants the agent discretionary file-system and code-modification actions that are not enforced by the code and therefore raise scope and safety concerns.

Install Mechanism

There is no package install spec; the skill is instruction + scripts. The only remote download is LocationList CSV from a known GitHub raw URL. No arbitrary installers or external archives are fetched. Risk from install mechanism itself is low.

Credentials

The runtime code reads a private key file and requires KID, Project ID, and API Host to construct signed JWTs — these are appropriate for QWeather integration. But the skill metadata failed to declare these required env vars/primary credential. The gen-jwt.mjs will load a private key path and sign tokens and also cache tokens to local/jwt-cache.json; storing private auth material under local/ without clear protections can be risky if local/ is synced or backed up. Requiring a user's private key and advising a default save location of ~/.ssh increases the potential for accidental exposure or key management mistakes.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. However SKILL.md's 'self-growing' guidance and the first-use flow instruct the agent to write local configuration (local/qweather.json, jwt-cache.json) and possibly generate a private key in a default system directory (~/.ssh) — actions that create persistent artifacts on the host. This is not inherently malicious but users should control where keys/config are stored and whether the agent is allowed to run commands that create files.

What to consider before installing

Before installing: 1) Note the registry metadata does NOT list the required secrets — the skill actually needs QWEATHER_KID, QWEATHER_PROJECT_ID, QWEATHER_PRIVATE_KEY_PATH, and QWEATHER_API_HOST (or a local/qweather.json). Ask the author to update the metadata. 2) The skill asks the agent to generate and store an Ed25519 private key and may default to ~/.ssh — do NOT accept default locations without verifying (use a dedicated secure path and do not overwrite existing SSH keys). 3) Inspect scripts yourself (they are present) and run init/test manually instead of letting an agent run them automatically; verify local/ is excluded from backups/version control so private data isn't leaked. 4) Understand the agent is instructed to 'self-grow' and update SKILL.md/files when adding features — clarify whether such changes require your explicit approval (prefer manual commits/PRs). 5) If you proceed, keep the private key and local/ directory offline/safely stored, and only provide the minimal credentials required. If the author cannot correct the missing metadata or clarify the self-modification behavior, treat installation as higher risk.

一个文档驱动、可自扩展的天气 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 缓存