bazhuayu-client 0.2.6__tar.gz

bazhuayu_client-0.2.6/.env.example

@@ -0,0 +1,14 @@
+# bazhuayu-client 环境变量示例。复制为 .env 并按需填写(.env 已被 .gitignore 忽略)。
+# SDK 本身不加载 .env 文件——由调用方(应用/脚本/测试)自行加载,如 python-dotenv。
+# Client() 构造参数缺省时回退这两个环境变量。
+
+# 平台 API 地址(缺省生产端点 https://api-datahub.bazhuayu.com;
+# 本地开发/预发环境按需覆盖)
+BAZHUAYU_BASE_URL=
+
+# API Key(控制台生成;留空则匿名访问)
+BAZHUAYU_API_KEY=
+
+# OAuth /token 端点(PasswordTokenProvider 的 token_url 缺省回退;
+# 缺省生产端点 https://openapi.bazhuayu.com/token,预发环境按需覆盖)
+BAZHUAYU_TOKEN_URL=

bazhuayu_client-0.2.6/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# uv 虚拟环境
+.venv/
+uv.lock
+
+# 工具缓存
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# 本地环境变量（模板见 .env.example）
+.env
+
+# Claude Code 本地配置
+.claude/settings.local.json
+
+# OS
+.DS_Store

bazhuayu_client-0.2.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bazhuayu (八爪鱼)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bazhuayu_client-0.2.6/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: bazhuayu-client
+Version: 0.2.6
+Summary: 八爪鱼 DataHub 官方 Python SDK：发现、调用、消费 Data App
+Project-URL: Homepage, https://www.bazhuayu.com
+Author: Bazhuayu DataHub Team
+License: MIT
+License-File: LICENSE
+Keywords: bazhuayu,data-app,datahub,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# bazhuayu-client-python — DataHub 官方 Python SDK
+
+八爪鱼 DataHub 的官方 Python 客户端（`bazhuayu-client`）：发现、调用、消费 Data App。
+自包含小项目，零平台侧依赖（运行时仅 `httpx`），只讲平台公开的 `/v1` REST API。
+仓库按 `<品牌>-client-<语言>` 命名，其他语言的客户端与之平级（如 bazhuayu-client-js）。
+
+## 安装
+
+```bash
+pip install bazhuayu-client
+```
+
+## 用法
+
+```python
+from bazhuayu_client import Client
+
+# base_url 缺省即生产端点 https://api-datahub.bazhuayu.com,本地/预发环境按需传入
+with Client(api_key="demo-key") as client:
+    # 发现
+    result = client.search("评论", limit=10)
+    detail = client.get_app("demo/reviews-store-query")   # 或卡片里的 app_id
+
+    # 调用（等到终态）并消费
+    run = client.call("demo/partner-reviews-api", {"product": "p-9001"})
+    for record in client.iterate_records(run["run_id"]):
+        print(record["content"], record["rating"])
+
+    # 盘点与对账
+    for r in client.iterate_runs(run_kind="production", created_from="2026-08-01T00:00:00Z"):
+        print(r["run_id"], r["state"], r["billing"])
+    print(client.billing(group_by="data_app", tz_offset=480))   # 按本地日/按 App 看花在哪
+
+    # 结果数据默认保留 90 天，要长期留存打保留标记
+    client.set_dataset_retention(run["dataset_id"], retained=True)
+```
+
+`call()` 发起运行并轮询到终态；需要非阻塞语义时用 `run()` 拿 `run_id` 后自行
+`get_run()` / `cancel()`。被点对点授权给自己的 App 不在市场结果里，用
+`search(shared_with="me")` 查。全部方法与错误映射见 `src/bazhuayu_client/client.py`。
+
+App 引用有两种形态，`get_app()` / `run()` / `call()` 及运行列表的 `data_app`
+过滤处等价可用：`<用户名>/<应用名>` 两段式引用（取自卡片的 `namespace` 与
+`app_name`，适合人读，发布者改名后旧引用失效）；不变标识 `app_id`
+（`app_<hex>`，取自卡片/详情的 `app_id` 字段，改名免疫）。写进配置、定时任务
+等长期集成建议钉 `app_id`。
+
+## 配置
+
+`Client()` 的 `base_url` / `api_key` 缺省时回退环境变量 `BAZHUAYU_BASE_URL` /
+`BAZHUAYU_API_KEY`（模板见 `.env.example`；SDK 不自动加载 `.env`，由调用方
+自行加载），再回退生产端点 `https://api-datahub.bazhuayu.com` / 匿名。
+
+## OAuth 登录（账号密码，替代 api_key）
+
+除 api_key 外，也可用八爪鱼账号密码经 openapi `/token` 端点换取 identity JWT
+调用平台（两通道互斥，归属与计费同一账户）：
+
+```python
+from bazhuayu_client import Client, PasswordTokenProvider
+
+provider = PasswordTokenProvider("user@example.com", "password")
+with Client("https://datahub.example.com", token_provider=provider) as client:
+    client.call("demo/partner-reviews-api", {"product": "p-9001"})
+```
+
+token 的缓存、快过期自动续期、refresh_token 一次性轮换与失效后密码重登都收在
+provider 内，线程安全；提交 run 前默认要求 token 剩余有效期 ≥ 12h（不足则先
+强制刷新，可用 `Client(run_token_min_ttl=)` 调整）——平台入队时快照凭证、
+终态重放扣费，提交时 token 越新鲜，长运行结束时扣费凭证过期的敞口越小。
+注意 refresh_token 一次性使用：**多进程不要共享同一账号的凭据序列**，每个
+进程各建 provider（各自密码登录）即可。`token_url` 缺省生产端点，可用参数或
+环境变量 `BAZHUAYU_TOKEN_URL` 覆盖。`token_provider` 也接受任意返回当前有效
+token 的无参 callable（自管续期时用）。
+
+## 测试
+
+```bash
+uv run pytest -q    # 离线单元测试（MockTransport，不依赖服务端）
+```

bazhuayu_client-0.2.6/README.md

@@ -0,0 +1,80 @@
+# bazhuayu-client-python — DataHub 官方 Python SDK
+
+八爪鱼 DataHub 的官方 Python 客户端（`bazhuayu-client`）：发现、调用、消费 Data App。
+自包含小项目，零平台侧依赖（运行时仅 `httpx`），只讲平台公开的 `/v1` REST API。
+仓库按 `<品牌>-client-<语言>` 命名，其他语言的客户端与之平级（如 bazhuayu-client-js）。
+
+## 安装
+
+```bash
+pip install bazhuayu-client
+```
+
+## 用法
+
+```python
+from bazhuayu_client import Client
+
+# base_url 缺省即生产端点 https://api-datahub.bazhuayu.com,本地/预发环境按需传入
+with Client(api_key="demo-key") as client:
+    # 发现
+    result = client.search("评论", limit=10)
+    detail = client.get_app("demo/reviews-store-query")   # 或卡片里的 app_id
+
+    # 调用（等到终态）并消费
+    run = client.call("demo/partner-reviews-api", {"product": "p-9001"})
+    for record in client.iterate_records(run["run_id"]):
+        print(record["content"], record["rating"])
+
+    # 盘点与对账
+    for r in client.iterate_runs(run_kind="production", created_from="2026-08-01T00:00:00Z"):
+        print(r["run_id"], r["state"], r["billing"])
+    print(client.billing(group_by="data_app", tz_offset=480))   # 按本地日/按 App 看花在哪
+
+    # 结果数据默认保留 90 天，要长期留存打保留标记
+    client.set_dataset_retention(run["dataset_id"], retained=True)
+```
+
+`call()` 发起运行并轮询到终态；需要非阻塞语义时用 `run()` 拿 `run_id` 后自行
+`get_run()` / `cancel()`。被点对点授权给自己的 App 不在市场结果里，用
+`search(shared_with="me")` 查。全部方法与错误映射见 `src/bazhuayu_client/client.py`。
+
+App 引用有两种形态，`get_app()` / `run()` / `call()` 及运行列表的 `data_app`
+过滤处等价可用：`<用户名>/<应用名>` 两段式引用（取自卡片的 `namespace` 与
+`app_name`，适合人读，发布者改名后旧引用失效）；不变标识 `app_id`
+（`app_<hex>`，取自卡片/详情的 `app_id` 字段，改名免疫）。写进配置、定时任务
+等长期集成建议钉 `app_id`。
+
+## 配置
+
+`Client()` 的 `base_url` / `api_key` 缺省时回退环境变量 `BAZHUAYU_BASE_URL` /
+`BAZHUAYU_API_KEY`（模板见 `.env.example`；SDK 不自动加载 `.env`，由调用方
+自行加载），再回退生产端点 `https://api-datahub.bazhuayu.com` / 匿名。
+
+## OAuth 登录（账号密码，替代 api_key）
+
+除 api_key 外，也可用八爪鱼账号密码经 openapi `/token` 端点换取 identity JWT
+调用平台（两通道互斥，归属与计费同一账户）：
+
+```python
+from bazhuayu_client import Client, PasswordTokenProvider
+
+provider = PasswordTokenProvider("user@example.com", "password")
+with Client("https://datahub.example.com", token_provider=provider) as client:
+    client.call("demo/partner-reviews-api", {"product": "p-9001"})
+```
+
+token 的缓存、快过期自动续期、refresh_token 一次性轮换与失效后密码重登都收在
+provider 内，线程安全；提交 run 前默认要求 token 剩余有效期 ≥ 12h（不足则先
+强制刷新，可用 `Client(run_token_min_ttl=)` 调整）——平台入队时快照凭证、
+终态重放扣费，提交时 token 越新鲜，长运行结束时扣费凭证过期的敞口越小。
+注意 refresh_token 一次性使用：**多进程不要共享同一账号的凭据序列**，每个
+进程各建 provider（各自密码登录）即可。`token_url` 缺省生产端点，可用参数或
+环境变量 `BAZHUAYU_TOKEN_URL` 覆盖。`token_provider` 也接受任意返回当前有效
+token 的无参 callable（自管续期时用）。
+
+## 测试
+
+```bash
+uv run pytest -q    # 离线单元测试（MockTransport，不依赖服务端）
+```

bazhuayu_client-0.2.6/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "bazhuayu-client"
+version = "0.2.6"
+description = "八爪鱼 DataHub 官方 Python SDK：发现、调用、消费 Data App"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Bazhuayu DataHub Team" }]
+keywords = ["bazhuayu", "datahub", "sdk", "data-app"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://www.bazhuayu.com"
+
+# 离线单元测试(tests/,MockTransport):`uv run pytest -q`;联调测试在平台仓库。
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "A"]
+
+[tool.ruff.lint.per-file-ignores]
+# input/type/format 等参数名有意贴平台 API 命名,豁免内置名遮蔽告警
+"src/bazhuayu_client/client.py" = ["A002"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bazhuayu_client"]
+
+# sdist 是对外发行物:只装用户可见面,内部协作文档(AGENTS/CLAUDE/TESTING)与
+# 测试不进包。发布渠道与命令见 AGENTS.md(不入 sdist)。
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "README.md", "LICENSE", ".env.example"]

bazhuayu_client-0.2.6/src/bazhuayu_client/__init__.py

@@ -0,0 +1,12 @@
+from bazhuayu_client.client import (
+    TERMINAL_STATES,
+    ApiError,
+    Client,
+    PasswordTokenProvider,
+    RunFailed,
+    TokenProvider,
+    __version__,
+)
+
+__all__ = ["Client", "ApiError", "RunFailed", "PasswordTokenProvider",
+           "TokenProvider", "TERMINAL_STATES", "__version__"]

bazhuayu_client-0.2.6/src/bazhuayu_client/client.py

@@ -0,0 +1,621 @@
+"""八爪鱼 DataHub Python SDK。
+
+- 薄封装平台 REST API（/v1），不感知平台内部实现；
+- `call()` = 循环续 wait=60 长轮询直到终态（缺省无总时限，可选 timeout）；
+- `iterate_records()` / `iterate_dataset_records()` / `iterate_runs()` 自动翻页，
+  屏蔽分页细节；
+- 服务端错误统一抛 ApiError（携带平台 Error 对象的 code/category/retryable）；
+  网络层异常（连接失败、超时）不做包装，直接透出 httpx 异常族。
+
+本包自包含（不依赖平台侧任何包），支持整目录 copy 改名发行（见 pyproject 注释）。
+"""
+
+from __future__ import annotations
+
+import base64
+import json as _json
+import os
+import threading
+import time
+from collections.abc import Callable, Iterator
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import quote
+
+import httpx
+
+try:
+    __version__ = version("bazhuayu-client")
+except PackageNotFoundError:  # 未安装、直接以源码路径运行时
+    __version__ = "0.0.0"
+
+DEFAULT_BASE_URL = "https://api-datahub.bazhuayu.com"
+ENV_BASE_URL = "BAZHUAYU_BASE_URL"
+ENV_API_KEY = "BAZHUAYU_API_KEY"
+ENV_TOKEN_URL = "BAZHUAYU_TOKEN_URL"
+DEFAULT_TOKEN_URL = "https://openapi.bazhuayu.com/token"
+API_PREFIX = "/v1"
+# OAuth token 常规续期阈值:剩余有效期低于此值即后台刷新(提前量吸收时钟偏差
+# 与在途请求耗时,避免拿着临期 token 撞 401)
+TOKEN_REFRESH_LEEWAY = 300.0
+# 提交 run(POST …/runs)前的强制新鲜度:平台入队时快照凭证、终态重放扣费,
+# token 越新鲜,长 run 结束时扣费凭证过期的敞口越小
+RUN_TOKEN_MIN_TTL = 12 * 3600.0
+MAX_WAIT_PER_POLL = 60.0  # 服务端 wait 长轮询硬上限
+MAX_ERROR_TEXT = 500  # ApiError.message 保留响应原文的截断上限
+EXPORT_LIMIT = 10000  # export_records 单次导出上限;超量请改用 iterate_records
+USER_AGENT = f"bazhuayu-client/{__version__}"
+
+# 与平台统一状态机对齐的终态集合（自包含内联，勿 import 平台包）
+TERMINAL_STATES = frozenset(
+    {"SUCCEEDED", "PARTIALLY_SUCCEEDED", "FAILED", "CANCELLED", "EXPIRED"})
+
+# 有产出的终态:call(raise_on_failure=True) 不视为失败
+_SUCCESS_STATES = frozenset({"SUCCEEDED", "PARTIALLY_SUCCEEDED"})
+
+
+class ApiError(Exception):
+    """服务端错误的统一异常:映射平台 Error 信封的 code/category/retryable;
+    非平台信封(网关 502、2xx 畸形响应)归一为 http-error / invalid-response。"""
+
+    def __init__(self, status_code: int, error: dict[str, Any]):
+        self.status_code = status_code
+        self.code = error.get("code", "error")
+        self.category = error.get("category", "internal")
+        self.retryable = bool(error.get("retryable"))
+        self.message = error.get("message", "")
+        # 字段级问题 [{path, message}]:message 压成一句话后无法按字段定位,
+        # 平台带了就原样透出（非 list 形态一律视为没带）
+        details = error.get("details")
+        self.details: list[dict[str, str]] | None = details if isinstance(details, list) else None
+        super().__init__(f"[{self.code}] {self.message}")
+
+
+class RunFailed(Exception):
+    """call(raise_on_failure=True) 时运行进入无产出终态(FAILED/CANCELLED/
+    EXPIRED)抛出;run 属性携带完整运行对象供排查。"""
+
+    def __init__(self, run: dict[str, Any]):
+        self.run = run
+        super().__init__(f"运行终态 {run.get('state')}（run_id={run.get('run_id')}）")
+
+
+def _invalid_response(status_code: int, text: str) -> ApiError:
+    """2xx 但响应体不符平台成功信封（非 JSON、缺 data、畸形运行对象…）时
+    统一抛这个,别把 JSONDecodeError / KeyError 裸漏给调用方。"""
+    return ApiError(status_code, {
+        "code": "invalid-response", "category": "internal",
+        "message": (text or f"HTTP {status_code}")[:MAX_ERROR_TEXT]})
+
+
+def _quote_id(value: str) -> str:
+    """单段路径参数(run_id / dataset_id 等)本不该含 / 与保留字符:
+    全量转义,防止畸形 id 改写请求路径。"""
+    return quote(value, safe="")
+
+
+def _quote_app_id(app_id: str) -> str:
+    """App 引用两种形态都要过这里:两段式 `<用户名>/<应用名>` 需保留 /,
+    逐段转义;单段 app_id(`app_<hex>`)天然单段同样适用。
+    空段与 . / .. 段直接拒绝,防路径穿越。"""
+    segments = app_id.split("/")
+    if any(seg in ("", ".", "..") for seg in segments):
+        raise ValueError(f"非法 app_id: {app_id!r}")
+    return "/".join(quote(seg, safe="") for seg in segments)
+
+
+def _jwt_exp(token: str) -> float | None:
+    """尽力解析 JWT payload 的 exp(epoch 秒);非 JWT / 无 exp 返回 None。
+    只做本地读取,不验签——有效性由服务端判定。"""
+    try:
+        payload_b64 = token.split(".")[1]
+        payload_b64 += "=" * (-len(payload_b64) % 4)
+        payload = _json.loads(base64.urlsafe_b64decode(payload_b64))
+        exp = payload.get("exp")
+        return float(exp) if isinstance(exp, (int, float)) else None
+    except Exception:
+        return None
+
+
+@runtime_checkable
+class TokenProvider(Protocol):
+    """Client(token_provider=) 接受的对象形态:返回当前有效的 Bearer token。
+
+    min_ttl 是调用方要求的最低剩余有效期(秒):实现应在剩余不足时先续期再
+    返回;无法续到更长也应返回现有 token(尽力语义),不要在此抛过期错误。
+    也可以直接传 `Callable[[], str]`(无 min_ttl 语义,提交 run 不强制刷新)。
+    """
+
+    def token(self, min_ttl: float = 0.0) -> str: ...
+
+
+class PasswordTokenProvider:
+    """OAuth 密码模式 token 提供者:向 openapi /token 端点用用户名密码换取
+    identity JWT,并在快过期时自动续期,供 Client(token_provider=) 使用。
+
+    - access_token 持内存缓存,剩余有效期低于 max(refresh_leeway, min_ttl)
+      时刷新;有效期优先取响应 expires_in,缺失时回退解析 JWT exp;
+    - refresh_token **一次性使用**(用一次即作废并换发新的):全程持锁单飞,
+      并发调用只有一次真实刷新;多进程勿共享同一 provider 的凭据序列;
+    - refresh_token 失效(绝对 7 天到期、被其他进程顶掉)时回落用户名密码
+      重新登录,对调用方透明;
+    - 凭证红线:username/password/refresh_token 不进日志、异常与 repr。
+
+    token_url 缺省回退环境变量 BAZHUAYU_TOKEN_URL,再回退生产端点
+    DEFAULT_TOKEN_URL;transport 仅供离线测试注入。
+    """
+
+    def __init__(self, username: str, password: str, *, token_url: str | None = None,
+                 refresh_leeway: float = TOKEN_REFRESH_LEEWAY, timeout: float = 30.0,
+                 transport: httpx.BaseTransport | None = None):
+        self._username = username
+        self._password = password
+        self._token_url = token_url or os.environ.get(ENV_TOKEN_URL) or DEFAULT_TOKEN_URL
+        self._leeway = refresh_leeway
+        self._lock = threading.Lock()
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at = 0.0  # epoch 秒;与 JWT exp 同一时间轴
+        self._http = httpx.Client(timeout=timeout, transport=transport,
+                                  headers={"User-Agent": USER_AGENT})
+
+    def __repr__(self) -> str:  # 凭证红线:不回显 username/password
+        return f"PasswordTokenProvider(token_url={self._token_url!r})"
+
+    def token(self, min_ttl: float = 0.0) -> str:
+        """返回当前有效 token;剩余有效期不足 max(refresh_leeway, min_ttl) 时
+        先刷新。刷新后即便仍不满足 min_ttl(服务端签发的有效期本就更短)也
+        返回新 token——已是能拿到的最新鲜凭证。"""
+        threshold = max(self._leeway, min_ttl)
+        with self._lock:
+            # 锁内复查:并发到期时第一个线程刷新,其余醒来直接命中新 token
+            if self._access_token and self._expires_at - time.time() >= threshold:
+                return self._access_token
+            self._refresh_locked()
+            assert self._access_token is not None
+            return self._access_token
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> PasswordTokenProvider:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _refresh_locked(self) -> None:
+        """持锁前提下续期:优先 refresh_token,服务端拒绝(过期/被顶掉)时
+        回落密码重登。网络层异常原样透出,不清 refresh_token(请求可能根本
+        没到服务端,凭据未必已作废)。"""
+        if self._refresh_token:
+            try:
+                self._grant({"grant_type": "refresh_token",
+                             "refresh_token": self._refresh_token})
+                return
+            except ApiError:
+                self._refresh_token = None
+        self._grant({"grant_type": "password",
+                     "username": self._username, "password": self._password})
+
+    def _grant(self, payload: dict[str, Any]) -> None:
+        resp = self._http.post(self._token_url, json=payload)
+        if resp.status_code >= 400:
+            # 只带服务端响应原文(不含我方请求体);格式非平台信封,统一归为 auth
+            raise ApiError(resp.status_code, {
+                "code": "auth-error", "category": "auth",
+                "message": (resp.text or f"HTTP {resp.status_code}")[:MAX_ERROR_TEXT]})
+        try:
+            data = resp.json()
+        except ValueError:
+            data = None
+        access = data.get("access_token") if isinstance(data, dict) else None
+        if not isinstance(access, str) or not access:
+            # 固定消息,不带响应原文——2xx 畸形体仍可能含凭证材料
+            raise ApiError(resp.status_code, {
+                "code": "invalid-response", "category": "internal",
+                "message": "token 响应缺少 access_token"})
+        expires_in = data.get("expires_in")
+        if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool):
+            expires_at = time.time() + float(expires_in)
+        else:
+            exp = _jwt_exp(access)
+            if exp is None:
+                raise ApiError(resp.status_code, {
+                    "code": "invalid-response", "category": "internal",
+                    "message": "token 响应缺少 expires_in 且 JWT 无 exp,无法调度续期"})
+            expires_at = exp
+        # 轮换:响应带新 refresh_token 则就地替换;没带则置空(旧的已一次性
+        # 用掉,留着必失败),下次续期直接走密码重登
+        new_refresh = data.get("refresh_token")
+        self._refresh_token = new_refresh if isinstance(new_refresh, str) and new_refresh else None
+        self._access_token = access
+        self._expires_at = expires_at
+
+
+class Client:
+    def __init__(self, base_url: str | None = None, api_key: str | None = None,
+                 timeout: float = 90.0, transport: httpx.BaseTransport | None = None,
+                 *, token_provider: TokenProvider | Callable[[], str] | None = None,
+                 run_token_min_ttl: float = RUN_TOKEN_MIN_TTL):
+        """base_url / api_key 缺省时依次回退环境变量 BAZHUAYU_BASE_URL /
+        BAZHUAYU_API_KEY(见 .env.example),再回退 DEFAULT_BASE_URL / 匿名。
+
+        token_provider 与 api_key 互斥:传入后 Authorization 改为每请求向
+        provider 取值(见 PasswordTokenProvider),且不再回退 BAZHUAYU_API_KEY;
+        provider 生命周期由调用方管理(close() 不关它)。
+        run_token_min_ttl 是提交 run(POST …/runs)前要求的 token 最低剩余
+        有效期(秒,缺省 12h,仅对带 min_ttl 语义的 provider 生效):入队时
+        平台快照凭证、终态重放扣费,提交前强制刷新可收窄长 run 扣费失败敞口。
+        """
+        if api_key and token_provider is not None:
+            raise ValueError("api_key 与 token_provider 互斥,只能传其一")
+        base_url = base_url or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL
+        # provider 在场即为显式选择 OAuth 通道,env 里的 api_key 不再参与
+        api_key = api_key or (None if token_provider is not None
+                              else os.environ.get(ENV_API_KEY))
+        self._token_provider = token_provider
+        self._run_token_min_ttl = run_token_min_ttl
+        headers = {"User-Agent": USER_AGENT}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._http = httpx.Client(base_url=base_url, headers=headers,
+                                  timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ── 底层请求 ──────────────────────────────────────────────
+    def _poll_timeout(self, wait: float) -> httpx.Timeout | None:
+        """wait 长轮询请求单独放宽 read 超时（wait+10s 缓冲），避免与较小的
+        Client(timeout=) 配置互杀；客户端 read 本就更宽或未设限则不覆盖。"""
+        t = self._http.timeout
+        if t.read is None or t.read >= wait + 10.0:
+            return None
+        return httpx.Timeout(connect=t.connect, read=wait + 10.0,
+                             write=t.write, pool=t.pool)
+
+    def _auth_headers(self, method: str, path: str) -> dict[str, str] | None:
+        """token_provider 通道的每请求取值;api_key 通道仍冻结在构造头,返回 None。
+
+        提交 run(POST …/runs)按 run_token_min_ttl 要求强制新鲜度;其余请求
+        (轮询/读结果)走 provider 自身的常规续期阈值。纯 callable 形态无
+        min_ttl 语义,直接取值。
+        """
+        tp = self._token_provider
+        if tp is None:
+            return None
+        if isinstance(tp, TokenProvider):
+            min_ttl = (self._run_token_min_ttl
+                       if method == "POST" and path.endswith("/runs") else 0.0)
+            return {"Authorization": f"Bearer {tp.token(min_ttl=min_ttl)}"}
+        return {"Authorization": f"Bearer {tp()}"}
+
+    def _request(self, method: str, path: str, *, params: dict[str, Any] | None = None,
+                 json: dict[str, Any] | None = None,
+                 timeout: httpx.Timeout | None = None) -> httpx.Response:
+        params = {k: v for k, v in (params or {}).items() if v is not None}
+        # timeout=None 对 httpx 意为"禁用超时",缺省须回落客户端配置的哨兵值
+        resp = self._http.request(
+            method, API_PREFIX + path, params=params, json=json,
+            headers=self._auth_headers(method, path),
+            timeout=timeout if timeout is not None else httpx.USE_CLIENT_DEFAULT)
+        if resp.status_code >= 400:
+            try:
+                payload = resp.json()
+            except ValueError:
+                payload = None
+            error = payload.get("error") if isinstance(payload, dict) else None
+            if not isinstance(error, dict):
+                # error 字段非 dict(裸字符串、FastAPI 校验数组…)按非信封处理
+                error = {}
+            if not error.get("message"):
+                # 非平台信封的错误（网关 502、框架直出的 422…）：别退化成一句空
+                # 消息的 internal error，把原文带上，调用方才有的可查。
+                error = {"code": error.get("code") or "http-error",
+                         "category": error.get("category") or "internal",
+                         "message": (resp.text or f"HTTP {resp.status_code}")[:MAX_ERROR_TEXT],
+                         "retryable": bool(error.get("retryable"))}
+            raise ApiError(resp.status_code, error)
+        return resp
+
+    def _data(self, method: str, path: str, **kw: Any) -> Any:
+        """请求并解平台成功信封 {"data": ...};204/空体返回 None(cancel 场景)。"""
+        resp = self._request(method, path, **kw)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        try:
+            payload = resp.json()
+        except ValueError:
+            payload = None
+        if not isinstance(payload, dict) or "data" not in payload:
+            raise _invalid_response(resp.status_code, resp.text)
+        return payload["data"]
+
+    # ── 发现 ──────────────────────────────────────────────────
+    def meta(self) -> dict[str, Any]:
+        """平台元信息（匿名可读的部署级常量），目前只有记账币种 currency
+        （ISO 4217 码）：金额字段（unit_price / amount / total_spent）一律
+        不带单位，单位以这里为准。"""
+        return self._data("GET", "/meta")
+
+    def search(self, query: str = "", *, type: str | None = None,
+               capability: str | None = None, owner: str | None = None,
+               shared_with: str | None = None, scope: str | None = None,
+               status: str | None = None,
+               offset: int = 0, limit: int = 5) -> dict[str, Any]:
+        """检索数据应用（市场视角）。
+
+        卡片带两种 App 引用：namespace + app_name 组成 `<用户名>/<应用名>`
+        两段式引用（改名后失效），以及改名免疫的不变标识 app_id
+        （`app_<hex>`，长期集成建议钉它）；两种形态在 get_app/run/call
+        处等价可用。
+        capability 按能力分类过滤：data-acquisition（数据获取）/
+        data-processing（数据处理），服务端只认这两个字面量。没有按平台/
+        站点的过滤维度：要找特定平台的 App，把平台名并入 query 检索词
+        （卡片 keywords 参与相关度打分）。
+        owner="me"（需 api_key）切换为归属视角：只列自己名下的 App（含未上架
+        形态），卡片额外带 status/scope；服务端只接受字面量 "me"。
+        shared_with="me"（需 api_key）列出被发布者点对点授权给我的 shared App
+        ——这类 App 不在市场结果里，不查这个视角就看不见。两个视角互斥
+        （同时传服务端 400），分开查询。
+        scope 无视角时是一等属性维度，直接决定候选集：缺省/"public"=市场；
+        "private"（需 api_key）=我的私有 App；"shared"（需 api_key）=可见的
+        全部 shared App（我分享出去的+分享给我的，双向）；"all"=可见全集
+        （匿名时恰为市场，自然退化）。属性模式 status 缺省 "published"
+        （显式可查 deprecated；draft 恒空，草稿盘点走 owner="me"），卡片
+        附 App 自身 scope 字段。配合 owner="me" 时 scope/status 退为视角内
+        再过滤（盘点收窄，缺省全出）。词表外取值服务端 422 拒绝。
+        """
+        return self._data("GET", "/data-apps", params={
+            "q": query, "type": type, "capability": capability, "owner": owner,
+            "shared_with": shared_with, "scope": scope, "status": status,
+            "offset": offset, "limit": limit})
+
+    def get_app(self, app_id: str) -> dict[str, Any]:
+        """app_id 接受两种引用形态（run()/call() 与 list_runs* 的 data_app
+        过滤同此口径）：
+
+        - `<用户名>/<应用名>` 两段式引用（取自卡片的 namespace 与 app_name），
+          适合人读与临时调用；发布者改名后旧引用失效，重新检索取新引用；
+        - 平台不变标识 app_id（`app_<hex>`，取自卡片/detail 的 app_id 字段），
+          改名免疫，长期集成建议钉它。
+
+        非公开 App（draft/private）仅归属用户带 key 可见，其他人 404。"""
+        return self._data("GET", f"/data-apps/{_quote_app_id(app_id)}")
+
+    # ── 调用 ──────────────────────────────────────────────────
+    def run(self, app_id: str, input: dict[str, Any], *, wait: float = 0,
+            max_records: int | None = None, version: str | None = None,
+            triggered_by: str = "sdk") -> dict[str, Any]:
+        """发起运行。sync App 直接返回终态（含 sample_records）；async App 立即返回 Run。
+
+        version 钉住 App 的历史版本运行（输入契约与价格都按该版本）；缺省最新版。
+        钉住已 yank 版本的新 run 被拒（422 version-yanked，在途 run 不受影响）。
+        triggered_by 标注调用来源（sdk/mcp/cli），供上层封装（如 MCP server）透传；
+        服务端只收 `^[a-z][a-z0-9_-]{0,31}$`。
+        不可见的 App（draft/private、未被授权的 shared）是 404；可见但维护中
+        （accepting_runs=false）是 403 app-not-accepting-runs；钱包欠费未解封
+        是 402 balance-negative（充值后自动解封）。
+        """
+        # wait=0 表示不长轮询:置 None 让 _request 连同其他未传参数一并过滤掉,
+        # 不在 query string 里出现(下同 get_run)
+        return self._data("POST", f"/data-apps/{_quote_app_id(app_id)}/runs", json=input, params={
+            "wait": wait or None,
+            "max_records": max_records,
+            "version": version,
+            "triggered_by": triggered_by,
+        }, timeout=self._poll_timeout(wait) if wait else None)
+
+    def call(self, app_id: str, input: dict[str, Any], *,
+             max_records: int | None = None, version: str | None = None,
+             poll_interval: float = 0.2,
+             timeout: float | None = None, raise_on_failure: bool = False) -> dict[str, Any]:
+        """发起并等到终态（循环续 wait 长轮询）。version 语义同 run()。
+
+        timeout 为总时限（秒），超过抛 TimeoutError（消息含 run_id）；超时不会
+        取消服务端运行，需要时由调用方拿 run_id 自行 cancel() 或续查。
+        缺省 None 维持无总时限。
+        终态含 FAILED / CANCELLED / EXPIRED：缺省一律正常返回，是否成功由
+        调用方检查 state；raise_on_failure=True 时无产出终态抛 RunFailed
+        （PARTIALLY_SUCCEEDED 视为有产出，正常返回）。未知的非终态 state
+        （未来新增的中间态）会继续轮询。
+        """
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        def next_wait() -> float:
+            # 剩余时限不足一轮时收缩长轮询,别让服务端 hold 超出总时限
+            if deadline is None:
+                return MAX_WAIT_PER_POLL
+            return min(MAX_WAIT_PER_POLL, max(deadline - time.monotonic(), 0.001))
+
+        run = self.run(app_id, input, wait=next_wait(), max_records=max_records,
+                       version=version)
+        while True:
+            state = run.get("state") if isinstance(run, dict) else None
+            if state in TERMINAL_STATES:
+                if raise_on_failure and state not in _SUCCESS_STATES:
+                    raise RunFailed(run)
+                return run
+            if not state or not run.get("run_id"):
+                # 2xx 但运行对象缺 state/run_id：明确报错，别 KeyError 或永久轮询
+                raise _invalid_response(200, f"运行响应缺少 state/run_id: {run!r}")
+            if deadline is not None and time.monotonic() >= deadline:
+                # 带上 run_id:超时不取消服务端运行,调用方需要句柄去 cancel/续查
+                raise TimeoutError(
+                    f"call() 超过总时限 {timeout}s"
+                    f"（run_id={run['run_id']}，state={state}，运行仍在服务端继续）")
+            time.sleep(poll_interval)
+            run = self.get_run(run["run_id"], wait=next_wait())
+
+    # ── 运行管理 ──────────────────────────────────────────────
+    def get_run(self, run_id: str, *, wait: float = 0) -> dict[str, Any]:
+        """查询单个运行。wait>0 时长轮询：服务端 hold 到状态变化或超时。
+
+        只读得到自己发起的 run（他人的与不存在的 run_id 一律 404）；输入回显中
+        App 契约标 sensitive 的字段是掩码——明文只进不出，本人回读也是掩码。
+        progress.status_text 是 App 自报的人读状态（有则透出，可能为 null）。
+        warnings 是结构化运行告警（如计费取量缺失 billing-qty-missing），
+        仅详情透出，list_runs 系列不带。
+        """
+        return self._data("GET", f"/runs/{_quote_id(run_id)}",
+                          params={"wait": wait or None},
+                          timeout=self._poll_timeout(wait) if wait else None)
+
+    def list_runs_page(self, *, status: str | None = None, data_app: str | None = None,
+                       triggered_by: str | None = None, run_kind: str | None = None,
+                       credential: str | None = None, created_from: str | None = None,
+                       created_to: str | None = None, offset: int = 0,
+                       limit: int = 50) -> dict[str, Any]:
+        """按页列出自己的运行（需 api_key），返回含 items 与 pagination 的信封。
+
+        归属按**用户**：同一个人换通道（SDK 的 key、门户）发起的 run 都在这一个
+        列表里；pagination.total 是筛选后的总数。筛选项可组合：
+
+        - status：运行状态；
+        - data_app：App 引用，`<用户名>/<应用名>` 两段式或不变标识 app_id
+          均可（口径见 get_app；解析不到得空结果集，不报错——报错会泄露
+          私有 App 的存在性）；
+        - triggered_by：来源渠道（sdk / mcp / api / cli）；
+        - run_kind：运行口径，production 生产 / test 作者调试（调试流量不冲稀
+          生产视角的分页）；
+        - credential：发起凭证的非密稳定标识（排查是哪把 key 在消耗额度），
+          取值与 billing(group_by="credential") 的分组键同源；
+        - created_from / created_to：发起时间范围，ISO-8601 绝对时刻、前闭后开。
+        """
+        return self._data("GET", "/runs", params={
+            "status": status, "data_app": data_app, "triggered_by": triggered_by,
+            "run_kind": run_kind, "credential": credential,
+            "created_from": created_from, "created_to": created_to,
+            "offset": offset, "limit": limit})
+
+    def list_runs(self, *, status: str | None = None, data_app: str | None = None,
+                  triggered_by: str | None = None, run_kind: str | None = None,
+                  credential: str | None = None, created_from: str | None = None,
+                  created_to: str | None = None, offset: int = 0,
+                  limit: int = 50) -> list[dict[str, Any]]:
+        """列出自己的运行（需 api_key），只要 items；筛选项同 list_runs_page。
+
+        需要筛选后的总数/翻页信息用 list_runs_page()，全量遍历用 iterate_runs()。
+        """
+        return self.list_runs_page(
+            status=status, data_app=data_app, triggered_by=triggered_by,
+            run_kind=run_kind, credential=credential, created_from=created_from,
+            created_to=created_to, offset=offset, limit=limit)["items"]
+
+    def iterate_runs(self, *, status: str | None = None, data_app: str | None = None,
+                     triggered_by: str | None = None, run_kind: str | None = None,
+                     credential: str | None = None, created_from: str | None = None,
+                     created_to: str | None = None,
+                     batch: int = 100) -> Iterator[dict[str, Any]]:
+        """自动翻页迭代自己的运行（屏蔽分页）；筛选项同 list_runs_page。"""
+        return self._paginate(
+            lambda offset: self.list_runs_page(
+                status=status, data_app=data_app, triggered_by=triggered_by,
+                run_kind=run_kind, credential=credential, created_from=created_from,
+                created_to=created_to, offset=offset, limit=batch),
+            key="items")
+
+    def cancel(self, run_id: str) -> dict[str, Any] | None:
+        """取消运行。返回更新后的运行对象；服务端空体响应时返回 None。"""
+        return self._data("POST", f"/runs/{_quote_id(run_id)}/cancel")
+
+    # ── 结果获取 ──────────────────────────────────────────────
+    def get_records(self, run_id: str, *, offset: int = 0, limit: int = 100,
+                    fields: str | None = None) -> dict[str, Any]:
+        """按页取 run 结果。fields 为逗号分隔的字段投影；返回含 records 与
+        pagination 的信封，大批量请改用 iterate_records()。"""
+        return self._data("GET", f"/runs/{_quote_id(run_id)}/records",
+                          params={"offset": offset, "limit": limit, "fields": fields})
+
+    def _paginate(self, fetch: Callable[[int], dict[str, Any]],
+                  key: str = "records") -> Iterator[dict[str, Any]]:
+        """fetch(offset) → {key: [...], "pagination": {count, has_more}}；
+        key 随端点而异（记录页是 records，运行列表是 items）。"""
+        offset = 0
+        while True:
+            page = fetch(offset)
+            records = page[key]
+            yield from records
+            if not page["pagination"]["has_more"]:
+                return
+            if not records:
+                # has_more 为真但本页 0 条：offset 无法前进，继续请求必死循环，
+                # 按服务端契约违例明确报错，不静默截断。
+                raise _invalid_response(200, "分页响应 has_more=true 但本页 0 条记录")
+            # 按实际取回的条数推进,不信 pagination.count——两者契约上相等,
+            # 服务端不一致时以实际条数为准,避免静默跳过/重复记录
+            offset += len(records)
+
+    def iterate_records(self, run_id: str, *, batch: int = 500,
+                        fields: str | None = None) -> Iterator[dict[str, Any]]:
+        """自动翻页迭代 run 结果（大批量出口，屏蔽分页）。fields 同 get_records。"""
+        return self._paginate(
+            lambda offset: self.get_records(run_id, offset=offset, limit=batch, fields=fields))
+
+    def export_records(self, run_id: str, format: str = "jsonl") -> str:
+        """jsonl / csv 文本导出（写文件由调用方决定）。
+
+        单次导出上限 EXPORT_LIMIT（10000）条，超量部分不包含在返回文本里；
+        需要全量请改用 iterate_records()。
+        """
+        resp = self._request("GET", f"/runs/{_quote_id(run_id)}/records",
+                             params={"format": format, "limit": EXPORT_LIMIT})
+        return resp.text
+
+    # ── 数据集 / 账户 ─────────────────────────────────────────
+    def list_datasets(self, *, offset: int = 0, limit: int = 50) -> list[dict[str, Any]]:
+        """列出自己的数据集（需 api_key），外加平台显式公开的种子/样例集。
+
+        run 产出的结果数据保留 90 天（按创建时间计）；要长期留存的数据集用
+        set_dataset_retention() 打保留标记（卡片的 retained 字段即该标记）。
+        """
+        return self._data("GET", "/datasets", params={"offset": offset, "limit": limit})["items"]
+
+    def set_dataset_retention(self, dataset_id: str,
+                              retained: bool = True) -> dict[str, Any]:
+        """置/撤数据集保留标记（幂等）：打了标记的数据集不参与 90 天到期清理。
+
+        标记是显式声明，读取不续期；只能标记自己 run 产出的数据集（他人的、
+        平台公开种子集、不存在的一律 404）。
+        """
+        return self._data("PUT", f"/datasets/{_quote_id(dataset_id)}/retention",
+                          json={"retained": retained})
+
+    def get_dataset_records(self, dataset_id: str, *, offset: int = 0,
+                            limit: int = 100) -> dict[str, Any]:
+        """按页取数据集记录，返回含 records 与 pagination 的信封；
+        大批量请改用 iterate_dataset_records()。"""
+        return self._data("GET", f"/datasets/{_quote_id(dataset_id)}/records",
+                          params={"offset": offset, "limit": limit})
+
+    def iterate_dataset_records(self, dataset_id: str, *,
+                                batch: int = 500) -> Iterator[dict[str, Any]]:
+        """自动翻页迭代数据集记录（大批量出口，屏蔽分页）。"""
+        return self._paginate(
+            lambda offset: self.get_dataset_records(dataset_id, offset=offset, limit=batch))
+
+    def account(self) -> dict[str, Any]:
+        """当前 api_key 的账户信息（配额、用量等，以平台返回为准）。"""
+        return self._data("GET", "/account")
+
+    def billing(self, *, group_by: str = "day", created_from: str | None = None,
+                created_to: str | None = None, tz_offset: int = 0) -> dict[str, Any]:
+        """账单聚合（需 api_key）：区间合计 + 分组明细，只含数据费。
+
+        group_by：day 按日（升序）/ data_app 按 App / credential 按发起凭证
+        （后两者按金额降序）。created_from / created_to 与 list_runs 同词汇
+        （ISO-8601 绝对时刻、前闭后开、按 run 发起时间归属），带同一组参数查
+        list_runs 就是这批数字对应的 run。
+        tz_offset 是 day 桶的时区偏移（相对 UTC 的分钟数，UTC+8 传 480），
+        缺省 0 即 UTC 日；只影响日归属，不改金额与区间语义。
+        """
+        return self._data("GET", "/billing", params={
+            "group_by": group_by, "created_from": created_from,
+            "created_to": created_to, "tz_offset": tz_offset or None})