# coding-plan-query

**Repository Path**: public_client/coding-plan-query

## Basic Information

- **Project Name**: coding-plan-query
- **Description**: 多平台余额助手 —— 多账号额度总览桌面客户端（Tauri + Vue3）。纯本地运行，数据不出本机；客户端更新由 Gitee 仓库托管，不需要服务端。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://coding-plan-query.kmsxsanshi.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 订阅额度查询助手（coding-plan-query）

本地优先的多账号 **AI Coding Plan 额度查询客户端**。录入 API Key 后，一屏看清每个账号的
**可用余额**、**各模型额度窗口**（5 小时 / 7 天 / 30 天 …）的已用百分比与重置倒计时，
余额不够、额度快用完时第一时间发现。纯本地运行：没有账号体系、没有服务端、没有遥测。

![余额总览](docs/screenshots/overview.png)

- **支持平台**：MiniMax（订阅 Coding Plan 与按量付费 Key）、智谱 GLM Coding Plan
- **运行形态**：Windows 桌面客户端（Tauri 2），另有跨平台 Web 版网关
- **下载**：[Gitee Releases](https://gitee.com/public_client/coding-plan-query/releases)

## 功能总览

### 余额总览：一屏看清所有账号

- 顶部四格读数条：账号可用 / 短期额度 / 长期额度 / 可用余额合计（后端统一聚合，前端只渲染）；
  账号可用那一格会直接点名最该先处理的那个号与原因
- 每个账号一张卡片：可用余额（现金 / 代金券 / 授信）、套餐名与到期时间、
  **全部额度窗口**（按模型区分，含已用百分比、绝对次数、重置倒计时）
- 平台筛选、**拖拽排序**（顺序落库，刷新后保持）
- 页头常驻**桌面悬浮窗**与**额度提醒**两个开关，齿轮直达对应设置

### 账号详情：这把 Key 能查到的数据全部展开

![账号详情](docs/screenshots/detail.png)

- **额度窗口**：按「额度来源 × 模型」分组，含已用百分比、绝对次数、窗口起止与重置时间
- **账户资金**：可用余额 / 现金 / 代金券 / 授信 / 欠款金额 / 余额预警
- **消费流水**：扣费明细 + 顶层汇总（条数 / 累计 token / 累计现金）
- **可用模型**：这把 Key 实际能调用的模型清单
- **套餐信息**：订阅到期时间、套餐名、可购档位
- **原始数据**：每个分区都给出**接口调用说明**（方法 / 命中地址 / 参数 / 请求头）
  与平台**未裁剪的原始响应**，便于核对新增字段与维护

> **分区独立成败**：某个分区被平台拒绝（权限不足 / 接口不存在 / Key 类型不匹配）时，
> 只在该分区标注原因，其余分区照常展示，不会整页失败。

### 桌面悬浮窗：常驻桌面的额度速览

一个置顶小窗，只保留最关键的两类数据：**5 小时窗口**与 **7 天额度**，
没有账号名、没有标题栏、没有倒计时——只有顺序序号和两列数字。

| 单行紧凑 | 叠条 |
| --- | --- |
| ![单行紧凑](docs/screenshots/overlay-compact.png) | ![叠条](docs/screenshots/overlay-stacked.png) |

- 常驻态不放任何按钮：**拖动整块面板**移动（带贴边吸附、位置记忆），
  **右键菜单**刷新 / 展开明细 / 关闭
- 展开后显示完整窗口数据；可再收成一枚进度环
- 悬浮窗在时，关闭主窗口变为**隐藏**（应用留在系统托盘）；托盘可唤起主窗口 / 悬浮窗 / 退出
- Web 版没有置顶窗口能力，该开关不显示

### 额度提醒与自动刷新

- **额度提醒**：剩余百分比跌破阈值档位（默认 3% / 5% / 10%）时弹出提醒；
  边沿触发去重，不会反复打扰。桌面端是**独立置顶小窗**（屏幕顶部居中，5 秒自动关闭），
  Web 版退化为应用内浮层
- **自动刷新**：30 / 60 / 120 秒可选（默认 30 秒），手动单条 / 全部刷新随时可用
- **离线可见**：额度与资金快照落 SQLite，断网时仍显示最后一次已知数据并标注错误

### 其余特性

- **主题**：白天 / 黑夜，选择即时生效并持久化
- **API Key 加密**：AES-256-GCM 字段级加密，主密钥托管在系统凭据库
  （Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service）；明文 Key 不出 Rust 层，界面只见掩码
- **客户端自更新**：更新信息与安装包托管在 Gitee Release，客户端并发分片下载、
  sha256 双重校验、下载与安装解耦，支持强制更新拦截（详见
  [docs/客户端更新方案.md](docs/客户端更新方案.md)）
- **Web 版**：同一套前端可由独立网关进程服务（`webserver` feature），浏览器直接使用

## 项目架构

**技术栈**

| 层 | 选型 |
| --- | --- |
| 桌面壳 | Tauri 2（Rust 2021） |
| 前端 | Vue 3.5 + TypeScript + Vite 8 + Pinia + Vue Router |
| UI | Naive UI 2 + Tailwind CSS 4 |
| 本地库 | SQLite（sqlx 0.8，WAL 模式） |
| 外部调用 | reqwest 0.12（TLS 走系统栈：Windows schannel，Linux/macOS OpenSSL） |

**分层**：依赖单向向内，`commands → service → dao / platform → domain`。

- **commands**：Tauri 命令薄壳，不做业务
- **service**：编排层——余额刷新、详情聚合、偏好与提醒判定、更新流程
- **dao**：Repository 模式持久化（账号 / 额度窗口 / 资金快照 / 应用设置）
- **platform**：平台插件层（扩展点，见下）
- **domain**：稳定领域模型（`QuotaSnapshot` / `QuotaWindow` / `AccountBalance` …）

**平台插件机制**：平台能力收敛在 `src-tauri/src/platform/`，按**端口（Port）+ 注册表（Registry）**
组织。一类查询一个端口，新增平台 = 新建插件目录 + 注册表加两行，业务层零改动：

| 端口 | 职责 |
| --- | --- |
| `BalanceProvider` | 额度窗口 |
| `AccountBalanceProvider` | 账户资金 |
| `UsageRecordProvider` | 消费流水 |
| `ModelCatalogProvider` | 可用模型 |
| `SubscriptionProvider` | 套餐信息 |

设计约束：`service` / `dao` / 迁移 / 前端**不出现任何 `if platform == "xxx"` 分支**；
额度用「窗口列表」表达（平台有几个模型、几个窗口都不用改模型与渲染）；
新增平台不需要数据库迁移。完整操作手册见
**[docs/平台插件开发指南.md](docs/平台插件开发指南.md)**。

**目录结构**

```
src/                        前端（Vue 3）
  api/                      命令封装（Facade）+ 调用通道（桌面 IPC / Web HTTP 自动分流）
  components/               AppNav / AppRail / 悬浮窗面板 / 更新面板 …
  views/                    余额总览 / 账号详情（分区可被平台覆盖）/ 设置 / 联系作者
  platforms/                平台展示档案（字段中文表 + 分区组件覆盖）
  stores/  types/  utils/   Pinia 状态 / 与 Rust 一一对应的类型契约 / 工具
src-tauri/src/              后端（Rust）
  domain.rs                 领域模型
  platform/                 平台插件层（mod.rs 端口契约 + minimax/ + zhipu/）
  dao/  service/  commands/ 持久化 / 编排 / 命令薄壳
  infra/                    db 迁移、HTTP 工厂、crypto（Key 加密）、app_host
  webapi.rs + bin/webserver.rs   Web 版网关（axum，独立进程）
docs/                       深度文档（平台插件开发指南 / 客户端更新方案）
```

## 开发

```bash
pnpm install
pnpm tauri:dev      # 开发模式（前端 5273 端口 + Tauri 窗口）
pnpm type-check     # 前端类型检查
pnpm tauri:build    # 打包 Windows 安装包（NSIS）
cd src-tauri && cargo test    # 后端单测

# Web 版网关（HTTP 栈只在 webserver feature 下编译，桌面包不含它）
cd src-tauri && cargo run --bin webserver --features webserver -- --port 8891 --dist ../dist
```

发行只提供 Windows 安装包；源码在 Linux/macOS 编译需先装 OpenSSL 开发包
（Debian/Ubuntu：`apt install libssl-dev pkg-config`，macOS：`brew install openssl`）。

## 数据存放位置

- 数据库：`%APPDATA%\com.genki-meow.coding-plan-query\coding-plan-query.db`
- 更新缓存：同目录下 `updates/`
- 应用内全部可见：设置 → 存储，每条路径可一键复制或打开所在目录

## 隐私与安全

- **纯本地**：没有账号体系、没有服务端、没有遥测；数据只落本机 SQLite
- **API Key 加密存储**：AES-256-GCM 字段级加密，主密钥托管系统凭据库，
  密文带 `enc:v1:` 前缀、老库升级无感；数据库文件脱离本机也读不出 Key
- **对平台只读**：只调用各平台的查询接口，不发起任何消耗额度的请求
- **反馈前请脱敏**：贴截图前遮住 API Key 段（界面显示的是掩码，但仍含首尾真实字符），
  不要直接附上数据库文件

## 联系作者与支持项目

有任何问题、需求，或想接入别的 Coding Plan 平台（Claude Code、Cursor、通义灵码、CodeBuddy …），
直接发邮件：**984769263@qq.com**（客户端里也有：左侧图标栏「联系作者」页）。
平台按插件方式接入，新增一家不影响已有平台；想自己动手实现的，照
[平台插件开发指南](docs/平台插件开发指南.md)写一个也行。

| 项目 | 地址 |
| --- | --- |
| 项目主页（源码 / 文档 / 更新记录） | https://gitee.com/public_client/coding-plan-query |
| 客户端下载（Windows 安装包 / 历史版本） | https://gitee.com/public_client/coding-plan-query/releases |
| 作者邮箱 | 984769263@qq.com |

> ### ⭐ 喜欢这个项目？欢迎点个 star
>
> 仓库地址：https://gitee.com/public_client/coding-plan-query
>
> Star 是最直接的鼓励，也能让更多人看到这个项目。

## License

[MIT](LICENSE)