语言 / Language: 中文 | English

将 DeepSeek Web 对话能力转换为 OpenAI、Claude 与 Gemini 兼容 API。后端为 Go 全量实现，前端为 React WebUI 管理台（源码在 webui/，部署时自动构建到 static/admin）。

文档入口：文档导航 / 架构说明 / 接口文档

重要免责声明

本仓库仅供学习、研究、个人实验和内部验证使用，不提供任何形式的商业授权、适用性保证或结果保证。

作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。

请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 LICENSE、相关协议以及你是否获得了作者的书面许可。

flowchart LR
    Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"]
    Upstream["☁️ DeepSeek API"]

    subgraph DS2API["DS2API 3.x（统一 OpenAI 内核）"]
        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["运行时核心能力"]
            Bridge["CLIProxy 转换桥\n(多协议 <-> OpenAI)"]
            OAEngine["OpenAI ChatCompletions\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 毫秒级)"]
            Tool["Tool Sieve\n(Go/Node 语义对齐)"]
        end
    end

    Client --> Router
    Router --> OA & CA & GA
    Router --> Admin
    Router --> WebUI

    OA --> OAEngine
    CA & GA --> Bridge
    Bridge --> OAEngine
    OAEngine --> Auth
    OAEngine -.账号轮询.-> Pool
    OAEngine -.工具调用解析.-> Tool
    OAEngine -.PoW 计算.-> Pow
    Auth --> DSClient
    DSClient --> Upstream
    Upstream --> DSClient
    OAEngine --> Bridge
    Bridge --> Client

详细架构拆分与目录职责见 docs/ARCHITECTURE.md。

• 后端：Go（cmd/ds2api/、api/、internal/），不依赖 Python 运行时
• 前端：React 管理台（webui/），运行时托管静态构建产物
• 部署：本地运行、Docker、Vercel Serverless、Linux systemd

• 统一路由内核：所有协议入口统一汇聚到 internal/server/router.go，并在同一路由树中注册 OpenAI / Claude / Gemini / Admin / WebUI 路由，避免多入口行为漂移。
• 统一执行链路：Claude / Gemini 入口先经 internal/translatorcliproxy 做协议转换，再进入 openai.ChatCompletions 统一处理工具调用与流式语义，最后再转换回原协议响应。
• 适配器分层更清晰：internal/adapter/{claude,gemini} 负责入口/出口协议封装，internal/adapter/openai 负责核心执行，DeepSeek 侧调用只保留在 OpenAI 内核中。
• Tool Calling 双运行时对齐：Go 侧（internal/toolcall）与 Vercel Node 侧（internal/js/helpers/stream-tool-sieve）保持一致的解析/防泄漏语义，覆盖 JSON / XML / invoke / text-kv 多风格输入。
• 配置与运行时设置解耦：静态配置（config）与运行时策略（settings）通过 Admin API 分离管理，支持热更新和密码轮换失效旧 JWT。
• 流式能力升级：/v1/responses 与 /v1/chat/completions 共享更一致的工具调用增量输出策略，降低不同 SDK 下的行为差异。
• 可观测与可运维增强：/healthz、/readyz、/admin/version、/admin/dev/captures 形成排障闭环，便于发布后验证。

可通过配置中的 claude_mapping 或 claude_model_mapping 覆盖映射关系。 另外，/anthropic/v1/models 现已包含 Claude 1.x/2.x/3.x/4.x 历史模型 ID 与常见别名，便于旧客户端直接兼容。

• ANTHROPIC_BASE_URL 推荐直接指向 DS2API 根地址（例如 http://127.0.0.1:5001），Claude Code 会请求 /v1/messages?beta=true。
• ANTHROPIC_API_KEY 需要与 config.json 中 keys 一致；建议同时保留常规 key 与 sk-ant-* 形态 key，兼容不同客户端校验习惯。
• 若系统设置了代理，建议对 DS2API 地址配置 NO_PROXY=127.0.0.1,localhost,<你的主机IP>，避免本地回环请求被代理拦截。
• 如遇“工具调用输出成文本、未执行”问题，请升级到包含 Claude 工具调用多格式解析（JSON/XML/ANTML/invoke）的版本。

Gemini 适配器将模型名通过 model_aliases 或内置规则映射到 DeepSeek 原生模型，支持 generateContent 和 streamGenerateContent 两种调用方式，并完整支持 Tool Calling（functionDeclarations → functionCall 输出）。

把 config.json 作为唯一配置源（推荐做法）：

cp config.example.json config.json
# 编辑 config.json

后续部署建议：

• 本地运行：直接读取 config.json
• Docker / Vercel：由 config.json 生成 DS2API_CONFIG_JSON（Base64）注入环境变量，也可以直接写原始 JSON

前置要求：Go 1.26+，Node.js 20.19+ 或 22.12+（仅在需要构建 WebUI 时）

# 1. 克隆仓库
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 2. 配置
cp config.example.json config.json
# 编辑 config.json，填入你的 DeepSeek 账号信息和 API key

# 3. 启动
go run ./cmd/ds2api

默认本地访问地址：http://127.0.0.1:5001

服务实际绑定：0.0.0.0:5001，因此同一局域网设备通常也可以通过你的内网 IP 访问。

WebUI 自动构建：本地首次启动时，若 static/admin 不存在，会自动尝试执行 npm ci（仅在缺少依赖时）和 npm run build -- --outDir static/admin --emptyOutDir（需要本机有 Node.js）。你也可以手动构建：./scripts/build-webui.sh

# 1. 准备环境变量和配置文件
cp .env.example .env
cp config.example.json config.json

# 2. 编辑 .env（至少设置 DS2API_ADMIN_KEY；如需修改宿主机端口，可额外设置 DS2API_HOST_PORT）
#    DS2API_ADMIN_KEY=请替换为强密码

# 3. 启动
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

默认 docker-compose.yml 会把宿主机 6011 映射到容器内的 5001。如果你希望直接对外暴露 5001，请设置 DS2API_HOST_PORT=5001（或者手动调整 ports 配置）。

更新镜像：docker-compose up -d --build

1. 点击上方 “Deploy on Zeabur” 按钮，一键部署。
2. 部署完成后访问 /admin，使用 Zeabur 环境变量/模板指引中的 DS2API_ADMIN_KEY 登录。
3. 在管理台导入/编辑配置（会写入并持久化到 /data/config.json）。

说明：Zeabur 使用仓库内 Dockerfile 直接构建时，不需要额外传入 BUILD_VERSION；镜像会优先读取该构建参数，未提供时自动回退到仓库根目录的 VERSION 文件。

1. Fork 仓库到自己的 GitHub
2. 在 Vercel 上导入项目
3. 配置环境变量（最少设置 DS2API_ADMIN_KEY；推荐同时设置 DS2API_CONFIG_JSON）
4. 部署

建议先在仓库目录复制模板并填写：

cp config.example.json config.json
# 编辑 config.json

推荐：先本地把 config.json 转成 Base64，再粘贴到 DS2API_CONFIG_JSON，避免 JSON 格式错误：

base64 < config.json | tr -d '\n'

流式说明：/v1/chat/completions 在 Vercel 上默认走 api/chat-stream.js（Node Runtime）以保证实时 SSE。鉴权、账号选择、会话/PoW 准备仍由 Go 内部 prepare 接口完成；流式响应（含 tools）在 Node 侧执行与 Go 对齐的输出组装与防泄漏处理。

详细部署说明请参阅 部署指南。

每次发布 Release 时，GitHub Actions 会自动构建多平台二进制包：

# 下载对应平台的压缩包后
tar -xzf ds2api_<tag>_linux_amd64.tar.gz
cd ds2api_<tag>_linux_amd64
cp config.example.json config.json
# 编辑 config.json
./ds2api

1. 复制示例配置：

cp opencode.json.example opencode.json

2. 编辑 opencode.json：

• 将 baseURL 改为你的 DS2API 地址（例如 https://your-domain.com/v1）
• 将 apiKey 改为你的 DS2API key（对应 config.keys）

3. 在项目目录启动 OpenCode CLI（按你的安装方式运行 opencode）。

建议优先使用 OpenAI 兼容路径（/v1/*），即示例里的 @ai-sdk/openai-compatible provider。 若客户端支持 wire_api，可分别测试 responses 与 chat，DS2API 两条链路都兼容。

{
  "keys": ["your-api-key-1", "your-api-key-2"],
  "accounts": [
    {
      "email": "[email protected]",
      "password": "your-password"
    },
    {
      "mobile": "12345678901",
      "password": "your-password"
    }
  ],
  "model_aliases": {
    "gpt-4o": "deepseek-chat",
    "gpt-5-codex": "deepseek-reasoner",
    "o3": "deepseek-reasoner"
  },
  "compat": {
    "wide_input_strict_output": true,
    "strip_reference_markers": true
  },
  "responses": {
    "store_ttl_seconds": 900
  },
  "embeddings": {
    "provider": "deterministic"
  },
  "claude_mapping": {
    "fast": "deepseek-chat",
    "slow": "deepseek-reasoner"
  },
  "admin": {
    "jwt_expire_hours": 24
  },
  "runtime": {
    "account_max_inflight": 2,
    "account_max_queue": 0,
    "global_max_inflight": 0,
    "token_refresh_interval_hours": 6
  },
  "auto_delete": {
    "mode": "none"
  }
}

• keys：API 访问密钥列表，客户端通过 Authorization: Bearer <key> 鉴权
• accounts：DeepSeek 账号列表，支持 email 或 mobile 登录
• token：配置文件中即使填写也会在加载时被清空（不会从 config.json 读取 token）；实际 token 仅在运行时内存中维护并自动刷新
• model_aliases：常见模型名（如 GPT/Codex/Claude）到 DeepSeek 模型的映射
• compat.wide_input_strict_output：建议保持 true（当前实现默认宽进严出）
• compat.strip_reference_markers：建议保持 true，用于清理可见输出中的引用/标记
• toolcall：旧字段，当前实现已固定为特征匹配 + 高置信早发；即使保留在配置里也会被忽略
• responses.store_ttl_seconds：/v1/responses/{id} 的内存缓存 TTL
• embeddings.provider：embedding 提供方（当前内置 deterministic/mock/builtin）
• claude_mapping：字典中 fast/slow 后缀映射到对应 DeepSeek 模型（兼容读取 claude_model_mapping）
• admin：管理后台设置（JWT 过期时间、密码哈希等），可通过 Admin Settings API 热更新
• runtime：运行时参数（并发限制、队列大小、托管账号 token 刷新间隔），可通过 Admin Settings API 热更新；account_max_queue=0/global_max_inflight=0 表示按推荐值自动计算，token_refresh_interval_hours=6 为默认强制重登间隔
• auto_delete.mode：请求结束后如何清理 DeepSeek 远端聊天记录，支持 none（默认，不删除）、single（仅删除当前会话）、all（清空全部会话）；旧配置里的 auto_delete.sessions=true 仍会被视为 all

提示：当检测到 DS2API_CONFIG_JSON 时，管理台会显示当前模式风险与自动持久化状态（含 DS2API_CONFIG_PATH 路径与模式切换说明）。

调用业务接口（/v1/*、/anthropic/*、Gemini 路由）时支持两种模式：

可选请求头 X-Ds2-Target-Account：指定使用某个托管账号（值为 email 或 mobile）。 Gemini 路由还可以使用 x-goog-api-key，或在没有认证头时使用 ?key= / ?api_key= 作为调用方凭据。

每账号可用并发 = DS2API_ACCOUNT_MAX_INFLIGHT（默认 2）
建议并发值 = 账号数量 × 每账号并发上限
等待队列上限 = DS2API_ACCOUNT_MAX_QUEUE（默认 = 建议并发值）
429 阈值 = in-flight + 等待队列 ≈ 账号数量 × 4

• 当 in-flight 槽位满时，请求进入等待队列，不会立即 429
• 超出总承载上限后才返回 429 Too Many Requests
• GET /admin/queue/status 返回实时并发状态

当请求中带 tools 时，DS2API 会做防泄漏处理与结构化转译：

1. 只在非代码块上下文启用执行型 toolcall 识别（代码块示例默认不触发）
2. 解析层以 XML/Markup 为最高优先级，同时兼容 JSON / ANTML / invoke / text-kv，并统一归一到内部工具调用结构
3. responses 流式严格使用官方 item 生命周期事件（response.output_item.*、response.content_part.*、response.function_call_arguments.*）
4. responses 支持并执行 tool_choice（auto/none/required/强制函数）；required 违规时非流式返回 422，流式返回 response.failed
5. 客户端请求哪种协议，就按该协议返回工具调用（OpenAI/Claude/Gemini 各自原生结构）；模型侧优先约束输出规范 XML，再由兼容层转译

说明：当前版本在 parser 层仍以“尽量解析成功”为优先，未启用基于 allow-list 的工具名硬拒绝。

想评估“把工具调用封装成 XML 再输入模型”的方案，可参考：docs/toolcall-semantics.md。

用于定位「responses 思考流/工具调用」等问题。开启后会自动记录最近 N 条 DeepSeek 对话上游请求体与响应体（默认 20 条，超出自动淘汰；单条响应体默认最多记录 5 MB）。

启用示例：

DS2API_DEV_PACKET_CAPTURE=true \
DS2API_DEV_PACKET_CAPTURE_LIMIT=20 \
go run ./cmd/ds2api

查询/清空（需 Admin JWT）：

• GET /admin/dev/captures：查看抓包列表（最新在前）
• DELETE /admin/dev/captures：清空抓包
• GET /admin/dev/raw-samples/query?q=关键词&limit=20：按问题关键词查询当前内存抓包，并按 chat_session_id 归并 completion + continue 链
• POST /admin/dev/raw-samples/save：把命中的某条抓包链保存为 tests/raw_stream_samples/<sample-id>/ 回放样本

返回字段包含：

• request_body：发送给 DeepSeek 的完整请求体
• response_body：上游返回的原始流式内容拼接文本
• response_truncated：是否触发单条大小截断

保存接口支持用 query、chain_key 或 capture_id 选中目标。例如：

{"query":"广州天气","sample_id":"gz-weather-from-memory"}

# 单元测试（Go + Node）
./tests/scripts/run-unit-all.sh

# 一键端到端全链路测试（真实账号，生成完整请求/响应日志）
./tests/scripts/run-live.sh

# 或自定义参数
go run ./cmd/ds2api-tests \
  --config config.json \
  --admin-key admin \
  --out artifacts/testsuite \
  --timeout 120 \
  --retries 2

# 发布前阻断门禁
./tests/scripts/check-stage6-manual-smoke.sh
./tests/scripts/check-refactor-line-gate.sh
./tests/scripts/run-unit-all.sh
npm ci --prefix webui && npm run build --prefix webui

详细测试指南请参阅 docs/TESTING.md。

# 运行所有单元测试
go test ./...

# 运行 tool calls 相关测试（调试工具调用问题）
go test -v -run 'TestParseToolCalls|TestRepair' ./internal/toolcall/

# 运行端到端测试
./tests/scripts/run-live.sh

工作流文件：.github/workflows/release-artifacts.yml

• 触发条件：仅在 GitHub Release published 时触发（普通 push 不会触发）
• 构建产物：多平台二进制包（linux/amd64、linux/arm64、darwin/amd64、darwin/arm64、windows/amd64）+ sha256sums.txt
• 容器镜像发布：仅推送到 GHCR（ghcr.io/cjackhwang/ds2api）
• 每个压缩包包含：ds2api 可执行文件、static/admin、WASM 文件（同时支持内置 fallback）、配置示例、README、LICENSE

本项目基于逆向方式实现，仅供学习、研究、个人实验和内部验证使用，不提供任何商业授权、稳定性保证或可用性保证。 作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。

请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 LICENSE、相关协议以及你是否获得了作者的书面许可。