modify: call 对齐 worker_manager 语义（换副本重试/冷静期/信封原样透传），0.1.1 补 orjson 依赖与回归测试

README.md

@@ -15,8 +15,9 @@ uv pip install -e utils/request
 ## 功能
 
 - **自动服务发现**：基于 Zenoh liveliness 自动发现存活的 Worker
-- **随机负载均衡**：在可用 Worker 间随机选择
-- **超时重试**：请求超时后自动重试
+- **随机负载均衡**：在可用 Worker 间随机选择；疑似故障副本进入 30s 冷静期被跳过
+- **换副本重试**：超时 / 无回复 / 业务错误时换一个「未试过」的副本重试，
+  无未试副本立即失败（不重复打同一个坏副本）；业务错误不列入冷静期
 - **同步/异步支持**：提供 `call`（异步）和 `call_sync`（同步）接口
 
 ---
@@ -44,11 +45,26 @@ async with Client(session=zenoh_session) as client:
 | `subject`     | `str`           | Zenoh 主题（如 `"example.add"`） |
 | `payload`     | `dict`          | 业务参数（自动封装为信封）       |
 | `method`      | `str`           | HTTP 方法（`"GET"` / `"POST"`）  |
-| `timeout`     | `float`         | 超时时间（秒）                   |
+| `timeout`     | `float`         | 单次调用超时（秒），换副本重试重新计时 |
+| `retries`     | `int`           | 失败重试次数（每次重试换一个未试过的副本） |
 
-> **信封协议**：`call()` 会把 `payload` 自动封装为
-> `{"meta": {"method": ...}, "data": payload}` 发送，**不再修改调用方传入的 dict**；
-> 若传入的 `payload` 已含 `meta`/`data` 结构则原样复用（仅补 `meta.method`）。
+> **信封协议**：`call()` 把 `payload` 封装为
+> `{"meta": {"method": ...}, "data": payload}` 发送，**不修改调用方传入的 dict**；
+> 若传入的 `payload` 已含 `meta`/`data` 键则视为完整信封**原样使用**（保留全部
+> 字段、不改写 `0`/`[]` 等 falsy 值），仅缺 `meta.method` 时补入。`meta` 非 dict
+> 会立即抛 `ValueError`，不会被发送。
+
+### 与网关 `worker_manager.call_raw` 的语义对齐
+
+- **载荷**：业务数据整体入 `data`；调用方自备信封时不改写（对齐 call_raw 的
+  "谁构造信封谁负责"）。
+- **回复**：worker 回复解析为 dict 返回，空回复兜底 `{}`（对齐 call_raw 的 `b"{}"`）。
+- **重试**：超时 / 无回复 / 业务错误换未试过的副本重试；超时与无回复的副本进入
+  30s 冷静期，后续调用跳过；失败终态抛 `RuntimeError` 并携带最后一个错误详情
+  （已尝试副本数、次数上限、具体原因）。
+- **信任模型**：本包定位为**内部 worker 请求工具**（worker 间调用 / 服务端内部直连），
+  走 Zenoh 直连、无 HTTP 链路：`meta.user_info` **不会**被注入或校验，需要时由调用方
+  自填；`cacheable`、实例定向（`instance_id`）等能力请走网关 HTTP 或 `call_raw`。
 
 ### 同步调用
 
@@ -83,6 +99,15 @@ result = client.call_sync(
 
 ---
 
+## 测试
+
+```bash
+python tests/test_client.py
+```
+
+---
+
 ## 依赖
 
 - `zenoh` — Zenoh Python 绑定（`eclipse-zenoh`）
+- `orjson` — JSON 序列化