Open CoDesign 内置 Atlas Cloud 提供商：OpenAI 兼容接入、密钥校验与模型发现机制解析

• 人工智能
• AI 应用
• 桌面应用

本文围绕仓库变更记录 .changeset/atlascloud-provider.md 展开，系统梳理 Open CoDesign 将 Atlas Cloud 纳入内置（builtin）提供商的全过程：从配置数据结构、首次启动引导（onboarding）、API Key 前缀识别，到/v1/models校验与模型发现，再到openai-chat线协议（wire）下的请求封装。读完本文，你将理解内置提供商在共享配置层（shared）、提供商运行时（providers）与桌面主进程（desktop）三层之间的协作方式，并能据此接入任意 OpenAI 兼容网关。

一、变更内容概览：一次跨包的内置提供商落地

该 changeset 声明了对@open-codesign/shared、@open-codesign/providers、@open-codesign/core、@open-codesign/desktop四个包的patch级修改，核心目标是：

Add Atlas Cloud as a built-in OpenAI-compatible provider for onboarding, validation, model discovery, and provider selection.

即把 Atlas Cloud 作为内置的 OpenAI 兼容提供商接入四条链路：

1. onboarding（首次引导）：用户在向导中可直接选择 Atlas Cloud 并粘贴 API Key；
2. validation（密钥校验）：应用通过其/v1/models端点验证密钥有效性；
3. model discovery（模型发现）：从该端点拉取模型列表填充模型选择器；
4. provider selection（提供商选择）：出现在内置提供商清单与设置页中，可作为活动提供商使用。

从仓库源码看，这一改动主要落实在共享配置层（packages/shared/src/config.ts）与提供商运行时（packages/providers/src/validate.ts、packages/providers/src/index.ts），并配套了对应的单元测试。

二、内置提供商的数据结构：BUILTIN_PROVIDERS

Open CoDesign 把所有内置提供商的静态元数据集中在共享包中，由 Zod schema 强校验。Atlas Cloud 在 packages/shared/src/config.ts 中注册如下：

atlascloud: { id: 'atlascloud', name: 'Atlas Cloud', builtin: true, wire: 'openai-chat', baseUrl: 'https://api.atlascloud.ai/v1', envKey: 'ATLASCLOUD_API_KEY', defaultModel: 'qwen/qwen3.5-flash', capabilities: { supportsKeyless: false, supportsModelsEndpoint: true, supportsReasoning: false, requiresClaudeCodeIdentity: false, modelDiscoveryMode: 'models', }, },

对照同一文件中的ProviderEntrySchema（packages/shared/src/config.ts），各字段含义如下：

默认能力推导逻辑

即便不显式声明capabilities，defaultProviderCapabilities（packages/shared/src/config.ts）也会根据wire、requiresApiKey、modelsHint自动推导：只要wire不是openai-codex-responses且未提供modelsHint，supportsModelsEndpoint即为true，modelDiscoveryMode相应地为'models'。Atlas Cloud 显式声明的内容与推导结果一致，测试在 packages/shared/src/config.test.ts 中对SUPPORTED_ONBOARDING_PROVIDERS、BUILTIN_PROVIDERS.atlascloud与PROVIDER_SHORTLIST.atlascloud逐一断言。

三、Onboarding 引导：短名单、默认模型与密钥前缀识别

3.1 引导短名单

Atlas Cloud 被列入SUPPORTED_ONBOARDING_PROVIDERS（packages/shared/src/config.ts），当前完整名单为：

['anthropic', 'openai', 'atlascloud', 'openrouter', 'ollama']

与之配套的PROVIDER_SHORTLIST.atlascloud（packages/shared/src/config.ts）为引导界面提供展示标签、官方密钥页面与推荐模型：

atlascloud: { provider: 'atlascloud', label: 'Atlas Cloud', keyHelpUrl: 'https://atlascloud.ai/', primary: ['qwen/qwen3.5-flash', 'deepseek-ai/deepseek-v4-pro'], defaultPrimary: 'qwen/qwen3.5-flash', },

用户在首次启动引导中可看到 Atlas Cloud 及其两个推荐模型（默认qwen/qwen3.5-flash）。

3.2 粘贴密钥自动识别提供商

引导流程支持“粘贴密钥自动判断提供商”，实现在detectProviderFromKey（packages/providers/src/index.ts）：

if (key.trim().startsWith('sk-ant-')) return 'anthropic'; if (key.trim().startsWith('sk-or-')) return 'openrouter'; if (key.trim().startsWith('apikey-')) return 'atlascloud'; if (key.trim().startsWith('sk-')) return 'openai'; if (key.trim().startsWith('AIza')) return 'google'; if (key.trim().startsWith('xai-')) return 'xai'; if (key.trim().startsWith('gsk_')) return 'groq';

Atlas Cloud 的密钥以apikey-前缀开头，用户无需手动选择提供商即可被引导到正确的配置流程。

3.3 密钥保存与校验的 IPC 输入校验

桌面主进程的 onboarding 参数解析层（apps/desktop/src/main/onboarding/provider-parsers.ts）对save-key、validate-key等 IPC 载荷做严格白名单字段校验。parseSaveKeyPayload与parseValidateKey均会检查provider是否属于SUPPORTED_ONBOARDING_PROVIDERS，未通过时抛出PROVIDER_NOT_SUPPORTED；密钥非空校验则豁免requiresApiKey === false的内置提供商（如 Ollama），而 Atlas Cloud 必须提供非空密钥。IPC 层转发测试见 apps/desktop/src/main/onboarding-ipc.test.ts。

四、Validation 校验流程：GET /v1/models与错误归类

4.1 端点构造

pingProvider（packages/providers/src/validate.ts）是引导阶段的密钥校验入口。针对 Atlas Cloud，端点规则为（packages/providers/src/validate.ts）：

case 'atlascloud': { const root = baseUrl ? normalizeValidateBaseUrl(baseUrl) : 'https://api.atlascloud.ai'; return { url: `${root}/v1/models`, headers: (apiKey) => ({ authorization: `Bearer ${apiKey}` }), }; }

校验请求携带Authorization: Bearer <apiKey>头发送到https://api.atlascloud.ai/v1/models。normalizeValidateBaseUrl会先剥离/v1尾缀及推理端点后缀（如/v1/chat/completions），避免拼接出/v1/v1/models这类双重路径。测试在 packages/providers/src/validate.test.ts 中模拟了该请求，断言 URL 与 Bearer 头，并期望返回{ ok: true, modelCount: 1 }。

4.2 响应归类与错误码

校验结果通过ValidateResult类型返回（packages/providers/src/validate.ts）：

type ValidateResult = | { ok: true; modelCount: number } | { ok: false; code: '401' | '402' | '429' | 'network' | 'parse'; message: string };

错误归类逻辑（statusToCode与statusMessage，packages/providers/src/validate.ts）：

• 401 / 403→401：密钥无效，提示用户复查；
• 402→402：账户无余额，提示充值或更换提供商；
• 429→429：被限流，提示稍后重试；
• 网络异常 →network；
• 响应体不符合预期结构 →parse。

成功时countModels会同时兼容{ data: [...] }与{ models: [...] }两种响应形态，并逐项校验每个模型条目至少包含字符串类型的id或name，从而保证模型列表可被上层消费。

五、Model Discovery：模型发现模式与配置持久化

5.1 动态模型发现

Atlas Cloud 的modelDiscoveryMode为'models'，意味着应用会直接调用其/v1/models端点拉取最新模型清单，而不是使用静态modelsHint。在 OpenAI 兼容体系中，这通常对应GET {baseUrl}/models，返回形如{ data: [{ id: 'qwen/qwen3.5-flash' }] }的列表。校验成功返回的modelCount同时也可用于给用户展示“检测到 N 个可用模型”。

5.2 v3 配置中的持久化形态

配置以 v3 形态落盘（ConfigV3Schema，packages/shared/src/config.ts）。内置提供商在首次迁移（migrateLegacyToV3）时自动播种：遍历SUPPORTED_ONBOARDING_PROVIDERS并cloneBuiltin每个条目，因此旧版 v1/v2 配置升级后会自动获得 Atlas Cloud 条目（packages/shared/src/config.ts）。运行时会通过providers['atlascloud'].baseUrl读取其地址，secrets['atlascloud']以SecretRef（密文 + 显示掩码）形式保存密钥，密钥明文不会落盘。

六、Wire 层实现：openai-chat下的兼容性处理

6.1 请求路由

complete（packages/providers/src/index.ts）是单次非流式补全的统一入口。它惰性加载@mariozechner/pi-ai，优先通过pi.getModel(provider, modelId)查注册表；查不到时若提供了wire与自定义baseUrl，则由synthesizeWireModel合成一个 PiModel（packages/providers/src/index.ts）。Atlas Cloud 的wire: 'openai-chat'会映射到api: 'openai-completions'适配器，并以https://api.atlascloud.ai/v1作为baseUrl。

6.2 推理（reasoning）启发式判断

synthesizeWireModel通过inferReasoning（packages/providers/src/index.ts）决定是否声明推理能力。对openai-chat线协议：

• 官方 OpenAI 域名（api.openai.com）按模型 ID 前缀（o1/o3/o4/gpt-[56]）判断；
• 第三方 OpenAI 兼容网关按REASONING_MODEL_ID_PATTERN启发式匹配（如claude-opus-4、deepseek-r、:thinking后缀等）。

由于 Atlas Cloud 内置条目的capabilities.supportsReasoning为false，默认不会向该端点声明推理模式，避免部分 OpenAI 兼容网关对developer角色或 reasoning 字段返回 HTTP 400（该问题在源码注释中被记为 issue #183）。openAIChatCompatForBaseUrl（packages/providers/src/index.ts）还会针对 DeepInfra 等已知特殊网关下调supportsDeveloperRole等兼容标志。

6.3 密钥与安全约束

complete起始处会检查密钥：非空密钥去除首尾空白后传入 pi-ai；空密钥仅在allowKeyless === true时才被放行（packages/providers/src/index.ts），而 Atlas Cloud 的supportsKeyless: false意味着必须配置真实密钥。用户自定义的httpHeaders会合并到请求头中，满足网关级自定义鉴权需求。

七、关键证据索引

• 变更声明： .changeset/atlascloud-provider.md
• 内置提供商注册与短名单： packages/shared/src/config.ts、packages/shared/src/config.ts
• 配置测试断言： packages/shared/src/config.test.ts
• 校验端点与错误归类： packages/providers/src/validate.ts
• 校验测试（URL 与 Bearer 头）： packages/providers/src/validate.test.ts
• 密钥前缀识别： packages/providers/src/index.ts
• IPC 载荷解析： apps/desktop/src/main/onboarding/provider-parsers.ts
• IPC 转发测试： apps/desktop/src/main/onboarding-ipc.test.ts

结语

Atlas Cloud 的落地是 Open CoDesign “统一提供商模型”的一个典型切片：共享层用 Zod schema 定义内置条目与能力声明，providers 层负责密钥识别、校验与 OpenAI 兼容请求封装，desktop 层负责 IPC 输入校验与引导流程串联。理解了这一套“注册 → 引导 → 校验 → 发现 → 出站请求”的闭环，你也就掌握了该仓库接入任意 OpenAI 兼容提供商（包括自建网关）的完整方法论。

• 人工智能
• AI 应用
• 桌面应用