Skip to content

dsh-freetap

Verified

dsh-freetap · v0.5.3 · MIT · Web UI

Free OpenCode Zen models for DeepSeek Harness (DSH): dsh-freetap is a native dsh-llm adapter plugin that needs no API key.

Install

dsh plugin add dsh-freetap

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Tags

Readme

dsh-freetap

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

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

npm license node DeepSeek Harness

English | 简体中文


dsh-freetap 会向 DSH 注册一个原生的 LlmAdapter,直接流式对接 OpenCode Zen 的匿名免费通道——也就是 OpenCode 官方 CLI 无需登录即可使用的那批免费模型,它们会以 dsh-freetap 这个常规 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 掌控

安装

从预构建的 Release 安装,无需构建步骤,也不需要工具链。

dsh plugin --profile web add https://github.com/ddldxiacan/dsh-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.tgz

就这一条,不用加任何参数,退出码 0。然后重启 DSH,在模型选择器的 dsh-freetap 分组里挑模型即可。

环境要求:DSH(DeepSeek Harness)0.1.7 及以上、带 web profile;Node.js ≥ 20(DSH 能跑就满足); 出站 HTTPS 需可达 opencode.ai 与 models.dev。

整个安装只装 7 个小包,且不执行任何依赖的构建脚本,所以在全新机器上、pnpm 默认(严格) 策略下就能直接装成功。这是本包刻意保证的性质,原因见下一节。

为什么安装不需要任何参数

更早的版本在运行时依赖完整的 @earendil-works/pi-ai 供应商矩阵,其中两个传递依赖自带安装脚本, pnpm 默认拦截,并把它升级成硬失败:

Error: ERR_PNPM_IGNORED_BUILDS
  × adding a new package
  ╰─▶ Ignored build scripts: @google/[email protected], [email protected]

更麻烦的是:pnpm 报错时已经把依赖写进 profile 的 package.json 了,而 DSH 只在 pnpm 退出码为 0 时才把包注册成 profile bundle。结果插件装上了却从不加载——模型选择器空白, 输出里也没有任何解释。

现在从源头解决,而不是让用户照着一长串说明去绕:这层线协议代码已随包的 lib/ 一起打包, 那些依赖根本不会被安装。当前发布包只依赖 yaml、undici、partial-json 和 @deepseek-ai/schemastery,它们都不执行脚本。

确认真的注册上了:profile 的 package.json 里,dsh-freetap 必须出现在 dsh.profile.bundles 下,而不只是 dependencies 里。

在可视化界面里安装(推荐给不用命令行的用户)

设置 → 插件 → 安装,把 tarball 链接粘进去:

https://github.com/ddldxiacan/dsh-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.tgz

一次就能装好,不会弹「需要允许安装脚本」——包里已经没有任何声明安装脚本的依赖。

万一你确实看到那个授权面板,说明你装的是 0.5.1 之前的旧构建:升级即可,或点「允许这些脚本并重试」。

其他安装方式

直接从 GitHub 安装(不经过 registry):

dsh plugin --profile web add github:ddldxiacan/dsh-freetap

这条路径之所以可用,是因为仓库根本身就是那个可安装的插件:它带着 dsh 清单, 而构建产物已提交在 packages/plugin/lib/ 下。git 安装无法执行构建——pnpm 会拦截 git 依赖的 prepare 脚本——所以把构建产物一并提交,才让这条路径成立。 需要稳定版本时建议锁定 tag:

dsh plugin --profile web add github:ddldxiacan/dsh-freetap#v0.5.1

从 npm 安装(已发布版本):

dsh plugin --profile web add dsh-freetap

验证:重启 dsh web,打开模型选择器,在 dsh-freetap 分组里选模型即可。

更新

按你当初安装的来源选一条,都是就地更新。

Release tarball —— 用带版本号的那个资产,不要用 latest:

# 把 0.5.1 换成你要升到的版本
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-freetap/releases/download/v0.5.1/dsh-freetap-0.5.1.tgz

不带版本号的 releases/latest/download/... 地址无法更新已安装的版本:pnpm 早已把该 URL 连同完整性哈希固定进 pnpm-lock.yaml,同一个 URL 会被判为已解析 (「Lockfile is up to date, resolution step is skipped」),加 --force、pnpm update、 pnpm install --force、删掉 node_modules 重装都绕不过去——只有每次发布都不同的 URL 才会重新解析。如果你正卡在还没有带版本资产的旧版本上,做一次性迁移(先移除再装,或者 直接用带版本的地址,后者即使在旧版本上也能生效):

dsh plugin --profile web remove dsh-freetap
dsh plugin --profile web add https://github.com/ddldxiacan/dsh-freetap/releases/latest/download/dsh-freetap.tgz

git 安装:跟随 master(git 依赖每次都会重新解析):

dsh plugin --profile web add github:ddldxiacan/dsh-freetap

npm 安装:

dsh plugin --profile web add dsh-freetap@latest

然后重启 DSH。确认新版本是否生效:比对 profile 里 node_modules/<包名>/package.json 的版本,并查看健康快照 ~/.dsh-freetap/adapter-status.json。

如果某次更新后插件装在 node_modules 里却始终不加载,那就是安装一节讲的 ERR_PNPM_IGNORED_BUILDS 那个坑:先 remove 再 add,让它重新算作新依赖, DSH 才会把它注册为 bundle。

配置

默认配置开箱即用。需要覆盖时,编辑 profile 的 cordis.patch.yml。 其中 name 必须是你实际安装的那个包名:git 安装、release tarball 与 npm 安装现在都是同一个名字 dsh-freetap。

- id: dsh-freetap
  name: dsh-freetap
  config:
    mode: adapter        # adapter(默认)| sidecar
    providerId: dsh-freetap
    refreshSeconds: 300  # 目录刷新周期(秒)
配置项 默认值 说明
mode adapter adapter:原生 LlmAdapter 直连 Zen。sidecar:旧版本地 agent 模式,不随包发行——请从 legacy/agent 自行构建并通过 agentPath 指定。
providerId dsh-freetap 在 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,插件 0.3.7 起支持:流存活超时,单位毫秒,取 1 到 600000 的整数。分别控制首事件等待、流中静默,以及 Responses 模型(muse-spark-*)的静默下限。冷启动慢时可调大 firstEventMs。不设置则使用默认值;修改后重启 DSH。

工作原理

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 指向产物。

健康状态与排查

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

~/.dsh-freetap/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 服务。
启动页报 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 池设置在插件页的 dsh-freetap 条目里。
只有 3 个模型 启动时网络未就绪,重试会在约 1 分钟内补齐;看 adapter-status.json 里的 lastError。
lastError: "fetch failed" 持续出现 出站 HTTPS 到 opencode.ai 被拦截;检查代理/VPN 规则。
对话中报限流错误(429 … Endpoint is unavailable) 匿名通道按 IP 限额,免费模型竞争大。#51 修复后,插件的 provider 重试策略会静默扛过 429 突发(8 次重试、约 1s→20s 退避、每步最坏约 90s),不再直接抛给用户;仍被打满时可降低思考强度、换一个竞争较小的 -free 模型,或在插件设置页开启 IP 池(多出口轮换)。
思考耗尽输出预算,没有正文 插件 0.3.6 会在模型支持 Off 时关闭思考重试一次。已有任何正文或工具调用则不会重试。重试保持原输出上限,仍可能失败,两次请求的用量合并统计。不支持 Off 的模型(如 Muse)需要手动调整设置或更换模型。
Muse 报 REGION_BLOCKED / "This model is not available in your country" Zen 不向当前网络地区提供该模型。插件 0.3.5 保留上游解释;旧版会把这个 403 误报为 API 密钥无效。匿名通道不需要个人密钥,可使用当前地区可用的模型。
连接 127.0.0.1:* 报错 残留的 sidecar 路由遮蔽了 adapter;插件 ≥ 0.2.1 启动时会自动清理。
安装时报 ERR_PNPM_IGNORED_BUILDS 你装的是 0.5.1 之前的旧构建,它依赖的 pi-ai 会带入 @google/genai 与 protobufjs(两者都有安装脚本)。升级到 0.5.1+ 即可——新版已把这层打包进来,只依赖无脚本的包。若必须留在旧版,加 --config.strict-dep-builds=false。

安全性

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

开发

git clone https://github.com/ddldxiacan/dsh-freetap.git
cd dsh-freetap/packages/plugin
pnpm install
pnpm typecheck && pnpm test
pnpm build                    # 打包到 lib/

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

发布:在 packages/plugin 执行 pnpm pack(prepack 会构建并同步文档)。

致谢

  • opencode2dsh,作者 @FishBottle7——本项目的上游,也是改名前的名字。 它的整体架构、目录回退链与请求伪装实现是这个分支的基础;上文引用的 issue 编号 均指该仓库。
  • opencode2api,作者 @jasonxu114514——legacy/agent 里的旧版 Go sidecar 是其匿名通道实现的移植版,目录回退链与请求伪装细节同样源自它。 本项目能成立,全靠它踩过的路。
  • OpenCode——运营免费匿名 Zen 通道。
  • @earendil-works/pi-ai——adapter 模式使用的线上协议层。
  • DeepSeek Harness 与 dsh-market 社区。

友链

LinuxDo —— 新的理想型社区

许可证

MIT © 2026 ddldxiacan,基于 opencode2dsh © FishBottle7