weather-observation-cli 0.1.0__py3-none-any.whl

weather_observation_cli/__init__.py

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

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/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

weather_observation_cli/main.py

@@ -0,0 +1,470 @@
+"""AI 可调用的气象观测命令入口。"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import io
+import json
+import os
+import platform
+import secrets
+import sys
+import tempfile
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any, NoReturn, Protocol, cast
+from urllib.parse import quote
+from uuid import uuid4
+
+from . import __version__
+from .client import DEFAULT_SERVER, Client, normalize_server
+from .errors import CliError
+from .storage import Credentials
+
+FIELDS = ("temperature", "humidity", "wind_speed", "hourly_rain", "pressure")
+DATA_HELP = """时间为带 +08:00 的 ISO 8601 整点，包含首尾，结束减开始最多 366 天。
+AI 将自然语言时间转换成明确范围。每小时保留一条记录，null 为缺测，0 为真实零值；
+不插值、不补零、不默认返回缺测统计。record_count 是小时记录数，不代表有效值数。
+字段及单位：temperature 空气温度 ℃；humidity 相对湿度 %；wind_speed 风速 m/s；
+hourly_rain 小时雨量 mm；pressure 气压 hPa。未选择的要素不返回。
+默认完整写入执行目录 weather-output/，返回绝对路径与记录数；--stdout 完整输出。
+数据文件包含 schema_version、source(id/name)、start_time、end_time、points。
+points 每条包含 observed_at 和所选字段。后续采集可修订历史值。
+示例：weather-observation observations query --station <ID>
+  --start 2026-09-11T00:00:00+08:00 --end 2026-09-11T23:00:00+08:00 --fields hourly_rain
+"""
+
+
+class Api(Protocol):
+    """便于独立验证的 HTTP 边界。"""
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        binary: bool = False,
+    ) -> Any:
+        """执行一条业务请求。"""
+        ...
+
+
+class Parser(argparse.ArgumentParser):
+    """把参数错误交给统一 JSON 出口。"""
+
+    def error(self, message: str) -> NoReturn:
+        """不回显可能含秘密的未知参数值。"""
+        raise CliError("INVALID_ARGUMENT", "参数无效或缺少必填项，请查看对应命令 --help", 2)
+
+
+def parser() -> Parser:
+    """构造无需登录即可读取的完整分层帮助。"""
+    root = Parser(
+        prog="weather-observation",
+        description="通过现有账号查询深圳气象观测、下载 Excel 报表及管理本人收藏。",
+        epilog=(
+            "首次运行 auth login，浏览器批准后再次运行。业务输出为 JSON；"
+            "错误为 ok=false/error(code,message)。退出码 0 成功、2 参数错误、"
+            "1 其他失败。仅支持普通用户业务。"
+        ),
+    )
+    root.add_argument("--version", action="version", version=__version__)
+    root.add_argument(
+        "--server",
+        default=DEFAULT_SERVER,
+        help="开发测试用服务源；凭据与默认服务隔离，置于子命令之前",
+    )
+    groups = root.add_subparsers(dest="group", required=True)
+    auth = groups.add_parser("auth", help="登录与授权管理").add_subparsers(
+        dest="action", required=True
+    )
+    login = auth.add_parser(
+        "login",
+        help="发起或完成浏览器授权",
+        description="首次返回网址并退出；用户授权后再次调用领取。请求十分钟过期，登录固定有效三十天。",
+    )
+    login.add_argument(
+        "--name", default=platform.node() or "CLI", help="网页显示的设备名称，最多 80 字"
+    )
+    login.add_argument(
+        "--credential-store",
+        choices=["keyring", "file"],
+        help="默认系统凭据管理器；用户明确同意后才能选择 file，不自动降级",
+    )
+    auth.add_parser("status", help="查看账号、到期时间和存储方式，不输出凭据")
+    auth.add_parser("logout", help="服务端撤销当前授权后清除本地凭据；网络失败时保留以便重试")
+    groups.add_parser("overview", help="普通用户系统概览")
+    stations = groups.add_parser("stations", help="发现站点").add_subparsers(
+        dest="action", required=True
+    )
+    listing = stations.add_parser("list", help="返回稳定 ID 和名称；多项匹配时请用户明确")
+    listing.add_argument("--search", help="名称包含搜索")
+    observations = groups.add_parser("observations", help="小时观测").add_subparsers(
+        dest="action", required=True
+    )
+    query = observations.add_parser(
+        "query",
+        help="单站点小时数据",
+        description=DATA_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add_range(query)
+    add_output(query, data=True)
+    reports = groups.add_parser("reports", help="Excel 报表").add_subparsers(
+        dest="action", required=True
+    )
+    download = reports.add_parser(
+        "download",
+        help="单站点 ZIP，包含小时、日数据 Excel 及完整性说明；始终导出全部要素",
+        description=DATA_HELP,
+    )
+    add_range(download)
+    add_output(download)
+    favorites = groups.add_parser(
+        "favorites", help="本人收藏，保存站点和范围；查看时跟随最新修订"
+    ).add_subparsers(dest="action", required=True)
+    listing = favorites.add_parser("list", help="分页列表，返回 items/total/page/page_size")
+    listing.add_argument("--page", type=int, default=1)
+    listing.add_argument("--page-size", type=int, default=20, help="1–100，默认 20")
+    create = favorites.add_parser(
+        "create", help="收藏单站点范围；重复创建返回原 ID 且不覆盖名称备注"
+    )
+    add_range(create)
+    create.add_argument("--name", default="", help="可选名称，最多 200 字")
+    create.add_argument("--notes", default="", help="可选备注，最多 2000 字")
+    for action, help_text in [
+        ("show", "收藏详情，不含小时数据"),
+        ("update", "只修改显式给出的名称备注，空字符串表示清空"),
+        ("cancel", "取消收藏，不删除观测数据；需要用户明确指令及 --yes"),
+        ("data", DATA_HELP),
+        ("download", "下载收藏单站点范围的最新 Excel ZIP"),
+    ]:
+        command = favorites.add_parser(
+            action, description=help_text, help=help_text.splitlines()[0]
+        )
+        command.add_argument("id", help="收藏 ID")
+        if action == "update":
+            command.add_argument("--name")
+            command.add_argument("--notes")
+        if action == "cancel":
+            command.add_argument("--yes", action="store_true", help="明确确认取消，不弹出交互提示")
+        if action in ("data", "download"):
+            add_output(command, data=action == "data")
+    return root
+
+
+def add_range(command: argparse.ArgumentParser) -> None:
+    """声明单站点和明确时间范围。"""
+    command.add_argument("--station", required=True, help="stations list 返回的稳定 ID")
+    command.add_argument("--start", required=True, help="起始整点，例如 2026-09-11T00:00:00+08:00")
+    command.add_argument("--end", required=True, help="结束整点，包含该小时，跨度最多 366 天")
+
+
+def add_output(command: argparse.ArgumentParser, *, data: bool = False) -> None:
+    """声明互斥的文件与标准输出方式。"""
+    output = command.add_mutually_exclusive_group()
+    output.add_argument("--output", help="目标文件路径，存在时拒绝覆盖")
+    if data:
+        output.add_argument(
+            "--stdout", action="store_true", help="完整 JSON 写标准输出，不创建文件"
+        )
+        command.add_argument(
+            "--fields", default=",".join(FIELDS), help="逗号分隔要素：" + ",".join(FIELDS)
+        )
+
+
+def time_range(args: argparse.Namespace) -> dict[str, str]:
+    """校验与后端相同的上海整点闭区间。"""
+    try:
+        start, end = datetime.fromisoformat(args.start), datetime.fromisoformat(args.end)
+        for value in (start, end):
+            if (
+                value.utcoffset() != timedelta(hours=8)
+                or value.minute
+                or value.second
+                or value.microsecond
+            ):
+                raise ValueError
+        if start > end or end - start > timedelta(days=366):
+            raise ValueError
+    except ValueError as error:
+        raise CliError(
+            "INVALID_ARGUMENT", "时间必须为 +08:00 整点，起止有序且跨度不超过 366 天", 2
+        ) from error
+    return {"source_id": args.station, "start_time": start.isoformat(), "end_time": end.isoformat()}
+
+
+def write_file(args: argparse.Namespace, content: bytes, label: str, suffix: str) -> str:
+    """完整写入临时文件后以不覆盖方式发布结果。"""
+    safe_label = "".join(c if c.isascii() and (c.isalnum() or c in "-_") else "-" for c in label)[
+        :160
+    ]
+    path = (
+        Path(args.output)
+        if args.output
+        else Path.cwd() / "weather-output" / f"{safe_label}-{uuid4().hex[:12]}.{suffix}"
+    )
+    path = path.absolute()
+    if path.exists() or path.is_symlink():
+        raise CliError("FILE_EXISTS", "目标文件已存在，请选择其他路径")
+    if not args.output:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            dir=path.parent, prefix=".weather-", delete=False
+        ) as stream:
+            temporary = Path(stream.name)
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.link(temporary, path)
+    except FileExistsError as error:
+        raise CliError("FILE_EXISTS", "目标文件已存在，请选择其他路径") from error
+    except OSError as error:
+        raise CliError(
+            "FILE_WRITE_FAILED", "结果文件保存失败，请检查目录、权限与磁盘空间"
+        ) from error
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    return str(path)
+
+
+def query_data(args: argparse.Namespace, api: Api, period: dict[str, str]) -> dict[str, Any]:
+    """保留逐小时值并移除覆盖标记和重复说明。"""
+    fields = list(dict.fromkeys(args.fields.split(",")))
+    if not fields or any(field not in FIELDS for field in fields):
+        raise CliError("INVALID_ARGUMENT", "未知气象要素，请查看 --help", 2)
+    response = api.request("GET", "/api/observation-trends", params=period)
+    data = {key: response[key] for key in ("source", "start_time", "end_time")}
+    data["points"] = [
+        {"observed_at": row["observed_at"], **{field: row[field] for field in fields}}
+        for row in response["points"]
+    ]
+    if args.stdout:
+        return data
+    label = f"{period['source_id']}-{period['start_time']}-{period['end_time']}"
+    path = write_file(
+        args,
+        json.dumps({"schema_version": "1", **data}, ensure_ascii=False).encode(),
+        label,
+        "json",
+    )
+    return {"path": path, "record_count": len(data["points"])}
+
+
+def execute(args: argparse.Namespace, api: Api) -> dict[str, Any] | list[Any]:
+    """执行已校验的普通用户命令。"""
+    if getattr(args, "output", None) and (
+        Path(args.output).exists() or Path(args.output).is_symlink()
+    ):
+        raise CliError("FILE_EXISTS", "目标文件已存在，请选择其他路径")
+    if args.group == "overview":
+        return api.request("GET", "/api/dashboard")  # type: ignore[no-any-return]
+    if args.group == "stations":
+        sources = api.request("GET", "/api/observation-trends/sources")
+        return [
+            item
+            for item in sources
+            if not args.search or args.search.casefold() in item["name"].casefold()
+        ]
+    if args.group in ("observations", "reports"):
+        period = time_range(args)
+        if args.group == "observations":
+            return query_data(args, api, period)
+        content = api.request("POST", "/api/reports/automatic-station", body=period, binary=True)
+        return {"path": write_file(args, content, f"{args.station}-{args.start}-{args.end}", "zip")}
+    base = "/api/report-favorites"
+    if args.action == "list":
+        if args.page < 1 or not 1 <= args.page_size <= 100:
+            raise CliError("INVALID_ARGUMENT", "页码至少 1，每页条数为 1–100", 2)
+        return api.request("GET", base, params={"page": args.page, "page_size": args.page_size})  # type: ignore[no-any-return]
+    if args.action == "create":
+        return cast(
+            dict[str, Any],
+            api.request(
+                "POST", base, body={**time_range(args), "name": args.name, "notes": args.notes}
+            ),
+        )
+    path = base + "/" + quote(args.id, safe="")
+    if args.action == "show":
+        return api.request("GET", path)  # type: ignore[no-any-return]
+    if args.action == "update":
+        changes = {
+            key: getattr(args, key) for key in ("name", "notes") if getattr(args, key) is not None
+        }
+        if not changes:
+            raise CliError("INVALID_ARGUMENT", "至少指定 --name 或 --notes", 2)
+        return api.request("PATCH", path, body=changes)  # type: ignore[no-any-return]
+    if args.action == "cancel":
+        if not args.yes:
+            raise CliError("CONFIRMATION_REQUIRED", "用户明确同意取消后，请指定收藏 ID 和 --yes")
+        api.request("DELETE", path)
+        return {"id": args.id, "cancelled": True}
+    favorite = api.request("GET", path)
+    period = {key: favorite[key] for key in ("source_id", "start_time", "end_time")}
+    if args.action == "data":
+        return query_data(args, api, period)
+    content = api.request("POST", path + "/report", binary=True)
+    return {
+        "path": write_file(
+            args,
+            content,
+            f"{period['source_id']}-{period['start_time']}-{period['end_time']}",
+            "zip",
+        )
+    }
+
+
+def auth_command(
+    args: argparse.Namespace, credentials: Credentials, state: dict[str, Any], api: Client
+) -> dict[str, Any]:
+    """处理可恢复的登录与显式撤销。"""
+    token = state.get("token")
+    if args.action == "status":
+        if not token:
+            return {
+                "status": "pending" if state.get("device_code") else "unauthenticated",
+                "storage": credentials.mode,
+            }
+        result = api.request("GET", "/api/cli/auth/me")
+        return {
+            "status": "authenticated",
+            "username": result["user"]["username"],
+            "expires_at": result["expires_at"],
+            "storage": credentials.mode,
+        }
+    if args.action == "logout":
+        if token:
+            try:
+                api.request("POST", "/api/cli/auth/logout")
+            except CliError as error:
+                if error.code != "AUTH_REQUIRED":
+                    raise
+        credentials.save({})
+        return {"status": "logged_out"}
+    if token:
+        try:
+            result = api.request("GET", "/api/cli/auth/me")
+            return {
+                "status": "authenticated",
+                "username": result["user"]["username"],
+                "expires_at": result["expires_at"],
+                "storage": credentials.mode,
+            }
+        except CliError as error:
+            if error.code != "AUTH_REQUIRED":
+                raise
+            state = {}
+            credentials.save(state)
+            api.token = None
+    if not 1 <= len(args.name.strip()) <= 80:
+        raise CliError("INVALID_ARGUMENT", "设备名称长度必须为 1–80", 2)
+    if state.get("expires_at") and datetime.fromisoformat(state["expires_at"]) <= datetime.now(UTC):
+        state = {}
+    if not state.get("device_code"):
+        state = {"device_code": secrets.token_urlsafe(32)}
+        credentials.save(state)
+    if not state.get("code"):
+        started = api.request(
+            "POST",
+            "/api/cli/auth/requests",
+            body={
+                "device_hash": hashlib.sha256(state["device_code"].encode()).hexdigest(),
+                "name": args.name.strip(),
+            },
+        )
+        state.update(started)
+        credentials.save(state)
+    else:
+        result = api.request(
+            "POST", "/api/cli/auth/token", body={"device_code": state["device_code"]}
+        )
+        if result["status"] == "authorized":
+            credentials.save(
+                {
+                    "token": result["access_token"],
+                    "username": result["user"]["username"],
+                    "expires_at": result["expires_at"],
+                }
+            )
+            return {
+                "status": "authenticated",
+                "username": result["user"]["username"],
+                "expires_at": result["expires_at"],
+                "storage": credentials.mode,
+            }
+        if result["status"] in ("denied", "expired"):
+            credentials.save({})
+            raise CliError(
+                "AUTH_DENIED" if result["status"] == "denied" else "AUTH_REQUEST_EXPIRED",
+                "授权未完成，请重新运行 auth login",
+            )
+    return {
+        "status": "pending",
+        "authorization_url": api.server + "/cli/authorize?code=" + quote(state["code"]),
+        "expires_at": state["expires_at"],
+        "next_action": "用户在浏览器批准后，再次运行 weather-observation auth login",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    """统一结构化输出，默认错误不暴露原始请求和凭据。"""
+    # Windows 管道和非 UTF-8 终端也提供一致的中文与 JSON 编码。
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+    try:
+        args = parser().parse_args(argv)
+        server = normalize_server(args.server)
+        mode = getattr(args, "credential_store", None)
+        if args.group == "auth" and args.action == "login" and mode is None:
+            mode = "keyring" if not Credentials(server).path.exists() else None
+        credentials = Credentials(server, mode)
+        data: dict[str, Any] | list[Any]
+        with credentials.locked():
+            state = credentials.load()
+            api = Client(server, state.get("token"))
+            if args.group == "auth":
+                data = auth_command(args, credentials, state, api)
+            else:
+                if not state.get("token"):
+                    raise CliError("AUTH_REQUIRED", "请先运行 auth login 完成浏览器授权")
+                data = execute(args, api)
+        print(json.dumps({"schema_version": "1", "ok": True, "data": data}, ensure_ascii=False))
+        return 0
+    except CliError as error:
+        print(
+            json.dumps(
+                {
+                    "schema_version": "1",
+                    "ok": False,
+                    "error": {"code": error.code, "message": str(error)},
+                },
+                ensure_ascii=False,
+            )
+        )
+        return error.exit_code
+    except (OSError, ValueError, KeyError, TypeError):
+        print(
+            json.dumps(
+                {
+                    "schema_version": "1",
+                    "ok": False,
+                    "error": {
+                        "code": "CLIENT_ERROR",
+                        "message": "客户端无法完成操作，请检查本地权限、输入和服务版本",
+                    },
+                },
+                ensure_ascii=False,
+            )
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

weather_observation_cli/storage.py

@@ -0,0 +1,171 @@
+"""用户级凭据存储与并发保护。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from .errors import CliError
+
+
+def config_directory() -> Path:
+    """按平台选择当前用户的配置目录。"""
+    if sys.platform == "win32":
+        return (
+            Path(os.environ.get("APPDATA", str(Path.home() / "AppData/Roaming")))
+            / "weather-observation"
+        )
+    if sys.platform == "darwin":
+        return Path.home() / "Library/Application Support/weather-observation"
+    return (
+        Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+        / "weather-observation"
+    )
+
+
+def protect(path: Path, *, directory: bool = False) -> None:
+    """限制本地文件权限，Windows 使用当前用户 ACL。"""
+    if sys.platform != "win32":
+        path.chmod(0o700 if directory else 0o600)
+        return
+    account = f"{os.environ.get('USERDOMAIN', '')}\\{os.environ.get('USERNAME', '')}".lstrip("\\")
+    rights = "(OI)(CI)F" if directory else "F"
+    result = subprocess.run(
+        ["icacls", str(path), "/inheritance:r", "/grant:r", f"{account}:{rights}"],
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise CliError("CREDENTIAL_STORAGE_UNAVAILABLE", "无法限制凭据文件访问权限")
+
+
+def atomic_json(path: Path, value: dict[str, Any]) -> None:
+    """以受限临时文件原子更新客户端自己的状态。"""
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".state-", delete=False) as stream:
+            temporary = Path(stream.name)
+            protect(temporary)
+            stream.write(json.dumps(value, ensure_ascii=False).encode())
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None and temporary.exists():
+            temporary.unlink()
+
+
+class Credentials:
+    """按服务地址隔离登录状态，不静默回退明文存储。"""
+
+    def __init__(self, server: str, mode: str | None = None, root: Path | None = None) -> None:
+        """初始化路径与显式存储选择。"""
+        self.server = server
+        self.root = root or config_directory()
+        self.key = hashlib.sha256(server.encode()).hexdigest()
+        self.path = self.root / f"{self.key}.json"
+        self.mode = mode
+
+    @contextmanager
+    def locked(self) -> Iterator[None]:
+        """同一服务的授权变更只允许一个客户端执行。"""
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        protect(self.root, directory=True)
+        lock_path = self.root / f"{self.key}.lock"
+        with lock_path.open("a+b") as stream:
+            protect(lock_path)
+            try:
+                if sys.platform == "win32":
+                    import msvcrt
+
+                    stream.write(b"0")
+                    stream.flush()
+                    stream.seek(0)
+                    msvcrt.locking(stream.fileno(), msvcrt.LK_NBLCK, 1)
+                else:
+                    import fcntl
+
+                    fcntl.flock(stream, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError as error:
+                raise CliError("CLI_BUSY", "另一个命令正在使用此登录状态，请稍后重试") from error
+            try:
+                yield
+            finally:
+                if sys.platform == "win32":
+                    stream.seek(0)
+                    msvcrt.locking(stream.fileno(), msvcrt.LK_UNLCK, 1)
+                else:
+                    fcntl.flock(stream, fcntl.LOCK_UN)
+
+    def backend(self) -> Any:
+        """只使用系统凭据后端，拒绝第三方明文后端。"""
+        try:
+            import keyring
+
+            backend: Any = keyring.get_keyring()
+            if type(backend).__module__ == "keyring.backends.chainer":
+                candidates = backend.backends
+            else:
+                candidates = [backend]
+            allowed = (
+                "keyring.backends.macOS",
+                "keyring.backends.Windows",
+                "keyring.backends.SecretService",
+                "keyring.backends.kwallet",
+            )
+            for candidate in candidates:
+                if type(candidate).__module__.startswith(allowed) and candidate.priority > 0:
+                    return candidate
+        except Exception as error:
+            raise CliError(
+                "CREDENTIAL_STORAGE_UNAVAILABLE",
+                "系统凭据管理器不可用；用户明确同意文件存储后，"
+                "可运行 auth login --credential-store file",
+            ) from error
+        raise CliError(
+            "CREDENTIAL_STORAGE_UNAVAILABLE",
+            "系统凭据管理器不可用；用户明确同意文件存储后，"
+            "可运行 auth login --credential-store file",
+        )
+
+    def load(self) -> dict[str, Any]:
+        """读取本服务状态，不在错误中暴露内容。"""
+        try:
+            marker = json.loads(self.path.read_text(encoding="utf-8")) if self.path.exists() else {}
+            if not marker and self.mode is None:
+                return {}
+            selected = marker.get("storage", self.mode or "keyring")
+            if self.mode and marker and self.mode != selected:
+                raise CliError("STORAGE_CONFLICT", "请先退出登录再更换凭据存储方式")
+            self.mode = selected
+            if selected == "file":
+                return dict(marker.get("state", {}))
+            value = self.backend().get_password("weather-observation", self.key)
+            return json.loads(value) if value else {}
+        except CliError:
+            raise
+        except Exception as error:
+            raise CliError("CREDENTIAL_STORAGE_UNAVAILABLE", "无法读取本地登录状态") from error
+
+    def save(self, state: dict[str, Any]) -> None:
+        """保存已选存储中的状态，系统存储失败时不降级。"""
+        try:
+            if self.mode == "file":
+                atomic_json(self.path, {"storage": "file", "state": state})
+            else:
+                self.backend().set_password("weather-observation", self.key, json.dumps(state))
+                atomic_json(self.path, {"storage": "keyring"})
+        except CliError:
+            raise
+        except Exception as error:
+            raise CliError(
+                "CREDENTIAL_STORAGE_UNAVAILABLE", "无法保存登录状态，可重新调用登录重试"
+            ) from error

weather_observation_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+weather_observation_cli/__init__.py,sha256=qJQml9PnGMGHsuQ7R_tN-hXLWTSRfGFGYgDS1Qzurz0,60
+weather_observation_cli/client.py,sha256=JnmbypqGqlF4gJMJL8x1ZM6TM-2AaEzzZZWGbyOU1ZM,3684
+weather_observation_cli/errors.py,sha256=0hfOoAw7YMUokelhz2X9NnQk4Rcm7cCv9DONZMNZi2c,339
+weather_observation_cli/main.py,sha256=KCyGD_wMsOvfCCWVbfcJKEl4yEJVJkuW8KLYkwIJyi4,19685
+weather_observation_cli/storage.py,sha256=DCv6MZ4m0VNPbvSoOmqG5o3O-IuzKHumEz4poTGhCTY,6724
+weather_observation_cli-0.1.0.dist-info/METADATA,sha256=g4If9eWi-H_SUpM9rEybv8x5yAPbGTauknyb9agJ-Ho,4251
+weather_observation_cli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+weather_observation_cli-0.1.0.dist-info/entry_points.txt,sha256=LkXBpbIz4SQKyMn_KxxyFp0KqzVq-ogMDN0CLF0qCjI,74
+weather_observation_cli-0.1.0.dist-info/RECORD,,

weather_observation_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

weather_observation_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+weather-observation = weather_observation_cli.main:main