opencode-model-fetch

从 models.dev 抓取官方模型能力数据，一键生成 OpenCode 第三方供应商可直接使用的模型配置属性。项目同时提供公共 TypeScript 核心模块、Node.js CLI，以及用于历史验证和过渡的 Python CLI。

解决什么问题

在 opencode 中配置第三方网关供应商时，自定义模型通常只有 id 和名字：

• 上下文上限、输入模态、价格分档等能力属性缺失，只能凭记忆手填
• reasoning 模型的变体（variants）缺失，或与 opencode 自动注入的默认变体重复出现
• 照搬 models.dev 原始条目会带入 opencode schema 不接受的字段，直接导致 opencode 拒绝启动
• reasoning_options 是 models.dev 的目录元数据，写进配置并不会生成变体（常见误区）

本工具自动完成：抓取 → schema 白名单过滤 → 按 SDK 生成变体 → 屏蔽不支持的自动变体 → 保留人工配置 → 输出可整体粘贴的 JSON。

特性

• 双数据源：优先在线 models.dev/api.json（嵌套目录，含 reasoning_options 全量元数据），失败自动回退本地快照
• 官方源优先：按 openai → xai → anthropic → … 优先级命中官方条目，避免抓到聚合站转述数据
• schema 白名单：只输出 opencode 允许的字段（该处配置 additionalProperties: false，多写即崩）
• 变体智能生成：
  • 按 OpenAI Responses、OpenAI Compatible、Anthropic、Bedrock、Google 五类 SDK 生成正确的 provider options
  • effort 和 budget_tokens 两种 models.dev 元数据都能转换为 OpenCode variants
  • 纯名称（plain）键与 OpenCode 自动注入的默认变体键碰撞覆盖，避免重复列表
  • 自动屏蔽「会被注入、但模型不支持」的档位（{"disabled": true}）
• 保真刷新：默认保留 base 中人工填写的 limit、非空 name、options、headers 和自定义字段；当前 SDK 无法安全生成变体时保留原 variants。已有自定义字段不会被工具主动删除，但仍需由使用者确保符合 OpenCode schema
• 两种命名风格：plain（默认）/ numbered（01-low 式，会提示重复风险）
• 容错：某模型抓取失败时保留 base 原条目并告警，不影响其余模型
• cc-switch 对齐：命令行公开的接口格式与 cc-switch 当前编辑器一致，默认使用 @ai-sdk/openai-compatible

TypeScript CLI（推荐）

要求 Node.js 20 或更高版本。CLI 运行时不依赖第三方 npm 包。

已发布到 npm registry：

npx @tttrove/opencode-model-fetch gpt-5.6-sol
npx @tttrove/opencode-model-fetch claude-opus-5 --npm @ai-sdk/anthropic

CLI 默认根据本地 locale 选择帮助、提示和警告语言：中文 locale 使用中文，其他 locale 使用英文。也可以显式指定语言：

opencode-model-fetch --lang zh --help
opencode-model-fetch --lang en --help

自动检测也可以通过环境变量覆盖：

OPENCODE_MODEL_FETCH_LANG=zh opencode-model-fetch --help

Windows PowerShell：

$env:OPENCODE_MODEL_FETCH_LANG = "zh"
opencode-model-fetch --help

也可以直接从 GitHub Release 使用：

npm exec --yes \
  --package=https://github.com/tttrove/opencode-model-fetch/releases/download/v0.1.0/tttrove-opencode-model-fetch-0.1.0.tgz \
  -- opencode-model-fetch gpt-5.6-sol

# 全局安装
npm install --global @tttrove/opencode-model-fetch
opencode-model-fetch gpt-5.6-sol

# 刷新完整供应商配置
opencode-model-fetch --base examples/base.example.json -o my-config.json

# 直接生成可合并进 opencode.json 的 provider 配置
opencode-model-fetch \
  --base examples/base.example.json \
  --provider-id my-gateway \
  --provider-name "My gateway" \
  -o opencode.json

# 指定接口格式和官方来源
opencode-model-fetch claude-opus-5 \
  --npm @ai-sdk/anthropic \
  --source anthropic

# 离线使用 models.dev api.json 快照
opencode-model-fetch --offline \
  --snapshot models-dev-api.json \
  gpt-5.6-sol

命令行参数与 Python 过渡版本保持一致：--lang、--style、--npm、--source、--offline、--snapshot、--base、--out、--provider-id、--provider-name。

--npm 只接受 cc-switch 当前公开的五种接口格式；不传时默认使用 @ai-sdk/openai-compatible：

| 参数值 | 接口格式 | |---|---| | @ai-sdk/openai | OpenAI Responses | | @ai-sdk/openai-compatible | OpenAI Compatible | | @ai-sdk/anthropic | Anthropic | | @ai-sdk/amazon-bedrock | Amazon Bedrock | | @ai-sdk/google | Google (Gemini) |

不传 --provider-id 时，--base 输出供应商配置本身，未使用 --base 时输出模型 map；传入 --provider-id 后输出完整的 { "provider": { "<id>": { ... } } }。

TypeScript CLI 的 stdout 只输出合法 JSON，进度和警告写入 stderr，因此可以安全重定向：

opencode-model-fetch gpt-5.6-sol > models.json

如果有模型未找到，CLI 会保留可用结果并返回退出码 2；参数、文件或网络回退失败返回退出码 1。

TypeScript API

import {
  applyModelsDevCapabilities,
  buildVariantsForModel,
  findModelsDevEntry,
  transformModelsDevEntry,
} from "@tttrove/opencode-model-fetch";

核心模块是纯 TypeScript 数据逻辑，不依赖 React、Tauri、浏览器 API、文件系统或 CLI 参数。cc-switch 当前仍维护自己的实现，并不依赖此 npm 包。

Python CLI（过渡保留）

GitHub 仓库中的 fetch_opencode_models.py 及其 unittest 会继续保留，确保 cc-switch issue/PR 中指向本仓库 Python 测试案例的链接和验证过程仍然有效。Python 版本仅依赖 Python 3.10+ 标准库，不包含在 npm tarball 中。

# 1. 准备种子文件（参考 examples/base.example.json）：
#    npm / options 原样保留，models 键名即待刷新的模型清单

# 2. 刷新全部模型，输出整份可粘贴配置
python fetch_opencode_models.py --base examples/base.example.json -o my-config.json

# 3. 只刷新指定模型，输出模型配置块
python fetch_opencode_models.py gpt-5.6-sol grok-4.6

# 常用参数
python fetch_opencode_models.py claude-opus-5 --source anthropic  # 手动指定官方源
python fetch_opencode_models.py claude-opus-5 --npm @ai-sdk/anthropic  # 指定接口格式（决定变体形态）
python fetch_opencode_models.py grok-4.6 --offline              # 不联网，用本地快照

# 显式选择语言
python fetch_opencode_models.py --lang zh --help
python fetch_opencode_models.py --lang en --help

# 运行 Python 零依赖测试
python -m unittest discover -s tests -v

把输出的 JSON 整体粘贴进 cc-switch 供应商编辑框；需要生成 opencode.json 的 provider 包装时，使用 --provider-id。重启 opencode 后生效。

开发验证

npm install
npm run typecheck
npm test
python -m unittest discover -s tests -v
npm pack --dry-run

TypeScript 测试使用 Node 内置 node:test，Python 测试使用标准库 unittest；两套实现共享同一组跨实现 fixture。

变体机制速览

OpenCode 会按供应商 SDK 对 reasoning 模型自动注入默认变体，并与你配置的 variants 按「同名覆盖、异名共存」合并。因此：

• 用 01-low 这类数字前缀键 → 与注入键不碰撞 → 列表出现重复项
• 用 low 这类纯名称键 → 碰撞覆盖 → 列表干净，且本工具生成的变体对象与注入对象同构，不丢失任何能力
• @ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/amazon-bedrock 和 Google SDK 的变体参数结构不同，不能只复制 reasoningEffort
• 对 reasoning_options 为空数组的模型，本工具会为 OpenCode 自动注入的档位写入 disabled，避免 UI 显示官方不支持的选项

完整机制分析（注入规则、五类 SDK、budget_tokens、合并语义、屏蔽策略、schema 雷区）见 docs/variant-mechanism.md。

离线快照（可选）

Invoke-WebRequest https://models.dev/api.json -OutFile models-dev-api.json

Node CLI 默认从当前工作目录读取 models-dev-api.json，也可以显式使用 --snapshot <path>。Python CLI 默认从脚本所在目录读取快照。

注意事项

• models.dev 只反映官方声明，你的网关是否真正支持某个 reasoning_effort 档位（尤其 max），建议实测后再保留对应变体
• API Key 建议用 {env:VAR} 形式引用环境变量，避免明文落盘
• 机制结论与实现以 cc-switch PR #6840 时校验的 OpenCode 行为为准；OpenCode 后续版本可能变化，升级后应重新验证

License

MIT