Metadata-Version: 2.5
Name: weather-observation-cli
Version: 0.1.0
Summary: 面向 AI 智能体的深圳气象观测客户端
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: keyring<26,>=25
Description-Content-Type: text/markdown

# weather-observation CLI

供 AI 智能体查询深圳气象观测、下载 Excel 报表及管理本人收藏的独立客户端。
默认连接 `https://weather.cavonxx.com`，只使用普通用户业务能力。

推荐通过 uv 安装：

```sh
uv tool install weather-observation-cli
weather-observation --help
weather-observation auth login
```

用户在返回的网址中使用已有账号批准，然后再次运行 `auth login`。请求十分钟有效；
成功登录固定三十天，到期重新授权。无浏览器的服务器可以在其他设备打开网址。
默认使用系统凭据管理器；不可用时先让用户明确选择，再运行：

```sh
weather-observation auth login --credential-store file
weather-observation auth status
weather-observation auth logout
```

`file` 使用当前用户私有配置目录，权限限制不是加密，也不能隔离同一用户运行的其他进程。
macOS 使用 `~/Library/Application Support/weather-observation/`，Linux 使用
`$XDG_CONFIG_HOME/weather-observation/`（默认 `~/.config/weather-observation/`），
Windows 使用 `%APPDATA%/weather-observation/`。凭据按服务源隔离。
退出时先撤销服务端授权；网络失败保留本地状态以便重试。也可在网页“CLI 授权”撤销。

## AI 使用顺序

1. 读取对应命令的 `--help`，用 `auth status` 检查身份；授权网址只交给用户本人。
2. `stations list --search 名称` 查找稳定 ID。多项匹配时请用户明确，不自动选首项。
3. 将自然语言范围转为带 `+08:00` 的 ISO 8601 整点。首尾包含，跨度最多 366 天。
4. 单站点调用查询、下载或收藏命令；多站点分别调用。
5. 默认返回绝对文件路径，使用代码读取完整 JSON 后分析。文件属于实际运行环境。

```sh
weather-observation observations query --station <ID> \
  --start 2026-09-11T00:00:00+08:00 --end 2026-09-11T23:00:00+08:00 \
  --fields temperature,hourly_rain
weather-observation reports download --station <ID> \
  --start 2026-09-11T00:00:00+08:00 --end 2026-09-11T23:00:00+08:00
weather-observation favorites list
weather-observation favorites show <ID>
weather-observation favorites data <ID>
weather-observation favorites download <ID>
```

要素为 `temperature`（℃）、`humidity`（%）、`wind_speed`（m/s）、`hourly_rain`（mm）、
`pressure`（hPa）。默认全部，可用 `--fields` 筛选。`null` 表示缺测，`0` 是真实零值。
每小时保留记录，记录数不等于有效值数；不插值、补零、抽样或默认附带缺测统计。

JSON、ZIP 默认保存到执行目录的 `weather-output/`。`--output` 指定文件；已有文件报错，
不提供覆盖选项。查询 `--stdout` 将完整 JSON 输出到终端，与 `--output` 互斥。
Excel ZIP 始终包含完整要素的小时、日数据工作簿及完整性说明。

收藏保存站点和时间范围，不冻结数据；详情用 `show`，数据用 `data`。修改只提交明确给出的
`--name`、`--notes`。只有用户明确要求取消指定收藏时才调用 `favorites cancel <ID> --yes`。
重复创建返回原 ID，不覆盖原名称备注；写请求网络失败时应先检查状态，不盲目重放。

所有业务命令输出 `schema_version`、`ok`，成功包含 `data`，失败包含 `error.code/message`。
退出码：0 成功，2 参数错误，1 其他失败。等待浏览器批准属于成功返回的 pending 状态。
日志和进度不进入 JSON。帮助不需要登录。服务支持 `--server` 开发覆盖参数（放在子命令前），
只允许 HTTPS 或本机 HTTP，不跟随服务重定向。

## 开发验证

Python 3.11 及以上。`uv sync` 后执行 `uv run pytest`、`uv run ruff check src tests`、
`uv run ruff format --check src tests`、`uv run mypy src tests`，使用 `uv build` 构建。
macOS、Windows、Linux 为目标平台；实际验证记录见仓库设计文档，未经验证的平台不宣称已通过。
