@opencode2dsh/dsh-plugin

dsh plugin --profile web add @opencode2dsh/dsh-plugin

<div align="center">

opencode2dsh

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

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





[English](README.md) | 简体中文

</div>

---

opencode2dsh 会向 DSH 注册一个原生的 LlmAdapter，直接流式对接

OpenCode Zen 的匿名免费通道——也就是

OpenCode 官方 CLI 无需登录即可使用的那批免费模型，它们会以 opencode2dsh

这个常规 provider 出现在你的 DSH 模型选择器里。

插件发出的请求与 OpenCode CLI 的流量完全同形（相同的 User-Agent、相同的

关联请求头），模型目录通过三级回退链保持新鲜。不用登录任何账号，也不用

自己部署任何东西。

特性

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

安装

从插件市场安装（推荐，收录后可用）：在 DSH 里打开 设置 → 插件市场，

搜索 opencode2dsh，一键安装。

从 npm 安装：

dsh plugin --profile web add @opencode2dsh/dsh-plugin

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

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

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

需要 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: opencode2dsh
  name: '@opencode2dsh/dsh-plugin'
  config:
    mode: adapter        # adapter（默认）| sidecar
    providerId: opencode2dsh
    refreshSeconds: 300  # 目录刷新周期（秒）

配置项 · 默认值 · 说明

mode · adapter · adapter：原生 LlmAdapter 直连 Zen。sidecar：旧版本地 agent 模式，不随包发行——请从 legacy/agent 自行构建并通过 agentPath 指定。

providerId · opencode2dsh · 在 DSH 中显示的 provider 名称。

refreshSeconds · 300 · 实时目录刷新间隔；定价元数据每 24 小时刷新。

allowedModels · [] · 模型白名单，仅 adapter 模式生效（旧 sidecar 忽略；插件 0.3.14 起，issue #83）：DSH 可展示和调用的模型 id，精确匹配。留空则暴露全部符合条件的免费模型。只做收敛——付费/弃用/本地阻止/探活规则仍然生效，直调名单外模型会在发起任何网络请求前快速失败并给出明确错误。

agentPath · 自动解析 · 仅 sidecar：agent 二进制路径。

agentArgs · — · 仅 sidecar：传给 agent 的额外 CLI 参数。

restartDelayMs / restartMaxDelayMs / maxConsecutiveCrashes · 1000 / 60000 / 5 · 仅 sidecar：重启退避与熔断阈值。

firstEventMs / bodyIdleMs / responsesBodyIdleMs · 30000 / 120000 / 300000 · 仅 adapter，插件 0.3.7 起支持：流存活超时，单位毫秒，取 1 到 600000 的整数。分别控制首事件等待、流中静默，以及 Responses 模型（muse-spark-*）的静默下限。冷启动慢时可调大 firstEventMs。不设置则使用默认值；修改后重启 DSH。

本地 OpenCode 委托（插件 0.3.x，[docs/delegation.md](docs/delegation.md)，ref #76）——针对持续 403 FreeTierError 凭据门禁的可选兜底。默认关闭；除非显式开启，匿名路径与现状逐字节一致：

    delegation:
      enabled: true        # 总开关，默认 false
      # opencodePath: ''   # 显式指定 opencode 二进制；否则 managed → 全局 → npm
      # minVersion: '1.18.0'  # 低于此版本的候选直接跳过
      # memLimit: '96MiB'  # 注入子进程的 GOMEMLIMIT
      # gcPercent: 30      # 注入子进程的 GOGC
      # trimIntervalMs: 60000  # Windows EmptyWorkingSet 节拍；0 关闭
      # startTimeoutMs: 60000  # 健康等待预算

开启后插件会保管你的 opencode 凭据（只取 opencode 一个条目，0600 种进隔离 XDG 根，绝不写日志），并仅在匿名车道与姊妹主机重试都被凭据门禁拒绝时，才把回合交给受管的本地 opencode serve。开启前请先读 [docs/delegation.md](docs/delegation.md) §2 的安全说明。

工作原理

DSH 会话
   │  harness chunk（block-start / text-delta / usage / finish …）
   ▼
ZenAdapter（注册的 LlmAdapter）
   │  pi-ai openai-completions 流式
   ▼
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 指向产物。

健康状态与排查

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

~/.opencode2dsh/adapter-status.json

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

现象 · 可能原因与处理

403 FreeTierError / "OpenCode's free tier can only be used from within OpenCode" · 上游限制免费通道的客户端，插件会保留该说明；这不是个人 API 密钥错误。请使用上游支持的 OpenCode 客户端或正式 API 服务。若拒绝是持续的（直连 + 姊妹主机都 403，而请求形状/IP 都干净），issue #76 的可选[本地委托](docs/delegation.md)会让回合改走你自己的 opencode 登录——读完安全说明后再开启 delegation.enabled。

启动页报 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 池设置在插件页的 opencode2dsh 条目里。

只有 3 个模型 · 启动时网络未就绪，重试会在约 1 分钟内补齐；看 `a

…(truncated)