dsh-opencode-xdbridge

DSH OpenCode XD Bridge

在 DeepSeek Harness 里使用 OpenCode Zen 的免费模型。

这是什么

把 OpenCode 的免费模型（big-pickle、LongCat、MiMo、Nemotron、Space Bunny 等）接进 DSH 的模型选择器，作为 opencode-xdbridge 分组使用，并在设置 → OpenCode-XD 里提供一个可视化的交互入口。

为什么必须这么做

OpenCode Zen 的免费模型有一个服务端门禁：

FreeTierError: OpenCode's free tier can only be used from within OpenCode

实测（2026-09-29）确认：

• 直连不行：https://opencode.ai/zen/v1/chat/completions 直接请求返回 403。
• 改 User-Agent 不行：试过 opencode、opencode/1.18.33、Bun/1.2.0 等 9 种写法，全部 403。判据不是 UA。
• 必须跑真正的 OpenCode 进程：本机启动真实 opencode serve 后，同一批免费模型立刻可用。
• 权限策略是关键：agent 的 permission 必须是 {'*':'ask'}；改成 {'*':'deny'} 或 tools: {'*':false} 会立刻变回 403。

所以本插件不自造协议技巧，而是：下载官方 OpenCode 二进制 → 在隔离环境里跑起来 → 在本地转成 OpenAI 兼容端点 → 注册给 DSH。

权限必须是 ask 意味着"每个本地操作都要审批"。插件在本地把所有审批请求全部拒绝，所以运行时看起来像正常 OpenCode 会话（门禁放行），但本地一个动作都不会执行。真正执行的是 DSH。

安装

从 npm（推荐，最省事）：

dsh plugin --profile <profile> add dsh-opencode-xdbridge

从 GitHub 源码：

dsh plugin --profile <profile> add github:XDTrees/dsh-opencode-xdbridge

或者手动链接（开发用）：

# 1. 链接插件到 profile
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-opencode-xdbridge" `
  -Target "D:\DSH\dsh-opencode-xdbridge"

# 2. 在 profile package.json 的 dsh.profile.bundles 里追加 "dsh-opencode-xdbridge"

# 3. 重启 DSH Desktop

首次启动会下载约 57 MB 的官方 OpenCode 运行时（只下载一次，缓存在数据目录）。

关于这次下载

下载的是 OpenCode 官方二进制（opencode-windows-x64 这个 npm 包，57.4 MB）。它必须存在，因为免费模型的门禁只认真实 OpenCode 进程发出的请求——插件自身只有 71 KB，不含模型代码。

下载被设计成不会失败，只会慢：

• 断点续传：已下载的部分会保留，中断后重启从断点继续，而不是从头再来。
• 30 分钟总预算：不再有单次请求的 5 分钟硬超时。
• 多源：优先 npm 官方 registry，取不到或太慢时自动改用本仓库 GitHub Release 上的同名包。
• 完整性校验：下载后比对 npm registry 发布的 sha512，不一致就丢弃重来——所以任何来源（包括镜像）都不可能让不同的代码被执行。

如果确实很慢，可以自己下载一次并指给它，插件会直接复制而不联网：

# 方式一：把已装好的 opencode 指给它
set OPENCODE_BINARY_PATH=C:\path\to\opencode.exe

# 方式二：指定一个下载源
set OPENCODE_XDBRIDGE_RUNTIME_URL=https://your-mirror/opencode-windows-x64-1.18.33.tgz

使用

重启后：

1. 模型选择器里会出现 OpenCode 免费模型 分组（provider 为 opencode-xdbridge），直接选即可。
2. 设置 → OpenCode-XD 是插件的交互面板（布局参考 OW Bridge 控制面板）。

可用的模型随上游变化，插件每次启动都会重新读取。

交互面板

设置页里这张卡片就是插件的控制台：

排序规则与 OW Bridge 一致：可用模型在前、待检测居中、不可用置底。

推荐用途是怎么来的

上游 OpenCode 的模型目录只提供 family、release_date、上下文与输出上限、图片与推理能力、推理档位——没有「推荐用途」字段。所以这一行是本插件按实测能力整理的，不是抄来的宣传语：

• 每条说明都基于该模型真实上报的上下文窗口、输出上限、图片输入、推理档位；
• 目录里没收录的新模型会自动退回按能力生成的一句话（例如「100 万上下文 · 图片输入 · 支持推理」），不会留空。

要改文案，编辑 src/client/index.js 里的 USE_NOTES，然后 npm run build。

图标

导航行与页面标题使用同一个内联 SVG 标记（菱形 + 桥拱，呼应 OpenCode 与本插件的「桥」定位）。DSH 的 settings.section 契约不带图标字段，外壳对不认识的 id 一律画齿轮，所以导航图标是用 CSS mask 覆盖上去的（社区页面的通行做法）。

几个设计取舍：

• 检测是串行的。并行探测会争抢同一份上游免费额度，让每次测量都更慢也更不可信。
• 检测会真的发请求，所以消耗少量免费额度；只回文本、不产生动作的模型会按「可用 · 仅对话」发布，而不是判为失败。
• 读取模型与检测是两件事。「读取」只问上游有哪些模型，是启动读取失败后的恢复路径；「检测」才验证模型是否真的能干活。
• 重启只换 OpenCode 进程，provider 与本地端点保持不变，所以不会出现重复注册。
• 面板每 5 秒轮询一次状态，关掉设置页即停止。

失败是怎么区分的

一次检测失败并不等于「模型不能用」，所以失败被分成两类：

这个区分很重要：超时说不了模型本身的任何事，因为一次慢就把它从选择器里拿掉，等于把能用的模型也一起收走了。

每个模型每次检测最多尝试 2 次，每次独立计时（90 秒）——早期版本让两次尝试共用一个 60 秒预算，慢模型的重试还没跑就被掐断，于是把「只回文本」这种有效结论误报成超时。实测把预算分开之后，可用模型从 4 个恢复到 6 个。

检测失败不会让模型变成不可再检测：失败记录只影响它是否出现在选择器里，模型始终留在目录中，下一次「检测全部」会重新试。

上下文长度与自动压缩

插件不会把模型的原始窗口直接报给 DSH，而是报一个可用预算：

可用 = (声明窗口 − 输出预留) × (1 − 15% 安全余量)

这么做的原因是一个实测过的故障：某个会话长到 约 144 万 token，而免费模型的窗口在 20 万～105 万之间。DSH 看到"窗口还够"就没有压缩，把请求发了出去，上游回了一句完全不含原因的 invalid_request_error: invalid request。用户看到的现象是"换哪个模型、选哪个档位都报错"，真实原因只是上下文超出了每一个模型的容量。

所以现在：

• 报小窗口 → DSH 的压缩机制会提前触发，自动总结历史，请求不会长到无法成功；
• 超限时直接说清楚 → 返回「对话上下文超出该模型的容量：约 144 万 token，Big Pickle 上限约 20 万 token。请新建会话，或让上下文压缩后重试」，而不是把上游那句含糊的话透传出去。

设置页的模型详情里会同时显示：可用上下文 / 声明的原始窗口。

中文的 token 估算按每字符 ≈ 1 token 计算，而不是"字节数 ÷ 4"。中文在 UTF-8 里占 3 字节/字，用字节估算会严重低估——这正是早期误判的原因之一。

配置

配置写在 profile 的 settings.yaml 里，命名空间 opencode-xdbridge：

opencode-xdbridge:
  dataDir: D:\DSH-data\opencode-xdbridge   # 运行时/日志存放位置
  binaryPath: C:\path\to\opencode.exe     # 用已有的 OpenCode，不下载
  runtimeVersion: 1.18.33                 # 固定版本
  autoRefresh: true                       # 启动后重新读一次模型清单

也可用环境变量 OPENCODE_XDBRIDGE_DATA_DIR 指定数据目录。

架构

DSH Harness
   │  (pi-ai provider "opencode-xdbridge")
   ▼
lib/adapter.js ──── pi-ai createProvider + openAICompletionsApi
   │
   ▼
lib/shim.js ─────── 127.0.0.1 随机端口，进程内随机密钥
   │                （OpenAI /v1/chat/completions ↔ JSON 信封）
   ▼
lib/backend.js ──── 会话管理、权限拦截、信封校验
   │
   ▼
lib/runtime.js ──── 隔离的 opencode serve（独立 XDG 根 + 随机密码）
   │
   ▼
OpenCode Zen 免费模型

发布与收录

对外发布涉及三条各自独立、各自会失败的通道：

发新版本的逐步操作见 release/checklist.md。

商店收录只是发现渠道。提了 PR 不等于会显示，但不影响安装—— dsh plugin add dsh-opencode-xdbridge 与 dsh plugin add github:XDTrees/dsh-opencode-xdbridge 都是现在就能用的。

安全设计

• 隔离运行时：独立的 XDG 根目录、随机服务密码、关闭自动更新/分享/项目配置；只转发常规系统与网络环境变量，不读取也不写入你自己 OpenCode 的配置、凭据和会话。
• 本地动作零执行：运行时被配置为"每个操作都要审批"，而插件把所有审批一律拒绝。模型若试图本地执行，插件会尽量把该动作转交给 DSH 作为外部工具调用，否则明确拒绝并告知模型原因。
• 回环端点加固：只监听 127.0.0.1 随机端口；校验 Host/Origin 必须是回环（防 DNS rebinding 与浏览器页面访问）；Bearer 常量时间比较；请求体上限 8 MB。
• 信封先校验后执行：模型返回的 JSON 信封必须先通过校验才能变成工具调用，工具名与参数都必须在本轮允许的列表和 schema 之内。
• 只暴露免费模型：只有当运行时报告的每一个计费维度都为 0 时，模型才会被列出。不可能悄悄花掉你的额度。

开发

npm run build        # 把 src/client/index.js 包成 lib/client.js
npm test             # 单元测试 + 四个独立校验（bundle / 渲染 / 声明 / 代理默认值），无需网络
npm run test:smoke   # apply() 注册 + 真实 PiAiAdapter + 检测流程
npm run test:e2e     # 端到端（需 OPENCODE_XDBRIDGE_E2E=1）

单独跑：

node test/client-bundle.test.mjs        # 模拟宿主加载器，验证卡片注册与渲染
node test/client-declaration.test.mjs   # 用宿主自己的代码校验 dsh.client 声明
node test/proxy-default-check.mjs       # 静态断言：代理变量没被写回 FORWARDED_ENV
node test/proxy-live.mjs                # 真实跑一次请求，验证运行时能到上游
node test/apply-smoke.mjs               # 用桩 ctx 验证 apply() 注册与全部路由
node test/harness-smoke.mjs             # 通过真实 PiAiAdapter 走一次 stream()
node test/probe-smoke.mjs               # 真实跑一次模型检测
node test/profile-load-check.mjs        # 用 DSH 自己的 loader 校验 profile

改了 src/client/index.js 必须重新 npm run build，否则 DSH 拿到的是旧的 lib/client.js。

集成测试会真实下载/使用官方 OpenCode 二进制并产生真实上游请求，因此默认关闭，需要 OPENCODE_XDBRIDGE_E2E=1 显式开启。

已知限制

• 依赖 OpenCode Zen 的免费额度：模型清单与可用性由上游决定，随时可能变化。
• 首次启动要下载：约 60 MB，之后复用缓存。
• 依赖 OpenCode 客户端接口（不是官方开放 API），OpenCode 更新后插件可能需要跟着调整。
• 免费额度被上游限流时，请求会失败并报出上游原始错误。
• 商店收录待维护者合并：收录条目已提交（PR #6129），但插件商店需要对方点合并才会显示。这只影响「别人能不能搜到」，不影响安装——dsh plugin add dsh-opencode-xdbridge 现在就能用。详见 list/。
• 界面显示名与包名不同：包名必须全小写（dsh-opencode-xdbridge，npm 规范），设置页显示为 OpenCode-XD / OpenCode-XDbridge。

致谢

• OpenCode —— 本插件运行并复用其官方二进制与本地服务接口。
• louchi1984-coder/ow-bridge —— 验证了"隔离 OpenCode + 本地 OpenAI 兼容端点 + 审批拦截"这一整体思路的可行性，其控制面板也是本插件设置页布局与交互逻辑的参考。本项目为独立实现，未复制其代码。

许可证

MIT