OpenCode 模型接入 A42Null/dsh-opencode-zen-plugin

@a42null/dsh-opencode-zen-plugin

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

- GitHub：<https://github.com/A42Null/dsh-opencode-zen-plugin>
- CNB 制品库：<https://cnb.cool/A42Null/dsh-opencode-zen-plugin>
- npm 包名：@a42null/dsh-opencode-zen-plugin（已发布到 npmjs；安装方式见下文）

只需在「设置 → 插件」粘贴 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://git@github.com/…" 或 'git' 不是内部或外部命令——此时请改用方式一/方式二，或先安装 Git for Windows。

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

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

可选：CNB 镜像源

同一个包也发布在 CNB 制品库 <https://cnb.cool/A42Null/dsh-opencode-zen-plugin>。包名带作用域，因此要把该作用域指向 CNB（不要去改默认源，否则会影响其他包）：

npm config set @a42null: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

两种镜像都只改 @a42null/ 的去向，其他包仍走你的默认源；想撤销用 npm config delete @a42null:registry。

通用

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: 源码安装需要它 → 改用方式一（npmjs）或方式二（预构建 tarball），或先安装 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 专用端点，不支持对话，已从目录排除 |
| 升级到带作用域包名后「配置」入口消失 / API Key 读不到 | profile 覆盖补丁 ~/.dsh/profiles/desktop/cordis.patch.yml 里的 name 仍是旧名 → 改为 @a42null/dsh-opencode-zen-plugin 后重启 DSH（API Key 会保留） |
| 启动失败：client-modules: duplicate factory registration / 1 entry did not activate | 0.3.5 的客户端模块 id 与包名不一致（改名遗留）→ 升级到 0.3.6 及以上；应急恢复可用启动失败对话框里的「禁用第三方插件、备份 profile patch 并重启」 |
| 卸载/更新报 ERR_PNPM_TARBALL_URL_MISMATCH | 锁文件记录的 tarball 源与当前生效源不一致 → 固定该作用域的源：npm config set @a42null:registry https://registry.npmjs.org |

发布（维护者）

推送与 package.json 中 version 一致的标签，即自动发布到 npmjs、CNB 制品库与 GitHub Packages（工作流 .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 访问令牌（生成时需勾选「制品库」权限） |
| GH_TOKEN | 否（推荐） | GitHub 经典令牌/PAT（勾选 write:packages），用于发布到 GitHub Packages；未配置时回落到内置 GITHUB_TOKEN（此时仓库的 Actions 工作流权限需为读写） |

npmjs 不需要任何密钥（走 OIDC 可信发布；若 OIDC 失败，任务会打印配置检查清单并失败）。三个注册表各自独立且幂等：任一失败不影响其余两个。CNB 的 npm 用户名固定为 cnb（如需不同可改工作流的 CNB_USERNAME）。标签版本与 package.json 不一致时任务会直接失败，避免发错版本。

文档

- OpenCode Console 模型与端点：https://opencode.ai/v2/docs/console/models
- OpenCode Console（付费网关）：https://opencode.ai/console