lisone/ds2api
1
0
Fork 0
mirror of https://github.com/CJackHwang/ds2api.git synced 2026-05-23 10:57:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update architecture diagrams for 4.x

Browse Source
This commit is contained in:
CJACK
2026-04-26 08:40:00 +08:00
parent 193351ac19
commit 66c2944be2
5 changed files with 172 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
README.MD
View File

@@ -35,25 +35,27 @@ flowchart LR
Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"] Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"]
Upstream["☁️ DeepSeek API"] Upstream["☁️ DeepSeek API"]
subgraph DS2API["DS2API 3.x（统一 OpenAI 内核）"] subgraph DS2API["DS2API 4.x（模块化 HTTP surface + PromptCompat 内核）"]
Router["chi Router + 中间件\n(RequestID / RealIP / Logger / Recoverer / CORS)"] Router["chi Router + 中间件\n(RequestID / RealIP / Logger / Recoverer / CORS)"]
subgraph Adapters["协议适配层"] subgraph HTTP["HTTP API surface"]
OA["OpenAI\n/v1/*"] OA["OpenAI\nchat / responses / files / embeddings"]
CA["Claude\n/anthropic/* + /v1/messages"] CA["Claude\n/anthropic/* + /v1/messages"]
GA["Gemini\n/v1beta/models/* + /v1/models/*"] GA["Gemini\n/v1beta/models/* + /v1/models/*"]
Admin["Admin API\n/admin/*"] Admin["Admin API\n资源子包"]
WebUI["WebUI\n/admin（静态托管）"] WebUI["WebUI\n/admin（静态托管）"]
Vercel["Vercel Node Stream\n/v1/chat/completions"]
end end
subgraph Runtime["运行时核心能力"] subgraph Runtime["运行时核心能力"]
Bridge["CLIProxy 转换桥\n(多协议 <-> OpenAI)"] Compat["PromptCompat\n(API -> 网页纯文本上下文)"]
OAEngine["OpenAI ChatCompletions\n(统一工具调用与流式语义)"] Chat["Chat / Responses Runtime\n(统一工具调用与流式语义)"]
Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"]
Pool["Account Pool + Queue\n(并发槽位 + 等待队列)"] Pool["Account Pool + Queue\n(并发槽位 + 等待队列)"]
DSClient["DeepSeek Client\n(Session / Auth / HTTP)"] DSClient["DeepSeek Client\n(Session / Auth / Completion / Files)"]
Pow["PoW 实现\n(纯 Go 毫秒级)"] Pow["PoW 实现\n(纯 Go)"]
Tool["Tool Sieve\n(Go/Node 语义对齐)"] Tool["Tool Sieve\n(Go/Node 语义对齐)"]
History["History Split\n(长历史文件化)"]
end end
end end
@@ -61,19 +63,23 @@ flowchart LR
Router --> OA & CA & GA Router --> OA & CA & GA
Router --> Admin Router --> Admin
Router --> WebUI Router --> WebUI
Router --> Vercel
OA --> OAEngine OA --> Compat
CA & GA --> Bridge CA & GA --> Compat
Bridge --> OAEngine Compat --> Chat
OAEngine --> Auth Compat -.长历史.-> History
OAEngine -.账号轮询.-> Pool Vercel -.Go prepare.-> Chat
OAEngine -.工具调用解析.-> Tool Vercel -.Node SSE.-> Tool
OAEngine -.PoW 计算.-> Pow Chat --> Auth
Chat -.账号轮询.-> Pool
Chat -.工具调用解析.-> Tool
Chat -.PoW 计算.-> Pow
Auth --> DSClient Auth --> DSClient
DSClient --> Upstream DSClient --> Upstream
Upstream --> DSClient Upstream --> DSClient
OAEngine --> Bridge Chat --> Client
Bridge --> Client Vercel --> Client
``` ```
详细架构拆分与目录职责见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 详细架构拆分与目录职责见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

40
README.en.md
View File

@@ -33,25 +33,27 @@ flowchart LR
Client["🖥️ Clients / SDKs\n(OpenAI / Claude / Gemini)"] Client["🖥️ Clients / SDKs\n(OpenAI / Claude / Gemini)"]
Upstream["☁️ DeepSeek API"] Upstream["☁️ DeepSeek API"]
subgraph DS2API["DS2API 3.x (Unified OpenAI Core)"] subgraph DS2API["DS2API 4.x (Modular HTTP Surface + PromptCompat Core)"]
Router["chi Router + Middleware\n(RequestID / RealIP / Logger / Recoverer / CORS)"] Router["chi Router + Middleware\n(RequestID / RealIP / Logger / Recoverer / CORS)"]
subgraph Adapters["Protocol Adapters"] subgraph HTTP["HTTP API Surface"]
OA["OpenAI\n/v1/*"] OA["OpenAI\nchat / responses / files / embeddings"]
CA["Claude\n/anthropic/* + /v1/messages"] CA["Claude\n/anthropic/* + /v1/messages"]
GA["Gemini\n/v1beta/models/* + /v1/models/*"] GA["Gemini\n/v1beta/models/* + /v1/models/*"]
Admin["Admin API\n/admin/*"] Admin["Admin API\nresource packages"]
WebUI["WebUI\n/admin (static hosting)"] WebUI["WebUI\n/admin (static hosting)"]
Vercel["Vercel Node Stream\n/v1/chat/completions"]
end end
subgraph Runtime["Runtime + Core Capabilities"] subgraph Runtime["Runtime + Core Capabilities"]
Bridge["CLIProxy Bridge\n(multi-protocol <-> OpenAI)"] Compat["PromptCompat\n(API -> web-chat plain text context)"]
OAEngine["OpenAI ChatCompletions\n(unified tools + stream semantics)"] Chat["Chat / Responses Runtime\n(unified tools + stream semantics)"]
Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"]
Pool["Account Pool + Queue\n(in-flight slots + wait queue)"] Pool["Account Pool + Queue\n(in-flight slots + wait queue)"]
DSClient["DeepSeek Client\n(session / auth / HTTP)"] DSClient["DeepSeek Client\n(session / auth / completion / files)"]
Pow["PoW Solver\n(Pure Go ms-level)"] Pow["PoW Solver\n(Pure Go)"]
Tool["Tool Sieve\n(Go/Node semantic parity)"] Tool["Tool Sieve\n(Go/Node semantic parity)"]
History["History Split\n(long history as files)"]
end end
end end
@@ -59,19 +61,23 @@ flowchart LR
Router --> OA & CA & GA Router --> OA & CA & GA
Router --> Admin Router --> Admin
Router --> WebUI Router --> WebUI
Router --> Vercel
OA --> OAEngine OA --> Compat
CA & GA --> Bridge CA & GA --> Compat
Bridge --> OAEngine Compat --> Chat
OAEngine --> Auth Compat -.long history.-> History
OAEngine -.account rotation.-> Pool Vercel -.Go prepare.-> Chat
OAEngine -.tool-call parsing.-> Tool Vercel -.Node SSE.-> Tool
OAEngine -.PoW solving.-> Pow Chat --> Auth
Chat -.account rotation.-> Pool
Chat -.tool-call parsing.-> Tool
Chat -.PoW solving.-> Pow
Auth --> DSClient Auth --> DSClient
DSClient --> Upstream DSClient --> Upstream
Upstream --> DSClient Upstream --> DSClient
OAEngine --> Bridge Chat --> Client
Bridge --> Client Vercel --> Client
``` ```
For the full module-by-module architecture and directory responsibilities, see [docs/ARCHITECTURE.en.md](docs/ARCHITECTURE.en.md). For the full module-by-module architecture and directory responsibilities, see [docs/ARCHITECTURE.en.md](docs/ARCHITECTURE.en.md).

78
docs/ARCHITECTURE.en.md
View File

@@ -102,33 +102,79 @@ ds2api/
```mermaid ```mermaid
flowchart LR flowchart LR
C[Client/SDK] --> R[internal/server/router.go] 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]
CA --> BR[translatorcliproxy] subgraph HTTP[HTTP API surface]
GA --> BR OA[internal/httpapi/openai]
BR --> CORE[internal/httpapi/openai/chat ChatCompletions] CHAT[openai/chat]
OA --> CORE 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] subgraph COMPAT[Prompt compatibility core]
CORE --> POOL[internal/account queue + concurrency] PC[internal/promptcompat]
CORE --> TOOL[internal/toolcall parser + internal/toolstream sieve] PROMPT[internal/prompt]
CORE --> DS[internal/deepseek/client] 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] DS --> U[DeepSeek upstream]
``` ```
## 3. Responsibilities in `internal/` ## 3. Responsibilities in `internal/`
- `internal/server`: router tree + middlewares (health, protocol routes, Admin/WebUI). - `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/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 only (no duplicated upstream execution). - `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/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/translatorcliproxy`: structure translation between Claude/Gemini and OpenAI.
- `internal/deepseek/{client,protocol,transport}`: upstream requests, sessions, PoW adaptation, protocol constants, and transport details. - `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/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/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. - `internal/chathistory`: server-side conversation history persistence, pagination, detail lookup, and retention policy.

78
docs/ARCHITECTURE.md
View File

@@ -102,33 +102,79 @@ ds2api/
```mermaid ```mermaid
flowchart LR flowchart LR
C[Client/SDK] --> R[internal/server/router.go] 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]
CA --> BR[translatorcliproxy] subgraph HTTP[HTTP API surface]
GA --> BR OA[internal/httpapi/openai]
BR --> CORE[internal/httpapi/openai/chat ChatCompletions] CHAT[openai/chat]
OA --> CORE 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] subgraph COMPAT[Prompt compatibility core]
CORE --> POOL[internal/account queue + concurrency] PC[internal/promptcompat]
CORE --> TOOL[internal/toolcall parser + internal/toolstream sieve] PROMPT[internal/prompt]
CORE --> DS[internal/deepseek/client] 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] DS --> U[DeepSeek upstream]
``` ```
## 3. internal/ 子模块职责 ## 3. internal/ 子模块职责
- `internal/server`：路由树和中间件挂载（健康检查、协议入口、Admin/WebUI）。 - `internal/server`：路由树和中间件挂载（健康检查、协议入口、Admin/WebUI）。
- `internal/httpapi/openai/*`：OpenAI HTTP surface，按 chat、responses、files、embeddings、history、shared 拆分。 - `internal/httpapi/openai/*`：OpenAI HTTP surface，按 chat、responses、files、embeddings、history、shared 拆分；chat/responses 共享 promptcompat、stream、toolcall 等核心语义。
- `internal/httpapi/{claude,gemini}`：协议输入输出适配，不重复实现上游调用逻辑。 - `internal/httpapi/{claude,gemini}`：协议输入输出适配，归一到同一套 prompt compatibility 语义，不重复实现上游调用逻辑。
- `internal/promptcompat`：OpenAI/Claude/Gemini 请求到 DeepSeek 网页纯文本上下文的兼容内核。 - `internal/promptcompat`：OpenAI/Claude/Gemini 请求到 DeepSeek 网页纯文本上下文的兼容内核。
- `internal/translatorcliproxy`：Claude/Gemini 与 OpenAI 结构互转。 - `internal/translatorcliproxy`：Claude/Gemini 与 OpenAI 结构互转。
- `internal/deepseek/{client,protocol,transport}`：上游请求、会话、PoW 适配、协议常量与传输层。 - `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/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/httpapi/admin/*`：Admin API 根装配与 auth/accounts/config/settings/proxies/rawsamples/vercel/history/devcapture/version 等资源子包。
- `internal/chathistory`：服务器端对话记录持久化、分页、单条详情和保留策略。 - `internal/chathistory`：服务器端对话记录持久化、分页、单条详情和保留策略。

4
docs/prompt-compatibility.md
View File

@@ -41,8 +41,8 @@ DS2API 当前的核心思路，不是把客户端传来的 `messages`、`tools`
```text ```text
客户端请求 客户端请求
-> 协议适配层（OpenAI / Claude / Gemini） -> HTTP API surface（OpenAI / Claude / Gemini）
-> 统一消息标准化 -> promptcompat 统一消息标准化
-> tool prompt 注入 -> tool prompt 注入
-> DeepSeek 风格 prompt 拼装 -> DeepSeek 风格 prompt 拼装
-> 文件收集 / inline 上传 / history split（OpenAI 链路） -> 文件收集 / inline 上传 / history split（OpenAI 链路）