lisone/ds2api
1
0
Fork 0
mirror of https://github.com/CJackHwang/ds2api.git synced 2026-05-02 07:25:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #199 from CJackHwang/codex/update-project-documentation-structure

Browse Source 
docs: refresh architecture overview and project structure maps
This commit is contained in:
CJACK.
2026-04-03 01:29:09 +08:00
committed by GitHub
parent b758ce9234 8b86f1c903
commit ca3c16c424
4 changed files with 73 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
README.MD
View File

@@ -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）

52
README.en.md
View File

@@ -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)

11
docs/CONTRIBUTING.en.md
View File

@@ -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

11
docs/CONTRIBUTING.md
View File

@@ -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 # 多阶段构建