AIClient-2-API/PROVIDER_ADAPTER_GUIDE.md

AIClient2API Provider 接入指南

本文档详细说明了如何向 AIClient2API 项目接入全新的模型提供商（Provider），涵盖从后端核心逻辑到前端 UI 管理的全流程调整。

1. 接入流程概览

1. 后端常量定义：在 src/utils/common.js 中添加标识。
2. 核心 Service 开发：在 src/providers/ 实现 API 请求逻辑。
3. 适配器注册：在 src/providers/adapter.js 注册。
4. 模型与号池配置：在 src/providers/provider-models.js 和 src/providers/provider-pool-manager.js 配置。
5. 前端 UI 全方位调整：
   • static/app/provider-manager.js：号池显示与顺序。
   • static/app/file-upload.js：上传路径映射。
   • static/components/section-config.html：配置按钮。
   • static/components/section-guide.html：使用指南。
6. 系统级映射（必做）：在 OAuth 处理器、凭据关联工具、用量统计等模块中建立映射。

---

2. 后端核心实现

2.1 定义常量

修改 src/utils/common.js，在 MODEL_PROVIDER 中添加新 key（格式建议：协议-名称-类型）。

2.2 核心 Service (Core)

在 src/providers/ 下创建新目录并实现 NewProviderApiService 类。 必选方法：constructor(config), initialize(), listModels(), generateContent(), generateContentStream()。

2.3 注册适配器

在 src/providers/adapter.js 中继承 ApiServiceAdapter，并在 getServiceAdapter 工厂方法中添加 switch 分支。

2.4 模型与号池默认配置

• 模型列表：在 src/providers/provider-models.js 的 PROVIDER_MODELS 对象中添加默认支持的模型 ID。
• 健康检查默认值：在 src/providers/provider-pool-manager.js 的 DEFAULT_HEALTH_CHECK_MODELS 中指定用于健康检查的默认模型。

---

3. 前端界面调整

3.1 号池显示逻辑 (static/app/provider-manager.js)

• 显示顺序：将新标识添加到 providerDisplayOrder 数组。
• 授权按钮：若支持 OAuth，在 generateAuthButton 的 oauthProviders 数组中添加标识。
• 路径提示：在 getAuthFilePath 中返回凭据文件的默认建议路径。

3.2 凭据上传路由 (static/app/file-upload.js)

• 修改 getProviderKey，建立提供商标识与 configs/ 子目录名的映射（例如：new-provider-api -> new-provider）。

3.3 凭据文件管理筛选器

需要在以下三个位置添加新提供商的筛选支持：

3.3.1 HTML 筛选器选项 (static/components/section-upload-config.html)

在 id="configProviderFilter" 的 <select> 元素中添加新的 <option>：

<option value="new-provider-type" data-i18n="upload.providerFilter.newProvider">New Provider OAuth</option>

3.3.2 JavaScript 提供商映射 (static/app/upload-config-manager.js)

在 detectProviderFromPath() 函数的 providerMappings 数组中添加映射关系：

{
    patterns: ['configs/new-provider/', '/new-provider/'],
    providerType: 'new-provider-type',
    displayName: 'New Provider OAuth',
    shortName: 'new-provider-oauth'
}

3.3.3 多语言文案 (static/app/i18n.js)

在中文和英文的翻译对象中添加筛选器文案：

// 中文版本 (zh-CN)
'upload.providerFilter.newProvider': 'New Provider OAuth',

// 英文版本 (en-US)
'upload.providerFilter.newProvider': 'New Provider OAuth',

3.4 配置管理界面 (static/components/section-config.html)

• 必须添加：在 id="modelProvider"（初始化提供商选择）容器中添加对应的 provider-tag 按钮。
• 可选添加：在 id="proxyProviders"（代理开关）中同步添加。

3.5 指南与教程 (static/components/section-guide.html)

• 在"项目简介"和"客户端配置指南"中添加新提供商的调用示例（如 {provider}/v1/chat/completions）。

---

4. 全局系统映射 (关键)

为确保新提供商的功能完整（如多账号自动切换、用量监控），必须在以下位置建立映射：

4.1 凭据路径键名映射 (src/services/service-manager.js)

在 getServiceAdapter 逻辑相关的 credPathKey 映射中，指定该提供商对应的配置文件路径键名。

4.2 自动关联工具 (src/utils/provider-utils.js)

在 CONFIG_FILE_PATTERNS 数组中添加配置，以便系统能根据文件路径自动识别并关联凭据：

{
    patterns: ['configs/new-dir/', '/new-dir/'],
    providerType: 'new-provider-api',
    credPathKey: 'NEW_PROVIDER_CREDS_FILE_PATH'
}

4.3 用量统计映射 (src/ui-modules/usage-api.js)

• 将标识添加到 supportedProviders 数组。
• 在 credPathKey 映射中添加路径键名，以便前端能展示每个账号的配额/用量。

4.4 OAuth 处理器 (src/ui-modules/oauth-api.js)

若支持 OAuth，需在 handleGenerateAuthUrl 中分发到相应的认证处理器。

---

5. 注意事项

1. 协议对齐：本项目内部默认使用 Gemini 协议。若上游为 OpenAI 协议，需在 src/convert/ 实现转换。
2. 安全：不要在 Core 代码中硬编码 Key，始终从 config 中读取动态注入的凭据。
3. 异常捕获：Core 代码必须抛出标准错误（包含 status），以便号池管理器识别并自动隔离失效账号。