Annekyl/deepseek-web-gateway

DeepSeek Web Gateway

Python
FastAPI
Tests
License

把个人的 DeepSeek 网页会话包装成仅监听本机的 OpenAI-compatible API，目标客户端是
DeepSeek Harness。生产路径使用 HTTP 请求网页私有接口，不用浏览器自动完成聊天。

A local OpenAI-compatible gateway backed by an authenticated DeepSeek Web session,
with streaming and prompt-based tool calling for DeepSeek Harness.

这是非官方、本地个人用途的兼容层。DeepSeek Web API、PoW、WAF 和登录态都可能
随时变化，也可能受服务条款或账号风控约束。正式、长期稳定用途应优先使用 DeepSeek
官方 API。

快速开始

git clone https://github.com/Annekyl/deepseek-web-gateway.git
cd deepseek-web-gateway

Windows 用户完成 .env 配置后，可以直接双击：

start-dsh.cmd       启动网关并打开交互式 DSH Web UI
start-gateway.cmd   只在后台启动 OpenAI-compatible API
stop-gateway.cmd    停止后台网关

命令行启动：

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
Copy-Item .env.example .env
填写 .env 后：
.\run.ps1

默认 API 地址：http://127.0.0.1:22217/v1，模型 ID：deepseek-web。

架构

flowchart LR
H[DeepSeek Harness / OpenAI client] -->|Chat Completions + tools| G[Local FastAPI Gateway]
G -->|Session + PoW + SSE| W[DeepSeek Web]
W -->|Text tool protocol| G
G -->|OpenAI tool_calls| H
H -->|tool result| G

当前能力

- GET /v1/models
- POST /v1/chat/completions，普通与 SSE 流式输出
- system、developer、user、assistant、tool 消息
- developer 自动映射为 system
- max_tokens 与 max_completion_tokens 同时接受
- prompt-based tools → 标准 OpenAI tool_calls
- tool result → 下一轮最终回答的完整 Agent Loop
- 严格 JSON 解析、JSON Schema 参数校验、一次协议修复重试
- 本地 Bearer API key、敏感日志脱敏、默认 127.0.0.1:22217

temperature 和 top_p 会被兼容层接受，但 DeepSeek Web 当前私有请求没有对应的稳定
参数，因此不会伪造映射。token 上限会作为提示加入上下文，并非精确 tokenizer 截断。
图像输入暂不支持。

网页协议边界

截至 2026-09-17，当前公开实现交叉验证的流程是：

1. 从 localStorage.userToken 读取 bearer token，并携带完整浏览器 Cookie。
2. POST /api/v0/chat_session/create 创建网页会话。
3. POST /api/v0/chat/create_pow_challenge 获取短时 PoW challenge。
4. 用 DeepSeekHashV1 解题，生成 x-ds-pow-response。
5. POST /api/v0/chat/completion，读取 DeepSeek patch-style SSE。

协议实现集中在 app/deepseek/，网页改版时不需要改 OpenAI 路由。参考实现与协议证据：

- sums001/Deepseek-API
- kittors/deepseek-web-api architecture
- ds2api completion endpoint

若 DeepSeek 只替换 PoW WASM，可把兼容版本放在本机并通过
DEEPSEEK_POW_WASM_PATH 切换，无需改路由或 API 适配代码。

安装

需要 Python 3.11+。

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
Copy-Item .env.example .env

获取本机登录态

1. 在普通 Chrome/Edge 中打开 https://chat.deepseek.com 并正常登录；验证码仍由你本人完成。
2. DevTools → Application → Local Storage → https://chat.deepseek.com，找到
userToken。其值通常是含 value 字段的 JSON；把 value 里的 token 填入
.env 的 DEEPSEEK_TOKEN。
3. DevTools → Network，选择一个发往 chat.deepseek.com/api/v0/ 的请求，在 Request
Headers 中复制完整 Cookie 值，填入 DEEPSEEK_COOKIE。不要只复制单个
ds_session_id，WAF Cookie 也可能是必需的。
4. 最好把同一请求的 User-Agent 填入 DEEPSEEK_USER_AGENT。

也可用 DEEPSEEK_AUTH_FILE 指向本机 JSON：

{
"token": "本机 token",
"cookie": "完整 Cookie header",
"user_agent": "浏览器 User-Agent"
}

把文件放在 data/ 或 session/ 下；两者均被 .gitignore 排除。项目不会打印这些
字段。登录态过期时重新复制即可。本项目不自动登录、不绕过验证码或风控。

启动

先在 .env 中修改 LOCAL_API_KEY，然后：

.\run.ps1

Windows 一键启动

可以直接双击仓库根目录中的文件：

- start-gateway.cmd：在后台启动网关；重复双击不会重复启动。
- stop-gateway.cmd：停止由一键脚本启动的网关。
- start-dsh.cmd：自动启动网关并打开正常的交互式 DSH Web UI；进入 DSH 后再输入任务。
- start-harness.cmd：兼容旧文件名，行为与 start-dsh.cmd 相同。

后台进程的 PID 和脱敏日志保存在被 Git 忽略的 data/ 目录。若需要前台查看实时日志，
仍可使用 run.ps1；前台和后台方式不要同时启动。

如需让交互式 DSH 以另一个目录作为工作区，可在 PowerShell 中运行：

.\scripts\start-dsh.ps1 -ProjectPath "D:\Study\你的项目"

默认地址为 http://127.0.0.1:22217/v1。run.ps1 会从 .env 读取 HOST 和
PORT，示例默认值仍固定为 loopback。也可直接运行 Uvicorn：

.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 22217

调用示例

$headers = @{
Authorization = "Bearer local-secret-key"
"Content-Type" = "application/json"
}
$body = @{
model = "deepseek-web"
messages = @(
@{ role = "user"; content = "你好" }
)
} | ConvertTo-Json -Depth 10

Invoke-RestMethod
-Uri "http://127.0.0.1:22217/v1/chat/completions"
-Method Post
-Headers $headers
-Body $body

仓库另有可直接运行的脚本：

.\scripts\test-chat.ps1 -ApiKey "你的 LOCAL_API_KEY"
.\scripts\test-tool-call.ps1 -ApiKey "你的 LOCAL_API_KEY"

第二个脚本会真实完成：模型返回 tool_calls → 本地模拟天气工具 → 发送 tool 消息 →
模型给出最终回答。

Tool Calling 设计

DeepSeek Web 没有 OpenAI 原生 function-calling channel。本项目将工具 schema、
tool_choice 和严格协议注入上下文，要求模型输出：

{"name":"get_weather","arguments":{"city":"北京"}}

适配器不会用正则提取 JSON，而是定位精确协议边界后调用 JSON parser，并以调用方提供
的 JSON Schema 校验 arguments。未知工具、非法 JSON、缺少必填参数、违反
tool_choice 都不会传给 Harness。检测到损坏协议时会新建网页会话重试一次；再次失败
则返回 OpenAI 风格 invalid_tool_call 错误。

带 tools 的流式请求需要等完整模型输出才能安全解析，因此 tool call 会在一个 SSE
chunk 中返回；普通文本仍按上游增量转发。

测试

.venv\Scripts\python.exe -m pytest -q

当前自动测试结果为 17 passed，覆盖 models、普通聊天、system、developer、stream、tool calling、tool result loop、
参数 schema 校验和本地认证。自动测试使用测试专用的确定性上游，不会访问你的账号；
生产 DeepSeek client 没有 mock fallback。

要验证真实 HTTP 协议而不访问 DeepSeek，可启动测试 app：

.venv\Scripts\python.exe -m uvicorn tests.http_app:test_app --host 127.0.0.1 --port 22218
Invoke-RestMethod -Headers @{Authorization="Bearer test-key"} http://127.0.0.1:22218/v1/models

错误映射

- 登录态缺失/过期：deepseek_credentials_missing / deepseek_auth_expired
- WAF、限流或风控 429：deepseek_rate_limited，保留 Retry-After
- 网络与 SSE 中断：deepseek_network_error / deepseek_stream_interrupted
- timeout：deepseek_timeout / deepseek_stream_timeout
- 网页协议变化：deepseek_protocol_error
- 工具 JSON 或 schema 持续非法：invalid_tool_call

非流式请求返回标准 OpenAI error JSON。流式响应若已发出 HTTP headers，错误会作为
data: {"error": ...} 后跟 data: [DONE] 结束，避免破坏 SSE framing。

DeepSeek Harness 配置

DeepSeek Harness 当前官方 dsh-llm-pi-ai provider 格式如下；apiKeyEnv 的值是
Harness 进程读取的环境变量名，不是明文密钥。字段名也已在本机安装的
DeepSeek Harness 0.1.2-rc.1 包中核对：

llm-pi-ai:
providers:
deepseek-web:
displayName: DeepSeek Web (local)
apiKeyEnv: DEEPSEEK_WEB_LOCAL_KEY
api: openai-completions
baseURL: http://127.0.0.1:22217/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: deepseek-web
displayName: DeepSeek Web

启动 Harness 前设置与 .env 中 LOCAL_API_KEY 相同的值：

$env:DEEPSEEK_WEB_LOCAL_KEY = "local-secret-key"

配置依据是 Harness 官方的
llm-pi-ai README
和
providers guide。
无需修改 Harness 源码。

仓库还提供了可直接叠加到 headless profile 的 smoke-test patch：

$env:DEEPSEEK_WEB_LOCAL_KEY = "与 LOCAL_API_KEY 相同的值"
dsh --profile headless --patch .\scripts\harness-smoke.patch.yaml "Reply with hello"

网关使用 DEEPSEEK_WEB_BASE_URL，特意避开 Harness 保留的
DEEPSEEK_BASE_URL 启动变量名，因此可以从本仓库目录直接运行上述命令。

已知限制

- Web 私有接口不是稳定 API；endpoint、header、PoW WASM 或 SSE patch 格式变化都会导致
适配层需要更新。
- prompt-based tool calling 无法达到服务端原生 constrained decoding 的确定性；本项目用
schema 校验和一次重试降低失败率，但不能宣称 100% 成功。
- 每个 OpenAI 请求都创建新的 Web session，并重放完整消息历史。这比复用网页会话多耗
上下文，但避免 Harness 重试、并发和 tool-result lineage 错配。
- 单账号建议低并发使用；WAF 429 时不要自动高频重试。
- 2026-09-18 已使用真实 DeepSeek Web 登录态和 DeepSeek Harness 验证完整文件工具循环；
该结果只代表当时的网页协议，不能保证未来私有接口不变。

安全

- 永远不要提交或粘贴 .env、Cookie、userToken、完整请求头或本地 API key。
- 默认只监听 127.0.0.1；项目不支持直接暴露到公网。
- 后台日志经过脱敏，但分享日志前仍应人工检查。
- 安全问题请参阅 SECURITY.md。

开源许可

项目代码采用 MIT License。PoW WASM 及其适配代码的第三方来源和许可见
THIRD_PARTY_NOTICES.md。