From b14685d9a5684144bf9217eaacaf3b6dddede64c Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Sun, 19 Apr 2026 18:09:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85detectInterfaceType?= =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/conversion_anthropic.md | 17 +++++++++++++++-- docs/conversion_design.md | 14 +++++++++++--- docs/conversion_openai.md | 19 +++++++++++++++++-- 3 files changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/conversion_anthropic.md b/docs/conversion_anthropic.md index edc2e68..866e6f6 100644 --- a/docs/conversion_anthropic.md +++ b/docs/conversion_anthropic.md @@ -42,7 +42,19 @@ | `/v1/messages/count_tokens` | 透传 | | `/v1/*` | 透传 | -### 2.2 接口能力矩阵 +### 2.2 detectInterfaceType + +``` +Anthropic.detectInterfaceType(nativePath): + if nativePath == "/v1/messages": return CHAT + if nativePath == "/v1/models": return MODELS + if nativePath matches "^/v1/models/[^/]+$": return MODEL_INFO + return PASSTHROUGH +``` + +**说明**：`detectInterfaceType` 由 Anthropic Adapter 实现，根据 Anthropic 协议的 URL 路径约定识别接口类型。 + +### 2.3 接口能力矩阵 ``` Anthropic.supportsInterface(type): @@ -54,7 +66,7 @@ Anthropic.supportsInterface(type): default: return false ``` -### 2.3 URL 映射表 +### 2.4 URL 映射表 ``` Anthropic.buildUrl(nativePath, interfaceType): @@ -771,6 +783,7 @@ Anthropic.encodeError(error): | 章节 | 检查项 | |------|--------| +| §2 | [x] `detectInterfaceType(nativePath)` 已实现，所有已知路径已覆盖 | | §2 | [x] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | | §2 | [x] 所有 InterfaceType 的 `buildUrl` 映射已确定 | | §3 | [x] `buildHeaders(provider)` 已实现，adapter_config 契约已文档化 | diff --git a/docs/conversion_design.md b/docs/conversion_design.md index f1a3925..8e66e11 100644 --- a/docs/conversion_design.md +++ b/docs/conversion_design.md @@ -384,6 +384,7 @@ interface ProtocolAdapter { supportsPassthrough(): Boolean // 同协议透传开关，默认 true // HTTP 级别 + detectInterfaceType(nativePath: String): InterfaceType // 根据协议的 URL 路径识别接口类型 buildUrl(nativePath: String, interfaceType: InterfaceType): String // 始终返回有效 URL；未知接口返回 nativePath buildHeaders(provider: TargetProvider): Map supportsInterface(interfaceType: InterfaceType): Boolean @@ -477,7 +478,6 @@ class ConversionEngine { // 非流式请求转换 convertHttpRequest(request, clientProtocol, providerProtocol, provider): HttpRequest { nativePath = request.url - interfaceType = detectInterfaceType(nativePath) if isPassthrough(clientProtocol, providerProtocol): providerAdapter = registry.get(providerProtocol) @@ -487,6 +487,9 @@ class ConversionEngine { clientAdapter = registry.get(clientProtocol) providerAdapter = registry.get(providerProtocol) + // 使用 clientAdapter 识别接口类型 + interfaceType = clientAdapter.detectInterfaceType(nativePath) + providerUrl = providerAdapter.buildUrl(nativePath, interfaceType) providerHeaders = providerAdapter.buildHeaders(provider) providerBody = convertBody(interfaceType, clientAdapter, providerAdapter, provider, request.body) @@ -840,7 +843,7 @@ TargetProvider // ─── 协议适配器 ─── ProtocolAdapter .protocolName() / .protocolVersion() / .supportsPassthrough() - .buildUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type) + .detectInterfaceType(nativePath) / .buildUrl(nativePath, type) / .buildHeaders(provider) / .supportsInterface(type) .decodeRequest(raw) / .encodeRequest(canonical, provider) .decodeResponse(raw) / .encodeResponse(canonical) .createStreamDecoder() / .createStreamEncoder() @@ -932,10 +935,14 @@ Canonical Model 是**活的公共契约**，不是固定不变的。其字段集 | 项目 | 说明 | |------|------| -| URL 路径模式 | 列出所有接口的 URL 路径和对应的 InterfaceType | +| URL 路径模式 | 列出所有接口的 URL 路径和对应的 InterfaceType，由 `detectInterfaceType` 实现 | | 接口能力矩阵 | 每种 InterfaceType 的支持状态（`supportsInterface`） | | URL 映射表 | 每种 InterfaceType 的目标 URL 路径（`buildUrl`） | +**重要**：`detectInterfaceType` 由各协议 Adapter 实现，因为不同协议有不同的 URL 路径约定。例如： +- OpenAI: `/v1/chat/completions` → CHAT +- Anthropic: `/v1/messages` → CHAT + ### D.3 请求头构建 | 项目 | 说明 | @@ -1049,6 +1056,7 @@ Canonical Model 是**活的公共契约**，不是固定不变的。其字段集 | 章节 | 检查项 | |------|--------| +| D.2 | [ ] `detectInterfaceType(nativePath)` 已实现，所有已知路径已覆盖 | | D.2 | [ ] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | | D.2 | [ ] 所有 InterfaceType 的 `buildUrl` 映射已确定 | | D.3 | [ ] `buildHeaders(provider)` 已实现，adapter_config 契约已文档化 | diff --git a/docs/conversion_openai.md b/docs/conversion_openai.md index 5d715ca..914757f 100644 --- a/docs/conversion_openai.md +++ b/docs/conversion_openai.md @@ -41,7 +41,21 @@ | `/v1/embeddings` | EMBEDDINGS | | `/v1/rerank` | RERANK | -### 2.2 接口能力矩阵 +### 2.2 detectInterfaceType + +``` +OpenAI.detectInterfaceType(nativePath): + if nativePath == "/v1/chat/completions": return CHAT + if nativePath == "/v1/models": return MODELS + if nativePath matches "^/v1/models/[^/]+$": return MODEL_INFO + if nativePath == "/v1/embeddings": return EMBEDDINGS + if nativePath == "/v1/rerank": return RERANK + return PASSTHROUGH +``` + +**说明**：`detectInterfaceType` 由 OpenAI Adapter 实现，根据 OpenAI 协议的 URL 路径约定识别接口类型。 + +### 2.3 接口能力矩阵 ``` OpenAI.supportsInterface(type): @@ -55,7 +69,7 @@ OpenAI.supportsInterface(type): default: return false ``` -### 2.3 URL 映射表 +### 2.4 URL 映射表 ``` OpenAI.buildUrl(nativePath, interfaceType): @@ -1141,6 +1155,7 @@ mapErrorCode(code): | 章节 | 检查项 | | ---- | -------------------------------------------------------------------------------------------- | +| §2 | [x] `detectInterfaceType(nativePath)` 已实现，所有已知路径已覆盖 | | §2 | [x] 所有 InterfaceType 的 `supportsInterface` 返回值已确定 | | §2 | [x] 所有 InterfaceType 的 `buildUrl` 映射已确定 | | §3 | [x]`buildHeaders(provider)` 已实现，adapter_config 契约已文档化 |