Zen 免费层代理kahlos/dsh-zen-proxy

dsh-zen-proxy

一个零依赖的本地代理，让
DeepSeek Harness
（dsh web）能够通过一个 OpenAI 兼容端点使用 OpenCode Zen 免费层——包括当前所有正在提供服务的
-free 模型以及 big-pickle——且无需任何上游 API 密钥。

为什么需要它

位于 https://opencode.ai/zen/v1 的 OpenCode Zen 免费层是一个普通的
OpenAI 兼容端点。任何客户端都可以使用 Authorization: Bearer public 匿名调用任何免费模型——但是网关会根据 User-Agent 将匿名流量分配到不同的配额类别：

- User-Agent: opencode/* → 可用（opencode 自有客户端的配额类别）
- 其他任何值（curl/…、deepseek-harness/…）→ FreeUsageLimitError 429

DeepSeek Harness 无法发送 opencode 的 UA（它自己的 User-Agent 是强制性的、不可覆盖的归属标头）。因此这个代理位于中间，重写请求身份。

工作原理

┌─────────────────┐   OpenAI 兼容         ┌──────────────────────┐   HTTPS    ┌─────────────────────┐
│  dsh web        │  baseURL             │  dsh-zen-proxy       │  转发       │  OpenCode Zen       │
│  (llm-pi-ai     │ ───────────────────► │  http://127.0.0.1:   │ ─────────► │  https://opencode.  │
│   custom        │                      │  8788/v1             │            │  ai/zen/v1          │
│   provider)     │ ◄─────────────────── │                      │ ◄───────── │                     │
└─────────────────┘   SSE / JSON         │  - UA 重写            │            │  Bearer public|sk-  │
│  - 标头注入           │            │                     │
│  - 请求体规范化        │            │                     │
└──────────────────────┘            └─────────────────────┘

该代理是一个透明转发器（请求体、方法、状态码、SSE 流均原样透传）。它只添加请求标头、重写 host/path，并为严格的后端规范化 chat-completions 请求体。

自 2026-08-24 起，该代理作为 Cordis 插件运行在 dsh web 进程内部（参见进程内集成），因此最左侧的一跳是同一进程内的回环。

文件

| 文件 | 用途 |
|---|---|
| zen-proxy.mjs | 代理引擎：createZenProxyServer() + normalizeChatBody() + 独立 CLI。零依赖，Node ≥ 20。 |
| plugin.mjs | Cordis 插件入口（dsh-zen-proxy）：在 dsh web 内部以进程内方式启动代理，与 harness 生命周期绑定。 |
| package.json | npm 元数据。 |
| SPEC.md | 完整设计规范：发现、架构、需求、风险、验证计划。 |
| AGENTS.md | 代理自身开发的工作约定。 |
| CHANGELOG.md | 里程碑与版本历史。 |
| docs/ | 集成深入解析、模型 effort 参考、故障排查指南。 |
| test/ | 代理引擎和生命周期的单元测试。 |

安装

独立运行（测试 / 回退方案）

node ~/projects/dsh-zen-proxy/zen-proxy.mjs

默认值：127.0.0.1:8788。环境变量覆盖：

| 环境变量 | 默认值 | 含义 |
|---|---|---|
| ZEN_PROXY_PORT | 8788 | 监听端口 |
| ZEN_PROXY_UA | opencode/1.15.5 | 发送到上游的 User-Agent —— 必须保持 opencode/ |

进程内集成（dsh web 配置）

前置条件： 已安装 DeepSeek Harness（dsh），并在
~/.dsh/profiles/web/ 处有一个 web 配置。

1. 添加依赖

将此仓库作为 file: 依赖添加到 ~/.dsh/profiles/web/package.json：

"dependencies": {
"dsh-zen-proxy": "file:"
}

然后运行：

cd ~/.dsh/profiles/web
npm install --no-audit --no-fund

2. 添加插件行

编辑 ~/.dsh/profiles/web/cordis.patch.yml 并添加一个 insert 条目：

- insert:
- id: zen-proxy
name: 'dsh-zen-proxy'

3. 验证

dsh web --dump-config | grep zen-proxy

应显示 zen-proxy 行。然后正常启动 dsh web —— 代理
会随 harness 一起启动和停止。

4. 配置提供方

~/.dsh/settings.yaml：

llm-pi-ai:
providers:
opencode-zen:
apiKeyEnv: OPENCODE_ZEN_KEY
api: openai-completions
baseURL: http://127.0.0.1:8788/v1
reasoning: max
compat:
thinkingFormat: openai
supportsReasoningEffort: true
models:
- id: big-pickle
name: Big Pickle
contextWindow: 200000
maxTokens: 32000
reasoningEfforts:
low: low
medium: medium
high: high
max: max
- id: x-preview-f-free
name: Ox Alpha Free (Unlimited)
contextWindow: 1000000
maxTokens: 131072
input: [ text, image ]
reasoningEfforts:
low: low
high: high
max: max
- id: hy3-free
name: Hy3 Free
contextWindow: 190000
maxTokens: 64000
reasoningEfforts:
low: low
medium: medium
high: high
- id: mimo-v2.5-free
name: MiMo V2.5 Free
contextWindow: 200000
maxTokens: 32000
reasoningEfforts:
low: low
medium: medium
high: high
max: max
- id: nemotron-3-ultra-free
name: Nemotron 3 Ultra Free
contextWindow: 1000000
maxTokens: 128000
reasoningEfforts:
low: low
medium: medium
high: high
max: max
- id: nemotron-3.5-lightning-free
name: Nemotron 3.5 Lightning Free
contextWindow: 262144
maxTokens: 262144
reasoningEfforts:
low: low
medium: medium
high: high
max: max
- id: laguna-s-2.1-free
name: Laguna S 2.1 Free
contextWindow: 256000
maxTokens: 32000
reasoningEfforts:
low: low
medium: medium
high: high
max: max
- id: muse-spark-1.2-contributor-free
name: Muse Spark 1.2 Free
contextWindow: 1048576
maxTokens: 131072
reasoningEfforts:
minimal: minimal
low: low
medium: medium
high: high

将凭据存储在 ~/.dsh/.credentials.yaml 中（权限模式 0600）：

OPENCODE_ZEN_KEY: public

两个文件均支持热重载——更改时无需重启 dsh。

验证

模型列表
curl http://127.0.0.1:8788/v1/models

非流式聊天补全
curl -X POST http://127.0.0.1:8788/v1/chat/completions \
-H "Authorization: Bearer public" -H "Content-Type: application/json" \
-d '{"model":"big-pickle","messages":[{"role":"user","content":"Say hello"}],"stream":false,"max_tokens":64}'

流式聊天补全
curl -N -X POST http://127.0.0.1:8788/v1/chat/completions \
-H "Authorization: Bearer public" -H "Content-Type: application/json" \
-d '{"model":"big-pickle","messages":[{"role":"user","content":"Count from 1 to 3"}],"stream":true,"max_tokens":128}'

所有请求都应返回 200。（使用默认 curl UA 直接对 https://opencode.ai/zen/v1
运行相同的 curl 命令，即可看到代理所规避的 429。）

注意事项

- UA 标注是策略规避，而非安全绕过。 该检查较为宽松，随时可能被收紧
（参见 SPEC §6）。
- 共享配额。 匿名免费层使用受 IP 速率限制，并与本机上的 opencode CLI
会话共享：大量使用 dsh 可能消耗 opencode 自身的免费配额，反之亦然。
- 仅限免费层。 上面列出的模型是免费阵容。付费模型需要来自
console.opencode.ai 的真实 sk- 密钥。使用密钥后，限制按密钥计算，
无需使用 UA 技巧。
- 免费阵容会轮换。 上游会不时下架模型。如果某个已配置的模型开始返回
400/500，请检查 models.dev/api.json 并刷新提供商配置中的模型列表。
- 流式传输可能不稳定。 上游流式后端有时会返回
"Endpoint is unavailable"（503）。代理会原样传递错误；dsh 重试策略
会处理瞬时故障。
- 推理强度被拒绝。 如果 dsh 显示 does not support reasoning
effort "max"，说明该模型未在提供商配置中声明该级别。已验证的矩阵见
docs/model-efforts.md。

测试

node --test

运行针对请求体规范化、服务器生命周期、404 处理以及 EADDRINUSE 行为的
单元测试——无需网络访问。