前言¶
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
