AIUsage

面向 AI 编程助手的本地优先用量追踪工具。

在一个本地仪表盘里追踪 20+ 款 AI 编程工具的 token、费用、会话、模型、项目、工具调用和配额压力。本地使用无需账号、无遥测、无需云同步。

功能亮点

要求： Node.js 20+，支持 macOS、Linux 和 Windows。

npm install -g @juliantanx/aiusage
aiusage serve

打开 http://localhost:3847 即可使用仪表盘。serve 会在启动时解析一次本地日志，然后启动本地 Web UI。

使用 pnpm：

pnpm add -g @juliantanx/aiusage

使用 Docker：

docker run -d \
  -p 3847:3847 \
  -v ~/.aiusage:/root/.aiusage \
  juliantanx/aiusage

Docker 示例中的 ~/.aiusage 挂载只会持久化 AIUsage 自己的数据。若要解析宿主机上的 AI 工具日志，还需要额外挂载对应日志目录，并配置相应的 AIUSAGE_*_PATH。详见 Docker 文档。

命令	用途
`aiusage` / `aiusage summary`	在终端输出用量摘要
`aiusage parse`	解析本地 AI 工具日志
`aiusage serve`	在 `3847` 端口启动本地仪表盘
`aiusage status`	查看数据源和本地数据库状态
`aiusage export --range month`	导出用量数据
`aiusage init`	配置可选同步
`aiusage sync`	使用已配置的后端同步数据
`aiusage widget`	启动桌面托盘小组件
`aiusage leaderboard`	查看公开排行榜
`aiusage login` / `aiusage upload`	授权当前设备并上传聚合排行榜数据
`aiusage pm2-start`	使用 PM2 后台运行仪表盘和小组件

默认路径和环境变量覆盖方式见数据源与数据源环境变量。

本地仪表盘默认在 localhost 上开放。设置 AIUSAGE_DASHBOARD_PASSWORD 后，可以保护仪表盘 API。

Shell	命令
macOS / Linux	`AIUSAGE_DASHBOARD_PASSWORD="change-me" aiusage serve`
Windows PowerShell	`$env:AIUSAGE_DASHBOARD_PASSWORD="change-me"; aiusage serve`
Windows CMD	`set AIUSAGE_DASHBOARD_PASSWORD=change-me && aiusage serve`

PM2 后台运行时，也可以在启动 aiusage pm2-start 时传入同名变量；修改密码后使用 pm2 restart aiusage-server --update-env 更新环境变量。详见仪表盘密码和 PM2。

AIUsage 采用本地优先设计。

如需报告安全问题，优先使用私密渠道。详见 SECURITY.md。

同步和排行榜是两个互相独立的可选功能。

同步用于在自己的多台设备之间保持数据一致，支持 GitHub、S3、R2 或 MinIO。使用 aiusage init 配置，再运行 aiusage sync。
排行榜 面向明确选择分享聚合数据的用户。先用 aiusage login 授权设备，再运行 aiusage upload。
参与排行榜时，可在站点设置中开启匿名模式。

官方站点负责账号、OAuth 登录、资料设置、授权设备、上传审核状态和管理员治理。CLI 负责本地解析、本地仪表盘、同步、终端摘要和签名上传。

安装可选的托盘 / 菜单栏小组件：

npm install -g @juliantanx/aiusage-widget
aiusage-widget

小组件读取同一个本地 AIUsage 数据库，并可从托盘菜单打开完整仪表盘。详见 Widget 文档。

git clone https://github.com/juliantanx/aiusage.git
cd aiusage
pnpm install
pnpm build
pnpm test
pnpm dev

项目结构：

路径	说明
`packages/core`	共享类型、数据库 schema、定价和工具函数
`packages/cli`	发布到 npm 的 CLI、解析器、本地 API 服务、同步和 PM2 辅助命令
`packages/web`	打包进 CLI 的本地仪表盘 UI
`packages/widget`	Electron 托盘 / 菜单栏小组件
`packages/site`	官方站点、文档、账号、上传和排行榜