前言¶
DeepSeek Harness（DSH）把模型接入做成插件化扩展：选 provider、配 profile，再在模型列表里切换。若你想用 OpenCode Zen 文档里列出的免费模型，常见做法是单独装 OpenCode CLI、起服务或再套一层代理。对只想在 Harness 里跑 agent、不想多维护一套运行时的人来说，这条路径偏重。
下面介绍社区插件 dsh-opencode-free（维护者 x5427876）：在 DSH 内通过原生 HTTP 调用 Zen 推理端点，模型出现在选择器里的 OpenCode Zen Free 分组，默认匿名访问，也可选填 Zen API Key。插件在 SkillHub 目录 归类为「模型推理」；源码与说明见 GitHub。目录站与 DeepSeek / 幻方无官方从属关系，插件本身也声明与 OpenCode、DeepSeek 无隶属关系。
这是什么¶
dsh-opencode-free 是 npm 包 dsh-opencode-free（当前 README 示例版本 0.3.6，MIT 许可证）。它注册 opencode-zen-free provider，经 DSH 的 PiAiAdapter 与 pi-ai 传输层直接请求 https://opencode.ai/inference/v1，工具执行仍留在 DSH 主机侧。不需要安装 OpenCode、登录流程、独立 server、容器或 LiteLLM。
匿名是默认鉴权方式；配置 config.apiKey 或环境变量 OPENCODE_API_KEY 时改用 Key，但不会自动切到付费模型，也不保证本来不可用的模型突然可用。
核心功能¶
README 中写明的集成能力包括：
- 模型选择器原生展示：流式输出、reasoning、tool calls、usage 与取消，与 DSH 侧能力对齐。
- 目录自动同步：元数据跟随 models.dev 与 Zen 在线目录；可在插件详情页隐藏个别模型。
- 可用性探测：详情页查看探测结果与延迟；配额用尽或 gate 拒绝不会因此从列表里删掉模型（结论可能为 inconclusive）。
- 缓存与回退：刷新失败时保留缓存列表；无缓存时回退到 pi-ai 内置模型列表。
Key 优先级：config.apiKey → OPENCODE_API_KEY → 匿名 public。
安装与启用¶
环境要求¶
| 依赖 | 版本 |
|---|---|
| DeepSeek Harness | 0.2.1-rc.2（须精确匹配；每个插件发行版只支持一个 DSH 版本） |
| Node.js | ^22.19.0 或 >=24.0.0 |
不要忽略 peer dependency 警告；README 写明四个 runtime peer 均为必需。
安装命令¶
先确认 DSH 版本，再按 profile 安装固定版本包（将 web 换成你的目标 profile）：
dsh --version
dsh plugin --profile web add dsh-opencode-free@0.3.6
若已安装过，应使用 update 而非重复 add。
验证包与合并后的配置：
dsh plugin --profile web list dsh-opencode-free --depth 0
dsh --profile web --dump-config
dsh-opencode-free 包与 opencode-free 插件条目应各出现一次。重启 DSH（或等待 HMR）后，在模型选择器中选择 OpenCode Zen Free 下的模型。
更新与移除：
dsh plugin --profile web update dsh-opencode-free
dsh plugin --profile web remove dsh-opencode-free
Profile 限制：详情页路由依赖 webServer 服务；内置 headless profile 不提供该服务，相关 UI 不可用。
典型用法¶
选模型与目录行为¶
模型选择器展示的是当前目录快照，而非固定写死的列表。上下文长度、是否支持图像、reasoning 等级来自各模型公开元数据。更细的刷新间隔、探测结果解读、缓存恢复与 Key 校验见仓库 usage guide。
在插件详情页可以启用或隐藏模型，并用 Probe now 检查可用性。读取模型列表也会在本地每天触发一次检查。探测会发送真实推理请求并消耗配额，一次只测一个已启用模型；结果会跨重启保留。
只有目录撤回或明确标记不可用时才会移除模型；gate 拒绝、配额耗尽、无效 Key、网络失败等属于 inconclusive，详见 catalogue decision rules。
可选 API Key（Desktop 示例）¶
Desktop 场景建议在 profile 的 cordis.patch.yml 里配置 Key，而不是依赖 shell 环境：
- id: opencode-free
name: dsh-opencode-free
config:
apiKey: <your Zen key>
修改配置后 reload DSH。Key 与配置勿写入 issue 或公开日志。
实现要点（匿名请求）¶
插件基于维护者对 OpenCode CLI 源码与请求校验的分析实现。匿名请求会携带 OpenCode CLI 格式的 identity 头、时间编码 session ID、流式参数，以及用于准入的 read / bash 工具声明（无实际执行能力；对缺失工具的调用会在进入主机 dispatch 前被拒绝）。Keyed 请求保留调用方原有 tools 与 prompt。
仅匿名路径上的适配包括：Windows 下将 DSH 的 pwsh 呈现为 bash 并在返回时还原；缺少 tools 时补充准入用声明；符合条件的无 tool compaction 请求会替换为 OpenCode 风格 summary system prompt。切换匿名与 Key 会改变请求前缀；compaction 是独立请求。
协议细节与证据边界见 protocol notes。
适用场景与注意¶
适合谁：已在用 DSH 0.2.1-rc.2、希望试用 OpenCode Zen 免费档模型、且接受非官方集成与上游变更风险的开发者。
安装前必读：
- 权限与拦截：插件以当前 DSH 进程权限运行；会对
globalThis.fetch与node:http(s)的request/get做进程级包装，仅作用于 Zen 推理源站 HTTPS 的/inference/v1路径。同进程内其他插件若也调用该端点，同样会被加上 identity 头。安装前应阅读源码与 DSH SAFETY.md。 - 匿名访问限制：身份字段由本插件发送，非官方 CLI；无第三方可用性保证，上游可随时变更导致失效。匿名配额按出口 IP 共享。
- 调试日志：
DSH_OPENCODE_FREE_DEBUG=1会输出含 Authorization 前缀等敏感片段的诊断信息，勿公开原始日志。 - 故障排查：插件未加载时核对 DSH 精确版本、peer、profile 与
webServer。出现403 FreeTierError … only be used from within OpenCode表示上游拒绝准入，单独出现并不能区分 IP、Key 或模型下架；重装不能解决 gate。详情页灰色「not measured」表示探测 inconclusive，不等于模型已消失。
维护者在 compat 报告中记录了部分模型的匿名 L0 验收，但 Web、Desktop、compaction 等仍标注为未完全验证；以 README Security and limitations 为准。
结尾¶
dsh-opencode-free 把 OpenCode Zen 免费模型接进 DSH 模型选择器，省去单独部署 OpenCode 运行时；代价是非官方协议适配、进程级 HTTP 包装与共享匿名配额等约束。使用前对齐 DSH 与插件版本，并在目录页或 GitHub 跟踪发行说明。
- 目录页：https://www.skillhub.cn/plugins/x5427876/dsh-opencode-free
- GitHub：https://github.com/x5427876/dsh-opencode-free
