使用说明 · AI 订阅额度查询助手

这是什么

AI 订阅额度查询助手（仓库名 coding-plan-query）是一个装在自己电脑上的桌面客户端，不是网页仪表盘，也不是某个平台的官方页面。它做的事情很具体：把你手里那几把 AI Coding Plan 的 API Key 填进去，它替你去问平台「这个号还剩多少钱、这 5 小时窗口用了多少、7 天额度还剩几条、什么时候重置」，然后把答案摊在一屏卡片上。

它有两种运行形态：

Windows 桌面客户端（当前正式发行的形态）：带置顶悬浮窗、系统托盘、额度提醒小窗、无边框自绘标题栏等桌面专属能力。
Web 版网关：同一套前端由一个独立的本地网关进程供浏览器使用，只是系统级能力不可用。

运行环境纯本地：没有账号体系、没有服务端、没有遥测，授权协议 MIT。

安装与下载

系统要求

项目	说明
操作系统	Windows 10 / 11（x64）
运行时依赖	需要 WebView2 运行时（Windows 10 / 11 已自带；检测不到时安装包会自动下载并安装 WebView2 引导程序）
安装包大小	约 2.5 MB（v0.6.0 的 `AI 订阅额度查询助手_0.6.0_x64-setup.exe` 实测 2,638,997 字节）
安装权限	per-user 安装，不需要管理员权限，不写系统目录
数据落盘位置	`%APPDATA%\com.genki-meow.coding-plan-query\`

下载哪一个文件

到 Gitee Releases 页选最新版本，下载 AI 订阅额度查询助手_{version}_x64-setup.exe。 不要下载源码 zip——那是给想自己编译的人看的源码，不是能直接双击运行的客户端。

Windows 提示「未知发布者」

双击安装包时，Windows 可能弹出「Windows 已保护你的电脑」，标题旁写「未知发布者」——点「更多信息」→「仍要运行」即可。原因很实在：这个安装包没有做代码签名（没有购买代码签名证书），SmartScreen 对未签名程序一律提示，不是文件被篡改或中毒。

升级不用回下载站

客户端内建更新通道，每次打开就真查一次远端：检查 → 分片并发下载 → sha256 双重校验 → 重启安装，全在客户端里完成。下载与安装是解耦的：下载完先落 pending-update.json，你可以当场装，也可以推迟到下次启动。

设置页里还能调「启动时自动检查更新」「发现新版本后自动下载」「分片并发下载数（1–8 路）」「静默安装」。版本号旁出现「更新」标签时点开即可。远程已发布新版但没有当前平台安装包时，按钮会被禁用。

从源码跑

发行只提供 Windows 安装包；源码在 Linux / macOS 编译需先装 OpenSSL 开发包（Debian/Ubuntu：apt install libssl-dev pkg-config；macOS：brew install openssl）。 Web 版网关可本地启动：cargo run --bin webserver --features webserver -- --port 8891 --dist ../dist。

三分钟上手

下哪个文件：在 Releases 页下载 AI 订阅额度查询助手_{version}_x64-setup.exe（约 2.5 MB），双击安装。
Windows 提示「未知发布者」：点「更多信息」→「仍要运行」。这是未签名安装包的常规提示。
API Key 从哪拿：
- MiniMax：控制台（platform.minimaxi.com）进入账户 / 接口密钥页面，复制以 sk-cp- 开头的那把 Key。
- 智谱 GLM：BigModel 开放平台（open.bigmodel.cn）的 API 密钥页，形如「32 位 hex + 点 + 16 位随机」的一串。
录进去：点右上角「添加账号」→ 卡片式单选里选平台 → 粘贴 Key（也可以写一句备注，如「主号 / 备用号」）→ 提交。提交时会立即向该平台验活：Key 无效会当场报错、不入库；有效则账号立刻出现在总览页。
第一次会看到什么：「余额总览」页顶部一条四格读数条（账号可用 / 短期额度 / 长期额度 / 可用余额合计），下面每个账号一张卡片——可用余额、套餐与到期、全部额度窗口的刻度条与重置倒计时，底部是「N 个模型」和「查看全部数据 →」。第一格一旦有受限账号会转红，并点名最该先处理的那一个。
建议先做的三件事：开额度提醒 → 调阈值档位 → 挂上悬浮窗。详见下一节。

首次配置建议

开额度提醒

设置 → 监控 → 额度提醒，打开「启用提醒」。桌面端是屏幕顶部居中的置顶小窗，5 秒自动关闭；Web 版退化为应用内顶部浮层。

设阈值档位

默认档位是剩余 ≤ 3% / 5% / 10%。填「剩余 %」（1–100 的整数）回车或点「添加」成档，档位以 ≤x% 标签展示、可单个移除。「预览提示」可用示例数据走一遍真实呈现层。

挂上悬浮窗

余额总览页头的「悬浮窗」开关打开，桌面右下角常驻一行行额度百分比；写代码时瞄一眼就知道该换号了。可在设置 → 桌面悬浮窗里换成「叠条」形态。

挑个刷新间隔

设置 → 监控 → 自动刷新，可选关闭 / 30 秒 / 60 秒 / 120 秒，默认 30 秒。自动刷新是静默的，只换数据不盖蒙版。

两套口径不要混着说

提醒阈值是你自配的「想被弹窗打扰到多紧」，而总览里「账号可用」的判定线是固定剩余 10%—— 后者回答的是「这个账号还能不能指望」。两者是不同的事，界面上也不会互相覆盖。

页面导览

主窗口

整个客户端的容器窗口，所有页面都从这里进。主窗口以无边框方式启动，Windows 系统标题栏被去掉，顶栏左侧是拖拽区，右侧是自绘的「最小化 / 最大化⇄还原 / 关闭」三枚按钮。左侧竖向图标栏放「余额总览 / 设置 / 联系作者」三个入口，顶栏再放一组同名页签，两处同时高亮。顶栏常驻自动刷新倒计时（下次刷新 mm:ss），左下角可一键切换白天 / 黑夜主题，点版本号打开「关于与更新」。

余额总览

这是 80% 时间的停留页。

四格读数条：账号可用（可用数 / 总数）、短期额度、长期额度、可用余额合计，全部由后端统一聚合，前端只渲染。
直接点名最该先救的那个账号：主数字转红，副文案写明原因与细节——额度将尽（哪条窗口剩多少）、套餐已到期（到期时刻）、余额已用尽（可用余额金额）、尚无数据（从未查询成功）。
账号卡：可用余额（现金 / 代金券 / 授信）、套餐名与到期（过期标红）、全部额度窗口刻度条与重置倒计时。
平台筛选：页头一排 chip，第一个固定「全部平台」，切换平台时读数条会收敛到该平台。
拖拽排序：按住卡片拖动即可调整顺序，顺序落本机 SQLite，刷新后保持；被筛掉的账号留在原位。
卡片三点菜单：编辑备注、删除账号（删除走二次确认）。
一键复制 API Key：明文不随列表下发，只在点复制时取一次。
手动 + 自动刷新：手动「全部刷新」给卡片盖「正在刷新」蒙版，自动刷新静默换数据；两者共用同一份在途请求，不会重复发两轮。
失败写明原因：列表加载失败给顶部提示条 + 重试按钮；单卡失败盖可点击的失败蒙版写明原因，并保留上次数值、补一句「显示的是上次成功获取的数据」。

账号详情

从卡片「查看全部数据 →」进入。页头四格是这个账号此刻的即时摘要（最紧张窗口 / 最近一次重置 / 可用余额 / 套餐到期），下面六个分区各自独立成败、各自可单独刷新：

额度窗口：按「额度来源 × 模型」分组，含已用百分比、刻度条、窗口起止、重置时间与绝对次数（平台给出时才显示）。
套餐信息：当前订阅到期时间、套餐名、额度重置日、当前套餐权益、可购买套餐档位表。
可用模型：这把 Key 实际能调用的模型清单。
账户资金：可用余额 / 现金 / 代金券 / 授信 / 欠款 / 余额预警。
消费流水：汇总四格 + 逐条扣费明细（时间、调用方法、状态、消耗 token 数与金额）。
原始数据：每个分区的接口方法、命中地址、查询参数、脱敏请求头，以及平台未裁剪的原始响应 JSON。

平台压根没这类数据的分区会显示「该平台不提供这类数据」，且不给永远失败的重试按钮；本次查询失败的分区盖失败蒙版，点一下只重试该分区。

设置

两级导航：第一栏是「界面 / 监控 / 应用 / 存储」四个分组，第二栏是组内条目，点条目后页面只渲染对应的一个分区。导航条 sticky 吸顶，当前条目 key 写进地址栏 ?item=xxx，支持 ?item=overlay、?item=alert 直达与分享链接。

界面：白天 / 黑夜主题分段按钮，点击立即生效并记住。
监控：桌面悬浮窗（开关 + 单行紧凑 / 叠条形态）、自动刷新（开关 + 间隔）、额度提醒（开关 + 阈值档位 + 预览提示）。
应用：客户端更新（检查更新、下载进度、重启安装、更新偏好）、应用信息快照、已注册平台清单。
存储：数据库与数据、安装位置、系统目录，每条给出用途说明与占用大小，可复制路径或打开所在目录。

桌面悬浮窗

独立的置顶小窗，压在其它窗口之上，不抢焦点、不占任务栏。常驻态每行只留序号 + 两列百分比 （取周期最短的计费窗口 + 周期 ≥2 天的周额度），没有账号名、没有标题栏、没有倒计时、没有按钮。

拖动整块面板移动，带贴边吸附与位置记忆；右键弹系统原生菜单：刷新 / 展开明细 / 置顶 / 关闭。
悬停可看到账号名、各条窗口的已用百分比与重置时间；右键展开可看完整明细，也能收成一枚进度环。
悬浮窗在时，关闭主窗口会变为隐藏，应用留在系统托盘；托盘可唤起主窗口 / 悬浮窗 / 退出。
Web 版没有置顶窗口能力，该开关不显示。

额度提醒

剩余百分比跌破阈值档位时触发，桌面端弹出屏幕顶部居中的置顶小横幅：点一下立即关，5 秒不点自动消失，底部进度条随剩余时间线性收窄。一次最多逐条列 3 条，其余合并成「另有 N 个额度窗口剩余不高于阈值」。

提醒只报剩余百分比，不报余额金额、消耗明细、Token 数与重置时间。

联系作者

邮箱可一键复制，「项目主页」与「客户端下载」两条外链可直接打开，底部是 star 邀请。申请接入新平台时，邮件里写清平台名称与接口文档（或控制台地址）即可。

交互速查

拖拽卡片调整账号顺序

↑ / ↓聚焦卡片时逐位移动

单击卡片进入账号详情

三点菜单编辑备注 / 删除账号

右上角铃铛额度提醒开关

右上角齿轮直达设置对应分区

N 个模型查看并复制模型清单

分区刷新图标只重刷这一个分区

悬浮窗右键刷新 / 展开明细 / 关闭

左下角版本号关于与更新

左下角主题图标白天 / 黑夜切换

托盘图标唤起主窗口 / 悬浮窗 / 退出

提示

手动刷新与自动刷新共用同一份在途请求：手动点下去时不会额外再向平台发两轮请求；手动刷新会给卡片盖蒙版且最短可见 400ms，自动刷新只换数据、不盖蒙版。

数据存放位置与卸载

全部应用内可见：设置 → 存储，每条路径可一键复制或打开所在目录。

路径	内容
`%APPDATA%\com.genki-meow.coding-plan-query\`	数据库、更新缓存与可能的密钥文件
`coding-plan-query.db`	账号、额度窗口、资金快照与应用设置（SQLite，WAL 模式）
`updates\`	客户端自更新下载与校验缓存

卸载 NSIS 包时如果不勾选「删除应用程序数据」，数据库与可能存在的密钥文件都留在上面这个目录里，Key 仍以密文形式存在。要彻底清除：卸载时勾选那个复选框，或卸载后手动删掉整个目录。删掉之后旧密文永久无法解开（主密钥一去，密文就解不开了），但不影响你重新录入新 Key 继续用。

反馈前请脱敏

平台原始响应会整份存进本机库，可能含邮箱、手机号、账号标识。贴截图前请遮住 API Key 段（界面显示的是掩码，但仍含首尾真实字符），也不要把数据库文件直接发给别人。

已知限制

写在这里是为了让你先知道，别用起来才发现。逐条照实写，不藏。

平台覆盖有限：当前只注册了 MiniMax 与智谱 GLM 两家。Claude Code、Cursor、通义灵码、CodeBuddy 尚未接入。
智谱没有账户资金能力：智谱账号不参与「可用余额合计」，详情页账户资金分区显示「该平台不提供这类数据」。
只有 Windows 桌面发行版：没有 macOS / Linux 桌面发行版；Web 网关在 macOS / Linux 可以编译运行，但没有悬浮窗与系统托盘。
桌面专属能力在 Web 版不可用：置顶悬浮窗、系统托盘、提醒置顶小窗、自绘标题栏仅桌面端有；Web 版的额度提醒退化为应用内浮层，且需要本地网关进程提供接口，纯静态托管拿不到判定结果。
主窗口本身不产生数据：需要平台 API Key 且客户端能连通平台接口。断网时只能显示最后一次成功获取的快照并标注「显示的是上次成功获取的数据」——那是快照，不是实时数据。
对平台严格只读：不提供充值、购买 / 续费套餐、修改 Key、导出数据等写操作；消费流水也没有筛选、排序、分页与导出。
安装包未做数字签名：只做 sha256 校验，因此 Windows 会提示「未知发布者」；强制更新一旦发布没有「稍后再说」的出口。
额度提醒的能力边界：只报剩余百分比；一次最多逐条列 3 条；边沿触发记忆只在本次运行期间有效，重启后已越线的窗口会再报一次；弹窗会抢占键盘焦点。
悬浮窗的诚实边界：常驻态只有序号与两列百分比，没有账号名、余额与倒计时；宽度不可配置；拉取失败不显示错误、只保留旧快照。
拖拽排序与账号管理是本机偏好：不做云同步、不做多设备共享。
详情页是只读视图：改备注、开关余额预警、购买 / 续费套餐、充值、停用 Key 等操作一律不在详情页。
部分设置项不可调：悬浮窗宽度不可设置；自动刷新间隔只有关闭 / 30 / 60 / 120 秒四档；主题只有白天与黑夜两档；没有「恢复默认设置」入口；存储分区是只读展示。
Web 版网关没有鉴权：只绑定本机并校验 Host 头，但同机任何能向该端口发请求的进程都能取到明文 Key，别在不可信的机器上开。

常见问题

Q1：现在支持哪些平台？

目前只有两家：MiniMax（订阅 Coding Plan 与按量付费 Key）和智谱 GLM Coding Plan——应用内这个平台的显示名是「智谱」。Claude Code、Cursor、通义灵码、CodeBuddy 尚未接入。平台清单在「设置 → 已注册平台」里可以直接看到。

Q2：为什么我在总览里看不到智谱的余额？

因为智谱插件未挂载账户资金端口，智谱账号在总览里不参与「可用余额合计」，详情页的账户资金分区会显示「该平台不提供这类数据」。「可用余额合计」只统计有资金快照的账号，合计的是可用余额而不是全部资金。

Q3：需要注册账号吗？

不需要。没有账号体系、没有服务端、没有遥测，录完 Key 直接用。

Q4：我的 API Key 会被上传吗？

不会。API Key 以 AES-256-GCM 字段级加密后落本机 SQLite，明文 Key 不出 Rust 层，界面只见掩码、点复制时才向后端取一次。全仓库对平台的请求只有 GET，没有任何针对平台的写操作。

唯一要注意的是 Web 版网关：它是一个没有鉴权的本机 HTTP 接口，同机任何进程都能向它发请求——所以别在不可信的机器上开 Web 网关，桌面版没有这个问题。

Q5：数据库文件被别人拿到会怎样？

读不出明文 Key——字段级加密的密钥不在库里，在系统凭据库（凭据库不可用时降级为数据目录密钥文件）。

但要注意：平台原始响应会整份存进本机库，可能含邮箱、手机号、账号标识，所以不要把数据库文件直接发给别人；反馈问题前请描述结构与字段名，并对截图脱敏。

Q6：支持 macOS / Linux 吗？

桌面版：目前只提供 Windows 安装包，没有 macOS / Linux 桌面发行版。

Web 版：macOS / Linux 可以自行按「安装与下载 → 从源码跑」编译本地网关（需先装 OpenSSL 开发包），然后在浏览器里用；但同样没有桌面悬浮窗与系统托盘，额度提醒也退化成页面顶部浮层。

Q7：Web 版和桌面版有什么区别？

Web 版是同一套前端由一个独立的本地网关进程服务，浏览器直接使用。它没有置顶窗口能力——悬浮窗开关在 Web 版不显示；额度提醒退化为应用内顶部浮层（切走标签页就看不见），而不是桌面端的屏幕顶部置顶小横幅。

Q8：额度提醒会不会一直弹？

不会。触发口径是边沿触发：某个额度窗口跌破阈值时提醒一次，之后每次刷新都超线也不再重复；只有回升到该档以上再跌破才再提醒一次。去重记忆放在后端进程内、多窗口共享，主窗口、悬浮窗、Web 浮层不会对同一条额度重复轰炸。

要注意的是：这份记忆只在本次运行期间有效，重启应用后清空——已经越线的窗口在下次启动后会再报一次。

Q9：提醒会弹哪些内容？

只报「剩余百分比」，不报余额金额、消耗明细、Token 数与重置时间。一次最多逐条列 3 条，其余合并成一行「另有 N 个额度窗口剩余不高于阈值」。

Q10：阈值怎么配？

设置 → 额度提醒里填「剩余 %」（1–100 的整数档），回车或点「添加」成档，档位以 ≤x% 标签展示。默认口径是 3% / 5% / 10%。

注意这个档位和总览里「账号可用」的判定线（固定剩余 10%）是两回事：前者是「你想被弹窗打扰到多紧」，后者是「这个账号还能不能指望」。

Q11：断网了还能看额度吗？

能显示最后一次成功获取的快照，并标注「显示的是上次成功获取的数据」。刷新失败只更新错误信息、保留上次数值，不会把「查不到」写成「额度为 0」。但这不是实时数据，断网或查询失败时看到的都是旧快照。

Q12：这个工具会消耗我的额度吗？

不会。全程只有 GET 查询请求，不发起任何推理调用——对平台只有「读」的动作，没有消耗额度的调用。它一分钱也不替你花，但也不会替你省。

Q13：能加多少个账号？

没有上限限制，只受平台接口限流。同一平台可以加多把 Key（比如主号 / 备用号），备注写清楚就行。

Q14：能在这个软件里充值、买套餐、改 Key 吗？

不能。对平台严格只读，客户端内也不提供模型调用 / 对话入口。充值和续费请去平台自己的控制台。

Q15：消费流水能筛选 / 排序 / 导出吗？

不能。目前只提供「展开全部明细 / 收起全部明细」两种查看方式，没有按时间 / 模型 / 状态的筛选、排序、分页与导出。

Q16：拖拽排序的顺序会同步到别的电脑吗？

不会。拖拽排序是本机偏好，顺序存本机 SQLite，不做云同步、不做多设备共享。团队之间要统一口径只能各装各的、或者各自截图对账。

Q17：悬浮窗为什么没有账号名、也没有倒计时？

这是刻意的设计取舍：常驻态把每一个像素都留给数据——只有从 1 开始的序号和两列百分比。需要确认是哪个账号，鼠标悬停即可看到账号名、各条窗口的已用百分比与重置时间；需要全部明细，右键展开明细视图。

Q18：客户端更新安全吗？

更新信息与安装包托管在 Gitee 公开仓库，不需要服务端、不需要登录、客户端不带任何令牌；下载走分片并发 + 断点续传，临时文件校验通过才改名，安装前复校 sha256。

但要照实说清楚：目前只做 sha256 校验，未做数字签名，因此不能宣称「已签名 / 已校验发布者身份」——这也是安装时 Windows 会提示「未知发布者」的原因。如果远端已发布新版但没提供当前平台安装包，按钮会被禁用、无法下载。

Q19：卸载了 Key 还在吗？

默认还在。卸载 NSIS 包时若不勾选「删除应用程序数据」，数据库与可能存在的密钥文件都留在数据目录，Key 仍以密文形式存在。要彻底清除：卸载时勾选那个复选框，或卸载后手动删掉整个目录。删掉之后旧密文永久无法解开，但不影响重新录入新 Key 继续用。

Q20：怎么反馈问题或申请接入新平台？

发邮件 984769263@qq.com，或走 Gitee 仓库「反馈」渠道。申请接入平台时，邮件里写清平台名称与接口文档（或控制台地址）即可。

Q21：项目开源吗？

反馈与平台接入

有问题、需求，或想接入别的 Coding Plan 平台，直接发邮件（客户端里也有：左侧图标栏「联系作者」页）。

申请接入新平台：邮件里写清平台名称与接口文档（或控制台地址）即可。平台按插件方式接入，新增一家不影响已有平台。
反馈问题：请先描述你的系统版本、客户端版本、复现步骤；截图前请遮住 API Key 段。
安全问题：请不要用公开 Issue 报告安全问题，也不要粘贴 API Key、数据库文件或含完整 Key 的日志；走仓库「反馈」渠道或邮件联系。处理承诺是先确认问题、给出修复版本，再公开说明。

从安装到用起来，照着做就行