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

【免费下载链接】Win-CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login. But for Window-Native项目地址https://gitcode.com/gh_mirrors/wi/Win-CodexBar点击查看免费下载Win-CodexBar 是一款 Windows 原生桌面工具无需登录即可在系统托盘实时显示 OpenAI Codex、Claude Code 等 AI 服务的用量额度。本文是一份面向贡献者的开发者指南用 6 个步骤带你从零添加一个全新的 AI Provider并将其注册到统一的 Provider 工厂让新数据源自动出现在托盘面板和设置界面中。先懂架构为什么 Win-CodexBar 的 Provider 设计如此简单Win-CodexBar 采用单一工厂Single Factory架构无论是桌面应用还是命令行工具所有 Provider 实例都必须通过同一个工厂函数创建严禁在别处重复造工厂。整个体系由三层构成层文件职责身份层rust/src/core/provider.rsProviderId枚举 CLI 名称 显示名 Cookie 域名实现层rust/src/providers/每个 Provider 一个独立模块封装抓取/解析/鉴权逻辑工厂层rust/src/core/provider_factory.rsinstantiate()把 ID 映射为具体实现match 穷尽匹配数据流向非常直观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()命令行中使用的短名如myaidisplay_name()界面显示名如MyAIcookie_domain()若该服务靠浏览器 Cookie 鉴权则填域名纯 API Key 服务填None如果用户可能用别名调用比如codex同时接受openai在from_cli_name()中补充别名分支即可。第 2 步实现 Provider trait 的三个必备方法在 rust/src/providers/ 下新建myai/mod.rs模块。Rust 侧的核心契约是Providertrait定义见此绝大多数方法都有默认实现你只需实现三个必备方法id()— 返回ProviderId::MyAImetadata()— 返回ProviderMetadata包含显示名、会话/周窗口标签、是否默认启用、仪表盘链接等fetch_usage()— 核心抓取逻辑按ctx.source_modeAuto/OAuth/Web/Cli分发请求远端接口解析 JSON最终构造UsageSnapshot返回建议参考两个真实实现学习写法纯 API Key 型最简洁rust/src/providers/zai/mod.rsAPI 浏览器 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;若服务需要浏览器 CookieProviderId的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。关键文件速查表环节文件路径ID 与元数据rust/src/core/provider.rs工厂注册rust/src/core/provider_factory.rsProvider traitrust/src/core/provider.rs模块注册rust/src/providers/mod.rs参考实现API Keyrust/src/providers/zai/mod.rs参考实现Cookierust/src/providers/venice/mod.rs前端图标apps/desktop-tauri/src/components/providers/providerIcons.ts测试目录apps/desktop-tauri/src/test/providerCatalog.ts官方 Provider 文档docs/PROVIDERS.md掌握以上 6 步你已具备向 Win-CodexBar 贡献任意新 AI 服务数据源的完整能力——从接口探索、Rust 模块实现到工厂注册、前端展示一条清晰的链路贯穿始终。赞分享【免费下载链接】Win-CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login. But for Window-Native项目地址https://gitcode.com/gh_mirrors/wi/Win-CodexBar点击查看免费下载相关推荐5分钟完整导出QQ空间历史说说GetQzonehistory 上手指南5分钟完整导出QQ空间历史说说GetQzonehistory 上手指南 去年写年度复盘我想翻翻自己写的第一条说说。打开 QQ 空间往回翻首页只肯显示前几年网页爬虫数据分析如何为 LibreDB Studio 添加一个新的数据库Provider 开发完整指南开发者必读如何为 LibreDB Studio 添加一个新的数据库Provider 开发完整指南开发者必读 LibreDB Studio 是一款 MIT 开源的浏览Strapi strapi/openapi 包扩展指南如何开发并注册一个自定义 Routes ProviderStrapi strapi/openapi 包扩展指南如何开发并注册一个自定义 Routes Provider 本文以 Strapi 仓库中 strapi后端CMS前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考