把多个 AI 服务的每周用量并排显示在一个桌面小卡片里。纯 PowerShell + WinForms,无第三方依赖, 不需要管理员权限,不向任何服务器上传数据。
English · 简体中文
截图由
-Demo模式生成:固定演示数据,不读取任何真实账号,不写状态文件,也不联网。
浅色主题使用同一套布局(设置窗口切换,或启动参数 -Theme light):
| 供应商 | 卡片显示 | 账号模式 | 凭证来源 |
|---|---|---|---|
| Grok | Build / Chat 等产品的周用量与重置时间 | 多账号,每个账号一行 | ~/.grok/auth.json |
| Kimi | 5 小时窗与周窗口的用量 | 多账号,每个登记账号一行 | ~/.kimi-code/credentials/kimi-code.json |
| ChatGPT / Codex | 5 小时窗与周窗口的用量 | 多账号,每个账号一行 | ~/.codex/auth.json |
| Gemini / Antigravity | 配额百分比与重置时间 | 多账号,每个登记账号一行 | Windows 凭据管理器 gemini:antigravity |
| Command Code | 5 小时窗与周窗口的用量,可选余额 | 多账号,每个登记账号一行 | ~/.commandcode/auth.json |
| OpenRouter | 密钥的已用额度与上限(未设上限时明确说明) | 每个密钥一行 | ~/.openrouter/auth.json 或 $env:OPENROUTER_API_KEY |
| DeepSeek | 账户总余额与充值 / 赠额明细(余额型,没有百分比) | 单账号 | ~/.deepseek/auth.json 或 $env:DEEPSEEK_API_KEY |
| Cline | Cline Dashboard 的 5 小时 / 周 / 月额度与对应重置时间 | 多账号,每个登记账号一行 | ~/.cline/data/settings/providers.json(CLI OAuth) |
| Claude Code | 5 小时窗与周窗口的用量 | 多账号,每个登记账号一行 | ~/.claude/.credentials.json(OAuth,不是 API key) |
| Cursor | 当前计费周期已用百分比与剩余额度 | 多账号,每个登记账号一行 | %APPDATA%\Cursor\User\globalStorage\state.vscdb |
| GLM / Z.AI | Coding Plan 的 5 小时窗与周窗口 | 多账号,每个登记密钥一行 | ~/.zai/auth.json、~/.zhipu/auth.json、~/.bigmodel/auth.json(或 ZCode 的 ~/.zcode/v2/config.json)或 $env:ZAI_API_KEY / $env:ZHIPU_API_KEY / $env:BIGMODEL_API_KEY |
| GitHub Copilot | Premium requests 的已用占比与配额重置日期 | 多账号,每个登记账号一行 | ~/.config/github-copilot/hosts.json / apps.json(也支持 OpenCode 的 auth.json) |
已经登录过对应 CLI 或扩展(Grok CLI、kimi、Codex CLI、Command Code CLI、Cline CLI、Antigravity、GitHub Copilot for VS Code、ZCode)就不会有额外配置负担:
卡片直接复用它们的凭证,只读不写(令牌过期时才会原地刷新)。OpenRouter 是纯 API-key 供应商:读取 ~/.openrouter/auth.json(或 $env:OPENROUTER_API_KEY),每个密钥一行;DeepSeek 同样只看 API-key(~/.deepseek/auth.json 或 $env:DEEPSEEK_API_KEY),卡片显示账户余额而不是百分比。
- 一个窗口看全部:圆角常驻卡片,已登记的账号会按供应商展开成多行。
- 深色 / 浅色双主题:设置窗口或启动参数(
-Theme dark|light)切换,全部颜色来自同一张调色板;窗口不透明度可调(0.5 – 1.0)。 - 不打断工作:常驻桌面、可置顶、拖拽移动、贴边吸附,位置与设置自动记忆。
- 托盘常驻:双击托盘图标显示 / 隐藏卡片;关闭窗口即退出并释放单实例互斥。
- 阈值提醒:用量达到 70% 与 90% 时弹一次气泡提醒,用满后自动重置提醒状态。
- 双击直达:双击任意一行直接打开该服务的官方用量页面。
- 趋势可视:每行进度条右侧画出最近 7 天迷你折线,颜色跟随当前用量(绿 / 黄 / 橙 / 红)。
- 耗尽预测:悬停提示按最近趋势估算额度耗尽时间,并提示是否早于本次重置。
- 1 - 3 列卡片:同一张卡片可以横向排成 2 列或 3 列,供应商多时不再拉得很长;列数在设置窗口或
ai-config.json里调。 - 每日汇总:可选在每天固定时刻弹一次汇总气泡,列出当时各行的用量;同一天只提醒一次。
- 历史报表导出:右键 → 导出历史,可选原始采样 CSV、按天汇总 CSV、月度报表 Markdown 与自包含 HTML;历史按 schema v2 写入月度归档,默认保留 90 天,原始导出跨月合并去重,历史为空时明确提示而不是生成空文件。
- 有界并发刷新:最多 3 个供应商 job 并行,同一供应商不并发;完成的 job 立即更新,错误按类型退避,失败行保留上次成功值。
- 多月对比:同一子菜单里的「多月对比 Markdown / HTML」把最近 3 个月并排成「供应商 × 月份」表格,每个单元格给出该月的采样数、天数与月初 / 月末 / 最低 / 最高,并单列一栏给出与上月的环比百分点变化;HTML 自包含,某个月没有采样的供应商也会占一行并显示
-。 - 趋势图窗口:右键 → 趋势图…(或启动时加
-TrendWindow),按供应商画出每日用量折线,可切换到 7 / 14 / 30 天;折线颜色沿用各组件在卡片上的用量颜色,图例给出最新百分比。窗口只读,不写任何文件。 - 集中设置:设置窗口写入
ai-config.json(供应商开关、刷新间隔、列数、主题、不透明度、阈值、分供应商阈值、静音时段、每日汇总),保存后即时生效。 - 失败可降级:单个供应商超时或报错只影响自己那一行,并进入指数退避(30 秒起,最长 15 分钟)。
- 本地优先:账号快照用 Windows DPAPI 加密,日志与错误文本统一脱敏,账号只以短哈希出现。
- 双引擎可用:Windows PowerShell 5.1 与 PowerShell 7.x 都支持,CI 双版本跑同一套离线测试。
- 可离线验证:
-Demo用固定数据渲染界面,适合截图、录屏与排查"是界面问题还是凭证问题"。 - 更新检查:右键菜单 → 关于… 显示版本、许可证与项目地址,一键检查 GitHub 上的最新 Release;有新版本时给出说明摘要与下载入口。
| 操作 | 效果 |
|---|---|
| 左键拖拽卡片 / 底部状态行 | 移动窗口,靠近屏幕边缘自动吸附 |
| 双击某一行 | 打开该服务的官方用量页 |
按 F5 |
立即刷新全部供应商 |
| 双击托盘图标 | 显示 / 隐藏卡片 |
| 右键卡片 | 打开菜单(见下图) |
| 悬停某一行 | 显示明细提示(含重置时间与耗尽预测) |
| 右键卡片 → 导出历史 | 子菜单六项:原始采样 CSV(全部历史,ai-usage-<时间戳>.csv)、按天汇总 CSV、月度报表 Markdown、月度报表 HTML、多月对比 Markdown、多月对比 HTML;单月报表默认导出最近一个有数据的月份,多月对比默认最近 3 个月 |
| 右键卡片 → 趋势图… | 打开趋势图窗口,默认最近 7 天,可切换 14 / 30 天 |
右键菜单包含:立即刷新、刷新间隔(1 / 5 / 15 / 60 分钟)、登记当前登录的 Grok / Gemini / Kimi / Claude / Command Code / Cursor / GLM / Copilot / Cline / ChatGPT 账号、 打开用量页(Grok / Gemini / Kimi / ChatGPT / Command Code / OpenRouter / DeepSeek / Cline / Claude / Cursor / GLM / Copilot)、 导出历史(原始采样 CSV / 按天汇总 CSV / 月度报表 Markdown / 月度报表 HTML / 多月对比 Markdown / 多月对比 HTML)、 趋势图…、设置…、关于…、浮在窗口上、开机启动、退出。
| 项目 | 要求 |
|---|---|
| 系统 | Windows 10 / 11(依赖 WinForms 与 DPAPI) |
| PowerShell | Windows PowerShell 5.1(系统自带)或 PowerShell 7.x |
| 权限 | 不需要管理员权限,不写注册表 |
| 依赖 | 无第三方模块,不需要安装任何东西 |
git clone https://github.com/Regine88/ai-usage-widget.git
cd ai-usage-widget
# 方式一:直接运行(推荐加 -ExecutionPolicy Bypass 以免被执行策略拦住)
pwsh -NoProfile -ExecutionPolicy Bypass -File .\AiUsageWidget.ps1
# 方式二:无窗口启动(等价于双击)
wscript.exe .\Start-AiUsageWidget.vbs如果只想先看看界面长什么样,不需要任何账号:
pwsh -NoProfile -File .\AiUsageWidget.ps1 -Demo# 从 clone 好的仓库安装(重复执行即为升级)
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
# 查看状态 / 卸载(保留用户数据)/ 彻底卸载
.\install.ps1 -Status
.\install.ps1 -Uninstall
.\install.ps1 -Uninstall -Purge安装器会把运行文件复制到 %LOCALAPPDATA%\Programs\AIUsageWidget,并创建开始菜单快捷方式;
ai-config.json、ai-history.jsonl 等用户数据永远不会被覆盖,卸载默认也保留。
不想安装时,直接双击 Start-AiUsageWidget.vbs 即可免安装运行。
也可以从 Releases 下载 zip 后安装:
.\install.ps1 -Zip .\ai-usage-widget-0.16.0.zipScoop 用户可以直接安装每个 Release 附带的 manifest:
scoop install https://github.com/Regine88/ai-usage-widget/releases/latest/download/ai-usage-widget.jsonpwsh -NoProfile -File .\AiUsageWidget.ps1 -Version
# AI Usage Widget 0.16.0Grok、Gemini、Kimi、ChatGPT / Codex、Command Code、Cline、Claude、Cursor、GLM 与 Copilot 都是一账号一行。当前登录会在刷新时记入快照;要保留切换前的账号,先登记再切换:
- 先用对应客户端登录一个账号;
- 右键卡片,选择该供应商的 登记账号;
- 在原来的客户端里切换到另一个账号,再登记一次,卡片会多出一行。
每个已登记账号用自己的令牌读取用量。刷新某个账号的令牌只写回这个账号的快照;当前正在使用的登录才会写回原来的凭证文件或凭据管理器。
注意:Cline 的网页登录与 Cline CLI 登录是两套会话。浏览器里切换账号不会改变 CLI token;切换 Cline 目标账号时要在终端执行 cline auth cline,登录完成后再点“登记 Cline 账号”。如果 CLI 仍是同一个 accountId,程序会用气泡提示“当前仍是已登记账号”,不会新增重复行。
登记的账号以受 DPAPI 保护的快照保存在 %LOCALAPPDATA%\AIUsageWidget\accounts\,文件名是账号的短哈希,不含邮箱。
行名默认就是账号短哈希(形如 Grok-1f4a2c7e)。想改成 a / b 这类短名字,在程序目录放一个
grok-aliases.json,内容形如 { "Grok-1f4a2c7e": "a" }(键取行名里的指纹)。别名只在本机生效,
该文件已被 .gitignore 排除,不会随仓库发布。
右键卡片 → 开机启动(再次点击即取消)。它只会在当前用户的启动文件夹里放一个指向
Start-AiUsageWidget.vbs 的快捷方式,不写注册表、不需要管理员权限。
| 开关 | 作用 |
|---|---|
| (无) | 正常启动卡片;已有实例在运行时不会重复启动 |
-Version |
输出版本号后退出 |
-Demo |
演示模式:固定数据渲染,不读凭证、不写状态、不联网、不记录历史与提醒 |
-Install |
注册开机启动,然后退出 |
-Uninstall |
移除开机启动,然后退出 |
-AddAccount |
把当前 ~/.codex/auth.json 登记为一个账号 |
-AddGrokAccount |
把当前 ~/.grok/auth.json 登记为一个账号 |
-AddGeminiAccount |
把当前 Antigravity 登录登记为一个 Gemini 账号 |
-AddKimiAccount |
把当前 Kimi 登录登记为一个账号 |
-AddClaudeAccount |
把当前 Claude Code 登录登记为一个账号 |
-AddCommandCodeAccount |
把当前 Command Code 登录登记为一个账号 |
-AddCursorAccount |
把当前 Cursor 登录登记为一个账号 |
-AddGlmAccount |
把当前 GLM / 智谱密钥登记为一个账号 |
-AddCopilotAccount |
把当前 GitHub Copilot 登录登记为一个账号 |
-MigrateSecrets |
把旧版本遗留在程序目录里的账号快照迁移到 DPAPI 目录 |
-IntervalSeconds <秒> |
指定刷新间隔(最小 15 秒,默认 300 秒,会被右键菜单的选择覆盖) |
-Theme <dark|light> |
只对本次运行强制深色 / 浅色主题,不改写 ai-config.json |
右键卡片 → 设置… 打开设置窗口,保存后写入程序目录下的 ai-config.json;
也可以直接编辑该文件,重启卡片生效。该文件已被 .gitignore 排除,不会随仓库发布。
| 字段 | 默认值 | 说明 |
|---|---|---|
intervalSeconds |
300 |
刷新间隔秒数(15 – 86400);右键菜单与设置面板写入同一字段 |
opacity |
0.96 |
窗口不透明度(0.5 – 1.0) |
theme |
"dark" |
界面主题:dark / light,设置窗口保存后即时切换 |
layout |
"full" |
行布局:full(名称 + 进度条 + 明细)/ compact(单行更矮) |
columns |
1 |
卡片列数(1 - 3);2 / 3 列时窗口按列加宽、行按行带折算 |
lockPosition |
false |
为 true 时禁止拖拽移动卡片 |
providerAlertThresholds |
{} |
可选,按供应商覆盖全局阈值,例如 { "grok": [80, 95] } |
showTrend |
true |
在每行进度条右侧显示 7 天迷你折线 |
showForecast |
true |
悬停提示里显示额度耗尽预测 |
trendDays |
7 |
折线与预测使用的天数(1 – 14) |
historyRetentionDays |
90 |
月度历史归档的保留天数(7 – 3650) |
historyMaxBytes |
10485760 |
历史归档总容量上限(1 MB – 1 GB);空间不足时优先淘汰旧月份并标记历史不完整 |
historySampleMinutes |
15 |
没有变化时仍写入定时有效采样的最小间隔(1 – 1440 分钟) |
alertThresholds |
[70, 90] |
触发气泡提醒的已用百分比,自动升序去重 |
quietHours |
{ "enabled": false, "start": "22:00", "end": "07:00" } |
静音时段,跨午夜自动识别 |
dailySummary |
{ "enabled": false, "time": "09:00" } |
每日汇总气泡;到点后每天只弹一次,日期记在 ai-state.json |
accountAliases |
{} |
稳定行 ID 到显示别名的映射 |
hiddenAccounts |
[] |
不显示在卡片上的稳定行 ID;账号快照仍保留 |
accountOrder |
[] |
稳定行 ID 的显示顺序,未列出的账号排在后面 |
providers |
全部 true |
供应商开关:grok / gemini / kimi / codex / commandcode / openrouter / deepseek / cline / claude / cursor / glm / copilot |
language |
"auto" |
界面语言:auto(跟随系统)/ zh-CN / en-US |
任何非法值(超范围、类型不对、时间格式错误)都会回退成默认值,不用担心把配置改坏。
language支持auto(跟随系统 UI 语言:中文系统用简体中文,其余用英文)、zh-CN、en-US; 设置窗口里的「界面语言」写入的就是这个字段,重启卡片后生效。- 文案集中在程序目录的
strings/zh-CN.json与strings/en-US.json,值里可以用{0}这类占位符,由代码传入。 - 读不到语言包或 JSON 损坏时自动回退到内置兜底表,界面不会变空白;缺某个键时显示键名本身,便于发现漏翻。
- 新增一门语言要改两处:把
strings/en-US.json复制成strings/<语言>.json并翻译值, 再在WidgetStrings.ps1的$script:WidgetStringLanguages里登记语言代码。 语言代码是白名单——配置里的值永远不会被直接当成文件名使用。
| 数据 | 位置 | 是否含凭据 |
|---|---|---|
| 账号快照(DPAPI 加密) | %LOCALAPPDATA%\AIUsageWidget\accounts\ |
加密存储,文件名为哈希 |
| 界面状态(位置 / 置顶 / 间隔) | <程序目录>\ai-state.json |
否 |
| 用量历史 | <程序目录>\ai-history.jsonl 与 <程序目录>\history\ai-history-YYYY-MM.jsonl |
否,以 schema v2 记录时间、账号、指标类型、窗口、周期和值 |
| 请求事件 | <程序目录>\ai-request-events.jsonl |
否,只有供应商 / 模型 / 状态 / 耗时 |
| 日志 | <程序目录>\ai-widget.log |
否,账号只以短哈希出现,自动轮转 |
| 账号别名(可选) | <程序目录>\grok-aliases.json |
否,只有短哈希与本地别名,已被 .gitignore 排除 |
| 安装元数据(可选) | <安装目录>\ai-install.json |
否,只有版本号、安装时间与文件清单 |
- 只在需要时访问各供应商自己的接口,请求固定使用 HTTPS,并在请求前做受信任主机白名单校验。
- 没有遥测、没有埋点、没有自动更新回传,程序不会把任何数据发送给本项目维护者。
- 更完整的安全设计说明见 SECURITY.md。
# 双版本跑全部离线测试(成功时每个套件都会打印 ALL PASSED)
$ps51 = Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'
foreach ($exe in @('pwsh', $ps51)) {
Get-ChildItem -Filter 'test-*.ps1' | Sort-Object Name | ForEach-Object {
$out = & $exe -NoProfile -ExecutionPolicy Bypass -File $_.FullName 2>&1 | Out-String
'{0,-32} {1}' -f $_.Name, $(if ($LASTEXITCODE -eq 0 -and $out -match 'ALL PASSED') { 'PASS' } else { 'FAIL' })
}
}界面改动请用 -Demo 模式做目视回归;解析与校验逻辑请补离线测试,不要依赖网络或真实账号。
详细的模块划分、worker 边界与新增供应商步骤见 docs/architecture.md 与
docs/providers.md。
AiUsageWidget.ps1 主程序:界面、菜单、定时器、后台抓取调度
UsageValidation.ps1 共享校验与脱敏纯函数
SecureSnapshot.ps1 DPAPI 账号快照读写
ApiKeyAuth.ps1 API-key 凭证读取与鉴权请求(OpenRouter / DeepSeek 共用)
GrokAccounts.ps1 Grok 多账号
GeminiAntigravity.ps1 Gemini / Antigravity 配额
KimiQuota.ps1 Kimi 载荷解析
CommandCodeQuota.ps1 Command Code 配额解析
OpenRouterQuota.ps1 OpenRouter 密钥配额解析
DeepSeekQuota.ps1 DeepSeek 余额解析
ClaudeQuota.ps1 Claude Code 配额解析
CursorQuota.ps1 Cursor 计费周期解析
ZaiQuota.ps1 GLM / Z.AI Coding Plan 配额解析
CopilotQuota.ps1 GitHub Copilot 配额解析与 token 发现
WidgetUpdates.ps1 版本比较与 GitHub Release 解析
ModelRequestRecorder.ps1 请求事件记录(仅元数据)
UsageHistory.ps1 历史聚合、趋势、耗尽预测与 CSV 导出
UsageReport.ps1 月度报表:按天 / 月度汇总与 CSV / Markdown / HTML 渲染
WidgetTrend.ps1 趋势图纯函数:每日序列裁剪、坐标换算与坐标轴刻度
WidgetConfig.ps1 ai-config.json 的读写与校验
WidgetPalette.ps1 深色 / 浅色调色板(界面颜色的唯一来源)
WidgetLayout.ps1 卡片行高与窗体尺寸(full / compact)
WidgetFormat.ps1 百分比、重置时间与错误文案
WidgetStrings.ps1 界面文案的语言包加载与查询
strings/ 语言包(zh-CN.json / en-US.json)
WidgetInstaller.ps1 安装 / 升级 / 卸载实现
WidgetPackage.ps1 发布包内容校验(期望清单、包内版本号、Scoop manifest)
install.ps1 安装入口脚本
tools/ 发布打包、打包校验与落地页构建脚本
site/ GitHub Pages 落地页(中英双语,构建时注入版本号)
Record-ModelRequest.ps1 外部写入请求事件的独立入口
test-*.ps1 每个模块对应的离线测试
Start-AiUsageWidget.vbs 无窗口启动器
docs/ 架构、供应商、排错文档与截图
GrokUsageWidget.ps1 / KimiUsageWidget.ps1 / ChatGptUsageWidget.ps1 是历史兼容入口,全部转发到聚合卡片;-Demo、-Theme、关于窗口不会出现在这些包装器的参数里。
- 架构说明:进程与线程模型、数据流、行模型约定、存储布局
- 供应商支持与扩展:每个供应商的数据来源,以及新增供应商的七步改造点
- 排错手册:卡片不显示、登录过期、超时、DPI、开机启动等常见问题
- 项目主页:GitHub Pages 自动构建的中英双语落地页
- 更新日志 · 贡献指南 · 安全策略 · 行为准则
欢迎提交 Issue 与 PR:新供应商、更多分发方式仍在路线图上。紧凑布局与锁定位置在 0.11.0 提供,多列布局与每日汇总在 0.13.0 提供,历史报表导出与发布包内容校验在 0.14.0 提供,多月对比与趋势图窗口在 0.15.0 提供。 提之前请先看 CONTRIBUTING.md,其中说明了测试要求(双 PowerShell 版本)与安全红线 (绝不提交凭据、日志与含个人信息的文件)。
本项目以 MIT 许可证 发布。
这是一个非官方工具,与 Grok / xAI、Kimi / Moonshot、OpenAI、Google、Command Code、OpenRouter、DeepSeek、Anthropic、Cursor、Z.AI / 智谱、GitHub 均无关联, 也未获得其背书。它只读取你本机已存在的登录凭证来显示配额,不绕过任何付费、限流或授权机制; 请自行确认使用方式符合各服务的条款。



