aming1029/dsh-sub2api-usage ↗★ 0
dsh-sub2api-usage
在侧边栏显示 Sub2API 余额与用量详情 适合使用 Sub2API 接口并希望在 DSH 侧边栏实时监控 API 余额和详细用量的用户。
安裝
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:aming1029/dsh-sub2api-usage說明文件
閱讀完整 README ↗dsh-sub2api-usage
把 Sub2API 的余额和用量搬进 DeepSeek Harness 的左侧边栏：底部常驻一条实时余额，点开是完整用量面板，查询接口的每一部分都能在界面上改。
English — A DeepSeek Harness sidebar plugin for Sub2API: an always-visible balance chip at the bottom of the sidebar, a full usage panel (balance / quota / subscription / daily / per-model / rate limits / raw response), and a settings tab where the base URL, mode, paths, headers and JSON pointers are all customisable. Every upstream request is issued by the host process, so your Sub2API site needs no CORS and the credential never reaches the page.
dsh plugin --profile desktop add github:aming1029/dsh-sub2api-usage
状态 v1.0.0 · 测试 107 项 node:test，另在真实部署上跑通 · 依赖 DSH（带插件管理器）、Node ≥ 18 · 许可证 MIT
目录
它能做什么
| 位置 | 内容 |
|---|---|
| 侧边栏底部（「设置」旁边） | 常驻余额小条：$12.34 用量，带状态圆点，点一下打开面板 |
| 侧边栏图标区 | 一个「Sub2API 用量」图标，和「插件 / 自动化任务」并列 |
| 主面板 · 概览 | 钱包余额、账户、剩余额度；额度使用条；订阅日/周/月；用量趋势折线图（按天 / 按小时切换、悬停读数、切换指标、切换区间）；模型用量；限流窗口 |
| 主面板 · 明细 | 识别到的字段清单、每个上游请求的状态码、原始响应 JSON |
| 主面板 · 设置 | 服务地址、模式、凭证、路径、JSON 指针、刷新间隔……全部可改 |
三种凭证（管理员 Key / 站点 Key / 账号密码）和「完全自定义请求」都支持，不写死任何一种部署；后台按间隔自动刷新（默认 120 秒），余额低于阈值时小条和图标冒黄点。
安装
前置条件
- DeepSeek Harness，且命令行里有
dsh（本仓库按--profile desktop举例，换成你自己的 profile 名）。 - Node ≥ 18（
package.json的engines要求）。 - 一个可访问的 Sub2API 部署，以及下面任意一种凭证。
从 GitHub 安装
dsh plugin --profile desktop add github:aming1029/dsh-sub2api-usage
从本地目录安装
git clone https://github.com/aming1029/dsh-sub2api-usage
dsh plugin --profile desktop add file:D:/path/to/dsh-sub2api-usage
装不上？
dsh plugin add github:…需要能从你这台机器访问github.com（git 走 443）。 网络受限时用上面的file:方式，或者只把目录拷过来（lib/、cordis.patch.yml、package.json三个是运行必需的）。
确认装好了
装好后不用重启：插件管理器会把它加进加载器树并即时生效，已经在开的页面通过 HMR 自动挂载。侧边栏底部应该立刻出现「未配置 用量」小条。
没出现就按 F5 刷新页面；还是没有，看排错。
快速开始
- 点侧边栏底部的余额小条（或图标区的「Sub2API 用量」）打开面板。
- 切到「设置」，按下面的表选一种模式填凭证。
- 点「保存并查询」。想先验证再保存，就点「测试连接（不保存）」——它用当前填的内容真发一次请求，但不写盘。
| 模式 | 填什么 | 能查到 |
|---|---|---|
| 站点 Key | sk-… | 该 Key 的钱包余额、订阅日/周/月、限流窗口、区间内的模型与按天用量 |
| 管理员 | 后台「系统设置 → 管理员 API Key」生成的 admin-…；填「用户 ID」查单个用户，留空或勾选「拉取用户列表」查列表 | 任意用户的 balance / frozen_balance / total_recharged |
| 账号密码 | 邮箱 + 密码（或直接填一个已登录的访问令牌） | 当前登录账号 |
| 自定义请求 | 方法 / 路径 / 请求头 / 请求体（+ 可选的 JSON 指针） | 任何返回余额的接口 |
不确定用哪种就选默认的「自动识别」：它按凭证形状判断——admin-… → 管理员，sk-… → 站点 Key，JWT 或邮箱密码 → 账号。
面板说明
侧边栏小条
| 显示 | 含义 |
|---|---|
$12.34 用量 + 绿点 | 查询正常 |
| 同上 + 黄点 | 余额低于「低余额提醒阈值」（默认 5），只是提醒，不是错误 |
未配置 用量 + 红点 | 还没填凭证（首次使用的正常状态） |
查询失败 用量 + 红点 | 请求出错，点开面板看红条里的原因 |
鼠标悬停小条会显示上次查询时间。
概览
按接口实际返回的内容渲染，没有的字段不会硬凑：管理员响应里没给你「冻结/已充值」就不显示那张卡；「剩余额度」和余额相同时也不重复显示。额度条、订阅日/周/月、按天用量折线图、模型用量、限流窗口同理，有才画。
用量趋势（折线图）
- 按天 / 按小时：左上角切换粒度，选择会存进「趋势默认粒度」，下次打开还是这个视图。
- 按天折线：纵轴刻度取整到 1 / 2 / 2.5 / 5 这类好读的整数，横轴按面板宽度自动抽稀日期标签，永远不会挤成一团。
- 悬停看单日：鼠标移到某一天，出现十字线 + 读数框，给出当天花费和站点返回的请求数、Tokens、实际扣费；也可以用
Tab聚焦图表后按←→逐天查看（键盘操作不依赖鼠标）。 - 切换指标：站点在按天数据里返回了请求数或 Tokens 时，左上角会出现「花费 / 请求 / Tokens」切换；没返回的指标不会显示成一个点不动的空页签。
- 区间快捷键：按天是
7 / 14 / 30 / 90 天（写回「统计区间（天）」），按小时是24 小时 / 3 / 7 / 14 天（写回「小时区间（小时）」）——都是保存配置，不是临时过滤，所以自动刷新后区间还在。 - 统计行：合计、日均（按小时视图是「时均」）、峰值（带日期或小时）、实际区间。
- 降级：区间里没有数据时显示空状态；只有一天数据时画一个点而不是一条看不出趋势的线。
按小时看用量（本机采样）
Sub2API 的 sk-… 接口只按天返回用量：请求里加 granularity=hour 也照样是 daily_usage；站点自己的小时接口（/api/v1/usage/dashboard/…?granularity=hour）要登录令牌，站点 Key 打不开（实测返回 Invalid token）。
所以按小时的数据由插件自己按小时采样：每次查询拿到的响应里都带「今天累计」（usage.today，或当天那条 daily_usage），宿主把相邻两次相减，差值记进它落到的那一个小时。代价和边界都摆明：
| 情况 | 表现 |
|---|---|
| 插件没在运行的小时 | 空着（线在这里断开），不会画成 0——没数据就是没数据 |
| 采样间隔被拉长（DSH 关过、休眠过） | 这段用量整段记在到达的那一小时，读数框里标「含中断时段」 |
| 跨过站点时区的零点 | 计数器归零时按新一天算，不会出现负数或巨大跳变 |
| 一小时里确实没人用 | 正常的 0（插件在跑就有这一笔） |
| 别的模式（管理员 / 账号） | 响应里没有累计值就不采样，按小时视图会说明「还没有小时数据」 |
保留最近 14 天（336 小时），存在 $DSH_HOME/sub2api-usage.hourly.json；页面上的「小时区间」决定看其中多少小时。采样不需要额外面向上游的请求——它搭在本来就要发的查询上，刷新间隔（默认 120 秒）就是采样间隔。
明细
三块内容：识别到的字段（扁平化的 路径 = 值 列表）、每个上游请求的 URL 与状态码、原始响应 JSON。换了站点或接口返回格式变了，先来这里对字段，再决定要不要填指针。
设置
查询模式
| 模式 | 上游请求 | 认证 |
|---|---|---|
key（站点 Key） | GET /v1/usage?start_date=&end_date=&timezone= | Authorization: Bearer sk-… |
admin（单个用户） | GET /api/v1/admin/users/{id} | x-api-key: admin-… 或管理员 Bearer |
admin（用户列表） | GET /api/v1/admin/users?search=&page=&page_size=&sort_by=&sort_order= | 同上 |
user（账号） | POST /api/v1/auth/login → GET /api/v1/auth/me | 登录返回的 access_token |
custom（自定义） | 你自己写的方法 / 路径 / 请求头 / 请求体 | 你自己写 |
响应既支持标准包封 {code, message, data}（code != 0 时把站点原文和修复建议一起报出来），也支持裸对象。
所有上游请求都由宿主（Node 侧）发出：站点不需要开 CORS，凭证也不会出现在页面里。
设置项参考
界面上能改的全部设置项、对应的配置文件字段和默认值：
查询接口
| 设置项 | 配置键 | 默认 | 说明 |
|---|---|---|---|
| 服务地址 | baseUrl | https://aiapi.aaming.icu | 任意 sub2api 部署；结尾斜杠会被去掉 |
| 查询模式 | mode | auto | auto / admin / key / user / custom |
| 凭证 | credential | 空 | 三态：留空=保持不变，填内容=替换，点「清除凭证」=清空 |
| 邮箱 / 密码 | email password | 空 | 仅账号模式使用 |
| 用户 ID | adminUserId | 空 | 管理员模式；留空或勾选下面的列表则查用户列表 |
| 搜索关键词 | search | 空 | 管理员列表的过滤条件 |
| 拉取用户列表 | listUsers | false | 勾上则查列表而不是单个用户 |
自定义请求（模式选 custom 时）
| 设置项 | 配置键 | 默认 |
|---|---|---|
| 方法 | custom.method | GET |
| 路径 | custom.path | /v1/usage?start_date={start}&end_date={end}&timezone={timezone} |
| 请求头（JSON 对象） | custom.headers | 空 |
| 请求体（JSON，GET 可留空） | custom.body | 空 |
路径里可用的占位符：{start} {end} {timezone} {id}。没填的占位符会原样保留（便于一眼看出配置漏了）。
字段映射与路径
| 设置项 | 配置键 | 默认 | 说明 |
|---|---|---|---|
| 余额 JSON 指针 | pointers.balance | 空 = 自动识别 | 见下一节 |
| 剩余额度指针 | pointers.remaining | 空 | 与余额不同时才单独显示一张卡 |
| 已用指针 | pointers.used | 空 | 额度进度条的分子 |
| 额度上限指针 | pointers.limit | 空 | 额度进度条的分母 |
| 用量路径 | paths.usage | /v1/usage | |
| 当前用户路径 | paths.me | /api/v1/auth/me | |
| 管理员单用户路径 | paths.adminUser | /api/v1/admin/users/{id} | {id} 会被「用户 ID」替换 |
| 管理员用户列表路径 | paths.adminUsers | /api/v1/admin/users |
还有几个只在配置文件里、界面上没放输入框的项（一般用不到）：
paths.login（/api/v1/auth/login）、paths.profile（/api/v1/user/profile）、pointers.frozen、pointers.recharged（不填也会自动识别 frozen_balance / total_recharged）、page、pageSize、sortBy、sortOrder、currency。
刷新与显示
| 设置项 | 配置键 | 默认 | 范围 / 说明 |
|---|---|---|---|
| 自动刷新间隔（秒） | intervalSec | 120 | 0 = 只手动刷新；失败后也不会比这个间隔更快重试 |
| 统计区间（天） | rangeDays | 30 | 1–365 |
| 趋势默认粒度 | granularity | day | day 或 hour：面板打开时趋势图先显示哪种 |
| 小时区间（小时） | hourlyHours | 24 | 6–336（本机采样最多保留 14 天） |
| 低余额提醒阈值 | lowBalance | 5 | 余额低于它时小条和图标出现黄点 |
| 货币符号 | currencySymbol | $ | 只影响显示 |
| 超时（毫秒） | timeoutMs | 15000 | 1000–120000 |
| 时区 | timezone | Asia/Shanghai | 作为 {timezone} 占位符和查询参数发给站点 |
JSON 指针怎么写
指针用来从返回的 JSON 里取数，下面这些写法都认：
| 写法 | 例子 |
|---|---|
| 带斜杠的 JSON Pointer | /data/quota/remaining |
| 点号路径 | data.balance |
| 数组下标（两种都行） | /data/items[0]/balance、data.items.0.balance |
留空表示自动识别，内置会依次尝试这些常见位置：
- 余额：
/data/balance、/balance、/data/user/balance、/user/balance、/data/account/balance、/data/wallet/balance、/data/remaining、/remaining、/data/quota/remaining、/quota/remaining - 冻结 / 已充值：
/data/frozen_balance、/data/frozenBalance、/data/total_recharged、/data/totalRecharged - 已用 / 上限：
/data/quota/used、/data/subscription/used_usd、/data/quota/limit、/data/subscription/limit_usd
取不到值时不会崩，明细页会把识别到的字段全列出来，照着复制一个指针过去就行。
宿主 HTTP 接口（脚本调用）
面板用的接口也在本机 HTTP 上，可以直接 curl 用来做脚本或监控：
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /sub2api-usage/api/state | 掩码后的配置 + 上次快照 + 配置文件路径 |
POST | /sub2api-usage/api/config | 保存配置补丁（凭证三态同上） |
POST | /sub2api-usage/api/query | 用已保存的配置查询；可带 {"days":7} 或 {"start":"2026-09-01","end":"2026-09-30"} 临时改区间 |
POST | /sub2api-usage/api/test | 用候选配置试查，不保存：{"config":{...}} |
## 配置文件
| 文件 | 内容 | 权限 |
| --- | --- | --- |
| `%DSH_HOME%\sub2api-usage.json` | 服务地址、模式、路径、指针、刷新间隔等（**可以安全分享**） | 普通 |
| `%DSH_HOME%\sub2api-usage.secrets.json` | 只有凭证和密码 | 0600 |
- `DSH_HOME` 默认是 `~/.dsh`（Windows 上常见 `D:\dsh-home`）。
- 想放到别处就设环境变量 `DSH_SUB2API_DIR`，两个文件都跟着走。
- 面板「设置」页底部会显示这两个文件的真实路径。
- 两个文件都是原子写入（先写临时文件再改名），写坏了也不会留下半个 JSON。