opencode-models-discovery 2.0.0 發佈：配置形狀全換，OpenCode v2 正式轉正

先說結論：opencode-models-discovery 2.0.0 在 2026 年 10 月 19 日發佈，把 OpenCode v2 正式扶正成主力，v1 退成兼容適配器。這不是一次常規升級——配置文件的形狀整個換了，你照着老教程抄，大概率一行都跑不起來。

我自己踩了三個跟頭，都寫在下邊。先說它是幹嘛的：這東西是個 OpenCode 插件，專門解決一個很煩的問題——你在 OpenCode 裏接了一堆 OpenAI 兼容的網關、本地模型服務、中轉 API，每上一個新模型就得手動去 config 裏敲一遍模型名、上下文長度、價格。這個插件讓你只配一次 baseURL，剩下的它自己拉。

一、這次到底變了什麼

倉庫是 yuhp/opencode-models-discovery，MIT 協議，2026 年 4 月建的，現在 188 星、57 個 fork。聽起來不算頂流，但它是 OpenCode 生態裏少數認真做「模型發現」這件事的項目。

2.0.0 的核心動作只有一個：把 OpenCode v2 提升爲首要穩定集成。具體到技術上，v2 用的是原生的 plugins / providers 配置結構、provider 生命週期 API、宿主託管存儲、Integration 憑證、原生 TUI、RPC handler 和 Agent Tools。

翻譯成人話：以前的插件是「我偷偷改你的配置」，現在是「宿主給我開了正規接口」。憑證不用寫進配置文件，緩存交給宿主管，模型覆蓋可以在 TUI 面板裏點着改，改完不用重啓。

v1 和 v2 的支持級別

宿主版本	支持級別	配置字段	存儲與憑證
OpenCode v2	穩定 / 主力	`plugins` 和 `providers`	宿主 `ctx.storage` / `ctx.integration`
OpenCode v1	遺留兼容	`plugin` 和 `provider`	v1 XDG 緩存 + auth 兜底

v1 不是被砍了，安全修復和嚴重回歸還會管。但新功能——生命週期、緩存、TUI、RPC、模型覆蓋——全部只往 v2 走，不會自動回移到 v1。

二、九個元數據格式，這纔是重頭戲

v2.0.0 官方文檔化了九種模型信息格式，把「元數據攝取」和「發現調度」徹底拆開了。這個設計挺聰明：調度邏輯不用爲每個廠商改一遍，加個格式適配器就行。

格式	拿到什麼	額外請求
`openrouter`	上下文長度、top provider 輸出上限、模態（text/image/audio）、prompt/completion 與緩存價格、工具調用標記、推理檔位（low/medium/high）	不額外請求
`aiproxy`	AIProxy 內聯 limits、價格、effort 檔 + models.dev 的顯示名	組裝
`bifrost`	內聯 limits、模態、按 token 計價、推理變體	不額外請求
`litellm`	富模型元數據、上下文限制、價格、能力	請求 `/v1/model/info`
`lmstudio`	已加載實例配置（LM Studio 0.4.0+ 原生 `/api/v1/models`）	一次
`llama-swap`	上下文長度、架構、函數調用標記	不額外請求
`models.dev`	公共目錄兜底，通用上下文與能力	拉 `models.json`
`omniroute`	limits、多模態、服務檔位（fast/flex）	不額外請求
`vllm`	直接抽 `max_model_len`	不額外請求

注意最後那句：如果你不配 modelInfoFormat，那就只有模型 ID，什麼元數據都沒有。這不是 bug，是設計——不猜你接的是什麼服務，避免拉一堆錯誤的價格和上下文長度進來。

我一開始就是沒配這個字段，看着列表裏一排模型只有名字，還在想「怎麼什麼都沒變」，翻了半天文檔才反應過來。

三、配置文件到底怎麼寫

這是最容易翻車的地方。v1 那套 plugin / provider / options 在 v2 裏全部作廢，換成了複數 + settings。

OpenCode v1	OpenCode v2
`plugin`	`plugins`
`provider`	`providers`
`provider.<id>.npm`	`providers.<id>.package`
`provider.<id>.options`	`providers.<id>.settings`
`options.baseURL`	`settings.baseURL`
`options.apiKey`	`settings.apiKey`
`options.modelsDiscovery`	`settings.modelsDiscovery`

一個能直接跑的 v2 配置長這樣：

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-models-discovery@2.0.0"
  ],
  "providers": {
    "gateway": {
      "package": "@opencode/ai/providers/openai-compatible",
      "name": "My Gateway",
      "settings": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "{env:GATEWAY_API_KEY}",
        "modelsDiscovery": {
          "enabled": true,
          "modelInfoFormat": "models.dev",
          "smartModelName": true,
          "cache": {
            "enabled": true,
            "ttlSeconds": 86400
          }
        }
      }
    }
  }
}

幾個必須注意的點：

modelsDiscovery.enabled 必須顯式寫 true。v2 不再默認開啓，這是行爲變更，不是可選項。
package 對 OpenAI 兼容服務統一是 @opencode/ai/providers/openai-compatible。
憑證寫 {env:KEY} 讓宿主解析，或者乾脆不寫 apiKey，直接用 OpenCode 原生的 /connect 交互式錄入。
默認拉的是 /v1/models（相對 baseURL 的 origin）。碰到 DeepSeek 這種只暴露 /models 的，得在 modelsDiscovery 里加 "endpoint": "/models"。
v2 完全不讀 v1 的 auth.json 和 OPENCODE_AUTH_CONTENT 兜底。指望它自己接上老憑證的，會卡在 401。

四、模型覆蓋和緩存，比想象中實用

v2 的模型覆蓋存在宿主存儲的 overrides:<providerID>:<modelID> 命名空間下。能改的字段包括顯示名、limits、能力、推理、附件、變體、價格、兼容性元數據。

有個細節值得誇：憑證和授權類字段會被拒絕，永遠不會被持久化。這個邊界劃得很清楚——覆蓋是覆蓋展示和調度參數，不是讓你把密鑰塞進去。

覆蓋可以在 /models-discovery-console 裏可視化編輯，列表裏被覆蓋過的模型標個 *。改完直接重載 provider、刷新 TUI 的模型列表，不用重啓服務。清緩存也不會刪覆蓋，這是很多人會誤操作的點。

緩存默認是關的，開了之後 TTL 默認 24 小時，存的是原始發現響應和富化結果，走宿主的 ctx.storage。注意 v1 的 XDG 緩存文件不會導入 v2，兩套命名空間完全隔離。

五、TUI 命令和 Agent Tools

v2 提供的入口有這四個：

/models-discovery-refresh
/models-discovery-console
models_discovery_refresh
models_discovery_status

前兩個是 TUI 命令，後兩個是給自動化用的 agent tools。models_discovery_status 傳 rawCache: true 能把緩存裏的原始模型和富化結果一起吐出來，排查「爲什麼價格不對」的時候特別有用。

控制檯還支持按 provider 過濾：/models-discovery-console status --provider <provider-id>。接了三五個網關的時候，這個能省不少翻找時間。

六、升級前先過這張檢查單

OpenCode 版本：v2 要求 ≥ 2.0.26；留在 v1 的至少 1.18.29。
字段全換：複數 + settings，npm → package，options → settings。
顯式開啓：每個要發現的 provider 都寫 enabled: true。
端點核對：不是 /v1/models 的，手動加 endpoint。

另外兩個容易忽略的：本地構建的話，package 要填 file:///绝对路径/dist，指向目錄而不是 index.js，改完代碼還得 opencode service restart 讓後臺服務加載新 bundle。第三個跟頭我就是栽在這兒——改了半天代碼沒生效，因爲服務根本沒重啓。

七、這東西值得裝嗎

看你的場景。

只用一個官方 API 的：不用裝。模型列表就那幾個，手寫一次管一年，插件反而多一層。
接了中轉站 / 聚合網關的：強烈建議。這類服務模型上得勤、名字亂、價格經常調，手動維護純屬自虐。
本地跑 LM Studio / vLLM / llama-swap 的：裝上。這類服務模型是按需加載的，插件能把你實際加載了哪些、各自的 max_model_len 是多少直接讀出來，比你自己查配置快得多。
企業自建網關的：值得評估。九個格式裏有 bifrost、omniroute 這種專門面向網關的，另外 includeBy / excludeBy 支持按原始字段做正則和等值過濾，能把不該給普通用戶看的模型直接擋在列表外。

至於 2.0.0 本身，發佈說明裏提到驗證覆蓋了 41 個測試文件、314 個測試，加上本地 OpenAI 兼容 HTTP 集成測試和編譯產物校驗。對於一個 188 星的項目來說，這個測試密度算認真的。

v1 還能用，但新東西都在 v2。想長期跟進的，早點把配置遷過去，別等到哪天 v1 適配器只剩安全補丁了再動手。

項目地址：github.com/yuhp/opencode-models-discovery，安裝直接 npm i opencode-models-discovery@2.0.0 或者按上面的配置把包名寫進 plugins，OpenCode 會自己解析加載。