dsh-opencode-go-catalog：DeepSeek Harness 的實時維護 OpenCode Go 模型目錄

前言¶

DeepSeek Harness (DSH) 的內置 opencode-go 路由依賴 @earendil-works/pi-ai 中的靜態目錄，不會自動更新。當上遊依賴未更新時，新模型（如 Step 5 或 Cat Jam）將不會出現在模型選擇器中。

dsh-opencode-go-catalog 插件通過維護三個協議分離的兄弟路由來解決這個問題。它從不觸碰內置的 opencode-go 路由，而是通過 settings.mutate 接口管理 opencode-go-extras、opencode-go-responses 和 opencode-go-messages 這三個路由。模型列表會從實時名錄（roster）和文檔接口（docs）中重建，無需人工干預。

核心功能¶

實時維護目錄：從 https://models.opencode.ai/api.json（註冊表）和 https://opencode.ai/zen/go/v1/models（名錄）獲取最新狀態。
協議分離路由：將模型按協議分爲三類，避免因協議不匹配導致的 500 或 401 錯誤。
- opencode-go-extras：使用 openai-completions 協議。
- opencode-go-responses：使用 openai-responses 協議。
- opencode-go-messages：使用 anthropic-messages 協議。
自動同步與快照：支持命令 /opencode-go-sync 強制同步，並保留一個經過篩選的快照作爲離線回退方案。
容錯機制：當源數據不可用或模型數量低於安全閾值時，自動切換到快照模式，確保模型選擇器不會空置。

安裝與啓用¶

該插件需通過手動方式安裝。

    cp -r dsh-opencode-go-catalog <profile>/node_modules/dsh-opencode-go-catalog

編輯配置目錄下的 package.json，在 dsh.profile.bundles 中添加插件名稱：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "dsh-opencode-go-catalog"
          ]
        }
      }
    }

重啓 DSH。

配置說明¶

在 cordis.patch.yml 中配置插件，以控制同步行爲和路由列表。這是一個整體替換（非深度合併），需包含所有字段：

- id: opencode-go-catalog
  name: dsh-opencode-go-catalog
  config:
    enabled: true            # false 時移除兄弟路由
    autoMembership: true     # false 時僅使用快照，不查詢名錄/文檔
    minAutoModels: 8         # 安全閾值：低於此數量使用快照
    minProtocolRows: 10      # 安全閾值：防止文檔重設計導致路由爲空
    minAutoRatio: 0.6        # 安全閾值：上次採用集的保留比例，0 禁用
    refreshReasoning: true   # false 時僅使用快照推理值，禁用自動模式
    sessionHeaderValue: 'dsh-opencode-go-catalog'  # 添加靜態會話頭
    intervalMinutes: 240     # 0 表示僅在啓動時同步
    startupDelaySeconds: 10
    refreshTimeoutMs: 120000
    catalogPath: ./catalog/models.json
    managedRoutes:
      - opencode-go-extras
      - opencode-go-responses
      - opencode-go-messages

常用命令與腳本¶

通過聊天命令或腳本文件管理目錄狀態。

聊天命令
* /opencode-go-sync：立即從實時源重寫模型列表。

腳本文件
* node bin/sync.mjs：默認模式，報告字段差異、新/死模型 ID，但不寫入文件。
* node bin/sync.mjs --auto：預覽自動模式下的輸出（新增、移除、未解析項）。
* node bin/sync.mjs --adopt：將實時成員寫入快照（保留當前回退快照）。
* node bin/sync.mjs --write：從註冊表重寫快照字段並標記日期。

注意事項¶

手添模型不持久：在設置界面手動添加到三個路由的模型，在下次同步（啓動、定時或命令觸發）時會被覆蓋刪除。如需持久化，請使用 --adopt 命令寫入快照或使用排除列表。
運行環境：插件以當前 DSH 進程權限運行。安裝前請檢查源碼與許可證（MIT）。
依賴條件：必須確保 DSH 正在運行，且已配置有效的 OPENCODE_GO_API_KEY（內置路由可用即代表配置正確）。

總結¶

dsh-opencode-go-catalog 爲 DSH 提供了動態的 OpenCode Go 模型目錄管理能力，解決了內置靜態目錄無法更新的痛點。通過協議分離和快照回退機制，它在不干擾現有路由的前提下，保證了模型列表的實時性和穩定性。插件源碼與文檔可參考 GitHub。