initial

2026-08-23 02:12:08 +08:00
commit 5987b2a1f2
19 changed files with 4174 additions and 0 deletions
@@ -0,0 +1,43 @@
+# AI API 中转站 — 资料索引
+
+本目录收集各 AI provider 的 API 规格与"怪癖"（quirks），用于实现一个多格式兼容的中转站（gateway）。
+
+**资料采集时间：2026-08-12。** 各家文档变动频繁（尤其是模型名与 thinking 相关参数），落地实现前请对照文件头部的来源 URL 复核。
+
+## 文件清单
+
+| 文件 | 内容 |
+| --- | --- |
+| **[api-design.md](./api-design.md)** | **本项目的 API 契约设计**（双模板入口、IR、能力降级、thinking 桥接）— 其余文件是它的调研依据 |
+| **[transform-spec.md](./transform-spec.md)** | **转写方案 v0.3**（四家求同存异、上游 Profile、请求/响应改写管线 R1–R9 / S1–S9、推理内容可信度分级）— api-design 的落地层 |
+| [openai.md](./openai.md) | OpenAI Chat Completions + Responses API 规格与怪癖 |
+| [anthropic.md](./anthropic.md) | Anthropic Messages API 规格与怪癖 |
+| [deepseek.md](./deepseek.md) | DeepSeek API 规格与怪癖 |
+| [kimi.md](./kimi.md) | Kimi（月之暗面 Moonshot）API 规格与怪癖，**含 Kimi For Coding 独立产品线对比**（§17） |
+| [china-providers.md](./china-providers.md) | 国产厂商（通义/GLM/Kimi/豆包/文心/混元/MiniMax/星火）的怪癖 |
+| [cross-provider-mapping.md](./cross-provider-mapping.md) | 三家之间的字段/语义映射表，含流式事件映射 |
+| [compatibility-layers.md](./compatibility-layers.md) | 各家官方提供的"他家格式兼容层"，可作为中转站行为的参考实现 |
+| [errors-and-limits.md](./errors-and-limits.md) | 错误码、限流、超时、请求体积上限对照 |
+
+## 中转站要处理的核心难题（速览）
+
+1. **消息模型不同构**：OpenAI 是扁平 `messages[]` + `role: system`；Anthropic 是 `messages[]` + 独立顶层 `system`，且 content 是 block 数组。转换必然有损。
+2. **推理内容（thinking/reasoning）不可互换**：Anthropic 的 `thinking` 文本只是**摘要**，真正的推理内容加密在 `signature` 里，服务端靠解密它重建思考——所以"翻译成字符串再翻译回来"是死路，只能把密文当 opaque blob 原样搬运。OpenAI 用 `encrypted_content`，DeepSeek 用明文 `reasoning_content`。三者回传规则均不同，详见 [cross-provider-mapping.md](./cross-provider-mapping.md) §7。
+3. **工具调用 ID 与结构**：Anthropic `tool_use.id` / `tool_result.tool_use_id`（在 user 消息里）；OpenAI Chat 用 `tool_calls[].id` / `role: tool` 消息；OpenAI Responses 用 `call_id`。
+4. **流式协议不同**：OpenAI 是增量 delta 的 `chat.completion.chunk` + `[DONE]`；Anthropic 是有状态的 block 事件机（`content_block_start/delta/stop`），且 `message_delta.usage` 是**累计值**。
+5. **未支持参数的处理策略**：三家普遍**静默忽略**而非报错。中转站应明确选择"静默忽略"还是"显式报错"，并保持一致。
+
+**国产厂商的坑是另一个维度**——不在语义层而在协议层：HTTP 200 里藏业务错误（MiniMax `base_resp`）、流式默认返回全量累积文本（阿里 `incremental_output`）、六种互不相同的鉴权方式、`finish_reason: "sensitive"` 打破 OpenAI 枚举。详见 [china-providers.md](./china-providers.md)，其中 §0 和 §9 是跨厂商的共性结论。
+
+**还有第三个维度：同一家 API 内部按模型/按入口分裂。** Kimi 是典型——`temperature` 在新模型上写死 1.0 且**传其他值直接 400**（OpenAI 客户端的默认值开箱打不通），但**同样的参数走它自家的 Anthropic 入口却被静默忽略**；流式 `usage` 的位置由 `stream_options.include_usage` 决定（不传就藏在 `choices[0].usage`）。即"合法请求体取决于 `model` 和入口"。详见 [kimi.md](./kimi.md)，§16 是可直接落地的接入 checklist。
+
+**第四个维度是文档可信度。** Kimi 已用真实 key 实测，**10 条文档明确写下的规则被推翻**（含"K3 思考恒开不可关"这样的核心设定、以及官方 Claude Code 配置页照抄会 404 的模型名），见 [kimi.md](./kimi.md) §14。教训是：涉及"报错/不支持/必须"的文档表述，落地前一律实测——**两个方向的错都有**（文档说不能实际能、文档说能实际不能）。
+
+**第五个维度：一个"厂商"可能是多个上游。** Kimi 的 `platform`（`api.moonshot.cn`）和 **Kimi For Coding**（`api.kimi.com/coding`）共用推理层却是两套接入实现——模型名、鉴权、限流、端点、错误语义、tool_call id 格式全不同，key 互不通用，且 coding 侧**不校验模型名**（传 `gpt-4` 返回 200 并原样回显）。中转站必须按两个上游配置。见 [kimi.md](./kimi.md) §17。
+
+## 未覆盖 / 待补
+
+- Google Gemini（`generateContent`）— 用户未列入，尚未收集。
+- 零一万物 Yi、百川、阶跃星辰 StepFun、商汤日日新。
+- OpenAI Realtime API、Batch API、Embeddings 等非 chat 端点。
+- DeepSeek `multi_round_chat`、`token_usage`、`rate_limit` 页面（内容与其他页重合度高，未单独抓取）。