@lls-a1/dsh-balance-float 0.0.0-stage → 1.1.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,91 @@
1
- # Temporary Holding Version
1
+ # 余额悬浮窗(balance-float)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ DSH Web UI 的悬浮小窗:显示当前 API 余额、今日已用、**每轮次消耗**和峰谷定价。
4
+ Host 半边自己维护本地用量账本(按轮记账 + 余额轮询),浏览器半边只读快照。
5
+
6
+ ## 安装
7
+
8
+ 插件以 DSH profile bundle 的方式挂载(Host + Client 两半,无构建步骤):
9
+
10
+ ```text
11
+ github:ming-a1/dsh-balance-float
12
+ ```
13
+
14
+ 在 DSH 的插件管理里粘贴上面的 spec 即可,总是拉默认分支的最新版本(不建议固定 tag,否则后续修复拿不到)。
15
+ 本地开发可以用 `link:/path/to/balance-float`,改完刷新页面即可生效。
16
+
17
+ 启用后 profile 里会多出一行 `id: balance-float`,可在 `config` 里覆盖账本路径、轮询间隔和 `apiKeyRef`(默认 `DEEPSEEK_API_KEY`,取不到时余额相关数字保持不动,不会归零)。
18
+
19
+ ## 两半
20
+
21
+ | 半边 | 文件 | 作用 |
22
+ | --- | --- | --- |
23
+ | Host | `index.js` + `lib/` | 订阅会话事件记账、轮询余额、写本地账本,注册只读路由 `GET /balance-float/snapshot` |
24
+ | Client | `client.js` | 在 `shell.overlay` 里注册悬浮窗(可拖动、每 4 秒刷新、点开看明细) |
25
+
26
+ ## 账本
27
+
28
+ - 位置:`$DSH_HOME/balance-float/usage.json`(可用 `storeFile` 改)。原子写入(临时文件 + rename),损坏时按默认结构重建。
29
+ - 首次运行若没有自己的账本,会从旧的 `.dshw-usage.json` **复制**一份做种子(余额、今日、历史、近期事件),之后两边互不影响。
30
+ - 字段:`date`、`dayStart`(今日 0 点余额)、`lastBalance`、`todayUsage`、`history`(按天)、`events`(每轮每模型一条,含 `ts`/`model`/`cost`/`tokens`)。
31
+
32
+ ## 记账与余额
33
+
34
+ - **逐轮记账**:监听 `session/event`,把 `assistant/message` 的 `usage` 按(会话, 轮次)聚合,`turn/end` 时按官方单价折成费用,每个模型追加一条事件(含 `input` / `cacheRead` / `output` 三个 token 分项)。子代理轮次同样计入。
35
+ - **Token 分项**:卡片里「Token 用量」默认折叠,标题右侧显示合计,展开后逐行给出缓存命中率(保留一位小数)/ 未缓存输入 / 缓存读取 / 输出;按日明细里同样给出这些行(本版本之前写入的事件只有合计,会显示为 0 并附提示)。
36
+ - **余额**:每 `refreshSeconds`(默认 20 秒)用 `credentials.resolve(apiKeyRef)` 取官方 API Key,请求 `https://api.deepseek.com/user/balance`,写回 `lastBalance`。密钥不出 Host 进程,也不写日志。
37
+ - **今日已用**:`dayStart - lastBalance`(能覆盖本机其它客户端的花费),同时不低过本地事件合计;跨零点时把昨日合计归档进 `history`,并用当前余额作为新一天基线。检测到充值(余额变大)时重设基线而不是报负数。
38
+ - 拿不到 Key 或接口失败时只保留已有数字,不会把余额写成 0。
39
+
40
+ ## 峰谷定价
41
+
42
+ - 峰时:北京时间周一至周五(不含法定节假日)`09:00–12:00`、`14:00–18:00`。
43
+ - 谷时:工作日 `12:00–14:00`、`18:00–次日 09:00`,以及周末、法定节假日全天。
44
+ - 卡片里「当前按X计费」后有一个 `?`,点开用两行展示(`峰` 红 / `谷` 绿各一行),再点收起,默认不占版面。
45
+ - 界面配色:**峰=红、谷=绿**(胶囊的时段标签、卡片徽标、单价表里当前生效的一侧)。
46
+ - 单价(元 / 百万 tokens,`谷 / 峰`):Flash 命中 `0.02 / 0.04`、未命中 `1 / 2`、输出 `4 / 8`;
47
+ Pro 命中 `0.15 / 0.3`、未命中 `4.5 / 9`、输出 `13.5 / 27`。
48
+ - 来源:<https://api-docs.deepseek.com/zh-cn/quick_start/pricing>。
49
+ - 2027 年节假日安排发布后,补 `lib/pricing.js` 的 `HOLIDAY_VALLEY` 表即可。
50
+
51
+ ## 配置
52
+
53
+ ```yaml
54
+ - insert:
55
+ - id: balance-float
56
+ name: 'dsh-balance-float'
57
+ config:
58
+ storeFile: '' # 账本路径,默认 $DSH_HOME/balance-float/usage.json
59
+ legacyFile: '' # 首次运行的种子账本,默认 $DSH_HOME/.dshw-usage.json
60
+ refreshSeconds: 20 # 余额轮询间隔
61
+ apiKeyRef: DEEPSEEK_API_KEY
62
+ ```
63
+
64
+ ## 外观设置
65
+
66
+ 胶囊右侧的滑杆图标(卡片标题栏里也有)打开外观面板,三项都即时生效并保存在 `localStorage['dsh.balance-float.appearance']`:
67
+
68
+ | 项 | 范围 | 说明 |
69
+ | --- | --- | --- |
70
+ | 背景透明度 | 0–90% | 0 用主题的 `--dsw-alias-bg-overlay`,越大越透(面板/胶囊/气泡一起) |
71
+ | 边框 | 0–100% | 边框层的不透明度 |
72
+ | 阴影 | 0–100% | 投影强度,0 时完全无影 |
73
+ | 圆角 | 0–20px | 胶囊、卡片、设置面板统一圆角,步长 5px,0 为直角(默认 16px;≥16 时胶囊为全圆) |
74
+ | 贴边收成小球 | 开/关 | 默认开。拖到屏幕左/右边缘(56px 内松手)时收成 46×46 的方形球,只显示余额(13px 粗体);左侧停靠时轮次气泡显示在球的右边,右侧停靠时显示在左边 |
75
+
76
+ 「恢复默认」回到 0% / 100% / 100%。实现是把背景与边框放在 `::before` / `::after` 图层上,文字和图标始终不透明,不会跟着变淡。
77
+
78
+ ## 交互
79
+
80
+ - 默认停在右下角,拖动后位置记在 `localStorage['dsh.balance-float.position']`。
81
+ - 收起态:余额 / 今日 / 当前时段与秒级倒计时;点开:本轮消耗与耗时、今日峰谷拆分、单价表、近 7 天柱状图、账本更新时间。
82
+ - 柱状图的每一根柱子可点击,打开该日明细:总消耗、调用次数与 tokens、峰谷拆分、按模型费用(数据来自账本事件;超出事件窗口的旧日期只显示总额)。
83
+ - 每结算完一轮,胶囊左下方浮出「本轮 ¥x」气泡,3 秒后自动淡出;同一轮只提示一次。
84
+ - 胶囊下方剩余空间 <120px(输入框就在这条底部带里)时,气泡自动翻到胶囊**上方**,尖角方向随之翻转;卡片开合或拖动胶囊后会重新量一次。
85
+ - 悬浮窗每 4 秒轮询一次,页面回到前台、窗口获得焦点或展开面板时立即补一次。
86
+ - 刷新按钮(环形箭头,请求中旋转)立即刷新;**点标题栏即可收起**(没有单独的收起按钮)。
87
+ - 卡片大号余额右侧有「充值 ↗」按钮,新标签页打开官方充值页 `platform.deepseek.com/top_up`(官方没有充值 API,只做跳转)。
88
+ - 页脚版本号可点击检查更新:悬停显示检查结果(有新版/已最新/失败),有新版时弹窗给出「复制安装链接」(`github:ming-a1/dsh-balance-float`),升级由插件管理器完成;插件本身不会修改自己的文件。
89
+ - 展开方向自适应:默认从胶囊**向下展开**;胶囊贴在屏幕底部、下方空间不够(<340px)时改为**向上展开**,并把卡片高度限制在视口内、内容区滚动。
90
+ - 卡片比胶囊宽(316px),靠右时自动改为右边缘对齐,不会顶出屏幕;胶囊本身的位置保持不变。
91
+ - 动效方向跟着展开方向走:向下展开从上方滑入、向上收起;向上展开从下方向上浮出、向下收回。均无缩放,收起先播 180ms 再卸载。