step-providers

一个 StepCode 插件：通过 /providers 命令对接 models.dev，快速把第三方模型导入到 StepCode。

/providers
┌─────────────────────────────────────────────┐
│ models.dev providers (235)                  │
│ Type to filter providers...                 │
│ → DeepSeek  |  deepseek                     │
│     2 models  |  https://api.deepseek.com   │
│   OpenRouter  |  openrouter                 │
│     301 models  |  https://openrouter.ai/api/v1
│   ...                                       │
│ ↑↓ navigate • enter select • esc cancel     │
└─────────────────────────────────────────────┘

功能

• 浏览和搜索 models.dev 的 200+ 个 provider。
• 支持一次导入全部模型，或在 TUI 里多选模型。
• 自动把 models.dev 元数据映射为 StepCode 的模型配置：
  • 上下文窗口、最大输出
  • 输入/输出价格、缓存价格、阶梯价格
  • reasoning / thinking level
  • 图片输入（vision）
• API key 只写入 auth.json，不会写进 models.json。
• 记录导入来源，/providers remove 只删除自己导入的模型，不影响手写配置。
• 模型目录缓存 24 小时；网络失败时自动回退到旧缓存。
• 导入后自动刷新 StepCode 的模型注册表，可立即 /model 选择。

安装

方式一：作为本地扩展

把 src/ 复制到全局扩展目录：

# Windows
xcopy /E /I src "%USERPROFILE%\.stepcode\agent\extensions\step-providers"

# macOS / Linux
cp -r src ~/.stepcode/agent/extensions/step-providers

或者只在当前仓库里试运行：

step -e ./src/index.ts

方式二：作为 Step 包安装

package.json 已经声明了 pi.extensions：

step install ./
# 或者从其他位置引用这个目录
step install /absolute/path/to/step-code-ntr

插件本身没有运行时依赖；devDependencies 只用于类型检查和测试。

使用

直接输入 /providers 打开交互菜单：

/providers                      交互菜单
/providers add [provider-id]    导入 provider（省略 id 则打开选择器）
/providers <provider-id>        add 的简写
/providers list                 查看已导入的 provider
/providers remove [provider-id] 移除已导入的模型
/providers key [provider-id]    保存 API key 到 auth.json
/providers search <query>       搜索 models.dev
/providers refresh              强制刷新 models.dev 缓存
/providers help                 查看帮助

常用示例：

# 交互式选择 provider，然后选择全部或部分模型
/providers

# 直接导入 DeepSeek 的全部可用模型
/providers add deepseek --all

# 只导入匹配的模型
/providers add openrouter --models "anthropic/claude-*,google/gemini-*"

# 非交互环境（print / CI）导入，使用环境变量里的 key
/providers add groq --all --no-key

# 移除
/providers remove deepseek --yes

非交互模式（-p / CI）下移除必须加 --yes；交互模式会弹出确认。

导入参数

参数	说明
--all	不询问模型，导入全部可用模型
--pick	直接打开模型多选器（仅 TUI）
--models a,b,c*	只导入匹配的模型 ID，支持 * 和 ?
--include-deprecated	包含 deprecated 模型
--include-no-tool	包含不支持 tool calling 的模型
--include-non-text	包含没有文本输出的模型
--no-key	跳过 API key 输入
--force	导入前强制刷新 models.dev 目录

默认会过滤掉以下模型：

• status: "deprecated"
• tool_call: false（编码代理必须能调用工具）
• 输出模态里没有 text

API Key

导入时可以输入 key，TUI 下输入会显示为圆点掩码，支持直接粘贴（包括终端的 bracketed paste）。key 会合并写入：

~/.stepcode/auth.json

已有的 Step 账号 OAuth 凭据会被保留。也可以用环境变量，插件会把 provider 的 env 字段写成 models.json 里的 apiKey 引用：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [...]
    }
  }
}

对于 StepCode 内置 provider，插件优先使用 StepCode 的规范环境变量。例如 xiaomi-token-plan-cn 会写成 $XIAOMI_TOKEN_PLAN_CN_API_KEY，而不是 models.dev 的 $XIAOMI_API_KEY；如果旧的 models.dev 变量已经在当前进程环境中设置，则保留旧变量。已有导入配置会在下次启动或执行 /providers 时自动修正。

优先级：auth.json > 环境变量。导入后也可以随时：

/providers key deepseek

/model 只显示已经配置认证的 provider。导入后如果看不到模型，请先用 /providers key <provider-id> 粘贴 key，或设置对应的环境变量，然后重新打开 /model。

写入的文件

文件	用途
~/.stepcode/models.json	provider 和模型配置（不含 key）
~/.stepcode/auth.json	API key（合并写入，保留其他凭据）
~/.stepcode/agent/models-dev-imports.json	导入记录，用于精确移除
~/.stepcode/agent/models-dev-cache.json	models.dev 目录缓存

注意：当前 StepCode 版本把 models.json / auth.json 放在配置根目录（~/.stepcode/），而不是 ~/.stepcode/agent/。插件会按照 StepCode 自己的 resolveStepConfigRoot() 规则自动定位。

映射规则

• models.dev 的 api 字段直接作为 baseUrl。
• 没有 api 字段的常见 provider 使用内置 endpoint 映射（OpenAI、Anthropic、Google、Groq、Mistral、xAI、Cerebras、Together、DeepInfra、Perplexity、Vercel、Cohere 等）。
• API 方言由 provider 的 npm 字段推断：
  • @ai-sdk/anthropic → anthropic-messages
  • @ai-sdk/google → google-generative-ai
  • @ai-sdk/openai → openai-completions / openai-responses
  • 其余 OpenAI 兼容 provider → openai-completions
• 第三方 OpenAI 兼容服务默认使用安全兼容项：
  • supportsDeveloperRole: false
  • maxTokensField: "max_tokens"
• 对 DeepSeek、Z.AI、Qwen/DashScope、Together、Baseten、OpenRouter 自动设置对应的 thinkingFormat。
• reasoning_options 里的 effort 值会映射到 StepCode 的 thinkingLevelMap；不支持的 level 用 null 隐藏。
• cost.tiers / context_over_200k 会映射成 StepCode 的 inputTokensAbove 阶梯价格。

限制

以下 provider 需要 StepCode 没有在 models.json 里建模的特殊认证或端点，插件会把它们标记为 unsupported，并说明原因：

• Amazon Bedrock（AWS SigV4）
• Azure OpenAI / Azure Cognitive Services
• Google Vertex AI
• Cloudflare AI Gateway
• GitLab Duo
• SAP AI Core
• watsonx.ai

这些 provider 仍然可以用内置 provider、手写 models.json 或 provider extension 接入。

models.dev 是社区维护的模型目录，价格和上下文长度可能滞后；导入后可以在 models.json 里继续手动覆盖。

开发

npm install
npm run typecheck
npm test

测试覆盖：

• /providers 参数解析
• models.dev 元数据映射（cost tier、thinking level、vision、filters）
• provider endpoint / env 模板解析
• models.json 合并与精确移除
• auth.json 合并（保留 OAuth 凭据）
• 目录缓存与网络失败回退

已验证

在 StepCode 0.1.6 上验证：

• /providers add deepseek --all 写入 ~/.stepcode/models.json。
• step --list-models 能看到导入的 deepseek/deepseek-flash 和 deepseek/deepseek-v4-pro。
• /providers remove deepseek --yes 能干净移除导入的模型，同时保留 auth.json 里的 key。

最近修复

• API key 输入框支持终端 bracketed paste（包括分多次到达的粘贴内容）和普通多行粘贴。
• 内置 provider 优先使用 StepCode 的规范环境变量，例如 xiaomi-token-plan-cn 使用 XIAOMI_TOKEN_PLAN_CN_API_KEY，避免 models.dev 的 XIAOMI_API_KEY 与内置认证不匹配。
• 已有的错误 env 引用会在下次启动或执行 /providers 时自动修正。
• /providers list 会显示环境变量是否已设置，例如 $XIAOMI_TOKEN_PLAN_CN_API_KEY (not set)。