Win-CodexBar 架构深度解析:Rust + Tauri + React 三层设计如何撑起 56 个 AI Provider
Win-CodexBar 架构深度解析:Rust + Tauri + React 三层设计如何撑起 56 个 AI Provider
Win-CodexBar 是一款 Windows 原生的 AI 用量监控工具,基于 Rust + Tauri + React 三层架构,无需登录即可在系统托盘实时显示 OpenAI Codex、Claude Code 等 56 个 AI Provider 的额度与花费。本文将带你拆解这套架构:共享 Rust 后端如何用"单一工厂"统一驱动所有 Provider,Tauri 外壳如何管理窗口与并发,React 前端又如何实现多表面路由——理解它,你会收获一套可复用的 Tauri 桌面应用架构设计思路。
🗺️ 整体架构一图看懂
Win-CodexBar 的代码库清晰地分为三层,各自独立成模块:
| 层 | 路径 | 角色 |
|---|---|---|
| 🦀 共享后端 + CLI | rust/(codexbar crate) |
Provider 逻辑、设置存储、浏览器 Cookie 解密、托盘图标、CLI |
| 🪟 桌面外壳 | apps/desktop-tauri/src-tauri/ |
Tauri 2 宿主:托盘、窗口管理、IPC 命令、悬浮条 |
| ⚛️ 前端 | apps/desktop-tauri/src/ |
React 18 + Vite 表面(托盘面板、设置、悬浮条) |
Cargo workspace 的根 Cargo.toml 将两层 Rust 代码声明为工作区成员,其中默认成员是 Tauri 外壳 crate,且外壳直接依赖共享后端:
[workspace]
members = [
"rust",
"apps/desktop-tauri/src-tauri",
]
这个设计的关键收益是:CLI 和桌面应用共用同一套 Provider 代码。codexbar usage 命令行的背后,与 GUI 背后跑的是完全相同的 codexbar crate——一套逻辑,两种入口。完整模块划分见 docs/ARCHITECTURE.md。
Win-CodexBar 的托盘面板正是这套架构的终端呈现——一张紧凑的卡片列表,实时显示各 Provider 的额度消耗与重置时间:
🦀 第一层:Rust 共享后端——56 个 Provider 的统一大脑
Provider 特性与 ID 枚举
所有 AI 服务商在 rust/src/core/provider.rs 中用一个枚举 ProviderId 统一编号。Codex、Claude、Gemini、Cursor、z.ai、MiniMax、Kiro……56 个服务商各占一个变体。这个枚举是整个系统的"总目录":设置、托盘、CLI、前端卡片全都围绕它展开。
每个 Provider 实现都遵循统一的 Provider trait(定义于 rust/src/core/provider.rs),核心职责只有一个:获取用量(fetch_usage)。解析响应、处理认证、计算重置时间等差异化的逻辑,都被约束在各自独立的模块里。
单一工厂模式:新增 Provider 只改三处
整个系统最值得学习的设计是 rust/src/core/provider_factory.rs 中的规范工厂函数 instantiate:
pub fn instantiate(id: ProviderId) -> Box<dyn Provider> {
match id {
ProviderId::Claude => Box::new(ClaudeProvider::new()),
ProviderId::Codex => Box::new(CodexProvider::new()),
ProviderId::Cursor => Box::new(CursorProvider::new()),
// ... 56 个分支,穷举匹配
}
}
注意这里的"穷举"(exhaustive):Rust 编译器会强制要求 match 覆盖 ProviderId 的每一个变体。如果你新增了一个 Provider 却忘了在工厂里接线,代码直接编译失败——编译器替你做了回归检查。
官方文档 docs/PROVIDERS.md 明确规定了接入新 Provider 的标准流程,一共三步:
- 在
ProviderId中新增变体,并补齐cli_name/display_name/ Cookie 域名等元数据; - 在
rust/src/providers/<name>/下实现Provider; - 在
provider_factory.rs中补上对应的 match 分支。
同时有一条铁律:永远不要在 Tauri 外壳里复制工厂逻辑,所有入口必须经由 instantiate_provider 构造实例。这就是为什么 56 个 Provider 在 GUI 和 CLI 中行为完全一致。
三种取数策略
每个 Provider 如何拿到用量数据?架构上收敛为统一词汇表(docs/PROVIDERS.md):
| 来源 | 含义(典型实现) |
|---|---|
web |
通过浏览器 Cookie 直接请求服务商仪表盘接口 |
cli |
读取本地 CLI 工具 / OAuth 登录态 |
oauth |
支持 OAuth 的服务商走授权流程 |
auto |
以上策略的自动回退顺序 |
其中 Cookie 方案是 Windows 平台的亮点:支持 Chrome(Stable / Beta / Dev / Canary)、Edge、Brave、Firefox 的会话导入,底层用 DPAPI + AES-GCM 解密浏览器 Cookie,实现在 rust/src/browser/ 目录(含 LevelDB/Chromium 本地存储读取器与解密逻辑)。手动粘贴 Cookie 头则作为 WSL 环境的兜底方案,细节见 docs/COOKIES.md。
🪟 第二层:Tauri 2 外壳——窗口、托盘与并发调度
外壳入口是 apps/desktop-tauri/src-tauri/src/main.rs,启动时完成插件装载、托盘初始化、悬浮条安装、自动刷新注册和 IPC 命令注册,产出可执行文件 codexbar-desktop-tauri.exe。
Provider 刷新:从命令层到缓存
当用户(或定时器)触发刷新时,数据流经如下链路(docs/ARCHITECTURE.md):
instantiate_provider(rust/src/core/provider_factory.rs)
↓
Provider::fetch_usage
↓
shell commands/providers.rs(信号量并发上限 + 超时保护)
↓
AppState.provider_cache
↓(Tauri 事件推送)
React useProviders
在 apps/desktop-tauri/src-tauri/src/commands/providers.rs 中可以看到并发的护栏设计:
const MAX_CONCURRENT_PROVIDER_FETCHES: usize = 8;
56 个 Provider 不会同时发起网络请求,而是通过信号量(semaphore)限制最多 8 个并发抓取,并附加超时保护——既不会打爆网络,也不会让某个慢接口卡死整个刷新周期。每个 Provider 抓取完成后立即推送 provider-updated 事件,UI 因此能"逐个点亮"卡片,而不是等全部完成才更新。
四个窗口表面
Tauri 外壳还管理着应用的四个界面表面(surfaces):
- 托盘面板(Tray panel):左键点击托盘图标弹出,宽 310px,高度自适应内容,失焦即关闭,是唯一的仪表盘布局;
- 弹出面板(flyout):从托盘菜单"Pop Out Dashboard"打开的大尺寸仪表盘窗口;
- 设置(Settings):独立窗口,含 general、providers、notifications、menuBar、usageSpend、advanced 等标签页;
- 悬浮条(Float bar):可选的常驻顶部容量条,由 apps/desktop-tauri/src-tauri/src/floatbar/ 模块管理,且必须固定深色主题,避免 WebView2 共享 profile 在
auto主题下影响其他窗口。
设置数据统一持久化在 %AppData%\Roaming\CodexBar\settings.json,敏感凭据(API key、手动 Cookie、token 账户)走 rust/src/secure_file.rs 提供的 DPAPI 加密存储。
⚛️ 第三层:React 前端——一个 App.tsx 路由四种窗口
前端入口 apps/desktop-tauri/src/App.tsx 的核心逻辑是按窗口 label 分发渲染:
function isSettingsWindow(): boolean {
return getCurrentWebviewWindow().label === "settings";
}
function isFlyoutWindow(): boolean {
return getCurrentWebviewWindow().label === "flyout";
}
- label 为
settings→ 直接渲染设置界面(支持?tab=providers深链到指定标签页); - label 为
floatbar→ 渲染悬浮条(apps/desktop-tauri/src/floatbar/FloatBar.tsx); - label 为
flyout→ 渲染托盘面板组件; - 其余 → 走
SurfaceRouter按表面模式切换托盘面板或设置。
这意味着 同一个前端构建产物驱动了四种窗口,且 Settings 与 FloatBar 使用 lazy 动态导入做代码分割,托盘面板则静态导入保证秒开。
上图的 Providers 设置页就是 apps/desktop-tauri/src/surfaces/settings/ 下的组件体系:左侧 Provider 列表支持拖拽排序与启用开关,右侧详情区提供 Cookie 来源(Automatic / Manual / Disabled)、凭据存储状态、托盘指标选择等逐项配置。
useProviders:前端订阅实时用量的中枢
apps/desktop-tauri/src/hooks/useProviders.ts 中的 useProviders hook 是前端数据流的枢纽,挂载时执行四步:
- 读取
AppState中已有的缓存快照,界面先显示旧数据(秒开不白屏); - 发起
refresh_providers触发新一轮抓取; - 监听
provider-updated事件,每个 Provider 完成即增量 upsert 进本地数组; - 监听
refresh-started/refresh-complete事件驱动"刷新中"状态。
配合 Tauri 事件系统(@tauri-apps/api/event),Rust 后端的每一次抓取结果都能毫秒级反映到 React 界面上——这就是"缓存 + 事件流"的单向数据架构:Rust 是唯一事实源,React 只做渲染与交互。
📊 架构总结:三层各司其职
| 关注点 | 归属层 | 关键机制 |
|---|---|---|
| Provider 注册与实例化 | Rust codexbar crate |
ProviderId 枚举 + 穷举工厂,编译期防遗漏 |
| 网络抓取与并发控制 | Tauri 外壳命令层 | 信号量上限 8 + 超时,AppState.provider_cache |
| 凭据安全 | Rust + Windows API | DPAPI 加密存储、浏览器 Cookie 解密导入 |
| 窗口与托盘 | Tauri 外壳 | 四表面路由、blur-dismiss、悬浮条 |
| 实时 UI | React 前端 | useProviders 事件订阅、缓存先行、增量更新 |
| 双入口复用 | 共享 crate | GUI 与 codexbar CLI 共用同一套 Provider 代码 |
这套"Rust 共享内核 + Tauri 系统外壳 + React 多表面前端"的三层设计,让 Win-CodexBar 既能用一套逻辑同时服务 GUI 和 CLI,又能以编译期保证维护 56 个 Provider 的正确性。
📚 延伸阅读
- docs/ARCHITECTURE.md — 架构总览:模块、入口点、数据流
- docs/PROVIDERS.md — Provider 工厂机制与接入规范
- docs/CLI.md — 命令行用法(
usage、cost、serve等) - docs/CONFIGURATION.md — 设置文件路径与存储说明
- docs/COOKIES.md — 浏览器 Cookie 导入原理

