opencode-catalog-bridge

opencode plugin — 自定义 provider 的模型自动从 models.dev 复用元数据（limit / cost / reasoning / variants 等），无需手写。

解决什么问题

opencode 的模型元数据（context 窗口、输出上限、cost、reasoning 能力等）来自 models.dev catalog。但 catalog 匹配按 providerID 严格隔离——如果你的 provider 用自定义名字（如 litellm、volces-ark、my-gateway），models.dev 里没这个名字，它下面所有模型的元数据全部为空，TUI 里 limit 显示为 0。

本 plugin 在 config 解析后自动按 modelID 从 models.dev 取标准元数据，逐字段补全。

安装

方式一：Git 引用（推荐）

// ~/.config/opencode/opencode.jsonc
{
  "plugin": [
    "opencode-catalog-bridge@git+https://github.com/anomalyco/opencode-catalog-bridge.git"
  ]
}

方式二：本地文件

{
  "plugin": [
    "/path/to/opencode-catalog-bridge/catalog-bridge.ts"
  ]
}

改完配置后重启 opencode（配置不热加载）。

使用

核心约定

自定义 provider 的 model，外层 key 必须对齐 models.dev 里的模型名。

models.dev 按 modelID（如 glm-5.2、deepseek-v4-pro）收录模型。plugin 用这个 key 去 catalog 查找匹配。

最小配置

{
  "plugin": [
    "opencode-catalog-bridge@git+https://github.com/anomalyco/opencode-catalog-bridge.git"
  ],
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://your-endpoint/v1",
        "apiKey": "sk-xxx"
      },
      "models": {
        "glm-5.2": {}
      }
    }
  }
}

glm-5.2 这个 key 对齐 models.dev，plugin 自动补全 limit（ctx=1M / out=128K）、cost、reasoning、variants 等。baseURL / apiKey / provider 名都由你自己定。

API id 与 catalog key 分离

如果你的 endpoint 后端用的 model name 跟 catalog 不一样（比如 LiteLLM 代理里叫 vibe-bot/glm-5.2），用 id 字段指定真实 API name，外层 key 保持对齐 catalog：

"models": {
  "glm-5.2": {
    "id": "vibe-bot/glm-5.2",
    "name": "GLM 5.2 (我的网关)"
  }
}

• 外层 key glm-5.2 → 桥接 catalog 元数据
• id → 发给 API 的真实 model name
• name → TUI 显示名（不写则用 catalog 的标准名）

自动补全的字段

字段	说明	来源
limit	context / input / output 窗口	models.dev
cost	input / output / cache_read / cache_write 单价	models.dev
reasoning	是否支持 reasoning	models.dev
tool_call	是否支持 tool calling	models.dev
attachment	是否支持附件	models.dev
temperature	是否支持 temperature 参数	models.dev
family	模型家族（如 glm / deepseek-thinking）	models.dev
release_date	发布日期	models.dev
interleaved	reasoning 字段名（如 {field:"reasoning_content"}）	models.dev
modalities	输入输出模态（text/image/audio/video/pdf）	models.dev
status	alpha / beta / active / deprecated	models.dev
experimental	是否实验性	models.dev
variants	reasoning effort 档位（从 reasoning_options 生成）	models.dev
options.reasoningEffort	默认 effort（取最高档，如 max）	models.dev

逐字段补全：用户已手写的字段不覆盖，只补缺失的。任何字段都可以手写覆盖 plugin 的自动值。

不改什么（闭包边界）

• model.id — 保留用户自定义的真实 API id
• provider.options（baseURL / apiKey）— endpoint 由用户自己配
• name — 保留用户自定义的显示名

数据来源优先级

opencode 官方 catalog  >  厂商官方(zhipuai/deepseek)  >  第一个有效数据

优先取 opencode 官方维护的标准数据（最可信）。过滤掉 output >= context 的异常数据。

前提条件

• opencode 的 models.dev 缓存存在（~/.cache/opencode/models.json）。opencode 首次联网运行时会自动拉取，之后每 60 分钟刷新。
• modelID 必须在 models.dev 里有收录。未收录的模型不会报错，只是跳过（可手写 limit 兜底）。

工作原理

opencode 启动
  ↓
plugin config hook 收到 merged config
  ↓
读 ~/.cache/opencode/models.json (models.dev 缓存)
  ↓
对 cfg.provider 里每个自定义 provider 的每个 model:
  按 modelID 查 catalog → 逐字段补全缺失的元数据
  ↓
opencode provider Store 解析 config (读到补全后的值)
  ↓
TUI / session 正常使用 (limit/cost/reasoning 全部正确)

plugin 走 v1 config hook（兼容 opencode 1.x 的 v1 provider system）。

License

MIT