zai-rs 0.5.0

# zai-rs

一个简洁、类型安全的 Zhipu AI Rust SDK。专注提升 Rust 开发者的接入效率：更少样板代码、更一致的错误处理、可读的请求/响应类型，以及开箱即用的示例。

> **0.5 release candidate** — `main` 分支包含 0.5 的 breaking release candidate。crates.io 当前公开版本为 0.2.0。安装 main 分支版本：`zai-rs = { git = "https://github.com/AnlangA/zai-rs", branch = "main" }`。迁移指南见 [docs/MIGRATING-0.5.md](docs/MIGRATING-0.5.md)。

## 快速开始

1. 准备环境
   - Rust 1.88+（edition 2024）
   - 设置环境变量：`ZHIPU_API_KEY="<your_api_key>"`
2. 构建
   - `cargo build`
3. 运行示例（examples/ 目录内）
   - `cargo run --example chat_loop`

更多设计和维护说明见 [架构说明](docs/ARCHITECTURE.md)，完整使用文档见 [docs/](docs/README.md)。

## 支持的模型

### 文本模型

| 模型 | 结构体 | Thinking | ReasoningEffort | Async | ToolStream |
|------|--------|----------|-----------------|-------|------------|
| glm-5.2 | `GLM5_2` | ✓ | ✓ | ✓ | ✓ |
| glm-5.1 | `GLM5_1` | ✓ | ✗ | ✓ | ✓ |
| glm-5 | `GLM5` | ✓ | ✗ | ✓ | ✓ |
| glm-5-turbo | `GLM5_turbo` | ✓ | ✗ | ✓ | ✓ |
| glm-4.7 | `GLM4_7` | ✓ | ✗ | ✓ | ✓ |
| glm-4.7-flash | `GLM4_7_flash` | ✓ | ✗ | ✓ | ✗ |
| glm-4.7-flashx | `GLM4_7_flashx` | ✓ | ✗ | ✓ | ✗ |
| glm-4.6 | `GLM4_6` | ✓ | ✗ | ✓ | ✓ |
| glm-4.5 | `GLM4_5` | ✓ | ✗ | ✓ | ✗ |
| glm-4.5-X | `GLM4_5_x` | ✓ | ✗ | ✓ | ✗ |
| glm-4.5-air | `GLM4_5_air` | ✓ | ✗ | ✓ | ✗ |
| glm-4.5-airx | `GLM4_5_airx` | ✓ | ✗ | ✓ | ✗ |
| glm-4.5-flash | `GLM4_5_flash` | ✓ | ✗ | ✓ | ✗ |

### 文本视觉模型

| 模型 | 结构体 |
|------|--------|
| autoglm-phone | `autoglm_phone` |
| glm-5v-turbo | `GLM5V_turbo` |
| glm-4.6v | `GLM4_6v` |
| glm-4.6v-flash | `GLM4_6v_flash` |
| glm-4.6v-flashx | `GLM4_6v_flashx` |
| glm-4.5v | `GLM4_5v` |

### 语音模型

| 模型 | 结构体 |
|------|--------|
| glm-4-voice | `GLM4_voice` |

## 示例（examples/）

### 可用示例

| 示例 | 描述 |
|------|------|
| `chat_text` | 基础文本对话 |
| `chat_stream` | 流式响应 |
| `chat_loop` | 多轮对话循环 |
| `chat_coding_plan` | 编程辅助对话（coding 专属端点） |
| `coding_plan_usage` | Coding Plan 余量 / 额度查询 |
| `chat_vision` | 视觉模型对话（图片/视频） |
| `chat_voice` | 语音模型对话 |
| `async_chat_text` | 异步对话任务提交与轮询 |
| `glm45_thinking_mode` | 深度思考模式 |
| `glm52_reasoning_effort` | GLM-5.2 推理深度控制（reasoning_effort） |
| `tool_stream_min` | 流式工具调用 |
| `function_call` | 函数调用 |
| `function_call_with_toolkits` | 工具集调用 |
| `translation_bot` | 翻译机器人 |
| `ocr` | OCR 手写文字识别 |
| `gen_image` | 图像生成 |
| `gen_video` | 视频生成 |
| `text_to_audio` | 文本转语音 |
| `audio_to_text` | 语音转文字 |
| `voice_clone` | 音色复刻 |
| `embedding` | 文本嵌入 |
| `files_upload` | 文件上传 |
| `knowledge_create` | 知识库创建 |
| `web_search` | 网络搜索 |
| `batches_create` | 批处理任务创建 |
| `batches_cancel` | 批处理任务取消 |

### 运行方式

```bash
# Windows PowerShell
$Env:ZHIPU_API_KEY = "<your_api_key>"
cargo run --example chat_loop

# macOS/Linux
export ZHIPU_API_KEY="<your_api_key>"
cargo run --example chat_loop
```

## API 覆盖度

### 模型 API
- [x] POST 对话补全（同步/异步/流式）
- [x] GLM-5.2 / GLM-5.1 / GLM-5 / GLM-4.7 / GLM-4.6 / GLM-4.5 系列支持
- [x] 思考模式（Thinking Mode），支持 clear_thinking 保留式思考
- [x] 推理深度控制（Reasoning Effort，GLM-5.2+：max/xhigh/high/medium/low/minimal/none）
- [x] 流式工具调用（Tool Stream）
- [x] 图像生成
- [x] 视频生成（异步）
- [x] 语音转文本
- [x] 文本转语音
- [x] 音色复刻/列表/删除
- [x] 文本嵌入/重排序/分词
- [x] OCR 手写识别

### 工具 API
- [x] POST 网络搜索
- [x] POST 内容安全
- [x] POST 文件解析
- [x] GET 解析结果

### 文件 API
- [x] GET 文件列表
- [x] POST 上传文件
- [x] DELETE 删除文件
- [x] GET 文件内容

### 批处理 API
- [x] GET 列出批处理任务
- [x] POST 创建批处理任务
- [x] GET 检索批处理任务
- [x] POST 取消批处理任务

### 知识库 API
- [x] GET 知识库列表
- [x] POST 创建知识库
- [x] GET 知识库详情
- [x] PUT 编辑知识库
- [x] DELETE 删除知识库
- [x] GET 知识库使用量
- [x] GET 文档列表
- [x] POST 上传文件文档
- [x] POST 上传 URL 文档
- [x] GET 文档详情
- [x] DELETE 删除文档
- [x] POST 重新向量化

### Coding Plan API
- [x] POST 编程辅助对话（`/api/coding/paas/v4`，专属端点）
- [x] GET 余量 / 额度查询（`/api/monitor/usage/quota/limit`，5 小时窗口 + 每周窗口）

```rust,no_run
use zai_rs::usage::CodingPlanUsageRequest;

# async fn go(key: String) -> zai_rs::ZaiResult<()> {
let resp = CodingPlanUsageRequest::new(key).send().await?;
if let Some(window) = resp.time_limit() {
    println!("5h 余量: {}/{}", window.remaining(), window.number);
}
# Ok(())
# }
```

### 实时 API
- [x] WebSocket 类型定义
- [x] 会话管理框架（`RealtimeClient` / `SessionBuilder`）
- [x] Bearer / JWT 双鉴权
- [x] 完整 client/server 事件（`ClientEvent` / `ServerEvent`）
- [ ] 音视频通话高级封装（待完善）