weather-observation-cli 0.1.0__tar.gz

weather_observation_cli-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# 操作系统生成文件
+.DS_Store
+Thumbs.db
+
+# 前端产物
+front/node_modules/
+front/dist/
+front/coverage/
+
+# 本地发布产物与诊断记录；需求和问题记录仍由 Git 维护
+/.scratch/releases/
+/.scratch/diagnostics/
+
+# 已退出版本管理的 Vue 模板示例，仅在现有本地工作区保留
+/front/.oxlintrc.json
+/front/src/assets/logo.svg
+/front/src/components/HelloWorld.vue
+/front/src/components/TheWelcome.vue
+/front/src/components/WelcomeItem.vue
+/front/src/components/__tests__/HelloWorld.spec.ts
+/front/src/components/icons/IconCommunity.vue
+/front/src/components/icons/IconDocumentation.vue
+/front/src/components/icons/IconEcosystem.vue
+/front/src/components/icons/IconSupport.vue
+/front/src/components/icons/IconTooling.vue
+
+# 后端环境与缓存
+back/.venv/
+back/.pytest_cache/
+back/.pytest-tmp*/
+.pytest-*/
+back/.mypy_cache/
+back/.ruff_cache/
+back/data/
+**/__pycache__/
+*.py[cod]
+
+# 独立 CLI 开发环境和构建结果
+cli/.venv/
+cli/.pytest_cache/
+cli/.mypy_cache/
+cli/.ruff_cache/
+cli/dist/
+weather-output/
+
+# SQLite 运行数据、备份与临时文件不得进入代码仓库
+*.sqlite
+*.sqlite3
+*.sqlite-shm
+*.sqlite-wal
+*.sqlite3-shm
+*.sqlite3-wal
+
+# 脱敏后的首次部署数据库快照
+!deploy/bootstrap/
+!deploy/bootstrap/app-public.sqlite3
+
+# 本地配置与密钥
+.env
+.env.*
+!.env.example

weather_observation_cli-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+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 为目标平台；实际验证记录见仓库设计文档，未经验证的平台不宣称已通过。

weather_observation_cli-0.1.0/README.md

@@ -0,0 +1,71 @@
+# 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 为目标平台；实际验证记录见仓库设计文档，未经验证的平台不宣称已通过。

weather_observation_cli-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "weather-observation-cli"
+version = "0.1.0"
+description = "面向 AI 智能体的深圳气象观测客户端"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.28,<1", "keyring>=25,<26"]
+
+[project.scripts]
+weather-observation = "weather_observation_cli.main:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.12", "mypy>=1.15"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/weather_observation_cli"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]

weather_observation_cli-0.1.0/src/weather_observation_cli/__init__.py

@@ -0,0 +1,3 @@
+"""独立气象观测客户端。"""
+
+__version__ = "0.1.0"

weather_observation_cli-0.1.0/src/weather_observation_cli/client.py

@@ -0,0 +1,87 @@
+"""限定目标服务且不跟随重定向的 HTTP 客户端。"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .errors import CliError
+
+DEFAULT_SERVER = "https://weather.cavonxx.com"
+
+
+def normalize_server(value: str) -> str:
+    """只允许 HTTPS 服务源，开发时允许本机 HTTP。"""
+    url = urlsplit(value)
+    if url.username or url.password or url.query or url.fragment or url.path not in ("", "/"):
+        raise CliError("INVALID_ARGUMENT", "服务地址必须是没有路径、凭据或查询参数的服务源", 2)
+    if not url.hostname or (
+        url.scheme != "https"
+        and not (url.scheme == "http" and url.hostname in ("127.0.0.1", "localhost", "::1"))
+    ):
+        raise CliError("INVALID_ARGUMENT", "服务地址必须使用 HTTPS，本机开发可使用 HTTP", 2)
+    try:
+        port = url.port
+    except ValueError as error:
+        raise CliError("INVALID_ARGUMENT", "服务端口无效", 2) from error
+    host = f"[{url.hostname}]" if ":" in url.hostname else url.hostname.lower()
+    suffix = f":{port}" if port and port != (443 if url.scheme == "https" else 80) else ""
+    return f"{url.scheme}://{host}{suffix}"
+
+
+class Client:
+    """不自动重试写请求，也不泄露服务响应中的敏感内容。"""
+
+    def __init__(self, server: str, token: str | None = None) -> None:
+        """保存目标服务和当前独立凭据。"""
+        self.server = server
+        self.token = token
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        binary: bool = False,
+    ) -> Any:
+        """返回 JSON 或 ZIP，HTTP 与网络失败使用稳定错误码。"""
+        headers = {"User-Agent": "weather-observation-cli/0.1.0"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        try:
+            with httpx.Client(timeout=120, follow_redirects=False) as client:
+                response = client.request(
+                    method, self.server + path, params=params, json=body, headers=headers
+                )
+        except httpx.HTTPError as error:
+            raise CliError(
+                "NETWORK_ERROR", "服务请求未完成；写操作的结果可能不确定，请先查询后再决定是否重试"
+            ) from error
+        codes = {
+            401: ("AUTH_REQUIRED", "登录无效或已过期，请运行 auth login"),
+            403: ("PERMISSION_DENIED", "没有执行此操作的权限"),
+            404: ("NOT_FOUND", "指定对象或服务接口不存在"),
+            409: ("CONFLICT", "操作与当前状态冲突，请重新查询"),
+            410: ("AUTH_REQUEST_EXPIRED", "授权请求已过期，请重新登录"),
+            422: ("INVALID_ARGUMENT", "参数无效，请查看对应命令 --help"),
+            429: ("RATE_LIMITED", "请求过于频繁，请稍后重试"),
+        }
+        if not response.is_success:
+            code, message = codes.get(
+                response.status_code, ("SERVICE_ERROR", f"服务返回 HTTP {response.status_code}")
+            )
+            raise CliError(code, message)
+        if response.status_code == 204:
+            return None
+        if binary:
+            if not response.content.startswith(b"PK"):
+                raise CliError("INVALID_RESPONSE", "服务没有返回有效 ZIP")
+            return response.content
+        try:
+            return response.json()
+        except ValueError as error:
+            raise CliError("INVALID_RESPONSE", "服务没有返回有效 JSON") from error

weather_observation_cli-0.1.0/src/weather_observation_cli/errors.py

@@ -0,0 +1,11 @@
+"""稳定且不回显凭据的错误。"""
+
+
+class CliError(Exception):
+    """携带机器可读错误码和退出码。"""
+
+    def __init__(self, code: str, message: str, exit_code: int = 1) -> None:
+        """保存公开错误信息。"""
+        super().__init__(message)
+        self.code = code
+        self.exit_code = exit_code