add-model-provider

添加模型提供商

提供一种用户可配置、可识别并能通过受支持的 API 路径使用的提供商。本技能还包括提供商文档工作流。

以下路径均相对于开源仓库根目录。在 Cloud 检出中，请在路径前加上 lobehub/，并遵循父仓库的安装和 Git 规则。托管模型配置属于单独的工作流：如果目标是托管模型，请使用部署运营方的模型接入流程。请勿将私有部署设置或路由信息复制到本技能或 OSS 变更中。

对于仅涉及文档的请求，请检查已实现的配置并遵循提供商文档；不要仅为满足此清单而添加运行时代码。

对于现有提供商的纯模型请求，请遵循 model-bank-metadata 中关于 knowledgeCutoff、family 和 generation 的说明，并采用其中针对单个模型的指导，而不是扫描整个仓库。对于其他模型卡字段（包括能力、价格和上下文限制），请使用以下研究方法并进行针对性验证。除非所请求的模型暴露出这些路径中已确认的缺口，否则跳过新增提供商注册、身份验证配置和提供商列表重新排序。

确定集成规范

• 区分新增提供商与向现有提供商添加模型。记录稳定的提供商 ID、显示名称、模型 ID、身份验证方式、端点和支持的 API 模式。文件名或导出名称的大小写可能与小写的提供商 ID 不同；请以实际使用方为准。
• 阅读官方公告、API 参考、模型目录、定价和迁移说明。记录功能、限制和定价信息的来源 URL 及访问日期。除了文档，也要搜索公告：参数变更往往只出现在发行说明中。如果抓取的页面只是空白的客户端渲染框架，请使用可渲染页面的浏览器。
• 验证实际要集成的端点。模型宣称具备某项能力，并不能证明兼容端点支持其搜索参数、工具、图像或结构化输出。不要将第三方端点或其凭据描述为提供商的官方 API。
• 对于本地服务或桌面应用，请阅读本地提供商集成。分别验证启动模式、已安装模型发现、浏览器访问和能力刷新；仅有一个兼容 OpenAI 的模型列表，并不能证明这些行为都受支持。
• 根据协议和身份验证方式，对比最新的提供商新增实现与最接近的现有实现。阅读它们的差异，而不只是文件列表。集成图和先例列出了注册链路和不同示例；历史上的遗漏并不意味着应该照做。
• 根据证据设置模型元数据：准确的 ID、系列／代际、上下文和输出限制、已知的发布日期／知识截止日期、能力、扩展参数、搜索行为、定价币种和计价单位。区分 API 用量价格与订阅权益、缓存输入与普通输入，以及当前促销价与标价。未知信息应标记为未知，不要编造数值；保留现有受支持的模型。

实现提供方

追踪从设置到配置再到运行时的请求流程时，请参考 集成映射与先例。

1. 注册提供方 ID、提供方卡片、单独的模型卡片、模型导入／映射／导出，以及包子路径导出。对于单独的模型库是事实来源的现代提供方卡片，保留 chatModels: []。
2. 如果提供方能保证某个模型可用，请设置可用的静态 checkModel。否则，省略该项，让用户从获取到的本地列表中选择并保存连接检查模型；不要在卡片中填入随意的示例。准确设置身份验证、模型获取、SDK 系列和浏览器请求相关选项。如果 API 没有模型列表端点，静态模型目录可能是正确选择。在依赖顶层或嵌套的浏览器请求标志之前，先追踪这两者的使用方。
3. 复用合适的运行时工厂或适配器。注册运行时及其公共导出。如果提供方需要独立的路由 API 适配器，也要接入 RouterRuntime API 类型和基础运行时映射；仅注册提供方并不能建立这条路径。
4. 分别验证流式聊天、非流式聊天和结构化生成的协议选择。仅支持 Responses 的提供方可能需要同时配置聊天和 generateObject，并防止调用方选择不受支持的模式。仅映射受支持的工具、搜索、响应格式和推理功能。切勿仅因为同系列的其他提供方支持某项功能，就启用该功能。
5. 添加适合该提供方的身份验证／配置接入。对于 API 密钥提供方，同时检查环境架构和运行时绑定，然后检查通用服务端配置和运行时初始化。OAuth 提供方应接入授权、刷新、断开连接和账户元数据路径，而不是臆造 API 密钥变量。
6. 对于新的用户可见参数，追踪模型卡片类型、已存储的聊天配置、控件、请求解析器和翻译。如果现有参数定义的语义匹配，优先复用。若推理状态必须跨多个轮次保留，应通过真实的流式／非流式路径测试序列化和重放，而不只是测试初始请求。

只有在确认存在问题时，才修改共享工厂或错误处理器。此清单不要求修改列出的每个文件。

品牌、排序与文档

• 在 @lobehub/icons 中分别检查服务商和模型图标：服务商品牌和模型系列可能需要不同的图稿。检查实际的模型 ID 匹配器，包括前缀、大小写变体，以及与现有模型名称的冲突。更改匹配器时，验证新的 ID，并保留旧系列的匹配规则。
• 如果缺少图标，请确认缺失的资源或映射，并在授权范围内准备合适的更改或明确的回退方案。不要悄悄使用不相关的品牌图标。提交外部图标 PR 或发布版本属于单独的授权操作；在声称 UI 问题已修复前，请确认使用方安装的版本包含预期映射。
• 在 DEFAULT_MODEL_PROVIDER_LIST 中有意安排服务商的位置；此数组控制默认列表顺序，不控制导入或枚举声明。遵循以下排序原则：
  • 将社区受欢迎程度更高的服务商排在更靠前的位置。依据当前的采用情况和生态认知度，而不是字母顺序、实现便利性或臆造的数值受欢迎程度评分。
  • 将本地模型管理器和推理服务放在一起，例如 Ollama、LM Studio、vLLM 和 Unsloth Studio。
  • 将路由器／聚合服务放在一起：这类服务通过统一 API 提供多个上游服务商的模型，例如 OpenRouter 和 AIHubMix。仅使用内部的 RouterRuntime 抽象并不足以将服务商归入此组。
  • 分组连续性优先于严格按受欢迎程度逐个排序。使用社区受欢迎程度来安排分组和独立服务商的位置，以及组内服务商的顺序。保留用户明确指定的位置和已有的用户自定义顺序。
  • 将新服务商插入合适的分组，不要重新排序无关服务商。若用户要求进行更广泛的排序整理，可以一并移动受影响的同组服务商。
• 按照 服务商文档 提供双语使用／设置说明、环境变量说明、现有 Docker 配置、安全示例和屏幕截图。确保 UI 和文档中的公开服务商身份以及实际凭据／端点要求保持一致。
• 在 locales/en-US/providers.json 和 locales/zh-CN/providers.json 中添加 <provider-id>.description，作为服务商的描述。packages/locales/src/default/providers.ts 中的默认命名空间由服务商卡片生成；不要在其中重复添加描述。为其他新文案遵循仓库惯例，并验证回退行为。对于少量服务商键，避免运行全仓库翻译任务。

验证用户路径

使用现有的提供商测试工具（packages/model-runtime/src/providerTestUtils.ts）和针对性的软件包测试。覆盖受支持的行为，而不是断言注册字符串是否存在：

• 提供商／模型查找能够解析新增的卡片和运行时；连接检查使用受支持的模型。
• 请求选择预期的 API 模式和端点，携带正确的身份验证信息，转换受支持的参数，并保留工具调用和结构化结果。在支持的情况下，测试流式和非流式路径。
• 缺少／无效凭据、模型获取失败和连接错误应生成有用的本地化消息，而不是原始代码或翻译键。对于旧版／无效的线路负载，应使用合成 HTTP 响应进行测试，不要将其强制转换为更严格的当前响应类型。
• 触发连接失败并展开其详情：错误必须能在设置页面中恢复。连接成功无法测试延迟加载的错误组件或它们共享的 UI 上下文。
• 提供商设置页面和模型行应在浅色／深色主题中显示预期的名称、图标、功能和默认顺序。文案有变更时，检查英文和中文。在实际 UI 中检查提供商和模型图标。
• 更改共享运行时错误或延迟加载的命名空间时，检查 Workbench 等其他受影响的界面。即使主应用已加载某个命名空间，其单独的语言包也可能需要该命名空间。

运行所属代码库的质量检查命令和相关软件包测试。对于在 Cloud 中开发的 OSS PR，还要验证 OSS 类型检查／构建环境：父级类型检查通过，并不能证明独立的 OSS 配置也能通过。单独归因工作区解析失败；不要为了制造通过结果而移除有效检查。

对于经授权的在线检查，使用代码库的验收工作流。不要读取机密文件，不要将凭据放入日志／屏幕截图，不要伪造屏幕截图，也不要声称基于模拟结果成功完成推理。如果无法获取在线凭据或访问权限，请准确报告未经验证的路径以及已完成的离线检查。

如果交付内容包含 PR，请遵循代码库的提交／PR 工作流，并持续监控当前头部提交的 CI 和部署。归因失败，修复范围内的问题，完成验证并推送，然后继续跟进，直至检查完成或遇到明确的阻碍。保留适用的独立审查门槛和仅限人工操作的合并规则。报告行为变更、验证情况、证据和剩余限制。