Win-CodexBar 架构深度解析:Rust + Tauri + React 三层设计如何撑起 56 个 AI Provider

原创2026-10-13 13:55:451,752 阅读

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 的额度消耗与重置时间:

Win-CodexBar 托盘面板:56 个 AI 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 的标准流程,一共三步:

  1. 在 ProviderId 中新增变体,并补齐 cli_name / display_name / Cookie 域名等元数据;
  2. 在 rust/src/providers/<name>/ 下实现 Provider;
  3. 在 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 动态导入做代码分割,托盘面板则静态导入保证秒开。

Win-CodexBar 设置页 Providers 标签:每个 AI Provider 的认证方式、数据源与托盘显示配置

上图的 Providers 设置页就是 apps/desktop-tauri/src/surfaces/settings/ 下的组件体系:左侧 Provider 列表支持拖拽排序与启用开关,右侧详情区提供 Cookie 来源(Automatic / Manual / Disabled)、凭据存储状态、托盘指标选择等逐项配置。

useProviders:前端订阅实时用量的中枢

apps/desktop-tauri/src/hooks/useProviders.ts 中的 useProviders hook 是前端数据流的枢纽,挂载时执行四步:

  1. 读取 AppState 中已有的缓存快照,界面先显示旧数据(秒开不白屏);
  2. 发起 refresh_providers 触发新一轮抓取;
  3. 监听 provider-updated 事件,每个 Provider 完成即增量 upsert 进本地数组;
  4. 监听 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 的正确性。

📚 延伸阅读

登录后查看全文
Win-CodexBar