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

docs: update API documentation, deployment guides, and README with new admin endpoints, compatibility notes, and build instructions

Browse Source
This commit is contained in:
CJACK
2026-03-29 19:17:07 +08:00
parent 075728cca6
commit aeb519c211
11 changed files with 224 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.env.example
View File

@@ -10,6 +10,8 @@ DS2API_ADMIN_KEY=change-me
DS2API_CONFIG_PATH=/app/config.json
# 2) inline JSON or Base64 JSON
# DS2API_CONFIG_JSON=
# 3) legacy compatibility alias
# CONFIG_JSON=
# Optional: static admin assets path
# DS2API_STATIC_ADMIN_DIR=/app/static/admin

81
API.en.md
View File

@@ -46,6 +46,7 @@ Use it per deployment mode:
- Local run: read `config.json` directly
- Docker / Vercel: generate Base64 from `config.json`, then set `DS2API_CONFIG_JSON`
- Compatibility note: `DS2API_CONFIG_JSON` may also contain raw JSON directly; `CONFIG_JSON` is the legacy fallback variable
```bash
DS2API_CONFIG_JSON="$(base64 < config.json | tr -d '\n')"
@@ -65,6 +66,7 @@ Two header formats accepted:
| --- | --- |
| Bearer Token | `Authorization: Bearer <token>` |
| API Key Header | `x-api-key: <token>` (no `Bearer` prefix) |
| Gemini-compatible | `x-goog-api-key: <token>` or `?key=<token>` / `?api_key=<token>` |
**Auth behavior**:
@@ -72,6 +74,7 @@ Two header formats accepted:
- Token is not in `config.keys` → **Direct token mode**: treated as a DeepSeek token directly
**Optional header**: `X-Ds2-Target-Account: <email_or_mobile>` — Pin a specific managed account.
Gemini-compatible clients can also send `x-goog-api-key`, `?key=`, or `?api_key=` as the caller credential source.
### Admin Endpoints (`/admin/*`)
@@ -124,13 +127,16 @@ Two header formats accepted:
| GET | `/admin/queue/status` | Admin | Account queue status |
| POST | `/admin/accounts/test` | Admin | Test one account |
| POST | `/admin/accounts/test-all` | Admin | Test all accounts |
| POST | `/admin/accounts/sessions/delete-all` | Admin | Delete all sessions for one account |
| POST | `/admin/import` | Admin | Batch import keys/accounts |
| POST | `/admin/test` | Admin | Test API through service |
| POST | `/admin/vercel/sync` | Admin | Sync config to Vercel |
| GET | `/admin/vercel/status` | Admin | Vercel sync status |
| POST | `/admin/vercel/status` | Admin | Vercel sync status / draft compare |
| GET | `/admin/export` | Admin | Export config JSON/Base64 |
| GET | `/admin/dev/captures` | Admin | Read local packet-capture entries |
| DELETE | `/admin/dev/captures` | Admin | Clear local packet-capture entries |
| GET | `/admin/version` | Admin | Check current version and latest Release |
---
@@ -580,6 +586,7 @@ Returns sanitized config.
```json
{
"keys": ["k1", "k2"],
"env_backed": false,
"accounts": [
{
"identifier": "user@example.com",
@@ -599,7 +606,7 @@ Returns sanitized config.
### `POST /admin/config`
Updatable fields: `keys`, `accounts`, `claude_mapping`.
Only updates `keys`, `accounts`, and `claude_mapping`.
**Request**:
@@ -620,7 +627,8 @@ Updatable fields: `keys`, `accounts`, `claude_mapping`.
Reads runtime settings and status, including:
- `admin` (JWT expiry, default-password warning, etc.)
- `success`
- `admin` (`has_password_hash`, `jwt_expire_hours`, `jwt_valid_after_unix`, `default_password_warning`)
- `runtime` (`account_max_inflight`, `account_max_queue`, `global_max_inflight`)
- `toolcall` / `responses` / `embeddings`
- `auto_delete` (`sessions`)
@@ -650,6 +658,8 @@ Request example:
{"new_password":"your-new-password"}
```
It also accepts `{"password":"your-new-password"}`.
### `POST /admin/config/import`
Imports full config with:
@@ -658,6 +668,8 @@ Imports full config with:
- `mode=replace`
The request can send config directly, or wrapped as `{"config": {...}, "mode":"merge"}`.
Query params `?mode=merge` / `?mode=replace` are also supported.
Import accepts `keys`, `accounts`, `claude_mapping` / `claude_model_mapping`, `model_aliases`, `admin`, `runtime`, `toolcall`, `responses`, `embeddings`, and `auto_delete`.
### `GET /admin/config/export`
@@ -683,6 +695,7 @@ Exports full config in three forms: `config`, `json`, and `base64`.
| --- | --- | --- |
| `page` | `1` | ≥ 1 |
| `page_size` | `10` | 1–100 |
| `q` | empty | Filter by identifier / email / mobile |
**Response**:
@@ -695,7 +708,8 @@ Exports full config in three forms: `config`, `json`, and `base64`.
"mobile": "",
"has_password": true,
"has_token": true,
"token_preview": "abc..."
"token_preview": "abc...",
"test_status": "ok"
}
],
"total": 25,
@@ -705,6 +719,8 @@ Exports full config in three forms: `config`, `json`, and `base64`.
}
```
Returned items also include `test_status`, usually `ok` or `failed`.
### `POST /admin/accounts`
```json
@@ -757,10 +773,14 @@ Exports full config in three forms: `config`, `json`, and `base64`.
"success": true,
"response_time": 1240,
"message": "API test successful (session creation only)",
"model": "deepseek-chat"
"model": "deepseek-chat",
"session_count": 0,
"config_writable": true
}
```
If a `message` is provided, `thinking` may also be included when the upstream response carries reasoning text.
### `POST /admin/accounts/test-all`
Optional request field: `model`.
@@ -774,6 +794,25 @@ Optional request field: `model`.
}
```
The internal concurrency limit is currently fixed at 5.
### `POST /admin/accounts/sessions/delete-all`
Deletes all DeepSeek sessions for a specific account. Request example:
```json
{"identifier":"user@example.com"}
```
Response:
```json
{"success": true, "message": "删除成功"}
```
If the account is missing or deletion fails, `success` becomes `false` and `message` contains the error.
The current handler returns the Chinese literal `删除成功` on success.
### `POST /admin/import`
Batch import keys and accounts.
@@ -851,16 +890,25 @@ Or manual deploy required:
}
```
Failed account checks are returned in `failed_accounts`, and any saved Vercel credentials are returned in `saved_credentials`.
### `GET /admin/vercel/status`
```json
{
"synced": true,
"last_sync_time": 1738400000,
"has_synced_before": true
"has_synced_before": true,
"env_backed": false,
"config_hash": "....",
"last_synced_hash": "....",
"draft_hash": "....",
"draft_differs": false
}
```
`POST /admin/vercel/status` can also accept `config_override` to compare a draft config against the current synced config.
### `GET /admin/export`
```json
@@ -870,6 +918,29 @@ Or manual deploy required:
}
```
This is the same payload as `GET /admin/config/export`, just with a shorter path.
### `GET /admin/version`
Checks the current build version and the latest GitHub Release:
```json
{
"success": true,
"current_version": "2.3.5",
"current_tag": "v2.3.5",
"source": "file:VERSION",
"checked_at": "2026-03-29T00:00:00Z",
"latest_tag": "v2.3.6",
"latest_version": "2.3.6",
"release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v2.3.6",
"published_at": "2026-03-28T12:00:00Z",
"has_update": true
}
```
If GitHub API access fails, the response includes `check_error` while still returning HTTP 200.
### `GET /admin/dev/captures`
Reads local packet-capture status and recent entries (Admin auth required):

80
API.md
View File

@@ -46,6 +46,7 @@ cp config.example.json config.json
- 本地运行：直接读取 `config.json`
- Docker / Vercel：从 `config.json` 生成 Base64，填入 `DS2API_CONFIG_JSON`
- 兼容写法：`DS2API_CONFIG_JSON` 也可直接填原始 JSON；`CONFIG_JSON` 是旧版兼容回退变量
```bash
DS2API_CONFIG_JSON="$(base64 < config.json | tr -d '\n')"
@@ -65,6 +66,7 @@ Vercel 一键部署可先只填 `DS2API_ADMIN_KEY`，部署后在 `/admin` 导
| --- | --- |
| Bearer Token | `Authorization: Bearer <token>` |
| API Key Header | `x-api-key: <token>`（无 `Bearer` 前缀） |
| Gemini 兼容 | `x-goog-api-key: <token>` 或 `?key=<token>` / `?api_key=<token>` |
**鉴权行为**：
@@ -72,6 +74,7 @@ Vercel 一键部署可先只填 `DS2API_ADMIN_KEY`，部署后在 `/admin` 导
- token 不在 `config.keys` 中 → **直通 token 模式**，直接作为 DeepSeek token 使用
**可选请求头**：`X-Ds2-Target-Account: <email_or_mobile>` — 指定使用某个托管账号。
Gemini 兼容客户端还可以使用 `x-goog-api-key`、`?key=` 或 `?api_key=` 作为凭据来源。
### Admin 接口（`/admin/*`）
@@ -124,13 +127,16 @@ Vercel 一键部署可先只填 `DS2API_ADMIN_KEY`，部署后在 `/admin` 导
| GET | `/admin/queue/status` | Admin | 账号队列状态 |
| POST | `/admin/accounts/test` | Admin | 测试单个账号 |
| POST | `/admin/accounts/test-all` | Admin | 测试全部账号 |
| POST | `/admin/accounts/sessions/delete-all` | Admin | 删除某账号的全部会话 |
| POST | `/admin/import` | Admin | 批量导入 keys/accounts |
| POST | `/admin/test` | Admin | 测试当前 API 可用性 |
| POST | `/admin/vercel/sync` | Admin | 同步配置到 Vercel |
| GET | `/admin/vercel/status` | Admin | Vercel 同步状态 |
| POST | `/admin/vercel/status` | Admin | Vercel 同步状态 / 草稿对比 |
| GET | `/admin/export` | Admin | 导出配置 JSON/Base64 |
| GET | `/admin/dev/captures` | Admin | 查看本地抓包记录 |
| DELETE | `/admin/dev/captures` | Admin | 清空本地抓包记录 |
| GET | `/admin/version` | Admin | 查询当前版本与最新 Release |
---
@@ -494,6 +500,8 @@ data: {"type":"message_stop"}
}
```
返回项还会包含 `test_status`，当前值通常为 `ok` 或 `failed`。
---
## Gemini 兼容接口
@@ -587,6 +595,7 @@ data: {"type":"message_stop"}
```json
{
"keys": ["k1", "k2"],
"env_backed": false,
"accounts": [
{
"identifier": "user@example.com",
@@ -606,7 +615,7 @@ data: {"type":"message_stop"}
### `POST /admin/config`
可更新 `keys`、`accounts`、`claude_mapping`。
只更新 `keys`、`accounts`、`claude_mapping`。
**请求**：
@@ -627,7 +636,8 @@ data: {"type":"message_stop"}
读取运行时设置与状态，返回：
- `admin`（JWT 过期、默认密码告警等）
- `success`
- `admin`（`has_password_hash`、`jwt_expire_hours`、`jwt_valid_after_unix`、`default_password_warning`）
- `runtime`（`account_max_inflight`、`account_max_queue`、`global_max_inflight`）
- `toolcall` / `responses` / `embeddings`
- `auto_delete`（`sessions`）
@@ -657,6 +667,8 @@ data: {"type":"message_stop"}
{"new_password":"your-new-password"}
```
也兼容 `{"password":"your-new-password"}`。
### `POST /admin/config/import`
导入完整配置，支持：
@@ -665,6 +677,8 @@ data: {"type":"message_stop"}
- `mode=replace`
请求可直接传配置对象，或使用 `{"config": {...}, "mode":"merge"}` 包裹格式。
也支持在查询参数里传 `?mode=merge` / `?mode=replace`。
导入时会接受 `keys`、`accounts`、`claude_mapping` / `claude_model_mapping`、`model_aliases`、`admin`、`runtime`、`toolcall`、`responses`、`embeddings`、`auto_delete` 等字段。
### `GET /admin/config/export`
@@ -690,6 +704,7 @@ data: {"type":"message_stop"}
| --- | --- | --- |
| `page` | `1` | ≥ 1 |
| `page_size` | `10` | 1–100 |
| `q` | 空 | 按 identifier / email / mobile 过滤 |
**响应**：
@@ -702,7 +717,8 @@ data: {"type":"message_stop"}
"mobile": "",
"has_password": true,
"has_token": true,
"token_preview": "abc..."
"token_preview": "abc...",
"test_status": "ok"
}
],
"total": 25,
@@ -764,10 +780,14 @@ data: {"type":"message_stop"}
"success": true,
"response_time": 1240,
"message": "API 测试成功（仅会话创建）",
"model": "deepseek-chat"
"model": "deepseek-chat",
"session_count": 0,
"config_writable": true
}
```
如果传入 `message`，还会附带 `thinking`（当上游返回思考内容时）。
### `POST /admin/accounts/test-all`
可选请求字段：`model`
@@ -781,6 +801,24 @@ data: {"type":"message_stop"}
}
```
内部并发上限当前固定为 5。
### `POST /admin/accounts/sessions/delete-all`
清空指定账号的所有 DeepSeek 会话。请求体示例：
```json
{"identifier":"user@example.com"}
```
响应：
```json
{"success": true, "message": "删除成功"}
```
如果账号不存在或删除失败，`success` 会是 `false`，`message` 会返回错误原因。
### `POST /admin/import`
批量导入 keys 与 accounts。
@@ -858,16 +896,25 @@ data: {"type":"message_stop"}
}
```
失败校验的账号会通过 `failed_accounts` 返回；成功保存到 Vercel 的凭据会通过 `saved_credentials` 返回。
### `GET /admin/vercel/status`
```json
{
"synced": true,
"last_sync_time": 1738400000,
"has_synced_before": true
"has_synced_before": true,
"env_backed": false,
"config_hash": "....",
"last_synced_hash": "....",
"draft_hash": "....",
"draft_differs": false
}
```
`POST /admin/vercel/status` 还可以携带 `config_override`，用于对比“草稿配置”和当前已同步配置。
### `GET /admin/export`
```json
@@ -877,6 +924,29 @@ data: {"type":"message_stop"}
}
```
该接口与 `GET /admin/config/export` 返回相同内容，只是路径更短。
### `GET /admin/version`
查询当前构建版本与 GitHub 最新 Release：
```json
{
"success": true,
"current_version": "2.3.5",
"current_tag": "v2.3.5",
"source": "file:VERSION",
"checked_at": "2026-03-29T00:00:00Z",
"latest_tag": "v2.3.6",
"latest_version": "2.3.6",
"release_url": "https://github.com/CJackHwang/ds2api/releases/tag/v2.3.6",
"published_at": "2026-03-28T12:00:00Z",
"has_update": true
}
```
如果 GitHub API 不可用，响应里会额外包含 `check_error`，但 HTTP 状态仍为 200。
### `GET /admin/dev/captures`
查看本地抓包状态与最近记录（需 Admin 鉴权）：

3
CONTRIBUTING.en.md
View File

@@ -70,6 +70,7 @@ docker-compose -f docker-compose.dev.yml up
5. Open a Pull Request
> 💡 If you modify files under `webui/`, no manual build is needed — CI handles it automatically.
> If you want to verify the generated `static/admin/` assets locally, you can still run `./scripts/build-webui.sh`.
## Build WebUI
@@ -129,6 +130,8 @@ ds2api/
│ ├── components/ # Shared components
│ └── locales/ # Language packs
├── scripts/ # Build and test scripts
├── tests/ # Unit tests, Node tests, and end-to-end tests
├── plans/ # Plans, gates, and manual smoke-test records
├── static/admin/ # WebUI build output (not committed)
├── Dockerfile # Multi-stage build
├── docker-compose.yml # Production

3
CONTRIBUTING.md
View File

@@ -70,6 +70,7 @@ docker-compose -f docker-compose.dev.yml up
5. 发起 Pull Request
> 💡 如果修改了 `webui/` 目录下的文件，无需手动构建——CI 会自动处理。
> 但如果你本地想验证 `static/admin/` 产物，还是可以手动运行 `./scripts/build-webui.sh`。
## WebUI 构建
@@ -129,6 +130,8 @@ ds2api/
│ ├── components/ # 通用组件
│ └── locales/ # 语言包
├── scripts/ # 构建与测试脚本
├── tests/ # 单元测试、Node 测试与端到端测试
├── plans/ # 计划、门禁和手工烟测记录
├── static/admin/ # WebUI 构建产物（不提交）
├── Dockerfile # 多阶段构建
├── docker-compose.yml # 生产环境

5
DEPLOY.en.md
View File

@@ -32,6 +32,7 @@ Config source (choose one):
- **File**: `config.json` (recommended for local/Docker)
- **Environment variable**: `DS2API_CONFIG_JSON` (recommended for Vercel; supports raw JSON or Base64)
- Compatibility note: `CONFIG_JSON` is the legacy fallback variable; `DS2API_CONFIG_JSON` may also contain raw JSON directly
Unified recommendation (best practice):
@@ -69,7 +70,7 @@ Default address: `http://0.0.0.0:5001` (override with `PORT`).
### 1.2 WebUI Build
On first local startup, if `static/admin/` is missing, DS2API will automatically attempt to build the WebUI (requires Node.js/npm).
On first local startup, if `static/admin/` is missing, DS2API will automatically attempt to build the WebUI (requires Node.js/npm; when dependencies are missing it runs `npm ci` first, then `npm run build -- --outDir static/admin --emptyOutDir`).
Manual build:
@@ -123,6 +124,8 @@ docker-compose up -d
docker-compose logs -f
```
The default `docker-compose.yml` maps host port `6011` to container port `5001`. If you want `5001` exposed directly, adjust the `ports` mapping.
### 2.2 Update
```bash

5
DEPLOY.md
View File

@@ -32,6 +32,7 @@
- **文件方式**：`config.json`（推荐本地/Docker 使用）
- **环境变量方式**：`DS2API_CONFIG_JSON`（推荐 Vercel 使用，支持 JSON 字符串或 Base64 编码）
- 兼容写法：`CONFIG_JSON` 是旧版回退变量；`DS2API_CONFIG_JSON` 也可以直接写原始 JSON
统一建议（最优实践）：
@@ -69,7 +70,7 @@ go run ./cmd/ds2api
### 1.2 WebUI 构建
本地首次启动时，若 `static/admin/` 不存在，服务会自动尝试构建 WebUI（需要 Node.js/npm）。
本地首次启动时，若 `static/admin/` 不存在，服务会自动尝试构建 WebUI（需要 Node.js/npm；缺依赖时会先执行 `npm ci`，再执行 `npm run build -- --outDir static/admin --emptyOutDir`）。
你也可以手动构建：
@@ -123,6 +124,8 @@ docker-compose up -d
docker-compose logs -f
```
默认 `docker-compose.yml` 会把宿主机 `6011` 映射到容器内的 `5001`。如果你希望直接对外暴露 `5001`，请调整 `ports` 配置。
### 2.2 更新
```bash

25
README.MD
View File

@@ -16,6 +16,14 @@
将 DeepSeek Web 对话能力转换为 OpenAI、Claude 与 Gemini 兼容 API。后端为 **Go 全量实现**，前端为 React WebUI 管理台（源码在 `webui/`，部署时自动构建到 `static/admin`）。
> **重要免责声明**
>
> 本仓库仅供学习、研究、个人实验和内部验证使用，不提供任何形式的商业授权、适用性保证或结果保证。
>
> 作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。
>
> 请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 `LICENSE`、相关协议以及你是否获得了作者的书面许可。
## 架构概览
```mermaid
@@ -68,7 +76,7 @@ flowchart LR
| 并发队列控制 | 每账号 in-flight 上限 + 等待队列，动态计算建议并发值 |
| DeepSeek PoW | WASM 计算（`wazero`），无需外部 Node.js 依赖 |
| Tool Calling | 防泄漏处理：非代码块高置信特征识别、`delta.tool_calls` 早发、结构化增量输出 |
| Admin API | 配置管理、运行时设置热更新、账号测试 / 批量测试、导入导出、Vercel 同步 |
| Admin API | 配置管理、运行时设置热更新、账号测试 / 批量测试、会话清理、导入导出、Vercel 同步、版本检查 |
| WebUI 管理台 | `/admin` 单页应用（中英文双语、深色模式） |
| 运维探针 | `GET /healthz`（存活）、`GET /readyz`（就绪） |
@@ -132,6 +140,7 @@ cp config.example.json config.json
后续部署建议：
- 本地运行：直接读取 `config.json`
- Docker / Vercel：由 `config.json` 生成 `DS2API_CONFIG_JSON`（Base64）注入环境变量
- 兼容写法：`DS2API_CONFIG_JSON` 也可以直接写原始 JSON；`CONFIG_JSON` 是旧版回退变量
### 方式一：本地运行
@@ -152,7 +161,7 @@ go run ./cmd/ds2api
默认监听地址：`http://localhost:5001`
> **WebUI 自动构建**：本地首次启动时，若 `static/admin` 不存在，会自动尝试执行 `npm install && npm run build`（需要本机有 Node.js）。你也可以手动构建：`./scripts/build-webui.sh`
> **WebUI 自动构建**：本地首次启动时，若 `static/admin` 不存在，会自动尝试执行 `npm ci`（仅在缺少依赖时）和 `npm run build -- --outDir static/admin --emptyOutDir`（需要本机有 Node.js）。你也可以手动构建：`./scripts/build-webui.sh`
### 方式二：Docker 运行
@@ -170,6 +179,8 @@ docker-compose up -d
docker-compose logs -f
```
默认 `docker-compose.yml` 会把宿主机 `6011` 映射到容器内的 `5001`。如果你希望直接对外暴露 `5001`，请调整 `ports` 配置。
更新镜像：`docker-compose up -d --build`
#### Zeabur 一键部署（Dockerfile）
@@ -311,9 +322,13 @@ cp opencode.json.example opencode.json
| `DS2API_JWT_EXPIRE_HOURS` | Admin JWT 过期小时数 | `24` |
| `DS2API_CONFIG_PATH` | 配置文件路径 | `config.json` |
| `DS2API_CONFIG_JSON` | 直接注入配置（JSON 或 Base64） | — |
| `CONFIG_JSON` | 旧版兼容配置注入 | — |
| `DS2API_WASM_PATH` | PoW WASM 文件路径 | 自动查找 |
| `DS2API_STATIC_ADMIN_DIR` | 管理台静态文件目录 | `static/admin` |
| `DS2API_AUTO_BUILD_WEBUI` | 启动时自动构建 WebUI | 本地开启，Vercel 关闭 |
| `DS2API_DEV_PACKET_CAPTURE` | 本地开发抓包开关（记录最近会话请求/响应体） | 本地非 Vercel 默认开启 |
| `DS2API_DEV_PACKET_CAPTURE_LIMIT` | 本地抓包保留条数（超出自动淘汰） | `5` |
| `DS2API_DEV_PACKET_CAPTURE_MAX_BODY_BYTES` | 单条响应体最大记录字节数 | `2097152` |
| `DS2API_ACCOUNT_MAX_INFLIGHT` | 每账号最大并发 in-flight 请求数 | `2` |
| `DS2API_ACCOUNT_CONCURRENCY` | 同上（兼容旧名） | — |
| `DS2API_ACCOUNT_MAX_QUEUE` | 等待队列上限 | `recommended_concurrency` |
@@ -340,6 +355,7 @@ cp opencode.json.example opencode.json
| **直通 token 模式** | 传入 token 不在 `config.keys` 中时，直接作为 DeepSeek token 使用 |
可选请求头 `X-Ds2-Target-Account`：指定使用某个托管账号（值为 email 或 mobile）。
Gemini 路由还可以使用 `x-goog-api-key`，或在没有认证头时使用 `?key=` / `?api_key=` 作为调用方凭据。
## 并发模型
@@ -511,4 +527,7 @@ go test -v -run 'TestParseToolCalls|TestRepair' ./internal/util/
## 免责声明
本项目基于逆向方式实现，仅供学习与研究使用。稳定性和可用性不作保证，请勿用于违反服务条款或法律法规的场景。
本项目基于逆向方式实现，仅供学习、研究、个人实验和内部验证使用，不提供任何商业授权、稳定性保证或可用性保证。
作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。
请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 `LICENSE`、相关协议以及你是否获得了作者的书面许可。

22
README.en.md
View File

@@ -16,6 +16,14 @@ Language: [中文](README.MD) | [English](README.en.md)
DS2API converts DeepSeek Web chat capability into OpenAI-compatible, Claude-compatible, and Gemini-compatible APIs. The backend is a **pure Go implementation**, with a React WebUI admin panel (source in `webui/`, build output auto-generated to `static/admin` during deployment).
> **Important Disclaimer**
>
> This repository is provided for learning, research, personal experimentation, and internal validation only. It does not grant any commercial authorization and comes with no warranty of fitness, stability, or results.
>
> The author and repository maintainers are not responsible for any direct or indirect loss, account suspension, data loss, legal risk, or third-party claims arising from use, modification, distribution, deployment, or reliance on this project.
>
> Do not use this project in ways that violate service terms, agreements, laws, or platform rules. Before any commercial use, review the `LICENSE`, the relevant terms, and confirm that you have the author's written permission.
## Architecture Overview
```mermaid
@@ -68,7 +76,7 @@ flowchart LR
| Concurrency control | Per-account in-flight limit + waiting queue, dynamic recommended concurrency |
| DeepSeek PoW | WASM solving via `wazero`, no external Node.js dependency |
| Tool Calling | Anti-leak handling: non-code-block feature match, early `delta.tool_calls`, structured incremental output |
| Admin API | Config management, runtime settings hot-reload, account testing/batch test, import/export, Vercel sync |
| Admin API | Config management, runtime settings hot-reload, account testing/batch test, session cleanup, import/export, Vercel sync, version check |
| WebUI Admin Panel | SPA at `/admin` (bilingual Chinese/English, dark mode) |
| Health Probes | `GET /healthz` (liveness), `GET /readyz` (readiness) |
@@ -132,6 +140,7 @@ cp config.example.json config.json
Recommended per deployment mode:
- Local run: read `config.json` directly
- Docker / Vercel: generate Base64 from `config.json` and inject as `DS2API_CONFIG_JSON`
- Compatibility note: `DS2API_CONFIG_JSON` may also contain raw JSON directly; `CONFIG_JSON` is the legacy fallback variable
### Option 1: Local Run
@@ -152,7 +161,7 @@ go run ./cmd/ds2api
Default URL: `http://localhost:5001`
> **WebUI auto-build**: On first local startup, if `static/admin` is missing, DS2API will auto-run `npm install && npm run build` (requires Node.js). You can also build manually: `./scripts/build-webui.sh`
> **WebUI auto-build**: On first local startup, if `static/admin` is missing, DS2API will auto-run `npm ci` (only when dependencies are missing) and `npm run build -- --outDir static/admin --emptyOutDir` (requires Node.js). You can also build manually: `./scripts/build-webui.sh`
### Option 2: Docker
@@ -170,6 +179,8 @@ docker-compose up -d
docker-compose logs -f
```
The default `docker-compose.yml` maps host port `6011` to container port `5001`. If you want `5001` exposed directly, adjust the `ports` mapping.
Rebuild after updates: `docker-compose up -d --build`
#### Zeabur One-Click (Dockerfile)
@@ -311,6 +322,7 @@ cp opencode.json.example opencode.json
| `DS2API_JWT_EXPIRE_HOURS` | Admin JWT TTL in hours | `24` |
| `DS2API_CONFIG_PATH` | Config file path | `config.json` |
| `DS2API_CONFIG_JSON` | Inline config (JSON or Base64) | — |
| `CONFIG_JSON` | Legacy compatibility config input | — |
| `DS2API_WASM_PATH` | PoW WASM file path | Auto-detect |
| `DS2API_STATIC_ADMIN_DIR` | Admin static assets dir | `static/admin` |
| `DS2API_AUTO_BUILD_WEBUI` | Auto-build WebUI on startup | Enabled locally, disabled on Vercel |
@@ -340,6 +352,7 @@ For business endpoints (`/v1/*`, `/anthropic/*`, Gemini routes), DS2API supports
| **Direct token** | If the token is not in `config.keys`, DS2API treats it as a DeepSeek token directly |
Optional header `X-Ds2-Target-Account`: Pin a specific managed account (value is email or mobile).
Gemini routes also accept `x-goog-api-key`, or `?key=` / `?api_key=` when no auth header is present.
## Concurrency Model
@@ -491,4 +504,7 @@ Workflow: `.github/workflows/release-artifacts.yml`
## Disclaimer
This project is built through reverse engineering and is provided for learning and research only. Stability is not guaranteed. Do not use it in scenarios that violate terms of service or laws.
This project is built through reverse engineering and is provided for learning, research, personal experimentation, and internal validation only. No commercial authorization is granted, and no warranty of stability, fitness, or results is provided.
The author and repository maintainers are not responsible for any direct or indirect loss, account suspension, data loss, legal risk, or third-party claims arising from use, modification, distribution, deployment, or reliance on this project.
Do not use this project in ways that violate service terms, agreements, laws, or platform rules. Before any commercial use, review the `LICENSE`, the relevant terms, and confirm that you have the author's written permission.

5
TESTING.md
View File

@@ -1,6 +1,6 @@
# DS2API 测试指南
语言 / Language: [中文 + English](TESTING.md)
语言 / Language: 中文 + English（同页）
## 概述 | Overview
@@ -14,6 +14,7 @@ DS2API 提供两个层级的测试：
| 端到端测试 | `./tests/scripts/run-live.sh` | 使用真实账号执行全链路测试 |
端到端测试集会录制完整的请求/响应日志，用于故障排查。
Node 单元测试脚本会先做 `node --check` 语法门禁，再以 `--test-concurrency=1` 串行执行测试文件，减少模块级共享状态带来的干扰。
---
@@ -66,6 +67,8 @@ DS2API 提供两个层级的测试：
4. **结果收集**：继续执行所有用例（不中断），写入最终汇总
如果你只想跳过这些 preflight 检查，可以直接运行 `go run ./cmd/ds2api-tests --no-preflight`。
---
## CLI 参数 | CLI Flags

21
docs/toolcall-semantics.md
View File

@@ -37,25 +37,28 @@
## 4) 关于“是否可以封装成 XML 再喂给模型”
结论：**可以做，而且建议把 XML 作为模型侧第一优先格式**，同时保持“输入兼容层 + 输出按客户端协议渲染”。
结论：**可以做，而且当前解析器已经能兼容 XML 作为输入格式之一**，但代码里并没有 `toolcall.prefer_xml_output` 这个开关。现有可调配置只有：
推荐架构：
- `toolcall.mode`：`feature_match` / `off`
- `toolcall.early_emit_confidence`：`high` / `low` / `off`
1. **Prompt 约束层**（默认开启）：强约束模型优先输出规范 XML tool block（例如 `<tool_calls><tool_call>...</tool_call></tool_calls>`）。
2. **解析兼容层**（已具备基础）：继续在 parser 中同时接受 JSON/XML/ANTML/invoke/text-kv。
3. **协议归一层**（必须）：无论模型输出什么格式，统一落到内部 `ParsedToolCall`。
4. **对外渲染层**：根据客户端请求协议渲染（OpenAI/Claude/Gemini 各自格式）。
推荐思路仍然是“输入兼容层 + 输出按客户端协议渲染”：
1. **Prompt 约束层**：如果你要尝试 XML-first，可以在系统提示词里约束模型输出规范 XML tool block（例如 `<tool_calls><tool_call>...</tool_call></tool_calls>`）。
2. **解析兼容层**：继续在 parser 中同时接受 JSON / XML / ANTML / invoke / text-kv。
3. **协议归一层**：无论模型输出什么格式，统一落到内部 `ParsedToolCall`。
4. **对外渲染层**：根据客户端请求协议渲染（OpenAI / Claude / Gemini 各自格式）。
这样可以同时获得：
- 减少模型端 JSON 转义/引号错误；
- 不破坏现有 SDK/客户端生态；
- 不破坏现有 SDK / 客户端生态；
- 逐步灰度（按模型、按租户、按请求开关）。
## 5) 落地建议（低风险迭代）
- 新增配置项：`toolcall.prefer_xml_output`（默认 `false`）。
- 对 `true` 场景在系统提示词里加入 XML 模板；保留 JSON 模板作为回退。
- 继续使用现有的 `toolcall.mode=feature_match` 和 `toolcall.early_emit_confidence=high` 作为默认策略。
- 如果要试 XML-first，把它放在 prompt 层或上游模板层，不要假设代码里已有专门的 XML 输出开关。
- 增加观测指标：
- `toolcall_parse_source`（json/xml/markup/textkv）；
- `toolcall_parse_success_rate`；