From 8b86f1c903da23b5a6cba16f9c5017739c4b9aee Mon Sep 17 00:00:00 2001 From: "CJACK." Date: Fri, 3 Apr 2026 01:28:48 +0800 Subject: [PATCH] docs: refresh architecture and project structure docs --- README.MD | 54 +++++++++++++++++++++++------------------ README.en.md | 52 +++++++++++++++++++++------------------ docs/CONTRIBUTING.en.md | 11 ++++++--- docs/CONTRIBUTING.md | 11 ++++++--- 4 files changed, 73 insertions(+), 55 deletions(-) diff --git a/README.MD b/README.MD index e6c6229..fe97880 100644 --- a/README.MD +++ b/README.MD @@ -29,40 +29,46 @@ ```mermaid flowchart LR Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"] + Upstream["☁️ DeepSeek API"] - subgraph DS2API["DS2API 3.0（统一 Go 路由内核）"] - Router["chi Router + 中间件\n(RequestID / Recoverer / CORS / Timeout)"] + subgraph DS2API["DS2API 3.x（统一 Go 路由内核）"] + Router["chi Router + 中间件\n(RequestID / RealIP / Logger / Recoverer / CORS)"] subgraph Adapters["协议适配层"] OA["OpenAI\n/v1/*"] CA["Claude\n/anthropic/* + /v1/messages"] GA["Gemini\n/v1beta/models/* + /v1/models/*"] + Admin["Admin API\n/admin/*"] + WebUI["WebUI\n/admin（静态托管）"] end - subgraph Runtime["运行时与核心能力"] + subgraph Runtime["运行时核心能力"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] - Pool["Account Pool + Queue\n(并发与轮询)"] - DS["DeepSeek Client\n(Session / Auth / HTTP)"] - Pow["PoW WASM (wazero)"] + Pool["Account Pool + Queue\n(并发槽位 + 等待队列)"] + DSClient["DeepSeek Client\n(Session / Auth / HTTP)"] + Pow["PoW WASM\n(wazero 预加载)"] + SSE["SSE/Stream Engine\n(统一流式消费)"] Tool["Tool Sieve\n(Go/Node 语义对齐)"] - Format["Response Render\n(OpenAI/Claude/Gemini)"] + Render["Formatter\n(OpenAI/Claude/Gemini 输出)"] end - - Admin["Admin API\n/admin/*"] - WebUI["WebUI Static\n/admin"] end - DS["☁️ DeepSeek API"] + Client --> Router + Router --> OA & CA & GA + Router --> Admin + Router --> WebUI - Client -- "请求" --> CORS --> Auth - Auth --> OA & CA & GA - OA & CA & GA -- "调用" --> DS - Auth --> Admin - OA & CA & GA -. "轮询选账号" .-> Pool - OA & CA & GA -. "计算 PoW" .-> PoW - OA & CA & GA -. "流式解析" .-> Stream - OA & CA & GA -. "工具调用防泄漏" .-> Sieve - DS -- "响应" --> Client + OA & CA & GA --> Auth + OA & CA & GA -.账号轮询.-> Pool + OA & CA & GA -.工具调用解析.-> Tool + OA & CA & GA -.流式处理.-> SSE + OA & CA & GA -.PoW 计算.-> Pow + + Auth --> DSClient + DSClient --> Upstream + Upstream --> DSClient + DSClient --> Render + Render --> Client ``` - **后端**：Go（`cmd/ds2api/`、`api/`、`internal/`），不依赖 Python 运行时 @@ -425,11 +431,10 @@ go run ./cmd/ds2api ```text ds2api/ -├── app/ # 统一 Handler 入口（供 Vercel / 本地共用） +├── app/ # 统一 HTTP Handler 组装层（供本地与 Serverless 复用） ├── cmd/ │ ├── ds2api/ # 本地 / 容器启动入口 │ └── ds2api-tests/ # 端到端测试集入口 -├── app/ # 统一 HTTP Handler 组装层（供本地与 Serverless 复用） ├── api/ │ ├── index.go # Vercel Serverless Go 入口 │ ├── chat-stream.js # Vercel Node.js 流式转发 @@ -443,8 +448,8 @@ ds2api/ │ ├── admin/ # Admin API handlers（含 Settings 热更新） │ ├── auth/ # 鉴权与 JWT │ ├── claudeconv/ # Claude 消息格式转换 -│ ├── compat/ # 兼容性辅助 -│ ├── config/ # 配置加载与热更新 +│ ├── compat/ # Go 版本兼容与回归测试辅助 +│ ├── config/ # 配置加载、校验与热更新 │ ├── deepseek/ # DeepSeek API 客户端、PoW WASM │ ├── js/ # Node 运行时流式处理与兼容逻辑 │ ├── devcapture/ # 开发抓包模块 @@ -468,6 +473,7 @@ ds2api/ │ └── build-webui.sh # WebUI 手动构建脚本 ├── tests/ │ ├── compat/ # 兼容性测试夹具与期望输出 +│ ├── node/ # Node 侧单元测试（chat-stream / tool-sieve） │ └── scripts/ # 统一测试脚本入口（unit/e2e） ├── docs/ # 部署 / 贡献 / 测试等辅助文档 ├── static/admin/ # WebUI 构建产物（不提交到 Git） diff --git a/README.en.md b/README.en.md index 7ca9a60..347c426 100644 --- a/README.en.md +++ b/README.en.md @@ -29,40 +29,46 @@ DS2API converts DeepSeek Web chat capability into OpenAI-compatible, Claude-comp ```mermaid flowchart LR Client["🖥️ Clients / SDKs\n(OpenAI / Claude / Gemini)"] + Upstream["☁️ DeepSeek API"] - subgraph DS2API["DS2API 3.0 (Unified Go Routing Core)"] - Router["chi Router + Middleware\n(RequestID / Recoverer / CORS / Timeout)"] + subgraph DS2API["DS2API 3.x (Unified Go Routing Core)"] + Router["chi Router + Middleware\n(RequestID / RealIP / Logger / Recoverer / CORS)"] subgraph Adapters["Protocol Adapters"] OA["OpenAI\n/v1/*"] CA["Claude\n/anthropic/* + /v1/messages"] GA["Gemini\n/v1beta/models/* + /v1/models/*"] + Admin["Admin API\n/admin/*"] + WebUI["WebUI\n/admin (static hosting)"] end subgraph Runtime["Runtime + Core Capabilities"] Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"] - Pool["Account Pool + Queue\n(concurrency and rotation)"] - DS["DeepSeek Client\n(session / auth / HTTP)"] - Pow["PoW WASM (wazero)"] + Pool["Account Pool + Queue\n(in-flight slots + wait queue)"] + DSClient["DeepSeek Client\n(session / auth / HTTP)"] + Pow["PoW WASM\n(wazero preload)"] + SSE["SSE/Stream Engine\n(unified streaming consumption)"] Tool["Tool Sieve\n(Go/Node semantic parity)"] - Format["Response Render\n(OpenAI/Claude/Gemini)"] + Render["Formatter\n(OpenAI/Claude/Gemini output)"] end - - Admin["Admin API\n/admin/*"] - WebUI["WebUI Static\n/admin"] end - DS["☁️ DeepSeek API"] + Client --> Router + Router --> OA & CA & GA + Router --> Admin + Router --> WebUI - Client -- "Request" --> CORS --> Auth - Auth --> OA & CA & GA - OA & CA & GA -- "Call" --> DS - Auth --> Admin - OA & CA & GA -. "Rotate accounts" .-> Pool - OA & CA & GA -. "Compute PoW" .-> PoW - OA & CA & GA -. "Parse streams" .-> Stream - OA & CA & GA -. "Tool anti-leak" .-> Sieve - DS -- "Response" --> Client + OA & CA & GA --> Auth + OA & CA & GA -.account rotation.-> Pool + OA & CA & GA -.tool-call parsing.-> Tool + OA & CA & GA -.stream handling.-> SSE + OA & CA & GA -.PoW solving.-> Pow + + Auth --> DSClient + DSClient --> Upstream + Upstream --> DSClient + DSClient --> Render + Render --> Client ``` - **Backend**: Go (`cmd/ds2api/`, `api/`, `internal/`), no Python runtime @@ -419,11 +425,10 @@ Response fields include: ```text ds2api/ -├── app/ # Unified handler entry (shared by Vercel/local) +├── app/ # Unified HTTP handler assembly (shared by local + serverless) ├── cmd/ │ ├── ds2api/ # Local / container entrypoint │ └── ds2api-tests/ # End-to-end testsuite entrypoint -├── app/ # Unified HTTP handler assembly (shared by local + serverless) ├── api/ │ ├── index.go # Vercel Serverless Go entry │ ├── chat-stream.js # Vercel Node.js stream relay @@ -437,8 +442,8 @@ ds2api/ │ ├── admin/ # Admin API handlers (incl. Settings hot-reload) │ ├── auth/ # Auth and JWT │ ├── claudeconv/ # Claude message format conversion -│ ├── compat/ # Compatibility helpers -│ ├── config/ # Config loading and hot-reload +│ ├── compat/ # Go-version compatibility and regression helpers +│ ├── config/ # Config loading, validation, and hot-reload │ ├── deepseek/ # DeepSeek API client, PoW WASM │ ├── js/ # Node runtime stream/compat logic │ ├── devcapture/ # Dev packet capture module @@ -462,6 +467,7 @@ ds2api/ │ └── build-webui.sh # Manual WebUI build script ├── tests/ │ ├── compat/ # Compatibility fixtures and expected outputs +│ ├── node/ # Node-side unit tests (chat-stream / tool-sieve) │ └── scripts/ # Unified test script entrypoints (unit/e2e) ├── docs/ # Deployment / contributing / testing docs ├── static/admin/ # WebUI build output (not committed to Git) diff --git a/docs/CONTRIBUTING.en.md b/docs/CONTRIBUTING.en.md index dd8ee2c..ad04e0e 100644 --- a/docs/CONTRIBUTING.en.md +++ b/docs/CONTRIBUTING.en.md @@ -94,11 +94,10 @@ Manually build WebUI to `static/admin/`: ```text ds2api/ -├── app/ # Unified handler entry (shared by Vercel/local) +├── app/ # Shared HTTP handler assembly (local + serverless) ├── cmd/ │ ├── ds2api/ # Local/container entrypoint │ └── ds2api-tests/ # End-to-end testsuite entrypoint -├── app/ # Shared handler assembly (local + serverless) ├── api/ │ ├── index.go # Vercel Serverless Go entry │ ├── chat-stream.js # Vercel Node.js stream relay @@ -112,7 +111,8 @@ ds2api/ │ ├── admin/ # Admin API handlers │ ├── auth/ # Auth and JWT │ ├── claudeconv/ # Claude message conversion -│ ├── config/ # Config loading and hot-reload +│ ├── compat/ # Go-version compatibility and regression helpers +│ ├── config/ # Config loading, validation, and hot-reload │ ├── deepseek/ # DeepSeek client, PoW WASM │ ├── js/ # Node runtime stream/compat logic │ ├── devcapture/ # Dev packet capture @@ -133,7 +133,10 @@ ds2api/ │ ├── components/ # Shared components │ └── locales/ # Language packs ├── scripts/ # Build and test scripts -├── tests/ # Unit tests, Node tests, and end-to-end tests +├── tests/ +│ ├── compat/ # Compatibility fixtures and expected outputs +│ ├── node/ # Node-side unit tests +│ └── scripts/ # Test script entrypoints (unit/e2e) ├── plans/ # Plans, gates, and manual smoke-test records ├── static/admin/ # WebUI build output (not committed) ├── Dockerfile # Multi-stage build diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5c55a99..0883df0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -94,11 +94,10 @@ docker-compose -f docker-compose.dev.yml up ```text ds2api/ -├── app/ # 统一 Handler 入口（供 Vercel / 本地共用） +├── app/ # 统一 HTTP Handler 装配（本地 + Serverless） ├── cmd/ │ ├── ds2api/ # 本地/容器启动入口 │ └── ds2api-tests/ # 端到端测试集入口 -├── app/ # 统一 Handler 装配（本地 + Serverless） ├── api/ │ ├── index.go # Vercel Serverless Go 入口 │ ├── chat-stream.js # Vercel Node.js 流式转发 @@ -112,7 +111,8 @@ ds2api/ │ ├── admin/ # Admin API handlers │ ├── auth/ # 鉴权与 JWT │ ├── claudeconv/ # Claude 消息格式转换 -│ ├── config/ # 配置加载与热更新 +│ ├── compat/ # Go 版本兼容与回归测试辅助 +│ ├── config/ # 配置加载、校验与热更新 │ ├── deepseek/ # DeepSeek 客户端、PoW WASM │ ├── js/ # Node 运行时流式/兼容逻辑 │ ├── devcapture/ # 开发抓包 @@ -133,7 +133,10 @@ ds2api/ │ ├── components/ # 通用组件 │ └── locales/ # 语言包 ├── scripts/ # 构建与测试脚本 -├── tests/ # 单元测试、Node 测试与端到端测试 +├── tests/ +│ ├── compat/ # 兼容夹具与期望输出 +│ ├── node/ # Node 侧单元测试 +│ └── scripts/ # 测试脚本入口（unit/e2e） ├── plans/ # 计划、门禁和手工烟测记录 ├── static/admin/ # WebUI 构建产物（不提交） ├── Dockerfile # 多阶段构建