Skip to content
dsh marketplace

dsh-opencode-zen-plugin

Verified

@a42null/dsh-opencode-zen-plugin · v0.3.6 · MIT · Web UI

OpenCode Console (Zen) models for DeepSeek Harness (DSH): fill in your Console API key under Settings → Plugins and the Console's chat models become selectable.

Install

dsh plugin add @a42null/dsh-opencode-zen-plugin

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

Source

Tags

Creators

Readme

@a42null/dsh-opencode-zen-plugin

English | 简体中文

DeepSeek Harness 插件：自动适配 OpenCode Console (Zen) 模型目录。

只需在「设置 → 插件」粘贴 OpenCode Console 的 API Key，即可在 DSH 中选用 Console 提供的对话模型 —— 模型列表、上下文窗口、端点路由、推理参数自动完成。

它不做的事：不能让 *-free 免费模型可用（只能在 OpenCode 客户端内运行）；会跳过 jev-* SystemOne 模型（不支持对话）；付费模型仍需 Console 账户有余额。

功能特性

  • 零配置模型目录：启动时及定时（默认 300 秒）拉取 https://opencode.ai/zen/v1/models（该接口无需鉴权），自动出现在 DSH 模型选择器中
  • 四协议自动路由（依官方文档端点表）：
    • gpt-* / grok-* / muse-spark* → OpenAI Responses API（/zen/v1/responses）
    • claude-* 及 qwen3.8-flash / qwen3.7-max / qwen3.7-plus / qwen3.6-plus / qwen3.5-plus → Anthropic Messages（/zen/v1/messages）
    • gemini-* → Google GenerateContent（/zen/v1/models/<id>:streamGenerateContent?alt=sse）
    • deepseek / glm / minimax / kimi / qwen3.8-max / big-pickle / *-free → OpenAI 兼容（/zen/v1/chat/completions）
  • 元数据自动同步：上下文窗口、输出预算、推理档位优先取 models.dev（7 天磁盘缓存 ~/.opencode-zen/models.dev.json），离线时回退插件内置静态目录，永远可用
  • 免费模型默认隐藏：*-free 属于 OpenCode 客户端内部的免费层，经 Console API 调用会返回 403 FreeTierError（"free tier can only be used from within OpenCode"），因此默认不列入模型列表；需要时可在设置中开启
  • 账务/权限错误可读：余额不足（402）、模型无访问权限（403 Model access is disabled）、免费层受限（403 FreeTierError）各自映射为独立错误码并附带处理建议，不再笼统显示为"密钥无效"
  • 推理参数透传：off / minimal / low / medium / high / xhigh / max 阶梯，自动映射各协议原生字段（reasoning_effort、thinking.budget_tokens、thinkingConfig.thinkingBudget、reasoning.effort）
  • 完整 Harness 流协议：文本 / 推理 / 工具调用分块流式输出、usage 计费、停止原因映射与错误分类（AUTH、QUOTA、FREE_TIER_BLOCKED、MODEL_ACCESS_DISABLED、RATE_LIMIT、INVALID_REQUEST、SERVER、TIMEOUT、TRANSPORT、CONTEXT_WINDOW_EXCEEDED、EMPTY_RESPONSE）
  • 工具调用与图片输入：vision 模型（claude- / gemini- / deepseek-v4-flash-vision 等）支持图片附件
  • 流看门狗：120 秒首包 / 300 秒空闲超时自动中止，避免挂死
  • 界面语言跟随 DSH：设置卡片按当前界面语言显示简体中文或 English

安装

方式一推荐：零配置，既不需要 git，也不需要改任何 registry。 只有方式三（GitHub 源码）需要本机已安装 git。

方式一：从 npmjs 安装（推荐）

dsh plugin add @a42null/dsh-opencode-zen-plugin

包页面：https://www.npmjs.com/package/@a42null/dsh-opencode-zen-plugin

方式二：预构建 tarball（无需 git）

在 DSH「设置 → 插件 → 添加插件」里粘贴，或命令行执行：

dsh plugin add https://github.com/A42Null/dsh-opencode-zen-plugin/releases/latest/download/dsh-opencode-zen-plugin.tgz

该地址始终指向最新版本（Release 资产名不含版本号，因此不会随发版失效）。

方式三：GitHub 源码（⚠️ 需要本机已安装 git 且在 PATH 中）

dsh plugin add github:A42Null/dsh-opencode-zen-plugin

pnpm 会调用 git ls-remote 解析该仓库。若机器没装 git，会报 Command failed: git ls-remote "git+ssh://[email protected]/…" 或 'git' 不是内部或外部命令—— 此时请改用方式一/方式二，或先安装 Git for Windows。

方式四：本地目录（开发调试用）

dsh plugin add D:\DSH\插件开发\opencode-zen-dsh-plugin，或通过插件管理器安装本地包目录。

可选：CNB 镜像源

同一个包也发布在 CNB 制品库 https://cnb.cool/A42Null/dsh-opencode-zen-plugin。需要改用它时：

npm config set registry https://npm.cnb.cool/A42Null/dsh-opencode-zen-plugin/-/packages/
dsh plugin add @a42null/dsh-opencode-zen-plugin

可选：GitHub Packages（同一包名，读取需令牌）

同一个包也发布到 GitHub Packages。

GitHub 的 npm 注册表读取包也需要令牌（即使包是公开的），因此它更适合作为镜像/归档，而不是首选安装方式：

npm config set @a42null:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken <GitHub 经典令牌，勾选 read:packages>
dsh plugin add @a42null/dsh-opencode-zen-plugin

注意这会把默认 registry 指向 CNB，用完请改回（例如 npm config set registry https://registry.npmmirror.com）。

通用

  1. 安装后重启 DSH（或重载插件），插件自动注册 provider opencode-zen（可经 cordis.patch.yml 的 providerId 覆盖）

插件包内含 dsh.bundle.patch（cordis.patch.yml），安装时自动向 profile 补丁写入注册行；同时通过 dsh.client 提供 Web 设置卡片。

配置（设置 → 插件 → OpenCode Zen → 配置）

DSH 的设置界面由插件的客户端半部（lib/client.js）贡献：本插件注册到 plugins.row.config 插槽（key = <包名>#<行 id>），因此在「设置 → 插件」里 opencode-zen 一行会出现「配置」入口。仅安装 host 半部（lib/index.js）时模型可用，但不会有任何设置界面。

字段 说明 默认值
apiKey OpenCode Console API Key，必填。在 https://opencode.ai/console 登录后获取 空
baseUrl OpenCode Zen 网关地址 https://opencode.ai/zen
includeFreeModels 是否包含免费（*-free）模型；默认关闭，因为它们只能在 OpenCode 客户端内使用 false
refreshSeconds 模型目录自动刷新间隔（秒，30–86400） 300

保存后立即生效，无需重启 DSH。作为兜底，也可用环境变量 OPENCODE_ZEN_API_KEY 提供 Key（配置项优先）。

鉴权

所有端点使用 Authorization: Bearer <apiKey>；Anthropic 端点同时附加 x-api-key 与 anthropic-version: 2023-06-01，Google 端点同时附加 x-goog-api-key。模型列表接口无需鉴权，未填 Key 时也能看到模型，但实际调用会返回 AUTH 错误提示。

运行状态与缓存

路径 内容
~/.opencode-zen/adapter-status.json 目录健康快照：status / total / updatedAt / lastError
~/.opencode-zen/models.dev.json models.dev 元数据缓存（7 天有效，tmp+rename 原子写入）
~/.opencode-zen/plugin-load.json 最近一次插件加载标记（build / loadedAt / pid），用于确认运行中的是哪一版代码
~/.opencode-zen/errors.log 适配器失败原始记录：时间、HTTP 状态、协议、模型、错误码、响应体片段（上限 128 KB，超出自动清空）

错误码命名对齐 DSH 规范：余额不足用 QUOTA（命中客户端"当前请求的额度已用尽"文案与全局欠费提示），密钥问题用 AUTH，免费层门禁用 FREE_TIER_BLOCKED，模型无权限用 MODEL_ACCESS_DISABLED（后两者在界面直接展示插件给出的中文说明）。

故障排查

现象 处理
安装失败：git ls-remote / 'git' 不是内部或外部命令 该机器没装 git，而 github: 源码安装需要它 → 改用方式一（预构建 tarball）或方式二（CNB 制品库），或先安装 Git for Windows
AUTH 错误 未填 API Key 或 Key 无效 → 在「设置 → 插件 → OpenCode Zen → 配置」粘贴；模型列表无需鉴权，故 Key 缺失时仍能看到模型
FREE_TIER_BLOCKED（403 FreeTierError） 选了 *-free 免费模型。免费层只能在 OpenCode 客户端内使用 → 关闭"包含免费模型"或改用付费模型
QUOTA（402 Insufficient account funds） Key 有效但 Console 账户余额不足 → 到 https://opencode.ai/console 充值
MODEL_ACCESS_DISABLED（403 Model access is disabled） 该 Console 账号没有此模型的访问权限 → 换一个模型
RATE_LIMIT（429） 调用频率超限 → 稍后重试
设置里找不到 opencode-zen 客户端半部未被加载（旧版安装/未重启）→ 确认 lib/client.js 存在、package.json 含 dsh.client 与 "./client" 导出，然后重启 DSH 并刷新页面
SERVER / TRANSPORT / TIMEOUT 网关或网络异常 → 稍后重试；查看 adapter-status.json 的 lastError
CONTEXT_WINDOW_EXCEEDED 输入超出模型上下文窗口 → 缩短会话或换更大窗口的模型
模型列表为空或陈旧 live 列表失败时自动回退内置静态目录；检查 adapter-status.json
jev-* 报 INVALID_REQUEST 该系列走 SystemOne 专用端点，不支持对话，已从目录排除

发布（维护者）

推送与 package.json 中 version 一致的标签，即自动发布到 npmjs 与 CNB 制品库（工作流 .github/workflows/publish.yml）：

npm version patch --no-git-tag-version   # 或手动修改 package.json 的 version
git commit -am "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main --follow-tags

两个注册表都是幂等的：目标上已存在同版本即跳过，因此重复推送标签不会失败；任务末尾还会校验 npmjs 上确实存在该版本。

npmjs 认证：Trusted Publishing（推荐，无需长期令牌）

在 https://www.npmjs.com/package/@a42null/dsh-opencode-zen-plugin → Settings → Trusted Publisher 填写：

字段 值
Publisher GitHub Actions
Organization A42Null
Repository dsh-opencode-zen-plugin
Workflow name publish.yml
Environment cnb（与工作流里的 environment: 一致；留空表示不限环境）

配好后 CI 通过 OIDC 直接换取发布凭证，不需要任何 token（工作流已声明 permissions: id-token: write）。这也是 npm 官方指定的迁移方向——它计划在 2027 年 1 月移除「bypass-2FA token 直接发布」。

Environment secrets（在 GitHub 网页配置，仓库内不保存任何令牌）

Settings → Environments → cnb → Environment secrets：

Secret 名 必填 说明
CNB_TOKEN 是 CNB 访问令牌（生成时需勾选「制品库」权限）

npmjs 不需要任何密钥（走 OIDC 可信发布；若 OIDC 失败，任务会打印配置检查清单并失败）。CNB 的 npm 用户名固定为 cnb（如需不同可改工作流的 CNB_USERNAME）。标签版本与 package.json 不一致时任务会直接失败，避免发错版本。

文档