docs: update architecture diagrams for 4.x

2026-05-02 07:25:26 +08:00 · 2026-04-26 08:40:00 +08:00
parent 573c717a5d
commit 40b8182984
5 changed files with 172 additions and 68 deletions
--- a/docs/ARCHITECTURE.en.md
+++ b/docs/ARCHITECTURE.en.md
@@ -102,33 +102,79 @@ ds2api/

 ```mermaid
 flowchart LR
-    C[Client/SDK] --> R[internal/server/router.go]
-    R --> OA[OpenAI HTTP API]
-    R --> CA[Claude HTTP API]
-    R --> GA[Gemini HTTP API]
-    R --> AD[Admin HTTP API]
+    C[Client / SDK] --> R[internal/server/router.go]

-    CA --> BR[translatorcliproxy]
-    GA --> BR
-    BR --> CORE[internal/httpapi/openai/chat ChatCompletions]
-    OA --> CORE
+    subgraph HTTP[HTTP API surface]
+        OA[internal/httpapi/openai]
+        CHAT[openai/chat]
+        RESP[openai/responses]
+        FILES[openai/files + embeddings]
+        CA[internal/httpapi/claude]
+        GA[internal/httpapi/gemini]
+        AD[internal/httpapi/admin/*]
+        WEB[internal/webui static admin]
+    end

-    CORE --> AUTH[internal/auth + config key/account resolver]
-    CORE --> POOL[internal/account queue + concurrency]
-    CORE --> TOOL[internal/toolcall parser + internal/toolstream sieve]
-    CORE --> DS[internal/deepseek/client]
+    subgraph COMPAT[Prompt compatibility core]
+        PC[internal/promptcompat]
+        PROMPT[internal/prompt]
+        HIST[internal/httpapi/openai/history]
+    end
+
+    subgraph RUNTIME[Shared runtime]
+        AUTH[internal/auth]
+        POOL[internal/account queue + concurrency]
+        STREAM[internal/stream + internal/sse]
+        TOOL[internal/toolcall + internal/toolstream]
+        DS[internal/deepseek/client]
+        POW[pow + internal/deepseek/protocol]
+    end
+
+    subgraph NODE[Vercel Node Runtime]
+        NCS[api/chat-stream.js]
+        JS[internal/js/chat-stream + stream-tool-sieve]
+    end
+
+    R --> OA --> CHAT
+    OA --> RESP
+    OA --> FILES
+    R --> CA
+    R --> GA
+    R --> AD
+    R --> WEB
+    R -.Vercel stream.-> NCS
+
+    CA --> PC
+    GA --> PC
+    CHAT --> PC
+    RESP --> PC
+    PC --> PROMPT
+    PC -.long history.-> HIST
+    PC --> AUTH
+
+    NCS -.Go prepare/release.-> CHAT
+    NCS --> JS
+    JS --> TOOL
+
+    AUTH --> POOL
+    CHAT --> STREAM
+    RESP --> STREAM
+    STREAM --> TOOL
+    POOL --> DS
+    DS --> POW
    DS --> U[DeepSeek upstream]
 ```

 ## 3. Responsibilities in `internal/`

 - `internal/server`: router tree + middlewares (health, protocol routes, Admin/WebUI).
- `internal/httpapi/openai/*`: OpenAI HTTP surface split into chat, responses, files, embeddings, history, and shared packages.
- `internal/httpapi/{claude,gemini}`: protocol wrappers only (no duplicated upstream execution).
+- `internal/httpapi/openai/*`: OpenAI HTTP surface split into chat, responses, files, embeddings, history, and shared packages; chat/responses share the promptcompat, stream, and toolcall semantics.
+- `internal/httpapi/{claude,gemini}`: protocol wrappers that normalize into the same prompt compatibility semantics without duplicating upstream execution.
 - `internal/promptcompat`: compatibility core for turning OpenAI/Claude/Gemini requests into DeepSeek web-chat plain-text context.
 - `internal/translatorcliproxy`: structure translation between Claude/Gemini and OpenAI.
 - `internal/deepseek/{client,protocol,transport}`: upstream requests, sessions, PoW adaptation, protocol constants, and transport details.
- `internal/stream` + `internal/sse`: stream parsing and incremental assembly.
+- `internal/js/chat-stream` + `api/chat-stream.js`: Vercel Node streaming bridge; Go prepare/release owns auth, account lease, and completion payload assembly, while Node relays real-time SSE with Go-aligned finalization and tool sieve semantics.
+- `internal/stream` + `internal/sse`: Go stream parsing and incremental assembly.
 - `internal/toolcall` + `internal/toolstream`: canonical XML tool-call parsing + anti-leak sieve (the only executable format is `<tool_calls>` / `<invoke name="...">` / `<parameter name="...">`).
 - `internal/httpapi/admin/*`: Admin API root assembly plus auth/accounts/config/settings/proxies/rawsamples/vercel/history/devcapture/version resource packages.
 - `internal/chathistory`: server-side conversation history persistence, pagination, detail lookup, and retention policy.
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -102,33 +102,79 @@ ds2api/

 ```mermaid
 flowchart LR
-    C[Client/SDK] --> R[internal/server/router.go]
-    R --> OA[OpenAI HTTP API]
-    R --> CA[Claude HTTP API]
-    R --> GA[Gemini HTTP API]
-    R --> AD[Admin HTTP API]
+    C[Client / SDK] --> R[internal/server/router.go]

-    CA --> BR[translatorcliproxy]
-    GA --> BR
-    BR --> CORE[internal/httpapi/openai/chat ChatCompletions]
-    OA --> CORE
+    subgraph HTTP[HTTP API surface]
+        OA[internal/httpapi/openai]
+        CHAT[openai/chat]
+        RESP[openai/responses]
+        FILES[openai/files + embeddings]
+        CA[internal/httpapi/claude]
+        GA[internal/httpapi/gemini]
+        AD[internal/httpapi/admin/*]
+        WEB[internal/webui static admin]
+    end

-    CORE --> AUTH[internal/auth + config key/account resolver]
-    CORE --> POOL[internal/account queue + concurrency]
-    CORE --> TOOL[internal/toolcall parser + internal/toolstream sieve]
-    CORE --> DS[internal/deepseek/client]
+    subgraph COMPAT[Prompt compatibility core]
+        PC[internal/promptcompat]
+        PROMPT[internal/prompt]
+        HIST[internal/httpapi/openai/history]
+    end
+
+    subgraph RUNTIME[Shared runtime]
+        AUTH[internal/auth]
+        POOL[internal/account queue + concurrency]
+        STREAM[internal/stream + internal/sse]
+        TOOL[internal/toolcall + internal/toolstream]
+        DS[internal/deepseek/client]
+        POW[pow + internal/deepseek/protocol]
+    end
+
+    subgraph NODE[Vercel Node Runtime]
+        NCS[api/chat-stream.js]
+        JS[internal/js/chat-stream + stream-tool-sieve]
+    end
+
+    R --> OA --> CHAT
+    OA --> RESP
+    OA --> FILES
+    R --> CA
+    R --> GA
+    R --> AD
+    R --> WEB
+    R -.Vercel stream.-> NCS
+
+    CA --> PC
+    GA --> PC
+    CHAT --> PC
+    RESP --> PC
+    PC --> PROMPT
+    PC -.长历史.-> HIST
+    PC --> AUTH
+
+    NCS -.Go prepare/release.-> CHAT
+    NCS --> JS
+    JS --> TOOL
+
+    AUTH --> POOL
+    CHAT --> STREAM
+    RESP --> STREAM
+    STREAM --> TOOL
+    POOL --> DS
+    DS --> POW
    DS --> U[DeepSeek upstream]
 ```

 ## 3. internal/ 子模块职责

 - `internal/server`：路由树和中间件挂载（健康检查、协议入口、Admin/WebUI）。
- `internal/httpapi/openai/*`：OpenAI HTTP surface，按 chat、responses、files、embeddings、history、shared 拆分。
- `internal/httpapi/{claude,gemini}`：协议输入输出适配，不重复实现上游调用逻辑。
+- `internal/httpapi/openai/*`：OpenAI HTTP surface，按 chat、responses、files、embeddings、history、shared 拆分；chat/responses 共享 promptcompat、stream、toolcall 等核心语义。
+- `internal/httpapi/{claude,gemini}`：协议输入输出适配，归一到同一套 prompt compatibility 语义，不重复实现上游调用逻辑。
 - `internal/promptcompat`：OpenAI/Claude/Gemini 请求到 DeepSeek 网页纯文本上下文的兼容内核。
 - `internal/translatorcliproxy`：Claude/Gemini 与 OpenAI 结构互转。
 - `internal/deepseek/{client,protocol,transport}`：上游请求、会话、PoW 适配、协议常量与传输层。
- `internal/stream` + `internal/sse`：流式解析与增量处理。
+- `internal/js/chat-stream` + `api/chat-stream.js`：Vercel Node 流式桥；Go prepare/release 管理鉴权、账号租约和 completion payload，Node 侧负责实时 SSE 转发并保持 Go 对齐的终结态和 tool sieve 语义。
+- `internal/stream` + `internal/sse`：Go 流式解析与增量处理。
 - `internal/toolcall` + `internal/toolstream`：canonical XML 工具调用解析与防泄漏筛分（唯一可执行格式：`<tool_calls>` / `<invoke name="...">` / `<parameter name="...">`）。
 - `internal/httpapi/admin/*`：Admin API 根装配与 auth/accounts/config/settings/proxies/rawsamples/vercel/history/devcapture/version 等资源子包。
 - `internal/chathistory`：服务器端对话记录持久化、分页、单条详情和保留策略。
--- a/docs/prompt-compatibility.md
+++ b/docs/prompt-compatibility.md
@@ -41,8 +41,8 @@ DS2API 当前的核心思路，不是把客户端传来的 `messages`、`tools`

 ```text
 客户端请求
-  -> 协议适配层（OpenAI / Claude / Gemini）
-  -> 统一消息标准化
+  -> HTTP API surface（OpenAI / Claude / Gemini）
+  -> promptcompat 统一消息标准化
  -> tool prompt 注入
  -> DeepSeek 风格 prompt 拼装
  -> 文件收集 / inline 上传 / history split（OpenAI 链路）