Zen 免费模型源 cloudfly-xiao/dsh-zen

dsh-zen

OpenCode Zen 免费模型接入 DSH (DeepSeek Harness) —— 一个插件，自动发现免费模型，零配置可用。

DSH 插件（Cordis 架构），向 ctx.llm 注册 opencode-zen provider 路由和免费模型目录，走 OpenCode Zen 公开的 OpenAI 兼容端点，SSE 流式输出，支持 DeepSeek 风格的 reasoning_content 思考流。

模型目录

| 模型 ID | 名称 | 上下文窗口 | 最大输出 |
| deepseek-v4-flash-free | DeepSeek V4 Flash Free | 200K | 128K |
| mimo-v2.5-free | MiniMax MiMo V2.5 Free | 200K | 32K |
| nemotron-3-ultra-free | Nemotron 3 Ultra Free | 1M | 128K |
| nemotron-3.5-lightning-free | Nemotron 3.5 Lightning Free | 256K | 256K |
| hy3-free | Hy3 Free | 190K | 64K |
| laguna-s-2.1-free | Laguna S 2.1 Free | 256K | 32K |
| big-pickle | Big Pickle (Free) | 200K | 32K |

上表是插件内置的基线目录（含精确上下文参数）。实际展示的目录 = 基线 + 自动发现的新模型 − 主动探测摘除的失效模型，详见下文「自动发现」。模型均声明推理能力（reasoning effort：low / medium / high，默认 high），支持工具调用。

自动发现

插件在启动时和运行期间（每 24 小时）自动调用 OpenCode Zen 的 /v1/models 端点，发现新上线的免费模型（ID 以 -free 结尾或已知例外如 big-pickle），并将其合并到模型目录中。

- 启动时：后台非阻塞拉取，发现后立即刷新 Models 页，无需重启。
- 运行中：每 24 小时自动刷新，新模型出现即可选用。
- 合并策略：硬编码的 DEFAULT_MODELS 优先（保留精确的 contextWindow / maxTokens），远程新发现的模型追加到目录末尾，使用默认参数。
- 容错：网络异常或上游不可达时静默回退到硬编码列表，不影响现有功能。
- 用户配置覆盖：如果用户在 settings 中显式指定了 models 字段，则跳过自动发现，完全使用用户配置。

认证标识（UA）自动跟踪

免费通道的「认证信息」是 User-Agent（opencode/<版本号>）。插件内置默认版本，并在每次发现周期中从 npm registry 检测 opencode 最新版本，若已更新则自动跟进（失败时保留上次的可用值），确保上游客户端版本校验不会让免费通道失效。

失效模型自动摘除（主动探测）

上游 /v1/models 列表仍包含免费期已结束的模型，仅凭列表无法保证目录真实可用。因此每个发现周期（启动 + 每 24 小时）会对目录中每个模型发送一个极小请求（max_tokens: 1）主动探测：

- 终态判定才摘除：免费推广期结束（401 ModelError: Free promotion has ended）或地区限制（403 RegionError）→ 自动从目录移除并记日志 removed unavailable model(s)；
- 瞬态错误不误删：429 限流、5xx、网络失败一律视为 unknown，不动目录；
- 运行时兜底：对话请求中命中同样的终态错误也会即时摘除（错误映射为 QUOTA / REGION，不会当作 AUTH 重试）。

探测每个模型约消耗几个 token 的免费配额，24 小时一轮，代价可忽略。

工作原理

DSH agent ──ctx.llm──▶ llm-zen 插件 ──HTTPS+SSE──▶ https://opencode.ai/zen/v1/chat/completions

1. 免费通道凭 User-Agent 放行。网关对非 opencode 客户端返回 HTTP 429 FreeUsageLimitError（"Error from provider (Console): Rate limit exceeded"）。本插件在请求头中固定 user-agent: opencode/1.18.18（放在 attributionHeaders() 之后展开以覆盖 DSH 默认标识），实测任意 opencode 前缀 UA（大小写不敏感）均可通过，与 API key 无关。
2. 可选付费通道。配置 API key 后以 Bearer 发送，走正式配额（见下文配置）。
3. 错误映射。429/配额类错误映射为 dsh-llm 的 QUOTA 失败码，上下文超长映射为 CONTEXT_WINDOW_EXCEEDED，并透传服务端 retry-after 供重试策略退避。

⚠️ 非官方机制声明：免费通道的 UA 白名单是 opencode.ai 的防滥用策略，本插件借官方客户端身份通过。若上游收紧（强制鉴别真实客户端 / 强制 key），免费通道会失效——届时配置有效 API key 即可恢复，插件其余部分不受影响。

环境要求

| 依赖 | 版本 | 说明 |
| dsh | 0.1.0-rc.7 | 插件以 peerDependencies 对齐同版本系的 @deepseek-ai/* 包 |
| Node.js | ≥ 22 | ESM + 原生 fetch |

已在 Termux (Android aarch64, Node 22/25) + dsh 0.1.0-rc.7 上实测：provider 注册、Models 页展示、流式对话（含 reasoning delta / usage 统计 / finish 语义）全部通过。

安装

方式一：插件控制台（推荐）

在 DSH Web 的插件控制台中按 GitHub 源安装本仓库（cloudfly-xiao/dsh-zen）。

方式二：本地克隆（开发）

bash
git clone https://github.com/cloudfly-xiao/dsh-zen ~/projects/dsh/dsh-zen

~/.dsh/profiles/web/package.json 的 dependencies 增加： json "dsh-zen": "file:/home/you/projects/dsh/dsh-zen"

建立符号链接（Node 按 realpath 解析，本地开发必须）： bash ln -s ~/projects/dsh/dsh-zen ~/.dsh/profiles/web/node_modules/dsh-zen

若需直接运行 tests/smoke.mjs，克隆目录里还要有指向 DSH 扁平闭包的符号链接： bash
mkdir -p ~/projects/dsh/dsh-zen/node_modules
ln -s ~/.dsh/profiles/node_modules/@deepseek-ai ~/projects/dsh/dsh-zen/node_modules/@deepseek-ai

注册插件（两种方式通用）

在 profile 的 ~/.dsh/profiles/web/cordis.patch.yml 顶层插入： yaml
- insert:
- id: llm-zen
name: 'dsh-zen'

重启服务加载： bash
dsh web

Termux/Android 注意：dsh plugin --profile web add 在 Termux 上常卡死，用上面的手动注册即可。另请用 Termux 原生环境（HOME 指向 Termux home）启动 dsh，proot 环境里的 ~/.dsh 是另一份配置，装错位置会导致服务起不来。

装好后 Models 页出现 OpenCode Zen 分区，免费模型即选即用（启动后自动从远端发现可用模型）。

配置

零配置即可用免费通道。需要定制时，在 Models 页 llm-zen 设置区或 dsh settings 中覆盖：

| 字段 | 类型 | 默认值 | 说明 |
| baseURL | string | https://opencode.ai/zen/v1 | 网关地址，可指向自建反向代理 |
| apiKeyEnv | credential-ref | OPENCODE_API_KEY | 凭据引用名（env / dsh credentials 均可） |
| models | array | 硬编码默认列表 + 远端自动发现 | 模型目录，可增删、覆盖 name / contextWindow / maxTokens；显式设置此项将跳过自动发现 |
| defaultContextWindow | number | 200000 | 目录外模型的兜底上下文窗口 |
| maxTokens | number | 32768 | 目录外模型的兜底最大输出 |
| streamIdleTimeoutMs | number | 300000 | SSE 空闲看门狗（毫秒），超时映射为 TIMEOUT |
| retryPolicy | object | 内置策略 | 传输层重试；429 已按 retry-after 退避 |

配置示例（settings）： yaml llm-zen: baseURL: https://zen-proxy.example.com/v1 apiKeyEnv: OPENCODE_API_KEY models:
- id: deepseek-v4-flash-free
contextWindow: 200000
maxTokens: 128000

测试 bash
node tests/smoke.mjs # 默认 deepseek-v4-flash-free
node tests/smoke.mjs mimo-v2.5-free # 指定模型

冒烟脚本独立于 DSH 运行时，覆盖：默认配置解析 → listModels（7 模型）→ resolveModel（上下文/输出元数据）→ 真实流式对话（reasoning delta、text delta、usage 统计、finish 语义）。全部通过时输出 [smoke] PASS。

故障排查

| 症状 | 原因与处理 |
| QUOTA / 429 FreeUsageLimitError | 请求未带 opencode UA——确认使用本插件 ≥1.1.0（UA 覆盖在 attributionHeaders() 之后）；自建反代时确认代理没有剥离/改写 User-Agent |
| 免费通道持续限流 | 上游策略收紧或该出口 IP 被限，配置有效 OPENCODE_API_KEY 走付费通道 |
| TIMEOUT: stream idle | 网络闪断或上游拥塞，可调大 streamIdleTimeoutMs；免费模型高峰期可能长时间排队 |
| 插件未出现在 Models 页 | cordis.patch.yml 未注册（见安装）；或装进了错误环境的 ~/.dsh（Termux vs proot） |
| 新模型未自动出现 | 确认 baseURL 可达；检查 DSH 日志中 llm-zen: discovered 行；若在 settings 中显式配置了 models 字段则自动发现被禁用 |
| 某模型 QUOTA: Free promotion has ended | 该模型免费期已结束，需订阅 OpenCode Go 或配置 API key；插件会自动将其从目录摘除（日志 removed from the catalog） |
| 某模型 REGION | 地区限制，该模型在你所在地区不可用；插件同样自动摘除 |
| dsh plugin add 卡死 | Termux 已知问题，手动注册 |

常见问题

免费通道稳定吗？
面向 opencode 官方客户端的通道，共享配额、按 IP/UA 维度限流，高峰期可能慢或短暂 429（插件按 retry-after 自动退避重试）。生产用途建议配 API key。

和 dsh 自带的 deepseek-official 什么关系？
互不相干：本插件新增独立 provider 路由 opencode-zen，不改动、不依赖现有 provider。
会发送哪些标识头？
除 User-Agent 外还带 DSH 的 attribution 头与匿名用户 ID（getOrCreateAnonymousUserId），用于网关侧归因，不含个人身份数据。

开发

lib/index.js 插件与适配器（ZenAdapter extends LlmAdapter） tests/smoke.mjs 独立冒烟测试

改动后跑冒烟验证，再按方式二更新本地符号链接即可热加载调试。

License

MIT