# qing-client (Python)

Qing 平台统一 SDK 的 Python 版本，与 npm 包 `qing-client` 的 API 设计对齐。

## 安装

```bash
pip install -e /path/to/client/pip
# 或发布后
pip install qing-client
```

## 使用

### 网关模式（前端/统一网关）

```python
from qingclient import Client
from qingclient.types import ClientConfig

config = ClientConfig(
    gateway_url="https://your-gateway.example.com",
    project_id="your-project-id",
    # 可选: org_id, app_id
)
client = Client(config)

# 登录后设置 token
res = client.auth.login("user", "password")
client.set_token(res.access_token)

# 调用各服务
user = client.user.get_current_user()
messages = client.msg.get_messages()
```

### 后端模式（直连各服务）

直连时各服务 URL 需包含该服务在后端的路径前缀，例如 token 服务为 `.../api/token`，这样 path `/wxh5/accesstoken` 才会请求到正确的完整路径。详见根目录 [client/README.md](../README.md) 的「SDK 与现有架构对齐说明」。

```python
from qingclient import Client
from qingclient.types import ClientConfig, UserContext

config = ClientConfig(
    auth_service_url="http://auth-svc",
    msg_service_url="http://msg-svc",
    user_service_url="http://user-svc",
    token_service_url="http://token-svc/api/token",  # 含路径前缀
    # ... 其他服务 URL
)
client = Client(config)

# 设置用户上下文（模拟请求方）
client.set_user_context(UserContext(
    user_id="uid",
    role="ADMIN",
    project_id="pid",
))

# 调用服务
messages = client.msg.get_messages()
```

### 服务列表（与 npm 一致）

- `client.auth` - 认证
- `client.msg` - 消息
- `client.user` - 用户
- `client.token` - Token 中控（公众号/小程序 access_token、jsapi_ticket、签名、小程序登录与获取手机号等）
- `client.file` - 文件
- `client.ai` - AI 对话
- `client.aigc` - AIGC
- `client.provider` - 提供商
- `client.usage` - 用量
- `client.audit` - 审计日志
- `client.fronthost` - 前端托管
- `client.org` - 组织
- `client.delivery_stream` - 投递流
- `client.ez_ability` - Ez 能力
- `client.im` - IM
- `client.hub` - 能力枢纽
- `client.task` - 任务

## 版本与发版

与 npm 包（client/npm）版本号对齐。**通过脚本自动递增**（沿用原 super/client/pip 方式）：

```bash
cd client/pip
./release.sh patch          # 1.0.17 → 1.0.18，并构建、上传 PyPI
./release.sh minor          # 1.0.17 → 1.1.0
./release.sh major          # 1.0.17 → 2.0.0
./release.sh patch --no-upload   # 仅递增 version.txt、同步 fallback_version 并本地构建，不上传
```

脚本会：读取 `version.txt` → 按 major/minor/patch 递增 → 写回 `version.txt` → 同步 `pyproject.toml` 的 `fallback_version` → 使用 `SETUPTOOLS_SCM_PRETEND_VERSION` 构建。与 npm 同步发版时，可先在本目录执行 `./release.sh patch --no-upload` 得到新版本号，再更新 npm 的 `package.json` 为同一版本。
