openbridge-token-usage-viewer/README.md

Token Usage Viewer

一个基于 TanStack Start + Bun + Tauri 的桌面应用，用于监控 Claude API 账户的 Token 配额使用情况。

采用 OpenBridge Design System 设计规范，提供专业的航海仪表盘风格界面。

功能特点

• 实时配额监控: 显示最多 4 个账户的 Claude Opus 4.5 (Thinking) 模型配额使用情况
• 可视化仪表盘: Apple Health 风格的圆环进度指示器，颜色根据剩余配额自动变化
• 智能告警系统:
  • 当配额剩余 < 20% 时显示警告 (Warning)
  • 当配额剩余 < 5% 时显示紧急告警 (Alarm)
• 主题切换: 支持白天/夜间模式切换，OpenBridge 设计系统主题
• 自动刷新: 配额数据每 5 分钟自动刷新
• 倒计时显示: 显示配额重置剩余时间
• SSR 支持: 服务端渲染，首屏即有数据

技术栈

核心框架

层级	技术	版本
前端框架	React	19.2
路由	TanStack Router	1.151
状态管理	TanStack Query	5.90
SSR 框架	TanStack Start	1.151
RPC 通信	ORPC (类型安全契约优先)	1.13
UI 组件	OpenBridge Web Components	0.0.17
样式	Tailwind CSS	v4
桌面壳	Tauri	v2.9
运行时	Bun	1.3.6

后端 & 数据

技术	说明
SQLite	Bun 内置驱动 (bun:sqlite)，无需额外安装
Drizzle ORM	类型安全 ORM，支持迁移
Nitro	服务端框架 (bun preset)
Zod	运行时类型验证

构建工具

技术	说明
Vite	开发服务器 + 构建
Turbo	任务并行化
Effect	函数式构建脚本
Biome	代码格式化 + Lint
React Compiler	自动优化，无需手动 memo

快速开始

前置要求

• Bun >= 1.0
• Rust (Tauri 桌面应用需要)

安装与运行

# 1. 克隆项目
git clone <your-repo-url>
cd openbridge-token-usage-viewer

# 2. 安装依赖
bun install

# 3. 启动开发服务器
bun run dev:vite    # 仅 Web (http://localhost:3000)
bun run dev         # Tauri 桌面应用 + Web

构建

bun run build:vite   # 构建 Web 版本 (输出到 .output/)
bun run build        # 构建 Tauri 桌面安装包

构建产物位置

类型	路径
Vite Web 构建	.output/
Sidecar 二进制	src-tauri/binaries/app-<target>
MSI 安装包	src-tauri/target/release/bundle/msi/app-desktop_0.1.0_x64_en-US.msi
NSIS 安装包	src-tauri/target/release/bundle/nsis/app-desktop_0.1.0_x64-setup.exe
macOS DMG	src-tauri/target/release/bundle/dmg/app-desktop_0.1.0_aarch64.dmg

配置

环境变量

应用会按以下优先级读取 TOKEN_USAGE_URL 配置：

1. 系统环境变量 (最高优先级)
2. 可执行文件同目录的 .env 文件
3. 默认值: http://10.0.1.1:8318/usage

方式 1: 环境变量

# Windows PowerShell
$env:TOKEN_USAGE_URL = "http://your-server:8318/usage"
.\app-desktop.exe

# Linux/macOS
TOKEN_USAGE_URL=http://your-server:8318/usage ./app-desktop

方式 2: 配置文件

在可执行文件同目录创建 .env 文件：

TOKEN_USAGE_URL=http://your-server:8318/usage

常用命令

开发

命令	说明
bun dev	启动 Tauri + Vite 开发服务器 (并行)
bun dev:vite	仅启动 Vite 开发服务器 (http://localhost:3000)
bun dev:tauri	仅启动 Tauri (需先启动 Vite)
bun db:studio	打开 Drizzle Studio 数据库管理界面

构建

命令	说明
bun build	完整构建 (Vite → 编译 → Tauri 打包)
bun build:vite	仅构建 Web 版本 (输出到 .output/)
bun build:compile	编译 Sidecar 二进制 (使用 build.ts)
bun build:tauri	构建 Tauri 桌面安装包

代码质量

命令	说明
bun typecheck	TypeScript 类型检查
bun fix	自动修复格式和 Lint 问题 (Biome)

数据库

命令	说明
bun db:init	初始化 SQLite 数据库
bun db:generate	从 schema 生成迁移文件
bun db:migrate	执行数据库迁移
bun db:studio	打开 Drizzle Studio

项目结构

├── src/
│   ├── components/                 # React 组件
│   │   ├── HealthRing.tsx          # 圆环进度指示器 (Apple Health 风格)
│   │   ├── TokenUsageDashboard.tsx # 主仪表盘 (告警+主题+圆环)
│   │   ├── Error.tsx               # 错误边界回退组件
│   │   └── NotFount.tsx            # 404 页面
│   │
│   ├── hooks/                      # React Hooks
│   │   ├── useCountdown.ts         # 倒计时 Hook (useMemo 优化)
│   │   └── useTheme.ts             # OpenBridge 主题切换 Hook
│   │
│   ├── orpc/                       # ORPC RPC 层
│   │   ├── contracts/              # 契约定义 (Zod schema)
│   │   │   └── usage.ts            # 使用量查询契约
│   │   ├── handlers/               # 服务端处理器
│   │   │   └── usage.ts            # 获取配额数据+存储历史
│   │   ├── middlewares/            # ORPC 中间件
│   │   │   └── db.ts               # 数据库连接 Provider
│   │   ├── client.ts               # 同构客户端 (SSR/CSR 自动切换)
│   │   ├── contract.ts             # 契约聚合
│   │   ├── router.ts               # 路由组合
│   │   ├── server.ts               # 服务端实例
│   │   └── types.ts                # 类型导出
│   │
│   ├── routes/                     # TanStack Router 文件路由
│   │   ├── __root.tsx              # 根布局 (OpenBridge 主题集成)
│   │   ├── index.tsx               # 首页 (SSR 预取+自动刷新)
│   │   └── api/rpc.$.ts            # ORPC HTTP 端点
│   │
│   ├── db/                         # 数据库层
│   │   ├── schema/                 # Drizzle Schema
│   │   │   └── usage-history.ts    # 使用量历史表
│   │   └── index.ts                # 数据库连接 (SQLite WAL)
│   │
│   ├── lib/                        # 工具函数
│   ├── env.ts                      # 环境变量验证 (t3-env)
│   └── router.tsx                  # 路由配置
│
├── src-tauri/                      # Tauri 桌面应用
│   ├── src/
│   │   ├── lib.rs                  # Tauri 入口
│   │   └── sidecar.rs              # Sidecar 进程管理
│   ├── binaries/                   # 编译后的 sidecar 二进制
│   └── tauri.conf.json             # Tauri 配置
│
├── build.ts                        # 跨平台构建脚本 (Effect 框架)
├── vite.config.ts                  # Vite 配置
├── drizzle.config.ts               # Drizzle ORM 配置
└── .output/                        # Vite 构建输出

架构说明

ORPC 同构客户端

ORPC 客户端根据运行环境自动选择最优调用方式:

• SSR (服务端): 直接调用 router 处理器，零网络开销
• CSR (客户端): 通过 /api/rpc 端点进行 HTTP 调用

// 使用 TanStack Query
const { data } = useSuspenseQuery(orpc.usage.getUsage.queryOptions())

Tauri Sidecar

应用采用 Sidecar 架构:

1. Tauri 壳: 提供原生窗口和系统集成
2. Bun 服务端: 编译为独立可执行文件，处理 SSR 和 API 请求
3. 通信: Tauri WebView 通过 localhost:3000 与 Sidecar 通信

数据流

Token API (http://10.0.1.1:8318/usage)
    ↓
ORPC Handler (usage.ts)
    ↓
SQLite (data/app.db) ← 历史记录存储
    ↓
TanStack Query Cache
    ↓
React Components (TokenUsageDashboard)

故障排除

清理缓存与重置

如果遇到构建问题、端口占用或缓存问题，按以下步骤重置：

1. 结束所有相关进程

# Windows PowerShell (管理员)
taskkill /F /IM "app.exe" 2>$null
taskkill /F /IM "app-desktop.exe" 2>$null
taskkill /F /IM "bun.exe" 2>$null
taskkill /F /IM "node.exe" 2>$null

# Linux/macOS
pkill -f "app-desktop" || true
pkill -f "bun" || true

2. 清除所有缓存

# Turbo 缓存
rm -rf .turbo

# Vite 缓存
rm -rf node_modules/.vite
rm -rf node_modules/.cache

# 构建输出
rm -rf .output

# Tauri sidecar binaries
rm -rf src-tauri/binaries/app-*

3. 完全清理 (可选，需要重新编译 Rust，耗时 2-5 分钟)

# 清除 Rust 编译缓存
rm -rf src-tauri/target

4. 确认端口已释放

# Windows
netstat -ano | findstr :3000

# Linux/macOS
lsof -i :3000

5. 重新构建

bun run build

常见问题

"An unhandled error happened!" 错误

1. 确保没有其他进程占用端口 3000
2. 尝试完全清理缓存后重新构建
3. 检查 .env 文件中的 TOKEN_USAGE_URL 配置是否正确

端口被占用 (EADDRINUSE)

# 查找占用端口的进程
netstat -ano | findstr :3000

# 结束进程 (替换 PID 为实际进程 ID)
taskkill /F /PID <PID>

MSI 安装后无法运行

1. 卸载旧版本: 控制面板 → 程序和功能 → 卸载 app-desktop
2. 重新安装新的 MSI
3. 确保安装目录有写入权限

许可证

MIT