diff --git a/README.MD b/README.MD index a525f02..412596e 100644 --- a/README.MD +++ b/README.MD @@ -35,25 +35,27 @@ flowchart LR Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"] 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)"] - subgraph Adapters["协议适配层"] - OA["OpenAI\n/v1/*"] + subgraph HTTP["HTTP API surface"] + OA["OpenAI\nchat / responses / files / embeddings"] CA["Claude\n/anthropic/* + /v1/messages"] GA["Gemini\n/v1beta/models/* + /v1/models/*"] - Admin["Admin API\n/admin/*"] + Admin["Admin API\n资源子包"] WebUI["WebUI\n/admin(静态托管)"] + Vercel["Vercel Node Stream\n/v1/chat/completions"] end subgraph Runtime["运行时核心能力"] - Bridge["CLIProxy 转换桥\n(多协议 <-> OpenAI)"] - OAEngine["OpenAI ChatCompletions\n(统一工具调用与流式语义)"] + Compat["PromptCompat\n(API -> 网页纯文本上下文)"] + Chat["Chat / Responses Runtime\n(统一工具调用与流式语义)"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] Pool["Account Pool + Queue\n(并发槽位 + 等待队列)"] - DSClient["DeepSeek Client\n(Session / Auth / HTTP)"] - Pow["PoW 实现\n(纯 Go 毫秒级)"] + DSClient["DeepSeek Client\n(Session / Auth / Completion / Files)"] + Pow["PoW 实现\n(纯 Go)"] Tool["Tool Sieve\n(Go/Node 语义对齐)"] + History["History Split\n(长历史文件化)"] end end @@ -61,19 +63,23 @@ flowchart LR Router --> OA & CA & GA Router --> Admin Router --> WebUI + Router --> Vercel - OA --> OAEngine - CA & GA --> Bridge - Bridge --> OAEngine - OAEngine --> Auth - OAEngine -.账号轮询.-> Pool - OAEngine -.工具调用解析.-> Tool - OAEngine -.PoW 计算.-> Pow + OA --> Compat + CA & GA --> Compat + Compat --> Chat + Compat -.长历史.-> History + Vercel -.Go prepare.-> Chat + Vercel -.Node SSE.-> Tool + Chat --> Auth + Chat -.账号轮询.-> Pool + Chat -.工具调用解析.-> Tool + Chat -.PoW 计算.-> Pow Auth --> DSClient DSClient --> Upstream Upstream --> DSClient - OAEngine --> Bridge - Bridge --> Client + Chat --> Client + Vercel --> Client ``` 详细架构拆分与目录职责见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 diff --git a/README.en.md b/README.en.md index 299d228..747993d 100644 --- a/README.en.md +++ b/README.en.md @@ -33,25 +33,27 @@ flowchart LR Client["🖥️ Clients / SDKs\n(OpenAI / Claude / Gemini)"] 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)"] - subgraph Adapters["Protocol Adapters"] - OA["OpenAI\n/v1/*"] + subgraph HTTP["HTTP API Surface"] + OA["OpenAI\nchat / responses / files / embeddings"] CA["Claude\n/anthropic/* + /v1/messages"] GA["Gemini\n/v1beta/models/* + /v1/models/*"] - Admin["Admin API\n/admin/*"] + Admin["Admin API\nresource packages"] WebUI["WebUI\n/admin (static hosting)"] + Vercel["Vercel Node Stream\n/v1/chat/completions"] end subgraph Runtime["Runtime + Core Capabilities"] - Bridge["CLIProxy Bridge\n(multi-protocol <-> OpenAI)"] - OAEngine["OpenAI ChatCompletions\n(unified tools + stream semantics)"] + Compat["PromptCompat\n(API -> web-chat plain text context)"] + Chat["Chat / Responses Runtime\n(unified tools + stream semantics)"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] Pool["Account Pool + Queue\n(in-flight slots + wait queue)"] - DSClient["DeepSeek Client\n(session / auth / HTTP)"] - Pow["PoW Solver\n(Pure Go ms-level)"] + DSClient["DeepSeek Client\n(session / auth / completion / files)"] + Pow["PoW Solver\n(Pure Go)"] Tool["Tool Sieve\n(Go/Node semantic parity)"] + History["History Split\n(long history as files)"] end end @@ -59,19 +61,23 @@ flowchart LR Router --> OA & CA & GA Router --> Admin Router --> WebUI + Router --> Vercel - OA --> OAEngine - CA & GA --> Bridge - Bridge --> OAEngine - OAEngine --> Auth - OAEngine -.account rotation.-> Pool - OAEngine -.tool-call parsing.-> Tool - OAEngine -.PoW solving.-> Pow + OA --> Compat + CA & GA --> Compat + Compat --> Chat + Compat -.long history.-> History + Vercel -.Go prepare.-> Chat + Vercel -.Node SSE.-> Tool + Chat --> Auth + Chat -.account rotation.-> Pool + Chat -.tool-call parsing.-> Tool + Chat -.PoW solving.-> Pow Auth --> DSClient DSClient --> Upstream Upstream --> DSClient - OAEngine --> Bridge - Bridge --> Client + Chat --> Client + Vercel --> Client ``` For the full module-by-module architecture and directory responsibilities, see [docs/ARCHITECTURE.en.md](docs/ARCHITECTURE.en.md). diff --git a/docs/ARCHITECTURE.en.md b/docs/ARCHITECTURE.en.md index ed23416..1f6b24a 100644 --- 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 `` / `` / ``). - `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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 24ea5c3..5094ea4 100644 --- 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 工具调用解析与防泄漏筛分(唯一可执行格式:`` / `` / ``)。 - `internal/httpapi/admin/*`:Admin API 根装配与 auth/accounts/config/settings/proxies/rawsamples/vercel/history/devcapture/version 等资源子包。 - `internal/chathistory`:服务器端对话记录持久化、分页、单条详情和保留策略。 diff --git a/docs/prompt-compatibility.md b/docs/prompt-compatibility.md index a84dd0f..6d6301c 100644 --- 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 链路)