Metadata-Version: 2.4
Name: qweather-skill
Version: 0.1.0
Summary: 专门为龙虾（OpenClaw）开发的和风天气查询技能
Author-email: yinguobing <yinguobing@gmail.com>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: cryptography>=42.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22.0; extra == 'dev'
Description-Content-Type: text/markdown

# qweather-skill

专门为龙虾（OpenClaw）开发的和风天气查询技能。

## 功能特性

基于 [和风天气 API](https://dev.qweather.com/)，提供以下能力：

- **城市定位**：城市搜索、热门城市、POI 搜索
- **天气预报**：实时天气、每日预报、逐小时预报
- **格点天气**：基于经纬度的高分辨率（3-5 公里）天气数据
- **空气质量**：实时空气质量、小时/每日预报、监测站数据
- **生活指数**：穿衣、洗车、运动、紫外线等指数预报
- **分钟级降水**：未来 2 小时每 5 分钟降水预报（中国地区）
- **天气预警**：台风、暴雨、高温等实时预警信息
- **天文数据**：日出日落、月升月落、月相、太阳高度角

## 安装

### 1. 通过 pip 安装

```bash
pip install qweather-skill
```

### 2. 本地开发安装

```bash
git clone https://github.com/yinguobing/qweather-skill.git
cd qweather-skill
uv sync --extra dev
```

## 身份认证

本技能支持两种身份认证方式，**JWT 为默认推荐方式**：

### 方式一：JWT（推荐，默认）

安全性更高，需在和风天气控制台生成 Ed25519 密钥对并上传公钥。

**注意：JWT 必须使用自定义 API Host**，默认的 `devapi.qweather.com` / `geoapi.qweather.com` 仅支持 API KEY。

环境变量方式：

```bash
export QWEATHER_KID="your_kid"
export QWEATHER_PROJECT_ID="your_project_id"
export QWEATHER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
export QWEATHER_BASE_URL="https://your-host.qweatherapi.com/v7"
export QWEATHER_GEO_URL="https://your-host.qweatherapi.com/geo/v2"
```

### 方式二：API KEY（兼容回退）

```bash
export QWEATHER_API_KEY="your_api_key_here"
```

## 快速开始

### Python API

```python
import asyncio
from qweather_skill import QWeatherClient, QWeatherConfig, GeoAPI, WeatherAPI

async def main():
    # 默认优先使用 JWT 环境变量，其次回退到 API KEY
    config = QWeatherConfig()
    async with QWeatherClient(config) as client:
        geo = GeoAPI(client)
        weather = WeatherAPI(client)

        # 1. 搜索城市
        resp = await geo.city_lookup("北京", number=1)
        location_id = resp.location[0].id

        # 2. 查询实时天气
        now = await weather.now(location_id)
        print(f"当前温度: {now.now.temp}°C, 天气: {now.now.text}")

        # 3. 查询未来 3 天预报
        daily = await weather.daily_forecast(location_id, days=3)
        for day in daily.daily:
            print(f"{day.fxDate}: {day.tempMin}°C ~ {day.tempMax}°C, {day.textDay}")

asyncio.run(main())
```

### CLI 命令行工具

#### JWT 方式

```bash
# 通过参数传入 JWT 凭据（必须同时指定自定义 API Host）
python -m qweather_skill 北京 \
  --kid YOUR_KID \
  --project-id YOUR_PROJECT_ID \
  --private-key ./ed25519-private.pem \
  --base-url https://your-host.qweatherapi.com/v7 \
  --geo-url https://your-host.qweatherapi.com/geo/v2

# 私钥也可以直接传 PEM 内容
python -m qweather_skill 北京 \
  --kid YOUR_KID \
  --project-id YOUR_PROJECT_ID \
  --private-key "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIE..." \
  --base-url https://your-host.qweatherapi.com/v7 \
  --geo-url https://your-host.qweatherapi.com/geo/v2
```

#### API KEY 方式

```bash
# 实时天气
python -m qweather_skill 北京 --key YOUR_API_KEY

# 未来 3 天预报
python -m qweather_skill 北京 --key YOUR_API_KEY --type daily --days 3
```

#### 更多查询类型

```bash
# 逐小时预报
python -m qweather_skill 北京 --type hourly --hours 24

# 空气质量
python -m qweather_skill 北京 --type air

# 生活指数
python -m qweather_skill 北京 --type indices

# 分钟级降水
python -m qweather_skill 北京 --type minutely

# 天气预警
python -m qweather_skill 北京 --type warning

# 日出日落
python -m qweather_skill 北京 --type sun --date 20241201

# 格点实时天气（基于经纬度）
python -m qweather_skill 北京 --type grid-now

# 空气质量每日预报
python -m qweather_skill 北京 --type air-daily --days 5

# 月相
python -m qweather_skill 北京 --type moon --date 20241201

# 太阳高度角
python -m qweather_skill 北京 --type solar --date 20241201 --time 1200 --tz 0800 --alt 43
```

## API 模块一览

| 模块 | 类 | 说明 |
|------|-----|------|
| `geo` | `GeoAPI` | 城市搜索、热门城市、POI 搜索 |
| `weather` | `WeatherAPI` | 实时天气、每日/逐小时预报 |
| `grid_weather` | `GridWeatherAPI` | 格点实时/每日/逐小时天气 |
| `air` | `AirAPI` | 实时空气质量、预报、监测站 |
| `indices` | `IndicesAPI` | 天气生活指数预报 |
| `minutely` | `MinutelyAPI` | 分钟级降水预报 |
| `warning` | `WarningAPI` | 实时天气预警 |
| `astronomy` | `AstronomyAPI` | 日出日落、月相、太阳高度角 |

## 运行测试

```bash
uv run pytest -v
```

## 打包与安装

### 构建 Python 包

```bash
uv build
```

产物位于 `dist/` 目录：
- `qweather_skill-0.1.0-py3-none-any.whl`
- `qweather_skill-0.1.0.tar.gz`

### 生成 Skill 压缩包

```bash
zip -r qweather-skill.zip . -x ".git/*" ".venv/*" "*/__pycache__/*" "dist/*"
```

## 项目结构

```
qweather-skill/
├── SKILL.md               # Skill 元数据与说明
├── pyproject.toml         # 项目配置
├── src/qweather_skill/    # 源代码
│   ├── __init__.py
│   ├── __main__.py        # CLI 入口
│   ├── client.py          # API 客户端
│   ├── config.py          # 配置管理
│   ├── models.py          # Pydantic 数据模型
│   ├── geo.py             # GeoAPI
│   ├── weather.py         # 天气 API
│   ├── grid_weather.py    # 格点天气 API
│   ├── air.py             # 空气质量 API
│   ├── indices.py         # 天气指数 API
│   ├── minutely.py        # 分钟降水 API
│   ├── warning.py         # 天气预警 API
│   └── astronomy.py       # 天文 API
└── tests/                 # 测试用例
```

## 许可证

[MIT](LICENSE)
