Win-CodexBar 开发者指南：如何从零添加一个全新的 AI Provider 并注册到工厂

Win-CodexBar 是一款 Windows 原生桌面工具，无需登录即可在系统托盘实时显示 OpenAI Codex、Claude Code 等 AI 服务的用量额度。本文是一份面向贡献者的开发者指南，用 6 个步骤带你从零添加一个全新的 AI Provider，并将其注册到统一的 Provider 工厂，让新数据源自动出现在托盘面板和设置界面中。

先懂架构：为什么 Win-CodexBar 的 Provider 设计如此简单

Win-CodexBar 采用"单一工厂"（Single Factory）架构：无论是桌面应用还是命令行工具，所有 Provider 实例都必须通过同一个工厂函数创建，严禁在别处重复造工厂。整个体系由三层构成：

数据流向非常直观：instantiate_provider→Provider::fetch_usage→ 壳层缓存 → 事件推送 → React 前端渲染。详见 docs/ARCHITECTURE.md 和官方说明 docs/PROVIDERS.md。

🔑最大红利：工厂的 match 是穷尽匹配——你在ProviderId里加了一个变体却没接进工厂，代码会直接编译失败，编译器替你兜底，漏注册几乎不可能发生。

从零添加全新 AI Provider 的 6 个步骤

以新增一个假想的MyAI服务为例，完整流程如下。

第 1 步：在 ProviderId 枚举中登记身份

打开 rust/src/core/provider.rs，在ProviderId枚举中加入MyAI变体，并按需补齐四个元数据方法：

• all()：全量 ID 列表（测试依赖它遍历）
• cli_name()：命令行中使用的短名，如"myai"
• display_name()：界面显示名，如"MyAI"
• cookie_domain()：若该服务靠浏览器 Cookie 鉴权则填域名，纯 API Key 服务填None

如果用户可能用别名调用（比如codex同时接受openai），在from_cli_name()中补充别名分支即可。

第 2 步：实现 Provider trait 的三个必备方法

在 rust/src/providers/ 下新建myai/mod.rs模块。Rust 侧的核心契约是Providertrait（定义见此），绝大多数方法都有默认实现，你只需实现三个必备方法：

1. id()— 返回ProviderId::MyAI
2. metadata()— 返回ProviderMetadata，包含显示名、会话/周窗口标签、是否默认启用、仪表盘链接等
3. fetch_usage()— 核心抓取逻辑：按ctx.source_mode（Auto/OAuth/Web/Cli）分发，请求远端接口，解析 JSON，最终构造UsageSnapshot返回

建议参考两个真实实现学习写法：

• 纯 API Key 型（最简洁）：rust/src/providers/zai/mod.rs
• API + 浏览器 Cookie 双通道型：rust/src/providers/venice/mod.rs

⚠️ 关键原则：把该服务的解析、鉴权逻辑全部封装在自己的模块内，不要在共享代码路径里写跨 Provider 的if myai分支。

第 3 步：在 providers/mod.rs 注册模块

打开 rust/src/providers/mod.rs，补两行声明——注册模块 + 重导出实现类型：

pub mod myai; pub use myai::MyAIProvider;

若服务需要浏览器 Cookie，ProviderId的cookie_domain()已填好域名后，可直接复用共享的browser_cookie_candidates_for_domain等辅助函数（rust/src/providers/mod.rs），无需自己解析 Cookie 文件。

第 4 步：注册到工厂——整个流程的核心

打开 rust/src/core/provider_factory.rs，在instantiate()的 match 中追加一个分支：

ProviderId::MyAI => Box::new(MyAIProvider::new()),

这就是"注册到工厂"的全部动作。由于 match 穷尽匹配，漏掉这一步会直接编译报错；反之，只要这里能编译通过，CLI 和桌面应用就同时自动支持了你的新 Provider——因为两者共用这一个工厂。

另外检查同文件的pace_capability()：如果你的服务没有"重置窗口节奏"这类高级规则，把ProviderId::MyAI加进UNSUPPORTED的长列表即可（第 167–249 行的大匹配臂）。

第 5 步：前端图标与目录注册

让新 Provider 在界面上有名字和图标，需注册两处：

• 图标注册表apps/desktop-tauri/src/components/providers/providerIcons.ts：在PROVIDER_ICON_REGISTRY中加一条{ id, brandColor, fallbackLetter, svgPath }。没有 SVG 时可只填品牌色 + 回退字母（如azureopenai的写法），SVG 图标放在 icons/ 目录。品牌色需与 Rust 侧 brand_color() 保持一致，有测试强制校验。
• 测试目录apps/desktop-tauri/src/test/providerCatalog.ts：加入["myai", "MyAI"]。这个目录被托盘面板、图标一致性等多个测试引用，加上新条目后测试会自动覆盖它。

第 6 步：跑测试并在托盘面板中验证

在仓库根目录运行：

# Rust 后端：工厂自测 + 你的模块测试 cargo test --manifest-path rust/Cargo.toml # 前端（apps/desktop-tauri 目录下，用 pnpm 而非 npm） pnpm test

其中 every_provider_id_is_instantiable 会遍历所有ProviderId逐一实例化并校验返回的id()一致——你的新 Provider 必须通过它。

构建后启动应用，在 设置 → Providers 页面能看到MyAI的配置入口：

点击托盘图标，新 Provider 的用量额度就会出现在托盘面板中，与其他服务并列显示进度条和重置时间：

添加 AI Provider 的常见坑与最佳实践清单

• ✅只走工厂：永远通过instantiate()创建 Provider，绝不在 Tauri 壳层或 CLI 里手写match复制一份
• ✅逻辑隔离（siloed）：身份、套餐、邮箱等展示信息按 Provider 独立，共享 UI 不做特殊分支
• ✅错误要分类：401/403 返回ProviderError::AuthRequired，缺凭据返回NotInstalled，解析失败返回Parse——壳层靠错误类型决定界面提示
• ✅默认禁用：新 Provider 的default_enabled建议设为false，由用户在设置中手动开启
• ❌避免：在fetch_usage里静默吞掉未知字段——格式无法解析时明确报错，而不是编造一个 0% 的额度

📌 完整构建与本地检查流程见 docs/BUILDING.md，本地 CI 一键检查脚本为scripts/local-check.ps1。

关键文件速查表

掌握以上 6 步，你已具备向 Win-CodexBar 贡献任意新 AI 服务数据源的完整能力——从接口探索、Rust 模块实现到工厂注册、前端展示，一条清晰的链路贯穿始终。