Zen 免费模型接入 defaver04/opencodezen4dsh

opencodezen4dsh

在 DSH（DeepSeek Harness）里原生使用 OpenCode Zen 的免费匿名模型。

无需 API Key。无需注册。无需额外进程。

opencodezen4dsh 是 FishBottle7/opencode2dsh （上游 0.3.11，MIT）的维护分支，开发于 defaver04/opencodezen4dsh。
它保留上游的原生 adapter 架构，并增加三处分支自有改进——见 CHANGELOG.md （fork.2）与 CHANGELOG.md （fork.1）：

1. 所有推理模型都有 xhigh 与 max 思考档位。
reasoningEfforts() 把 models.dev 声明的档位与
FORCED_EFFORT_LEVELS = ['xhigh', 'max'] 取并集：元数据没有声明档位的模型
（big-pickle、mimo-v2.6-flash-free 等）或声明档位偏短的模型（step-5-preview-free、muse-spark--contributor-free）不再隐藏 Zen 网关实际接受的档位（reasoning_effort: max 与 reasoning.effort: xhigh 实测均返回 200）。
2. muse-spark-1.2-contributor-free 与 muse-spark-1.3-contributor-free 已解禁。* 上游 issue #56 记录的 403 RegionError 并非在所有出口 IP 都能复现；两个 id 在 POST /zen/v1/responses 实测返回 HTTP 200，因此回到模型选择器（实时目录暴露数 7 → 9）。仍被拦截的模型及复测证据： jev-1.13-free（400 ModelProtocolUnsupported，仅 SystemOne）、 exo-free 与 ling-3.0-flash-fin-free（已从 GET /v1/models 下架）。
3. 无身份工具调用不再污染会话日志（fork.2）。
免费通道的模型偶尔会用文本形的 <tool_call><parameter=…> 仿写代替原生调用， pi-ai 此时会组装出 id:""/name:"" 的工具调用——过去会被原文持久化，毒化整段历史（tool call id requires a nonempty string，会话无法打开）。
此类调用现在降级为普通文本（参数原文保留），对话继续而不污染日志。

请从构建产物安装，而不是手工打补丁：

从本仓库构建（prepack 会构建 lib/）
git clone https://github.com/defaver04/opencodezen4dsh.git && cd opencodezen4dsh/packages/plugin
pnpm install && pnpm pack
dsh plugin --profile web add ./opencodezen4dsh-dsh-plugin-<version>.tgz

或直接取最新 Release 下挂的 .tgz（release 工作流会跑 typecheck + 全量单测、打包并上传）。
安装后请重启 dsh web——Cordis 每个进程只导入一次插件模块，光刷新选择器不会加载新 bundle。

opencodezen4dsh 会向 DSH 注册一个原生的 LlmAdapter，直接流式对接 OpenCode Zen 的匿名免费通道——也就是 OpenCode 官方 CLI 无需登录即可使用的那批免费模型，它们会以 opencodezen4dsh 这个常规 provider 出现在你的 DSH 模型选择器里。

插件发出的请求与 OpenCode CLI 的流量完全同形（相同的 User-Agent、相同的关联请求头），模型目录通过三级回退链保持新鲜。不用登录任何账号，也不用自己部署任何东西。

特性

- 零凭据、零配置——匿名通道不需要任何 Key；装好、重启、开聊
- 原生 adapter，无 sidecar——一个 npm 包，没有子进程、没有二进制、没有本地端口（旧版 Go sidecar 不随包发行，见 legacy/）
- CLI 同形伪装——请求携带 OpenCode CLI 的 User-Agent 和整套会话/请求/项目关联头，按会话派生
- 思考等级可选——带推理的免费模型在 DSH 模型选择器里出现思考等级选项（模型声明档位的按声明展示，其余提供 Off/Minimal/Low/Medium/High，本分支再强制加上 xhigh/max）；Off 向上游发送 reasoning_effort: "none" 真正停思考，不选则保持上游默认
- 按声明支持图片输入——只要 models.dev 的模型条目在 modalities.input 里列了 image，图片附件就会被放行；只声明 text 的模型仍然拒绝；元数据缺省时退回已验证的视觉家族
- 实时目录 + 三级回退——上游实时列表 ∩ 元数据判定免费，断网时依次回退到磁盘缓存与已验证的静态名单
- 自愈能力——启动期快速重试、周期刷新，并落盘健康快照便于排查
- 规范的错误呈现——上游故障（限流、鉴权、超时、传输）以分类的 finish 原因送达 DSH，重试策略始终由 DSH 掌控
- 会话日志安全——免费通道模型的无身份工具调用会被降级为文本，不再毒化持久化历史（fork.2）

安装

从插件市场安装（收录后推荐）：在 DSH 里打开 设置 → 插件市场，搜索 opencodezen4dsh，一键安装。

从 GitHub Release 安装（当前推荐）：

下载最新 Release 下挂的 .tgz，然后：
dsh plugin --profile web add ./opencodezen4dsh-dsh-plugin-<version>.tgz

从源码安装（自行打包）：

git clone https://github.com/defaver04/opencodezen4dsh.git
cd opencodezen4dsh/packages/plugin
pnpm install && pnpm pack
dsh plugin --profile web add ./opencodezen4dsh-dsh-plugin-<version>.tgz

验证：重启 dsh web，打开模型选择器，在 opencodezen4dsh 分组里选模型即可。

需要 DSH（DeepSeek Harness）0.1.7 及以上、带 web profile（IP 池设置页依赖 0.1.7 的插件页契约）；Node.js ≥ 20（DSH 能跑就满足）；出站 HTTPS 需可达 opencode.ai 与 models.dev。

配置

默认配置开箱即用。需要覆盖时，编辑 profile 的 cordis.patch.yml：

- id: opencodezen4dsh
name: '@opencodezen4dsh/dsh-plugin'
config:
mode: adapter # adapter（默认）| sidecar providerId: opencodezen4dsh refreshSeconds: 300 # 目录刷新周期（秒）

| 配置项 | 默认值 | 说明 |
| mode | adapter | adapter：原生 LlmAdapter 直连 Zen。sidecar：旧版本地 agent 模式，不随包发行——请从 legacy/agent 自行构建并通过 agentPath 指定。 |
| providerId | opencodezen4dsh | 在 DSH 中显示的 provider 名称。 |
| refreshSeconds | 300 | 实时目录刷新间隔；定价元数据每 24 小时刷新。 |
| agentPath | 自动解析 | 仅 sidecar：agent 二进制路径。 |
| agentArgs | — | 仅 sidecar：传给 agent 的额外 CLI 参数。 |
| restartDelayMs / restartMaxDelayMs / maxConsecutiveCrashes | 1000 / 60000 / 5 | 仅 sidecar：重启退避与熔断阈值。 |
| firstEventMs / bodyIdleMs / responsesBodyIdleMs | 30000 / 120000 / 300000 | 仅 adapter：流存活超时，单位毫秒，取 1 到 600000 的整数。分别控制首事件等待、流中静默，以及 Responses 模型（muse-spark-）的静默下限。冷启动慢时可调大 firstEventMs。不设置则使用默认值；修改后重启 DSH。 |

工作原理

DSH 会话 │ harness chunk（block-start / text-delta / usage / finish …）
▼
ZenAdapter（注册的 LlmAdapter） │ pi-ai openai-completions 流式（chat 模型） │ pi-ai openai-responses 流式（muse-spark-，在 Zen 上仅支持 Responses） ▼ https://opencode.ai/zen/v1 ← Authorization: Bearer public 携带与 CLI 同形的请求头： user-agent: opencode/…
x-opencode-client, x-opencode-session, x-session-affinity,
X-Session-Id, x-opencode-request, x-opencode-project

- 会话关联——session/project id 由会话首条用户消息经 SHA-256 派生（同一会话稳定、不可逆推），每个请求再附带一个全新的随机 id，与 CLI 行为一致。
- 目录回退链——S1：实时 GET /v1/models；S2：models.dev 定价元数据判定 "免费"；S3：编译期验证的静态名单。上游故障时由磁盘缓存（约 7 天有效期）兜底。
- 韧性——adapter 在启动时立即注册；若首次目录拉取撞上网络尚未就绪（VPN/TUN 重连、DNS 等），会以短周期重试（约 1 分钟内），随后转入常规刷新。
- sidecar 模式（mode: sidecar，旧版）——拉起本地 Go agent（ opencode2api 的单租户移植版），监听 127.0.0.1:<随机端口>、token 鉴权，并注册标准 llm-pi-ai 路由。
不随包发行；请从 legacy/agent 构建（go build ./cmd/agent）并把 agentPath 指向产物。

健康状态与排查

插件在每轮刷新后写入健康快照：

~/.opencodezen4dsh/adapter-status.json

{
"status": "ready",
"total": 64,
"exposed": 9,
"lastError": "",
"writtenAt": "2026-08-29T07:01:54.915Z"
}

| 现象 | 可能原因与处理 |
| 启动页报 Failed to load plugins … list slot "plugins.item" requires options.id，或 IP 池条目没有配置页 | DSH 早于 0.1.7 的插件页契约。升级 DSH 到 0.1.7（推荐最新）；页面挂载门控是 configForms.whileServed，0.1.6 及更早上整页不出现，模型路由不受影响。 |
| 安装插件后 DSH 0.1.7/0.2 无法启动，报 pending … settingsScope | 更新插件到 0.3.5+；DSH 0.2 的 IP 池设置在插件页的 opencodezen4dsh 条目里。 |
| 只有 3 个模型 | 启动时网络未就绪，重试会在约 1 分钟内补齐；看 adapter-status.json 里的 lastError。 |
| lastError: "fetch failed" 持续出现 | 出站 HTTPS 到 opencode.ai 被拦截；检查代理/VPN 规则。 |
| 对话中报限流错误（429 … Endpoint is unavailable） | 匿名通道按 IP 限额，免费模型竞争大。插件的 provider 重试策略会静默扛过 429 突发（8 次重试、约 1s→20s 退避、每步最坏约 90s），不再直接抛给用户；仍被打满时可降低思考强度、换一个竞争较小的 -free 模型，或在插件设置页开启 IP 池（多出口轮换）。 |
| 思考耗尽输出预算，没有正文 | adapter 在模型支持 Off 时关闭思考重试一次。已有任何正文或工具调用则不会重试。重试保持原输出上限，仍可能失败，两次请求的用量合并统计。不支持 Off 的模型（如 Muse）需要手动调整设置或更换模型。 |
| Muse 报 REGION_BLOCKED / "This model is not available in your country" | Zen 不向当前网络地区提供该模型。adapter 保留上游解释，而不是把 403 误报为 API 密钥无效。匿名通道不需要个人密钥，可使用当前地区可用的模型。 |
| 连接 127.0.0.1: 报错 | 残留的 sidecar 路由遮蔽了 adapter；插件启动时会自动清理。 |
| 安装时报 ERR_PNPM_IGNORED_BUILDS | pi-ai 的传递依赖（@google/genai、protobufjs）带构建脚本，运行时并不需要。在插件市场里按提示选择允许/拒绝，或在 profile 的 pnpm-workspace.yaml 的 allowBuilds: 下把这两项设为 false。 |

安全性

- 不涉及任何机密：匿名通道的 Key 就是字面量 public；插件不存储任何东西，也没有任何遥测。
- 安装产物仅限 lib/；不执行任何依赖的构建脚本。
- 所有请求均从你的机器直连 opencode.ai / models.dev。

开发

git clone https://github.com/defaver04/opencodezen4dsh.git
cd opencodezen4dsh/packages/plugin
pnpm install
pnpm typecheck && pnpm test
pnpm build # 打包到 lib/

旧版 Go sidecar 在 legacy/agent（go test ./...）。架构说明与移植记录见 docs/。

发布：在 packages/plugin 执行 pnpm pack（prepack 会构建并同步文档）；推送 v tag 后，release 工作流会跑 typecheck + 全量单测、打包，并把 .tgz 挂到 GitHub Release。

致谢

- opencode2dsh，作者 @FishBottle7——本分支基于的上游项目（0.3.11，MIT）。分支自有改动列在本文件顶部与 CHANGELOG.md。
- opencode2api，作者 @jasonxu114514——legacy/agent 里的旧版 Go sidecar 是其匿名通道实现的移植版，目录回退链与请求伪装细节同样源自它。
- OpenCode——运营免费匿名 Zen 通道。
- @earendil-works/pi-ai——adapter 模式使用的线上协议层。
- DeepSeek Harness 与 dsh-market 社区。

许可证

MIT © FishBottle7（上游）与 defaver04（分支）。见 LICENSE。