# zend-token API 设计

> 状态：设计草案 v0.2 · 2026-08-12
> 依据：[openai.md](./openai.md)、[anthropic.md](./anthropic.md)、[deepseek.md](./deepseek.md)、[china-providers.md](./china-providers.md)、[cross-provider-mapping.md](./cross-provider-mapping.md)
>
> v0.2 变更：单一 IR → **双规范模型**（§3）；`/v1/responses` 提升为一等入口。
>
> **后续**：本文的落地层是 [transform-spec.md](./transform-spec.md)（转写方案 v0.3），它在双规范模型之上补齐了上游 Profile、改写管线与 Kimi 实测结论。以下两处已被 v0.3 修正：§8.1 的"Claude 族上游一律 opaque 搬运 signature"只对 **Anthropic 官方真机**成立（见 transform-spec §7.1 的可信度分级）；§6 的能力矩阵需按**上游身份三元组**而非 provider 划分（同一家的两个入口行为可能相反）。

本文只定义**对外 API 契约与桥接语义**，不涉及技术栈、存储、部署选型。

---

## 1. 设计原则

1. **双族对等** — OpenAI 族与 Claude 族是**同等公民**，不是"主格式 + 转换层"。
2. **同族零损** — 同族内的入口/上游组合不经过跨族转换，不付出任何有损代价。
3. **有损集中** — 所有跨族有损只发生在**一处**（§5 跨族桥），集中实现、集中测试、集中记录。
4. **降级必须可见** — 上游能力不足导致的任何语义变化都要可观测。**静默忽略是各家的通病，我们不重复它**（§7）。
5. **上游怪癖不外泄** — MiniMax 的 `base_resp`、阿里的全量流、智谱的 `sensitive` 都在网关内消化。
6. **不发明第三种方言** — 扩展一律走命名空间（`ztoken` 对象 / `X-Ztoken-*` header），不污染标准字段。

---

## 2. 端点总览

| 端点 | 族 | 说明 |
| --- | --- | --- |
| `POST /v1/chat/completions` | OpenAI | 生态最广 |
| `POST /v1/responses` | OpenAI | 新接口，reasoning 能力完整 |
| `POST /v1/messages` | Claude | Claude Code 等客户端 |
| `POST /v1/messages/count_tokens` | Claude | token 预估 |
| `GET /v1/models` | 共用 | 模型列表 |
| `GET /v1/models/{model}` | 共用 | 含**能力矩阵**（本项目扩展，§6） |

认证同时接受两种 header，互为别名：

```
Authorization: Bearer <ztoken-key>     # OpenAI 风格
x-api-key: <ztoken-key>                # Claude 风格
```

`anthropic-version` 接受但不校验（我们只有一个版本）。

---

## 3. 双规范模型（核心）

### 3.1 为什么不用单一 IR

单一 IR 看起来更"优雅"，但有个真实缺陷：**它强迫每条路径都付出一次有损转换**。

实际流量分布是高度不均的——OpenAI 入口 → OpenAI 兼容上游（DeepSeek、智谱、Kimi、豆包、混元、千帆 v2、星火、阿里兼容模式）会是绝大多数。这条路径上，源和目标本来就是同一种方言，却要绕经 block 模型往返，白白丢失顺序信息又白白重建。

改为按族划分后：

```
Chat ─┐                                    ┌─ DeepSeek / 智谱 / Kimi / 豆包 /
      ├─→ 【OaiIR】 ──┬── 同族直出 ────────┤   混元 / 千帆v2 / 星火 / 阿里兼容
Responses ─┘          │                    └─ MiniMax / DashScope 原生
                      │
                 ╔════╧════╗
                 ║ 跨族桥  ║  ← 唯一的有损点
                 ╚════╤════╝
                      │
Messages ──→ 【AnthIR】┴────────────────────── Anthropic / DeepSeek-anthropic /
                                                阿里 Anthropic 兼容
```

**同族路径零转换成本；跨族只有一处，集中攻。** 这也让"Claude 入口 → Claude 上游"这条最脆弱的路径（thinking signature 必须原样保住）天然安全——它根本不进桥。

### 3.2 OaiIR — OpenAI 族规范模型

**以 Responses 的 item 模型为基线**，因为 `Responses item ⊃ Chat message`：Chat 把文本放 `content`、工具放 `tool_calls`，无法表达 reasoning 与 text 的交错顺序，Responses 的异构 `output[]` 可以。

```jsonc
{
  "model": "<逻辑模型名>",
  "instructions": "...",            // 顶层系统指令（Chat 的 system/developer 归一到这）
  "items": [                        // 异构数组，顺序即语义
    {"type":"message", "role":"user"|"assistant", "content":[Part]},
    {"type":"function_call", "call_id":"...", "name":"...", "arguments":"<json string>"},
    {"type":"function_call_output", "call_id":"...", "output":"..."},
    {"type":"reasoning", "id":"...", "summary":[...], "encrypted_content":"...?"}
  ],
  "tools": [{"type":"function","name":...,"parameters":{...},"strict":bool}],
  "tool_choice": {...},
  "sampling": {"max_output_tokens":int, "temperature":0..2, "top_p":..., "stop":[...],
               "frequency_penalty":?, "presence_penalty":?, "seed":?, "n":1},
  "reasoning": {"effort":"none|minimal|low|medium|high|xhigh|max", "summary":"auto|none"},
  "text": {"format": {"type":"text"|"json_object"|"json_schema", "schema":?, "strict":?}},
  "stream": bool,
  "passthrough": {"<provider>": {...}}
}
```

`Part` 类型：`input_text` / `output_text` / `input_image` / `input_file` / `refusal`。

**注意 `arguments` 是 JSON 字符串**而非对象——这是 OpenAI 族的原生形态，保留它可以让同族直出时零解析。

### 3.3 AnthIR — Claude 族规范模型

以 Messages 的 block 模型为基线：

```jsonc
{
  "model": "<逻辑模型名>",
  "system": [{"type":"text","text":"...","cache_control":?}],
  "messages": [
    {"role":"user"|"assistant", "content":[Block]}
  ],
  "tools": [{"name":..., "description":..., "input_schema":{...}, "strict":?}],
  "tool_choice": {"type":"auto"|"any"|"tool"|"none", "disable_parallel_tool_use":?},
  "sampling": {"max_tokens":int, "temperature":0..1, "top_p":?, "top_k":?, "stop_sequences":[...]},
  "thinking": {"mode":"auto"|"on"|"off", "effort":?, "budget_tokens":?, "display":"summarized"|"omitted"},
  "output_config": {"format":?, "effort":?},
  "stream": bool,
  "passthrough": {"<provider>": {...}}
}
```

`Block` 类型：`text` / `image` / `document` / `tool_use` / `tool_result` / `thinking` / `redacted_thinking` / `server_tool_use` / 各类 `*_tool_result`。

**`tool_use.input` 是对象**（不是字符串）——与 OaiIR 的 `arguments` 字符串形成明确对比，跨族时必须做 parse/stringify。这是个容易漏的点：Anthropic 流式下发的 `input_json_delta` 是部分 JSON 字符串，但终态是对象。

### 3.4 两族各自的不变量

族内归一在入口层立即完成，避免畸形约束泄漏进下游逻辑。

**OaiIR：**
1. `system` / `developer` 消息全部提升到 `instructions`，按原顺序用 `\n` 拼接。
2. Chat 的 `tool` role 消息转成 `function_call_output` item。
3. Chat 的 `assistant.tool_calls[]` 拆成独立的 `function_call` item，排在该 message item 之后。

**AnthIR：**
1. `role` 只有 `user` / `assistant`。
2. `content` 恒为数组（裸字符串包装成 `[{type:"text"}]`）。
3. **连续同 role 消息自动合并**为一条。这一条直接消化百度 v1 的"必须严格交替"约束。

**两族共同：**
- `max_output_tokens` / `max_tokens` 缺省时由能力矩阵填默认值，并标注 `X-Ztoken-Defaulted`。理由：Anthropic 侧必填，取严格的一方可以让每个 adapter 不必各写一份兜底。

### 3.5 路由决策

```
入口族 == 上游族  →  同族直出（零转换）
入口族 != 上游族  →  过跨族桥（§5）
```

`GET /v1/models/{model}` 暴露上游族，客户端可以据此选择同族入口以避开有损。

---

## 4. 入口方言层

三个入口各自负责"方言 → 族规范模型"的归一，不做跨族的事。

### 4.1 `/v1/chat/completions` → OaiIR

按 §3.4 归一。以下字段接受但按能力矩阵处理（可能降级，§7）：
`n`、`logprobs`、`top_logprobs`、`logit_bias`、`seed`、`frequency_penalty`、`presence_penalty`、`response_format`、`parallel_tool_calls`、`tools[].function.strict`。

响应回投影为 Chat 结构时：
- `function_call` item → `message.tool_calls[]`（`call_id` → `id`）
- `reasoning` item → `message.reasoning_content`（摘要文本）
- **`logprobs` 字段恒存在**（值可为 `null`）——OpenAI spec 列为 required，省略会打破严格客户端。

### 4.2 `/v1/responses` → OaiIR

近乎恒等映射（OaiIR 本就以它为基线）。需处理的：

| 字段 | 处理 |
| --- | --- |
| `input` 为 string | 包装成单个 user message item |
| `previous_response_id` | **v0.1 不支持**，返回 400 `unsupported_parameter`（我们无状态，见 §12 开放问题 1） |
| `conversation` | 同上 |
| `store` | 恒为 `false`，请求 `true` 时 L1 降级 |
| `background` | 不支持，L3 |
| `include` | 按能力矩阵过滤 |
| `context_management` | L1 丢弃（网关不做自动压缩） |

### 4.3 `/v1/messages` → AnthIR

按 §3.4 归一。`thinking` 参数接受三种历史写法并统一：

| 客户端传入 | AnthIR |
| --- | --- |
| `{"type":"enabled","budget_tokens":N}` | `mode:"on"`, `budget_tokens:N` |
| `{"type":"adaptive","display":D}` | `mode:"auto"`, `display:D` |
| `{"type":"disabled"}` | `mode:"off"` |

**这吃掉了 Anthropic 的代际地雷** —— 客户端不会再踩到"4.5 只认 enabled、4.7 只认 adaptive、Fable 5 两个都拒、Opus 5 的 disabled 还和 effort 冲突"（见 anthropic.md §5 的模型矩阵）。这是相对直连 Anthropic 的明确增值点。

`stop_reason: pause_turn` **不对外暴露**：网关内部完成服务端工具续跑循环后才返回终态。理由是 OpenAI 族无法表达它，两个族的行为必须一致。

### 4.4 扩展字段约定

三个入口统一，请求体顶层接受 `ztoken` 对象（未知子字段忽略不报错）：

```jsonc
{
  "ztoken": {
    "thinking": {"mode":"on","effort":"high"},      // 跨族统一的思考控制
    "strict_capability": false,                      // true = 能力不足报错而非降级
    "allow_degradation": ["vision","n"],             // 显式放行 L3
    "passthrough": {"dashscope": {"enable_search": true}}
  }
}
```

用嵌套对象而非顶层字段，是为了避免和未来的官方字段撞名。OpenAI SDK 的 `extra_body` 可直接塞它，客户端零改造。

---

## 5. 跨族桥（难点集中区）

这一节是整个设计里唯一有损的地方，所以要写得最细。

### 5.1 结构差异总览

| 维度 | OaiIR | AnthIR | 桥接难度 |
| --- | --- | --- | --- |
| 容器 | 扁平 `items[]`，工具调用是**独立 item** | `messages[].content[]`，工具调用是**消息内的 block** | 中 |
| 工具入参 | `arguments`: **JSON 字符串** | `input`: **对象** | 低（parse/stringify） |
| 工具结果 | 独立 `function_call_output` item | user 消息内的 `tool_result` block | 中 |
| 工具 ID | `call_id` | `tool_use.id` / `tool_result.tool_use_id` | 低（需映射表） |
| 系统指令 | `instructions` 字符串 | `system` block 数组 | 低 |
| 推理 | `reasoning` item + `encrypted_content` | `thinking` block + `signature` | **高**（§8） |
| 温度 | 0~2 | 0~1 | 低（clamp） |
| 工具错误 | 靠 output 文本表达 | `tool_result.is_error` 布尔 | 中（有损） |

### 5.2 OaiIR → AnthIR

```
instructions                    → system: [{type:"text", text}]
message(role=user)              → messages[].role=user, content=[blocks]
message(role=assistant)         → messages[].role=assistant, content=[blocks]
function_call                   → 并入前一条 assistant 消息的 content:
                                    {type:"tool_use", id:call_id, name, input:JSON.parse(arguments)}
function_call_output            → 新建/并入 user 消息:
                                    {type:"tool_result", tool_use_id:call_id, content:[{type:"text"}]}
reasoning                       → {type:"thinking", thinking:summary, signature:<信封>}
input_text/output_text          → {type:"text"}
input_image                     → {type:"image", source:{...}}
input_file                      → {type:"document", source:{...}}
refusal part                    → 丢弃（L2），原文记入 degraded 说明
```

**关键动作**：`function_call` item 必须**回填**进它前面那条 assistant message 的 content 数组，而不是新建消息——否则会产生连续两条 assistant 消息，违反 AnthIR 不变量 3（虽然会被自动合并，但顺序可能错）。

**`arguments` 解析失败**（模型吐出非法 JSON，流式截断时常见）：不要抛异常。降级为 `input: {}` 并标记 L2，把原始字符串放进 `ztoken` 诊断字段。

### 5.3 AnthIR → OaiIR

```
system[]                        → instructions（用 \n 拼接）
content[].text                  → message part(output_text / input_text)
content[].tool_use              → 独立 function_call item:
                                    {call_id:id, name, arguments:JSON.stringify(input)}
content[].tool_result           → 独立 function_call_output item
content[].thinking              → reasoning item{summary:[thinking], encrypted_content:<信封>}
content[].redacted_thinking     → reasoning item（summary 为空，data 进信封）
content[].image                 → input_image part
content[].document              → input_file part（PDF 可直传的上游）/ L3（不可传的）
tool_result.is_error=true       → output 文本前缀 "Error: "（**有损**，见 5.4）
server_tool_use / *_tool_result → L3：OpenAI 族无对应概念
citations                       → annotations（尽力而为，L2）
```

### 5.4 已知有损清单

跨族时必然丢失的信息，全部记入 `X-Ztoken-Degraded`：

| 丢失项 | 方向 | 级别 | 说明 |
| --- | --- | --- | --- |
| `tool_result.is_error` 语义 | A→O | L2 | OpenAI 无此字段，只能退化成文本前缀 |
| `thinking` 与 `text` 的交错顺序 | A→O(Chat) | L2 | Chat 的 message 结构表达不了；**走 Responses 入口则无损** |
| `cache_control` 断点 | O→A / A→非 Anthropic | L1 | 上游若非 Anthropic 则无处安放 |
| `top_k` | O→A 时反向缺失 | L1 | OpenAI 族无此参数 |
| `n > 1` | O→A | L3 | Anthropic 恒为 1 |
| `logprobs` | O→A | L2 | Anthropic 不支持，返回 null |
| server tools（web_search 等） | A→O | L3 | 概念不存在 |
| `citations` 精确位置 | A→O | L2 | annotations 表达力更弱 |
| **`signature` 真实性** | A→O→A 往返 | **L3** | 见 §8.4，往返后无法发回 Anthropic 上游 |

### 5.5 禁止跨族的情形

以下组合**直接返回 400**，不做勉强转换：

1. **Claude 入口 + 请求含 `thinking` + 非 Claude 族上游 + 后续要回传** — 见 §8.4。
2. **`n > 1` 且上游为 Claude 族** — 除非 `allow_degradation` 含 `n`。
3. **含 `server_tool_use` 历史的会话切到 OpenAI 族上游** — 历史无法表达，续接必然错乱。

---

## 6. 模型路由与能力矩阵

### 6.1 逻辑模型名

```jsonc
{
  "id": "qwen-max",
  "upstream": {
    "family": "openai",              // openai | anthropic —— 决定是否过桥
    "provider": "dashscope",
    "model": "qwen-max-latest",
    "endpoint_ref": null             // 火山方舟填 "ep-2024xxxx"
  },
  "capabilities": { ... }
}
```

**火山方舟的 Endpoint ID 是账号级资源**（china-providers.md §4），所以路由表是 `(tenant, logical_model) → upstream`，全局表仅作 fallback。

模型别名支持"伪装"：把 `claude-sonnet-4-6` 指向任意上游，让硬编码模型名的客户端直接可用。但**不静默兜底未知模型名**——未匹配返回 404，避免拼写错误被掩盖（DeepSeek 的 Anthropic 兼容层就是反面教材）。

### 6.2 能力矩阵

```jsonc
"capabilities": {
  "family": "openai",
  "streaming": true,
  "streaming_incremental": true,   // false = 上游返回全量累积，网关需差分（阿里）
  "tools": true,
  "tool_strict": false,
  "parallel_tools": true,
  "vision": true,
  "documents": false,
  "json_mode": true,
  "json_schema": false,
  "thinking": "always_on" | "optional" | "none",
  "thinking_opaque": true,         // 思考内容必须原样回传（Anthropic=true）
  "prefill": false,                // 助手前缀续写（DeepSeek prefix / Kimi partial）
  "n_max": 1,
  "temperature_range": [0.0, 1.0],
  "max_output_tokens": 8192,
  "cache": "explicit" | "automatic" | "none"
}
```

---

## 7. 能力降级协议

各家的通病是静默忽略。我们保留静默以维持生态兼容，但**强制可观测**。

### 7.1 三级降级

| 级别 | 定义 | 默认行为 |
| --- | --- | --- |
| **L1 无害** | 丢弃不改变输出语义 | 静默丢弃，仅记 header |
| **L2 降质** | 输出仍可用但质量/精度变化 | header + 结构化 warning |
| **L3 变义** | 客户端拿到的东西与请求语义不符 | **报 400**，除非显式放行 |

| 参数/能力 | 级别 |
| --- | --- |
| `seed`、`logit_bias`、`metadata`、`user`、`store` | L1 |
| `temperature` clamp、`top_k` 丢弃、penalty 丢弃、`logprobs` 返回 null | L2 |
| **`tools[].strict` 失效** | **L3** |
| **图片/文档输入被丢弃** | **L3** |
| **`n > 1` 退化为 1** | **L3** |
| **`json_schema` 降级为 `json_object`** | **L3** |

### 7.2 可观测通道

```
X-Ztoken-Upstream: dashscope/qwen-max-latest (family=openai, bridged=false)
X-Ztoken-Degraded: seed=dropped(L1), temperature=clamped(L2,2.0->1.0), strict=ignored(L3)
X-Ztoken-Defaulted: max_output_tokens=4096
```

`bridged=true/false` 让调用方知道自己是否付了跨族代价——这是选择入口的直接依据。

**严格模式**：`ztoken.strict_capability: true` 时，任何 L2 及以上降级直接 400，错误体列出全部冲突项。

L3 默认报错是本设计与所有现有兼容层的最大分歧。宁可让调用方显式声明"我接受图片被丢弃"，也不要让他拿到一个看起来正常、实际模型根本没看到图的响应。放行方式：

```jsonc
"ztoken": {"allow_degradation": ["vision", "n", "strict"]}
```

---

## 8. thinking / reasoning 桥接

依据 anthropic.md §5：Anthropic 的 `thinking` 文本只是**摘要**，真实推理加密在 `signature` 里，**改一个字节就 400**。所以桥接必须搬运不透明数据，不是翻译文本。

### 8.1 四象限

| 入口族 | 上游族 | 策略 |
| --- | --- | --- |
| Claude | Claude | **原样透传**，不解包不重打包 —— 唯一能保住真 signature 的路径 |
| OpenAI | OpenAI | 原样透传 `encrypted_content` / `reasoning_content` |
| OpenAI | Claude | 摘要 → `reasoning_content`；真 signature 装进信封放 `encrypted_content` |
| Claude | OpenAI | 上游 `reasoning_content` → `thinking.thinking`；`signature` 填我们的信封 |

**两条同族路径都不进桥**，这正是双规范模型的最大收益。

### 8.2 信封格式

```
ztk1.<base64url(AES-GCM(payload))>
```

`payload` = 上游原始 block/item 数组 + 元数据（provider、model、family、生成时间）。客户端视其为**完全不透明**。`ztk1.` 前缀用于版本演进；解析不了的信封当作"无思考上下文"降级，不报错。

### 8.3 无状态优先

默认下发信封由客户端原样回传，网关不存储。与 OpenAI 的 `encrypted_content`、Anthropic 的 `signature` 同一思路，行业已验证。

风险是客户端裁剪未知字段。缓解：信封放在**该族的原生位置**（OpenAI 族 → `reasoning.encrypted_content`；Claude 族 → `thinking.signature`），这两个位置是各自 SDK 会保留的标准字段，比自定义字段安全得多。

> 有状态 handle 模式作为可选项保留，不进 v0.2 契约。

### 8.4 A→O→A 往返的硬限制

**这是必须写进对外文档的一条。**

Claude 上游的思考经 OpenAI 族客户端往返后，回来的 `signature` 是**我们的信封**，不是 Anthropic 的原始 signature。网关可以解开信封还原原始 block —— 但前提是**信封没被裁剪**。

若客户端丢弃了 `encrypted_content`，原始 signature 就永久丢失，此时：

- 该会话**不能再发回 Anthropic 上游**（会 400 或丢失推理连续性）。
- 网关的行为：剥离全部 thinking block，标记 `X-Ztoken-Degraded: thinking=lost(L3)`，并按 §7 规则报错或放行。

因此 §5.5 规定：Claude 入口 + thinking + 非 Claude 上游 + 需回传的组合，默认拒绝。

### 8.5 三条实现硬约束

1. **切换上游模型时必须剥离 thinking block** —— 其他模型静默忽略但**照样计费**。故障转移路径尤其注意。
2. **信封只走 body，绝不走 header** —— Claude 4+ 的 signature 显著变长，header 有截断风险，截断的 signature 下一轮直接 400。
3. **不得按 `type == "thinking"` 过滤** —— 会漏掉 `redacted_thinking`，直接破坏协议。

---

## 9. 流式契约

### 9.1 对外保证

无论上游行为如何：

1. **增量语义** — 每个事件只含新增内容。上游返回全量累积时（阿里 `incremental_output=false`）网关做差分，由能力矩阵 `streaming_incremental: false` 驱动。
2. **事件顺序合法** — Claude 族保证 `message_start` → block 三段式 → `message_delta` → `message_stop`；OpenAI 族保证首 chunk 带 role、末尾 `data: [DONE]`。
3. **usage 位置固定** — Chat 下需 `stream_options.include_usage` 才发末尾 usage chunk（`choices` 为空数组）；Messages 下 `message_delta.usage` 为**累计值**。
4. **中途错误可表达** — §10.3。

### 9.2 跨族流式的状态机

跨族时流式比非流式难得多，因为要**在流上重建结构**：

**O→A**：OpenAI chunk 无"块结束"信号，只能靠 `tool_calls[].index` 变化和 `finish_reason` 推断边界。网关需维护 block index 状态机，在文本↔工具切换时补发 `content_block_stop` / `content_block_start`。

**A→O**：
- `content_block_start(text)` → 吞掉（无对应）
- `content_block_start(tool_use)` → 发一个带 `id`/`name`、`arguments:""` 的 tool_calls chunk
- `input_json_delta.partial_json` → 追加到 `arguments`
- `thinking_delta` → `delta.reasoning_content`
- **`signature_delta` → 无处安放**，必须缓冲到 block 结束后装信封，随末尾 chunk 下发
- `message_delta.usage` 累计值 → 取末值，不累加
- `ping` → 丢弃或转 SSE 注释行保活

### 9.3 上游怪癖消化清单

| 上游怪癖 | 处理 |
| --- | --- |
| 阿里全量累积流 | 差分成增量 |
| 阿里需 `X-DashScope-SSE: enable` | adapter 自动附加 |
| Anthropic `fallback` block 无 delta | 解析器不假设每 block 至少一个 delta |
| Anthropic 200 后发 `error` 事件 | 转成客户端族的错误表达 |
| OpenAI `[DONE]` 非 JSON | 单独识别，不进 JSON 解析器 |
| MiniMax 200 内嵌错误 | 流首帧即检测 `base_resp`，转真实状态码 |

### 9.4 provider 透传

`ztoken.passthrough.<provider>` 在**匹配到该 provider 时**原样并入上游请求体，不匹配则丢弃。用于阿里 `enable_search`、`repetition_penalty` 这类无法归一的自有参数。透传字段不参与能力校验，风险由调用方承担。

---

## 10. 错误模型

### 10.1 双族错误格式

按入口族返回对应格式，**HTTP 状态码两族一致**：

```jsonc
// OpenAI 族
{"error": {"message":"...", "type":"invalid_request_error", "param":"tools[0].strict", "code":"capability_unsupported"}}

// Claude 族
{"type":"error", "error":{"type":"invalid_request_error","message":"..."}, "request_id":"req_..."}
```

两族都返回 `X-Ztoken-Request-Id`。

### 10.2 上游错误归一

| 上游 | 对外 |
| --- | --- |
| MiniMax 200 + `base_resp.status_code != 0` | **翻译成真实状态**（1002→429、1004→401、1008→402、1039→400） |
| DeepSeek 402 余额不足 | 429 + `insufficient_quota` |
| Anthropic 529 overloaded | 503 |
| DeepSeek 422 | 400 |
| 智谱 `finish_reason:"sensitive"` | 非错误 → 映射 `content_filter`，原值放 `ztoken.upstream_finish_reason` |

**MiniMax 这条是网关的核心价值之一**：上游用 200 表达限流会让所有标准重试/熔断中间件失效，还原成 429 后通用组件即可正常工作。

### 10.3 流式中途错误

已发 200 后无法改状态码：

- **Claude 族**：发 `event: error`（与官方一致）。
- **OpenAI 族**：发含 `error` 字段的 data chunk，随后 `data: [DONE]`。OpenAI 无官方规范，此为我们的事实约定，需写进对外文档。

---

## 11. usage 归一

两族 usage 互转按 cross-provider-mapping.md §5。**最易错的一条**：

```
OpenAI prompt_tokens = Anthropic (input_tokens + cache_read_input_tokens + cache_creation_input_tokens)
```

直接用 `input_tokens` 在缓存命中时会低报到 1%。

网关自身计费**以上游原始 usage 为准**，不依赖任何投影结果。

---

## 12. 开放问题

1. **`previous_response_id` / `conversation` 要不要支持？** 支持就意味着网关有状态（要存会话）。当前设计是 400 拒绝。若要支持，建议只做"信封化"——把历史塞进加密信封由客户端持有，保持无状态。
2. **L3 默认报错**是否可接受？会让"能跑就行"的客户端在我们这里失败、在别家静默成功。我认为值得，但这是产品取向。
3. **信封是否需对客户端可解密？** 目前完全不透明（网关持密钥）。若要客户端可自查，需改成签名而非加密。
4. **`cache_control` 对非 Anthropic 上游**：接受并 L1 丢弃，还是直接拒绝？
5. **多模态是否代下载转码？** 图片 base64/url 支持度各家不一，代下载会引入出网请求和体积限制。

---

## 13. 实现顺序

1. **两个族规范模型 + 三个入口方言层**（不接上游，用 echo adapter 打通）
2. **能力矩阵 + 降级引擎**（§7，纯逻辑，可完整单测）
3. **第一个上游 adapter：DeepSeek**（OpenAI 兼容，同族直出，最简单）
4. **跨族桥的非流式路径**（§5）—— 用双向往返测试保证：`O→A→O` 与 `A→O→A` 的可逆部分必须恒等
5. **流式规范化层**（§9，含阿里全量差分）—— 最易出 bug，值得先写对照测试
6. **跨族桥的流式路径**（§9.2）—— 全项目最难的一块，状态机需单独设计
7. **Anthropic adapter**（thinking 原样透传路径）
8. **国产 adapter 批量接入**

第 4 步和第 6 步是这个项目的技术核心，其余都是工程量。