🎯 OpenCode插件系列: opencode-commandcode-provider

类型: OpenCode Provider 插件

1. 这是什么插件？

Command Code Provider 是一个 OpenCode provider 插件，桥接 Command Code API 到 OpenCode 生态系统。它实现 @ai-sdk/provider 的 LanguageModelV3 接口，让 OpenCode 用户可以通过单一 API Key 使用 Claude、GPT、Gemini、DeepSeek、Qwen、Kimi、GLM、MiniMax、Step 等 20+ 模型。

主要特性:

单一 API Key — 一个 Key 访问 20+ 主流模型，无需多个账户
自动模型注册 — 插件启动时自动从 models.json 发现并注册所有可用模型
流式/非流式支持 — 完整支持 SSE 流式输出和非流式生成
工具调用 — 支持所有模型的工具调用能力
推理支持 — 支持 Claude、GPT 等模型的推理过程输出
API Key 多源解析 — 支持显式传入、环境变量、本地 auth.json 等多种方式

支持的模型家族:

模型家族	代表模型	上下文窗口
Anthropic Claude	Claude Sonnet 4.6, Claude Opus 4.7	1M
OpenAI GPT	GPT-5.5, GPT-5.4, GPT-5.3 Codex	256K-400K
Google Gemini	Gemini 3.5 Flash, Gemini 3.1 Flash Lite	1M
DeepSeek	DeepSeek V4 Flash, DeepSeek V4 Pro	1M
Qwen	Qwen 3.7 Max, Qwen 3.6 Plus	1M
其他	Kimi K2.6, GLM-5.1, MiniMax M2.7, Step 3.5 Flash	200K-1M

2. 有什么用？

在以下场景中使用它：

✅ 通过单一 API Key 访问多个模型家族（Anthropic、OpenAI、Google 等）
✅ 避免多个 API 账户管理的复杂性
✅ 按需切换模型（从轻量 Haiku 到强大 Opus）
✅ 利用不同模型的优势（推理用 Claude，编码用 Codex，性价比用 DeepSeek）
✅ 统一计费（通过 Command Code 平台统一管理用量）

技术特性:

LanguageModelV3 接口 — 完整实现 OpenCode 的最新模型接口标准
SSE 流解析 — 健壮的 SSE/JSON Lines 解析器，支持跨 chunk 边界
消息转换 — 自动将 OpenCode V3 格式转为 Command Code API 请求格式
工具过滤 — 自动过滤 OpenCode 内部工具，只发送 type: "function" 的工具
超时控制 — 5 分钟硬限制 + 用户 abort 信号转发
错误处理 — 解析 JSON 错误体，包含 [model=xxx] 后缀便于调试

3. 怎么用？

简单安装

opencode plugin commandcode-go-opencode-provider

这会自动安装插件并注册所有可用模型。

连接 API Key

在 OpenCode 中运行 /connect，搜索 Command Code，输入你的 API Key：

/connect

选择模型

运行 /models 从可用模型中选择：

/models

或手动添加到 `opencode.json`:

{
  "plugin": ["commandcode-go-opencode-provider/server"],
  "provider": {
    "commandcode": {
      "npm": "commandcode-go-opencode-provider",
      "name": "Command Code",
      "env": ["COMMANDCODE_API_KEY"]
    }
  },
  "model": "commandcode/deepseek-v4-flash"
}

环境变量方式

设置 COMMANDCODE_API_KEY 环境变量，无需使用 /connect：

COMMANDCODE_API_KEY=your-key opencode

API Key 解析优先级

插件按以下顺序查找 API Key：

1. 显式传入 options.apiKey
2. options.env?.COMMANDCODE_API_KEY
3. process.env.COMMANDCODE_API_KEY
4. ~/.commandcode/auth.json 中的 apiKey / commandcode 字段
5. ~/.pi/agent/auth.json 中的 commandcode.access (OAuth)
6. undefined（未找到，抛出错误）

支持三种 auth.json 格式：

// 格式 1: 直接 API Key
{ "apiKey": "sk-xxx" }

// 格式 2: Command Code 专用字段
{ "commandcode": "sk-xxx" }

// 格式 3: OAuth 格式
{ "commandcode": { "type": "oauth", "access": "sk-xxx" } }

4. 可用模型列表

完整模型列表维护在 [models.json](https://file+.vscode-resource.vscode-cdn.net/Users/vec/workspace/docs/opencode-commandcode-provider/models.json) 中。运行 bun run sync 可从 Command Code CLI 最新版本同步。

模型 ID	名称	层级	推理	上下文
`claude-haiku-4-5-20251001`	Claude Haiku 4.5	premium	no	200K
`claude-opus-4-7`	Claude Opus 4.7	premium	yes	1M
`claude-sonnet-4-6`	Claude Sonnet 4.6	premium	yes	1M
`gpt-5.3-codex`	GPT-5.3 Codex	premium	yes	400K
`gpt-5.4`	GPT-5.4	premium	yes	400K
`gpt-5.4-mini`	GPT-5.4 Mini	premium	yes	400K
`gpt-5.5`	GPT-5.5	premium	yes	256K
`deepseek/deepseek-v4-flash`	DeepSeek V4 Flash	open-source	yes	1M
`deepseek/deepseek-v4-pro`	DeepSeek V4 Pro	open-source	yes	1M
`google/gemini-3.1-flash-lite`	Gemini 3.1 Flash Lite	open-source	yes	1M
`google/gemini-3.5-flash`	Gemini 3.5 Flash	open-source	yes	1M
`zai-org/GLM-5`	GLM-5	open-source	no	200K
`zai-org/GLM-5.1`	GLM-5.1	open-source	no	200K
`moonshotai/Kimi-K2.5`	Kimi K2.5	open-source	no	256K
`moonshotai/Kimi-K2.6`	Kimi K2.6	open-source	no	256K
`MiniMaxAI/MiniMax-M2.5`	MiniMax M2.5	open-source	no	200K
`MiniMaxAI/MiniMax-M2.7`	MiniMax M2.7	open-source	no	1M
`Qwen/Qwen3.6-Max-Preview`	Qwen 3.6 Max Preview	open-source	yes	1M
`Qwen/Qwen3.6-Plus`	Qwen 3.6 Plus	open-source	yes	1M
`Qwen/Qwen3.7-Max`	Qwen 3.7 Max	open-source	yes	1M
`stepfun/Step-3.5-Flash`	Step 3.5 Flash	open-source	yes	1M

模型层级说明

层级	说明	适用场景
premium	Anthropic、OpenAI 顶级模型	复杂推理、高质量代码生成
open-source	开源模型（DeepSeek、Qwen 等）	高性价比、长上下文任务

5. 什么时候用？

在以下场景使用：

✅ 需要访问多个模型家族但不想管理多个 API 账户
✅ 想通过单一平台统一计费和用量追踪
✅ 需要在不同场景切换模型（编码用 Codex，推理用 Claude，性价比用 DeepSeek）
✅ 使用 OpenCode 并希望模型自动注册和发现
✅ 需要流式输出和工具调用支持
✅ 需要推理过程可见（Claude、GPT 的 reasoning 输出）

不要使用的场景：

❌ 只需要单一模型（直接使用官方 provider 更简单）
❌ 已有其他 provider 的完整配置（迁移成本可能高于收益）
❌ 需要非标准模型参数（当前支持 temperature、top_p、top_k、max_tokens）

6. 开发指南

本地开发

git clone https://github.com/brent-weatherall/opencode-commandcode-provider.git
cd opencode-commandcode-provider
bun install

本地测试

创建 opencode.local.json（已被 gitignore）：

{
  "plugin": ["file:///path/to/commandcode-go-opencode-provider/server"],
  "provider": {
    "commandcode": {
      "npm": "file:///path/to/commandcode-go-opencode-provider",
      "name": "Command Code (local)",
      "env": ["COMMANDCODE_API_KEY"]
    }
  }
}

运行 opencode --config opencode.local.json 使用本地构建测试。

同步模型

bun run sync              # 从 Command Code CLI 更新 models.json
bun run sync:global       # 更新 models.json + 写入全局配置
bun run generate-readme   # 从 models.json 自动生成 README 模型表格

运行测试

bun test                  # 运行单元测试
bun test tests/integration/  # 运行集成测试
bun test:all              # 运行所有测试
bun run typecheck         # TypeScript 类型检查

测试覆盖

测试文件	用例数	覆盖范围
`auth.test.ts`	7	API Key 解析优先级、环境变量、显式参数
`convert.test.ts`	14	请求构建、消息转换、工具转换、边界情况
`model.test.ts`	13	流式请求、非流式请求、错误处理、请求头、URL
`stream.test.ts`	14	SSE 解析、事件映射、边界处理、chunk 拆分
`plugin.test.ts`	12	插件配置、认证、模型注册
`index.test.ts`	6	入口函数、API Key 缺失、模型创建

7. 架构概览

┌────────────────────────────────────────────────┐
│             Entry Point (index.ts)             │
│         createCommandCode() 工厂函数            │
├────────────────────────────────────────────────┤
│             Plugin Layer (plugin.ts)           │
│        OpenCode 插件集成 + 自动注册              │
├────────────────────────────────────────────────┤
│   ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│   │ auth.ts  │  │convert.ts│  │stream.ts │    │
│   │ Key解析   │  │ 请求转换  │  │ SSE解析   │    │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘    │
│        └──────────────┼─────────────┘           │
│                       ▼                        │
│              ┌──────────────┐                  │
│              │  model.ts    │                  │
│              │LanguageModel │                  │
│              │    V3 实现   │                  │
│              └──────┬───────┘                  │
├──────────────────────┼─────────────────────────┤
│                      ▼                         │
│           Command Code API (HTTP)              │
│        POST /alpha/generate (SSE)              │
└────────────────────────────────────────────────┘

数据流

用户操作 → OpenCode CLI
  → 加载 plugin.ts → 注册 provider + 模型列表
  → 调用模型
    → createCommandCode() → resolveApiKey()
    → new CommandCodeLanguageModel(modelId, { apiKey })
    → doStream() / doGenerate()
      → buildRequest() → 转换消息格式
      → HTTP POST /alpha/generate
      → parseStreamEvents() → 解析 SSE 流
      → 返回 LanguageModelV3StreamResult

⚠️ 重要注意事项

模型 ID 简化规则

插件自动简化模型 ID 以便使用：

去除 provider/ 前缀并转小写
deepseek/deepseek-v4-flash → deepseek-v4-flash
Qwen/Qwen3.7-Max → qwen3.7-max

请求头

所有请求包含以下头信息：

x-command-code-version: 0.26.20（API 兼容性版本）
x-cli-environment: production
x-project-slug: opencode

超时控制

5 分钟硬限制（AbortController）