液态玻璃余额卡 SoDaZilla-zzz/dsh-liquid-glass-balance-card

dsh-liquid-glass-balance-card

一个用于 DeepSeek Harness（DSH）网页界面 的可拖动 液态玻璃悬浮卡片，用于显示你的 DeepSeek API 余额、累计消费 和 Token 用量。

一个给 DeepSeek Harness（DSH）网页界面 使用的插件：在页面右上角显示 DeepSeek API 余额、累计消费 与 Token 用量，采用可拖动的液态玻璃卡片。

由 sooodaaa 用 ❤️ 创建 · 创作者：sooodaaa

🎬 Demo / 效果演示

Demo GIF

GIF 预览 · 完整视频见下方播放器。

完整演示：液态玻璃效果、3D 立体厚度、颜色调节、余额与用量统计、充值入口。

完整演示：液态玻璃效果、3D 立体厚度、颜色自定义、余额与用量统计，以及充值入口。

✨ Features / 功能

| English | 中文 |
| 默认悬浮在右上角的卡片 | 默认悬浮在右上角 |
| 可拖动；位置会保存在 localStorage 中 | 可拖动，位置自动保存在浏览器 localStorage |
| 液态玻璃效果，参数可调节 | 液态玻璃效果，参数可实时调节 |
| 3D 厚度效果，带开关、深度和侧向角度控制 | 3D 立体厚度效果：可开关、调节厚度与侧向角度 |
| 自定义玻璃颜色，同时保留液态玻璃特性 | 自定义玻璃颜色，调节后仍保持液态玻璃特性 |
| 显示总余额、可用状态、赠送余额与充值余额 | 显示总余额、可用状态、赠送余额与充值余额 |
| 币种偏好（CNY / USD / Auto），避免多币种冲突 | 币种偏好（人民币/美元/自动），避免多币种余额冲突 |
| 累计消费与累计 Token | 累计消费金额与累计 Token 用量 |
| 双层用量统计：本地（由 DSH 会话日志聚合）+ 总计（线上）（DeepSeek 官方平台用量） | 双层用量统计：本地（由 DSH 会话日志聚合）+ 总计（线上）（DeepSeek 官方平台用量） |
| 时间范围：今天 / 昨天 / 最近 7 天 / 最近 30 天 / 全部 | 时间维度：今天 / 昨天 / 近7天 / 近30天 / 全部 |
| 可选的平台 userToken 凭据，用于线上总计 | 可选配置 DeepSeek 平台 userToken 以启用线上「总计」 |
| 在卡片设置中切换显示/隐藏线上总计 | 卡片设置中可开关「总计（线上）」显示 |
| 用于 7 天/30 天消费与 Token 趋势的液态玻璃柱状图，下方显示日期范围 | 近7天/近30天液态玻璃柱状图展示消费与 Token 趋势，柱状图下方显示日期范围 |
| 一键 DeepSeek 充值链接 | 一键跳转 DeepSeek 官方充值入口 |
| 在卡片设置中手动输入 API key | 支持在卡片设置中手动填写 API Key |
| 回退到 DSH DEEPSEEK_API_KEY 凭据 | 未填写手动 Key 时自动使用 DSH 已配置的 DEEPSEEK_API_KEY |
| 每 60 秒自动刷新 + 手动刷新 | 每 60 秒自动刷新，也可手动刷新 |
| 在插件配置卡片中可配置刷新间隔（余额与线上总计） | 插件配置卡中可分别设置余额与线上「总计」的自动刷新间隔 |
| 跟随 DSH 明暗主题变量（--dsw-） | 跟随 DSH 明暗主题变量（--dsw-） |

📦 Install / 安装

需要 DSH CLI 和 pnpm。

需要 DSH CLI 与 pnpm。

dsh plugin --profile web add dsh-liquid-glass-balance-card

重启 DSH Web / Restart DSH Web：

dsh web

打开 http://127.0.0.1:3080 并刷新页面，右上角会出现卡片。

Open http://127.0.0.1:3080 and refresh the page. The card appears in the top-right corner.

手动安装 / Manual install：将包放入 profile 的 node_modules，并在 ~/.dsh/profiles/web/cordis.patch.yml 中加入：

Put the package into the profile's node_modules, then add a loader entry to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
- id: liquid-glass-balance-card
name: dsh-liquid-glass-balance-card

⚙️ 配置 / Configuration

API Key

你可以通过卡片上的齿轮图标，或 设置 → 插件 → 插件配置 → DeepSeek 余额卡片（与官方插件配置卡片同款 UI）来配置 Key：

You can set the key from the gear icon on the card, or from the official plugin-configuration card under Settings → Plugins → 插件配置 → DeepSeek 余额卡片:

1. 粘贴 DeepSeek API Key 并点击「保存」 / Paste a DeepSeek API Key and click Save；
2. Key 通过 DSH 官方凭据系统存储（引用名 DSH_LIQUID_GLASS_API_KEY，由 harness 凭据提供者管理，不落任何插件自有的明文文件），浏览器永远看不到明文 / The key is stored through the official DSH credentials seam (reference DSH_LIQUID_GLASS_API_KEY, managed by the harness credential provider, never in a plugin-owned plaintext file); the browser never sees the value；
3. 点击「清除」可删除手动 Key，之后回退使用 DSH 自身的 DEEPSEEK_API_KEY / Click Clear to remove the manual key and fall back to the DSH DEEPSEEK_API_KEY。

手动 Key 优先于 DSH 已配置的 DEEPSEEK_API_KEY。若两者都没有，卡片会显示明确的错误提示。

Manual key takes priority. If neither is configured, the card shows a clear error.

升级说明：v0.1 存储在 $DSH_HOME/storages/dsh-liquid-glass-balance-card.json 的旧 Key 会在下次启动时自动迁移进凭据系统，随后旧文件被删除。

Upgrade note: keys stored by v0.1 in $DSH_HOME/storages/dsh-liquid-glass-balance-card.json are migrated into the credentials seam automatically on the next start, then the legacy file is removed.

平台 Token（用于线上总计）/ Platform Token (for online totals)

线上「总计」统计读取的是 DeepSeek 平台控制台的私有用量接口，需要已登录平台会话的 userToken（普通 API Key 无法读取）。可在卡片设置（齿轮）或 设置 → 插件 → 插件配置 → DeepSeek 余额卡片 中粘贴，并通过 DSH 凭据系统存储（引用名 DSH_LIQUID_GLASS_PLATFORM_TOKEN）。

The online 「总计」 statistics are read from DeepSeek's private platform dashboard endpoints, which require the userToken of a signed-in platform session (an API key cannot read them). You can paste it in the card settings (gear icon) or in Settings → Plugins → 插件配置 → DeepSeek 余额卡片, and it is stored through the DSH credentials seam under DSH_LIQUID_GLASS_PLATFORM_TOKEN.

获取方式 / How to get it：

1. 在浏览器中登录 https://platform.deepseek.com / Sign in to https://platform.deepseek.com in your browser；
2. 打开开发者工具（F12）→ 应用(Application) → 本地存储(Local Storage) → platform.deepseek.com → 复制 userToken 的值 / Open DevTools (F12) → Application → Local Storage → platform.deepseek.com → copy the value of userToken；
3. 粘贴到卡片或插件设置中并保存 / Paste it into the card/plugin settings and Save。
Token 不会回流到浏览器：浏览器只访问本地宿主路由；宿主仅将其发送给 platform.deepseek.com 的两个用量接口。

玻璃效果参数

所有参数均可在设置面板实时调节：

| 参数 | 范围 |
| 透明度 | 0% ~ 80% |
| 背景模糊 | 0px ~ 40px |
| 饱和度 | 100% ~ 300% |
| 高光强度 | 0% ~ 100% |
| 流动光线 | 0% ~ 50% |
| 3D 立体厚度 | 0px ~ 40px（可开关） |
| 侧向角度 | -30° ~ 30° |
| 玻璃颜色 | 自定义取色器（保持液态玻璃特性） |

参数保存在浏览器 localStorage，并提供「恢复默认」按钮。

用量统计

卡片显示累计消费与累计 Token，可切换时间维度：

- 今天
- 昨天
- 近7天
- 近30天
- 全部

每个时间维度下都有两层统计：

- 本地: 由宿主侧本地聚合 DSH 会话日志，并使用 DeepSeek 官方价格时间表计价，不会向任何第三方发送数据。
- 总计（线上）: 通过 DeepSeek 平台控制台用量接口（platform.deepseek.com/api/v0/usage/amount 与 .../cost）读取的官方用量；该接口只有已登录的平台会话（userToken）可以读取，普通 API Key 无法访问。需要可选配置平台 userToken（见下文）。可以在卡片设置（齿轮 → 统计显示 → 显示总计（线上统计））中隐藏「总计」区域。

准确性说明：「总计」为账号全部用量（含非 DSH 客户端的调用）；按北京时间分天对齐（与平台日历一致）；多币种账号优先显示余额对应币种；最多回溯 36 个月（超出会在卡片上提示）。平台数据相对实时用量可能有延迟；「本地」数据本身是基于会话日志的估算，两者存在小幅差异属正常现象。
统计区分为上下两块、以横线分隔：本地在上，总计（线上）在下，每块的累计数值与其 7d/30d 柱状图放在一起（该时间维度有柱状图时）。图表指标可在「消费金额 / Tokens / 输入 / 缓存 / 输出」间切换（Tokens 可拆分为输入、缓存命中、输出三类，本地与线上数据均含这些字段）。近7天图每根柱子下方标注日期，近30天图日期仅显示在鼠标悬浮提示中，图下方显示所覆盖的日期范围。

统计区分为上下两块、以横线分隔：本地在上，总计（线上）在下，每块的累计数值与其 7d/30d 柱状图放在一起（该时间维度有柱状图时）。图表指标可在「消费金额 / Tokens / 输入 / 缓存 / 输出」间切换（Tokens 可拆分为输入、缓存命中、输出三类，本地与线上数据均含这些字段）。近7天图每根柱子下方标注日期，近30天图日期仅显示在鼠标悬浮提示中，图下方显示所覆盖的日期范围。

🔒 隐私说明 / Privacy

- 你的 API Key 永远不会离开你的机器。浏览器只与本地宿主路由通信。
- API Key 不会离开你的机器，浏览器只访问本地宿主路由。
- 用量统计由本地 DSH 会话日志计算；可选的线上「总计」使用你的平台 userToken 读取 DeepSeek 官方平台用量接口（仅由宿主发送给 platform.deepseek.com）。
- 用量统计由本地 DSH 会话日志计算；可选的线上「总计」使用你的平台 userToken 读取 DeepSeek 官方平台用量接口（仅由宿主发送给 platform.deepseek.com）。
- 无统计、无追踪、无远程遥测。
- 无统计、无追踪、无远程遥测。

🏗 工作原理 / Architecture

| 部分 / Part | 文件 / File | 作用 / Responsibility |
| 宿主侧 / Host | lib/index.js | 注册本地路由：设置、余额、统计、线上统计；本地会话日志聚合 + 平台用量聚合 / Local routes: settings, balance, stats, online-stats; local aggregation from session logs + platform usage aggregation |
| 计价 / Pricing | lib/pricing.js | DeepSeek 官方价格时间表与峰谷计价 / Official DeepSeek pricing timeline + peak/off-peak pricing |
| 浏览器侧 / Browser | lib/client.js | shell.overlay 悬浮卡片、拖动、玻璃参数、统计 UI、充值入口 / shell.overlay floating card, drag, glass sliders, stats UI, recharge link |
| 组合层 / Composition | cordis.patch.yml | bundle 补丁层 / Bundle patch layer |

🛠 开发 / Development

git clone
cd dsh-liquid-glass-balance-card
edit lib/index.js or lib/client.js, then install locally:
修改 lib/index.js 或 lib/client.js 后本地安装测试：
dsh plugin --profile web add .

修改 lib/client.js 后重启 dsh web 并强制刷新页面；修改宿主代码（lib/index.js）后需要重启 DSH Web。

修改 lib/client.js 后重启 dsh web 并强制刷新页面；修改宿主代码（lib/index.js）后需要重启 DSH Web。

📄 协议 / License

MIT