qwen-code Auth Provider Registry：以 Provider 为统一抽象重构 API Key、OAuth 与订阅套餐认证体系

qwen-code Auth Provider Registry：以 Provider 为统一抽象重构 API Key、OAuth 与订阅套餐认证体系

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

导读

本文基于 qwen-code 仓库中的 auth/motivation.md 设计文档，系统讲解 Qwen Code 认证模块的一次关键重构：把原本各自独立的 API Key、OAuth、订阅套餐（Coding Plan / Token Plan）与自定义 Provider 设置流程，统一收敛到「Provider 配置 + ProviderInstallPlan 安装计划」这一共享抽象之上。读完本文，你将掌握ProviderConfig声明式契约的字段语义、buildInstallPlan如何把用户输入翻译成唯一可被设置写入器理解的安装计划、applyProviderInstallPlan的分步落盘与回滚机制，以及如何通过新增一个 provider preset 文件为项目贡献一个新的内置第三方提供商。

一、重构动机：从「各自为政的认证流程」到「统一的 Provider 抽象」

重构前的认证模块把每一条配置路径都建模为独立的流程：API Key 是一种、OAuth 是一种、订阅套餐又是一种、自定义 Provider 还是一种。但在实践中，所有这些路径产出的最终结果完全相同——都是对用户~/.qwen/settings.json中 provider 配置的更新。

因此这次重构把Provider 设置提升为共享抽象：一个 provider 描述它如何被展示、如何收集凭据、会安装哪些模型、以及应该应用哪份 settings 补丁。API Key、OAuth、Coding Plan、Token Plan、自定义向导，本质上都是某个 provider 的设置方法（setup methods），而不是独立的认证架构。

从当前仓库的实际代码布局看，这套抽象最终落在 packages/core/src/providers/ 目录（设计文档中的路径为packages/cli/src/auth/，实现时下沉到 core 包以便 CLI、VS Code 插件、Web Shell 等多端复用），结构为：

packages/core/src/providers/ ├── all-providers.ts # Provider 注册表与查找函数 ├── provider-config.ts # buildInstallPlan、模型构建、元数据版本计算 ├── types.ts # ProviderConfig / ProviderSetupInputs / ProviderInstallPlan 等类型 ├── install.ts # applyProviderInstallPlan 设置写入器 ├── model-discovery.ts # 从 /models 拉取账户模型推荐 └── presets/ ├── alibaba-coding-plan.ts ├── alibaba-token-plan.ts ├── alibaba-standard.ts ├── deepseek.ts ├── grok.ts ├── idealab.ts ├── minimax.ts ├── modelscope.ts ├── moonshot.ts ├── openrouter.ts ├── requesty.ts ├── zai.ts └── custom-provider.ts

重构目标（Goals）

• 保持/auth用户流程易于理解：包括 Alibaba ModelStudio（第一方 Qwen 设置）、DeepSeek / MiniMax / Z.AI 等常见内置第三方集成、OpenRouter 等 OAuth Provider，以及面向本地服务器、代理或未内置 provider 的自定义入口。
• 把 provider 特有数据下沉到小型声明式配置：每个 provider 的展示信息、协议、凭据键、模型清单全部声明化。
• 让第三方 provider 贡献变得简单：增加一个常见 provider 通常只需「新增一个 provider 配置 + 测试」。
• 通过ProviderInstallPlan与applyProviderInstallPlan集中化 settings 写入。
• UI 分组与安装行为解耦：分组只为用户在/auth中导航服务，不驱动设置逻辑。
• 保留模型列表归属（model ownership）与 provider 元数据的路径，使 provider 模型更新可以被检测并安全应用。

二、核心抽象：ProviderConfig 声明式契约

ProviderConfig是内置 provider 的声明式契约，定义于 packages/core/src/providers/types.ts。它聚合了：provider 标签、协议、base URL 选项、环境变量键、模型列表、模型元数据、UI 分组与设置行为。字段语义如下：

一个真实的内置 provider 示例：Z.AI

文档中特别强调「Z.AI 必须使用 setup 专属的 base URL」，这在 packages/core/src/providers/presets/zai.ts 中得到了精确落实——通过BaseUrlOption[]让用户在设置界面二选一：

export const zaiProvider: ProviderConfig = { id: 'zai', label: 'Z.AI API Key', description: 'Quick setup for Z.AI models', protocol: AuthType.USE_OPENAI, baseUrl: [ { id: 'standard-api-key', label: 'Standard API Key', url: 'https://api.z.ai/api/paas/v4', documentationUrl: 'https://docs.z.ai/', }, { id: 'coding-plan', label: 'Coding Plan', url: 'https://api.z.ai/api/coding/paas/v4', documentationUrl: 'https://docs.z.ai/', }, ], envKey: 'ZAI_API_KEY', models: [ { id: 'GLM-5.2', contextWindowSize: 1000000, enableThinking: true }, { id: 'GLM-5.1', contextWindowSize: 204800, enableThinking: true }, { id: 'GLM-5', contextWindowSize: 204800 }, { id: 'GLM-5-Turbo', contextWindowSize: 204800 }, ], modelsEditable: true, modelNamePrefix: 'Z.AI', uiGroup: 'third-party', };

可以看到：Coding Plan指向https://api.z.ai/api/coding/paas/v4，Standard API Key指向https://api.z.ai/api/paas/v4，与设计文档完全一致。

另一处示例：Alibaba Coding Plan 的专属校验

alibaba-coding-plan.ts 展示了 provider 级校验与地域 base URL 选项的配合——Coding Plan 的 API Key 必须以sk-sp-开头，且中国区与国际区使用不同端点：

envKey: CODING_PLAN_ENV_KEY, // 'BAILIAN_CODING_PLAN_API_KEY' baseUrl: [ { id: 'aliyun', label: 'China (Beijing)', url: 'https://coding.dashscope.aliyuncs.com/v1', ... }, { id: 'alibabacloud', label: 'Singapore (International)', url: 'https://coding-intl.dashscope.aliyuncs.com/v1', ... }, ], validateApiKey: (key) => !key.startsWith('sk-sp-') ? 'Invalid API key. Coding Plan API keys start with "sk-sp-". Please check.' : null,

三、安装计划：buildInstallPlan与applyProviderInstallPlan

设计文档定义了这条核心链路：buildInstallPlan把 provider 配置 + 收集到的设置输入转换为ProviderInstallPlan——这是 settings 写入器唯一需要理解的对象；applyProviderInstallPlan再应用该计划，更新环境设置、modelProviders、选中的 auth 类型、可选的模型选择与 provider 元数据，从而让 settings 持久化与收集输入的 UI 流程彻底解耦。

ProviderInstallPlan 的结构

定义于 types.ts：

export interface ProviderInstallPlan { providerId: ProviderId; authType: AuthType; env?: Record<string, string>; // 例如 { ZAI_API_KEY: 'sk-...' } legacyCredentials?: { apiKey?: string; baseUrl?: string }; modelSelection?: { modelId: string; baseUrl?: string }; modelProviders?: ProviderModelProvidersPatch[]; // 含 authType、models、mergeStrategy、ownsModel providerState?: ProviderInstallState; // 例如 providerMetadata.coding-plan.version display?: { successMessage?: string; nextSteps?: string[] }; }

buildInstallPlan（provider-config.ts）负责把ProviderConfig + ProviderSetupInputs翻译为上述计划，其中包括：

• 解析 envKey 与模型名前缀：envKey与modelNamePrefix都支持「字符串」或「函数」两种形态，函数形态在安装时按实际 protocol / baseUrl 动态求值；
• 构建模型配置：固定模型清单直接映射ModelSpec；可编辑清单则对已知 ID 查表继承元数据、未知 ID 走高级配置；自定义 provider 完全由用户输入的 modelIds + advancedConfig 生成模型，并把enableThinking、multimodal、contextWindowSize、maxTokens翻译进generationConfig（例如extra_body.enable_thinking、reasoning.effort、samplingParams.max_tokens）；
• 空模型保护：模型列表为空时直接抛错No models configured for provider ...；
• 默认模型选择：取第一个模型作为modelSelection.modelId；
• 合并策略：默认prepend-and-remove-owned（新模型前置并移除旧的 owned 模型）。

applyProviderInstallPlan 的分步落盘

applyProviderInstallPlan（install.ts）通过ProviderSettingsAdapter抽象执行写入，完整执行顺序为：

1. backup：settings.backup?.()创建回滚备份；
2. env：写入env.<KEY>并同步process.env。此处有双重防护：一是拒绝清单——NODE_OPTIONS、NODE_PATH、LD_PRELOAD、PATH、HOME、TMPDIR等进程级环境变量一律禁止由安装计划写入（防止代码注入 / PATH 劫持 / home 重定向）；二是遮蔽检测——若 shell 环境或.env文件已存在同名但不同值的变量，会向用户输出警告，提示重启后 shell/.env 值将优先；
3. modelProviders：对每个 patch 按mergeStrategy合并（append直接追加；replace-owned替换 owned 模型；默认prepend-and-remove-owned移除 owned 后前置新模型），写入modelProviders.<authType>；
4. authType：写入security.auth.selectedType；
5. legacyCredentials：按需写入security.auth.apiKey/security.auth.baseUrl；
6. modelSelection：这里有一个关键的保护逻辑——重复应用计划不得悄悄移走用户已选的模型（见源码注释 #5819）：若计划仍然包含当前model.name（且 baseUrl 匹配或为空），则跳过模型切换；真正首次设置才采纳 provider 默认模型。若确实切换，且计划只按模型 ID 选择，会用空字符串墓碑清掉旧model.baseUrl，避免下次启动解析到共享同一模型 ID 的过期 provider；
7. providerState：逐字段写入providerMetadata.<providerId>.<field>（如version、baseUrl）；
8. persist→reloadModelProviders→syncAuthState→refreshAuth→cleanupBackup。

值得强调的是适配器契约中的一条关键警告（见 types.ts 中ProviderSettingsAdapter注释）：CLI 的LoadedSettings适配器每次setValue都会立刻落盘，因此进程中途崩溃可能留下部分写入——这正是backup()/restore()作为回滚路径存在的原因，调用方不能假设「persist 之前磁盘未被触碰」。

失败回滚与结构化错误

整个 try/catch 链路对每一步失败都做了尽力而为的回滚：settings.restore()恢复设置文件备份、还原已改写的process.env原值、把内存中的 runtime providers 恢复为安装前快照（防止refreshAuth失败后会话持有未真正安装成功的 provider）。最终抛出的ProviderInstallError是运行时类（非接口），携带step与authType结构化属性用于诊断，cause保留原始错误，同时保证用户可见的error.message干净可读。

四、用户流程：/auth 的四类入口如何汇聚到同一安装路径

/auth依然呈现多个入口点，但全部收敛到同一条 provider 安装路径：

1. Alibaba ModelStudio（第一方 Qwen 设置）

包含三种子路径，对应三个独立 preset：

• Coding Plan（alibaba-coding-plan.ts）：面向个人开发者、含周配额；环境变量键BAILIAN_CODING_PLAN_API_KEY，提供中国（北京）与新加坡（国际）双区域端点，API Key 以sk-sp-开头并由validateApiKey前置校验；
• Token Plan（alibaba-token-plan.ts）；
• Standard API key（alibaba-standard.ts）。

Coding Plan preset 还开启了supportsModelDiscovery: true，可从 ModelStudio 的/models接口拉取账户当前可用的模型推荐，并支持 image / video 多模态（如qwen3.5-plus、qwen3.6-plus的modalities: { image: true, video: true }）。

2. 第三方 Provider（内置默认配置的常见提供商）

• 每个 provider 拥有自己的 base URL、env key、默认模型与模型元数据；
• 当前注册表（all-providers.ts 的ALL_PROVIDERS）内置：DeepSeek、Grok、MiniMax、Z.AI、Moonshot、IdeaLab、ModelScope、OpenRouter、Requesty 等；
• Z.AI 必须使用 setup 专属 base URL：Coding Plan 为https://api.z.ai/api/coding/paas/v4，Standard API key 为https://api.z.ai/api/paas/v4（已在上文 preset 源码中验证）。

3. OAuth（浏览器授权）

面向 OpenRouter 等路由平台的浏览器授权流程。OAuth 专属机制可以留在 provider 实现内部，但最终产物仍然是一份 provider install plan——这正是「OAuth 只是 provider 的一种设置方法」这一核心论点的体现。

4. 自定义 Provider（本地服务器 / 代理 / 未内置提供商）

见 custom-provider.ts：

export const customProvider: ProviderConfig = { id: 'custom-openai-compatible', label: 'Custom Provider', description: 'Manually connect a local server, proxy, or unsupported provider', protocol: AuthType.USE_OPENAI, protocolOptions: [ AuthType.USE_OPENAI, AuthType.USE_OPENAI_RESPONSES, AuthType.USE_ANTHROPIC, AuthType.USE_GEMINI, ], baseUrl: undefined, envKey: generateCustomEnvKey, models: undefined, modelNamePrefix: '', showAdvancedConfig: true, ownsModel: (model) => typeof model.envKey === 'string' && model.envKey.startsWith(CUSTOM_API_KEY_ENV_PREFIX), mergeModelsByIdentity: true, uiGroup: 'custom', };

向导依次收集协议（四选一）、base URL、API Key、模型 ID，以及高级模型选项（thinking、多模态输入、上下文窗口、max tokens）。两个实现细节值得注意：

• 派生环境变量键：generateCustomEnvKey把(protocol, baseUrl)的 SHA-256 摘要前 12 位十六进制（48 位）作为后缀，形如QWEN_CUSTOM_API_KEY_<PROTOCOL>_<NORMALIZED_URL>_<12HEX>，避免结构不同的端点互相覆盖 API Key，同时保持变量名可读、可粘贴进面板；
• 按身份合并：mergeModelsByIdentity: true使/auth可以新增另一个自定义模型，而不会删除同一端点下其他模型的既有配置。

五、模型归属（Model Ownership）与更新检测

设计文档对模型更新的要求是：静态内置 provider 可以把元数据持久化在providerMetadata.<providerId>下（含模型列表版本与 base URL），从而在 provider 内置模型列表变化时提示用户更新 owned 模型，同时不覆盖用户无关的自定义模型；自定义 provider 的模型列表是用户自撰写的，不应被视为可自动更新的内置列表。

源码中的实现（provider-config.ts）：

• PROVIDER_METADATA_NS = 'providerMetadata'是元数据命名空间前缀，例如providerMetadata.coding-plan.version；
• computeModelListVersion对模型配置 JSON 做SHA-256 哈希，作为模型列表版本指纹；每次安装时写入providerMetadata.<id>.version与providerMetadata.<id>.baseUrl；
• resolveMetadataKey只对带静态models列表的 provider 返回元数据键，并拒绝含.的 provider id——因为setValue采用点路径遍历，providerMetadata.foo.bar会被拆成嵌套对象导致设置树被悄悄破坏，因此在注册期就显式抛错；
• 自定义 provider（models: undefined）不产生元数据键，天然不会被当作可自动更新的内置模型列表；
• UI 侧通过useProviderUpdates（packages/cli/src/ui/hooks/useProviderUpdates.ts）比对已保存版本与模板版本，触发用户可感知的模型更新提示。

归属判定则依靠ownsModel：预设默认由envKey+modelNamePrefix推导（模型须envKey相同且名称以[<prefix>]开头）；Coding Plan 等复杂预设自定义为「envKey 匹配且 baseUrl 属于中国区/国际区之一」；自定义 provider 则以环境变量键前缀QWEN_CUSTOM_API_KEY_识别。findProviderByCredentials（all-providers.ts）正是利用providerMatchesCredentials在/doctor、system-info 诊断中反查 provider。

六、非目标（Non-goals）与贡献边界

设计文档明确了四条红线，用于约束后续演进方向：

1. 不把 API Key、OAuth、Coding Plan、Token Plan 提升为顶层 settings 架构——它们只是 provider 的设置方法；
2. 不让 settings 写入耦合到 React 组件或 CLI 命令处理器——统一经由applyProviderInstallPlan+ProviderSettingsAdapter；
3. 不让 UI 分组成为业务逻辑轴——uiGroup只服务于/auth导航（ALIBABA_PROVIDERS/THIRD_PARTY_PROVIDERS分组见 all-providers.ts）；
4. 不要求贡献者理解完整 auth UI 才能添加简单第三方 provider。

这意味着贡献一个新内置 provider 的标准动作是：在 presets/ 新增一个声明式ProviderConfig文件 → 在 all-providers.ts 的ALL_PROVIDERS注册 → 在tests/presets/ 补上对应测试（现有 DeepSeek、MiniMax、Z.AI、Grok、Moonshot、IdeaLab、OpenRouter、Requesty 等均遵循此模式）。另外，若新 provider 从新环境变量键读取凭据，还需按 all-providers.ts 头部注释的要求，把该键加入 CI 无 AK 门禁的清除列表（.github/workflows/ci.yml与scripts/tests/no-ak-integration-ci.test.js），防止门禁泄漏 runner 凭据。

安装与合并行为本身由tests/install.test.ts 与tests/provider-config.test.ts 覆盖，包括合并策略、回滚、模型选择保留、元数据版本等核心语义。

结语

Auth Provider Registry 重构的实质，是把「认证」从一组平行的 UI 流程，收敛为「声明式 provider 配置 → 安装计划 → 统一设置写入器」的三段式管道。ProviderConfig让第三方贡献者只需描述「provider 长什么样、凭据怎么收、模型装哪些」，ProviderInstallPlan让设置持久化与 UI 彻底解耦，而applyProviderInstallPlan通过拒绝清单、遮蔽检测、分步回滚与版本化元数据，为设置写入提供了可靠性与安全性兜底。这套设计不仅适用于当前 Qwen Code 的/auth界面，也同时服务于 CLI、ACP 重连、VS Code 插件等所有需要安装 provider 的入口，是理解项目认证与模型配置体系的枢纽。

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code