DeepSeek Harness 插件：dsh-opencode-go

前言¶

DeepSeek Harness（DSH）採用插件化架構，允許開發者針對不同的後端模型服務註冊自定義路由。在集成 OpenCode Go 等第三方模型時，往往需要處理會話一致性、客戶端標識規範以及憑證管理等問題。dsh-opencode-go 是一款適配 DeepSeek Harness 的 LLM provider 插件，它註冊了 zen-go 路由，並確保每次出站推理請求都攜帶每會話穩定的 x-opencode-session 頭部。

核心功能¶

該插件主要解決以下技術需求：

• 路由註冊：在 DSH 中註冊 zen-go 路由，避免與用戶自建 profile 的常用名衝突。
• 多端面支持：支持三種 API 端面：
  • chat/completions：兼容 OpenAI 格式，支持 mimo、deepseek-v4、glm、kimi、longcat、hy。
  • responses：支持 grok、gpt-5.6-luna、muse-spark，包含獨立的 response.incomplete 終態。
  • messages：兼容 Anthropic 格式，支持 minimax、qwen，使用 x-api-key 鑑權。
• 會話管理：自動爲請求攜帶 x-opencode-session 頭部（取自會話 ID，缺失時生成 UUID），保證會話追蹤。
• 客戶端標識：使用自定義的 User-Agent（deepseek-harness/<版本> (+url) dsh-opencode-go/<版本>），便於運營方識別與放行，而非通用的 Go-http-client/1.1。
• 憑證解析：支持分層憑證解析順序（進程環境變量 -> 託管 store -> 項目/家目錄 .env），存換 Key 無需重啓。
• 設置面板：提供 Web 界面設置，支持在 Models 頁行和側邊欄錄入 Key、勾選模型、配置上下文/輸出上限、設置端面與思考檔位。
• 推理檔位：支持 Low/Medium/High/Xhigh 等檔位，不同端面（chat/responses/messages）對應不同的參數字段。
• 多模態與圖片處理：
  • 支持 vision 模型。
  • 當請求內聯圖片總量超過 maxRequestImageBytes（默認 64 MiB）時，拋出 IMAGE_OFFLOAD_REQUIRED 信號，由 DSH 的卸載機制處理，本插件不直接丟棄圖片。
  • 單圖大小由 attachment 服務的准入歸一化決定，本插件不負責圖片大小限制。
• 用量記錄：統一記錄三端面的 usage（prompt_tokens / input_tokens），並生成 usage.l 用量賬本，記錄模型、會話、實際 Session 頭、輸入輸出及推理消耗。

安裝與啓用¶

使用以下命令安裝插件：

dsh plugin --profile web add github xia-sc/dsh-opencode-go

安裝完成後，需要重啓 DSH Web 服務。在會話的模型選擇器中，選擇 zen-go/<模型> 即可使用。

配置憑證：
在 $DSH_HOME/.credentials.yaml 中添加 Key，或在設置卡中直接粘貼保存。也可以設置環境變量 OPENCODE_GO_API_KEY。

配置¶

在 DSH 的配置中，需設置 llm-opencode-go section 或 layer config。關鍵配置項如下：

注意：官方 /v1/models 不返回上下文窗口，modelCaps 需手動填寫。如果設置卡中的配置被拒絕（例如在 responses 端面配置了 chat 纔有的 max 檔），整段設置會被丟棄並沿用默認值。

典型用法與注意事項¶

1. 本地源碼安裝：如果從本地源碼安裝，必須先運行腳本以建立依賴橋接：

    cd <插件源碼目錄>
    node scripts/setup-local-deps.cjs
    dsh plugin --profile web add <插件源碼目錄>

2. Token 預算管理：在 responses 系端面中，高推理 effort 容易消耗大量 token，建議在設置中配合較大的 maxTokens 起步。

3. 價格說明：價格由計費插件決定，本插件只負責用量上報。

4. 圖片限制：本插件不負責圖片大小限制，該限制由 attachment 服務的准入歸一化決定。

結語¶

dsh-opencode-go 提供了從路由註冊到會話管理、憑證解析及用量記錄的一站式解決方案，適合需要集成 OpenCode Go 生態並在 DSH 中統一管理的場景。更多細節可查閱項目目錄或 GitHub 倉庫。