阿里云余额悬浮条 wai549077/dsh-aliyun-balance

dsh-aliyun-balance

阿里云代金券 / 余额看板 —— 在 DSH 界面上悬浮一行，一眼看到还有多少钱能花。

主要服务于领了阿里云 300 元「云工开物」高校认证学生专属代金券、并用千问平台 API 接入 DSH 的用户—— 随时知道这张券还剩多少、什么时候到期。

可用 ☰ ¥128.50 ← 界面上浮着这一行（数字是你自己的）

- 悬停这一行 → 展开明细卡片（券余额、面值 / 已用、最早失效时间、现金 / 信控）
- 点 ☰ → 打开完整面板（配凭据、调外观、切显示项）

只报「还剩多少」，不报「花了多少」。 插件只读阿里云 BSS 的当前存量，不做任何消费统计 ——想知道花了多少请用 dsh-cost-meter（见与其它插件的关系）。

📘 还没领券 / 还没接千问 API？ 本仓库有一份完整图文教程：从领阿里云 300 元高校学生券 → 建千问 AI 平台 API Key → 接入 DSH → 装上本插件盯券余额，21 张截图一步步走完。

最快三步

1. 装插件 —— 见安装（克隆本仓库到本地固定目录，让 DSH 装上）
2. 拿 AK/SK —— 阿里云 RAM 里建一个只读子账号，创建 AccessKey
3. 填进去 —— DSH 里打开面板 → 凭据区填 AK / SK → 保存 → 点「测试连接」

不配置也能用：那一行会显示「未配置」。

实测环境：DSH Desktop（Windows）2.0.17。web profile（dsh web）的注入机制同源，但未经实测，欢迎反馈（见安装）。

安装

DSH 是从本地目录装插件的：先在一个固定位置拿到本插件的目录，再让 DSH 装上。
下面几种方式拿到的目录内容一致，区别只是你怎么拿到它。

npm 包已上线（dsh-aliyun-balance），
GitHub 仓库也已公开。插件市场直装随后上线 —— 上线后一句话即可：对 DSH 说「把 dsh-aliyun-balance 装上」，它会调用内置的 plugin_manager 装进 desktop profile。

从 GitHub 克隆（推荐）

git clone https://github.com/wai549077/dsh-aliyun-balance.git dsh-aliyun-balance

下载 zip

在本仓库页面下载 zip，解压到固定位置。

从 npm 拿

npm i dsh-aliyun-balance

或让 DSH 自己装（不能用于 desktop profile，见下）：

dsh plugin add dsh-aliyun-balance

让 DSH 装上

把含 package.json 的那一层目录放到一个固定位置 —— 别放临时目录，装好后移动目录需要重装。
然后在 DSH 桌面端的会话里说：

把 D:\Plugins\dsh-aliyun-balance 这个本地目录作为插件装上

装完自检

- 界面上出现那一行，显示可用合计（券 + 余额）
- %USERPROFILE%\.dsh\.dsh-aliyun-balance.log 里应出现 {"event":"apply"}

没看到那一行就重开一次客户端 —— 新装通常热生效，但实测有热生效不完整的先例。

桌面端与 web profile

⚠️ 桌面端读的是 desktop profile，而 dsh plugin 命令行按设计拒绝操作它（profile "desktop" is managed exclusively by the Electron application）。所以：

| 目标 | 装法 |
| 桌面端 | 上面的对话式安装（或插件市场直装） |
| web（dsh web） | dsh plugin --profile web add dsh-aliyun-balance |

实测环境是 DSH Desktop（Windows）2.0.17。web profile 的注入机制同源，但未经实测，欢迎反馈。

配置凭据

1. 建一个 RAM 子账号

阿里云控制台 → RAM 访问控制 → 用户 → 创建用户。不要用主账号。

建议勾选「使用永久 AccessKey 访问」，不要勾「使用控制台访问」（不给它登录密码，权限更小）。

2. 只给只读权限

| 方式 | 做法 |
| 授权单个 Action | bss:DescribeAcccount（查余额，官方原文就是双 c）、bss:DescribeCoupons（查代金券） |
| 或者直接挂系统策略 | AliyunBSSReadOnlyAccess |

插件只查余额与代金券这两类接口，不查其它任何阿里云接口。

面板里可以改 endpoint，但只允许 .aliyuncs.com（含国际站，如 business.ap-southeast-1.aliyuncs.com）；填成别的域名会被拒绝。所以插件的网络出口不会超出阿里云，但也不止固定的那一个主机。

3. 创建 AccessKey

为该子账号创建 AccessKey，拿到 AccessKey ID / Secret。

⚠️ Secret 只在创建时显示一次，关掉就再也看不到了（只能删了重建）。先复制出来再关窗口。

4. 填进 DSH

打开本插件的面板 → 凭据与设置 → 填入 AK / SK → 保存凭据（提交后输入框即清空）→ 测试连接 验证。

⚠️ 凭据是明文落盘的

插件把 AK/SK 写进 DSH 官方凭据服务，而 DSH 的本地凭据文件 ~/.dsh/.credentials.yaml 是明文 YAML（靠文件权限保护）。因此：

- 一定要用只读子账号的 AK，不要用主账号 AK
- 插件的设置接口永不回显密钥，只返回 hasAk / hasSk
- 插件只调用 business.aliyuncs.com 一个主机，只做查询，没有任何写操作

界面

那一行

可用 ☰ ¥128.50 —— 「可用」是可用合计 = 代金券余额 + 阿里云账户余额：券会被抵扣掉、账户余额也能花，两者相加才是真正还能用的钱。

| 操作 | 效果 |
| 按住拖动 | 拖到任意位置，自动记忆 |
| 双击 | 复位到默认位置 |
| 单击 | 立即绕过缓存刷新一次（☰ 按钮除外，它只管开面板） |
| 悬停 | 展开明细卡片 |

挂件默认贴着窗口底部；窗口比默认位小时会自动收进视口内，不会跑出屏幕。缩放窗口（小窗 ↔ 全屏）会重新定位：贴着底部放的就始终贴底，拖到别处的就钉在原地不动。换窗口大小也不会飘。

悬停明细

纯展示，不可交互（鼠标进不去）。显示：可用合计、券余额、阿里云余额、现金 / 信控、券面值与已用、券失效时间、计价时段、数据时间（计价时段可在菜单里关掉）。

每一行都是从阿里云直接读到的，没有一个是推算出来的。

菜单面板

点 ☰ 打开，再点一次收起（鼠标移到按钮上，会在下方冒一个「菜单」小提示框）。面板是三个入口行：

[ ] 凭据与设置 ·············· AK·SK 已配置 ▸ [ ] 外观与挂件 ·············· 可拖动 · 默认外观 ▸ [✓] 计价时段 ················ 闲时（便宜）· 4小时后转忙 ▸

- 每行右侧是当前值摘要 —— 不展开也能看出状态
- 点一行才展开该区的设置项，可同时展开多个，状态会记住；默认全部收起
- 行左侧带方框的是该项总开关；点开关不会展开这一行（否则想关掉时会顺手把区拉开）
- 关闭方式：右上角 × / Esc / 点面板外
- 面板整体落在那一行之外，不会被挂件挡住；屏幕中部时高度按剩余空间自动收，不顶出视口

凭据与设置：AK / SK 输入、保存凭据、测试连接、立即刷新，以及一行只读的自动刷新节奏提示。

外观与挂件：

| 选项 | 说明 |
| 锁定位置 | 勾选后钉在当前坐标，拖动与双击复位停用 |
| 背景色 / 文字色 | 取色器，实时生效 |
| 不透明度 | 0–100%，只淡背景与投影；边框与文字不随之变淡 |
| 隐藏边框 | 关掉那一行的描边 |
| 恢复默认外观 | 回到出厂值（见下） |

- 出厂默认是「只留文字 + 细描边」：颜色跟随 DSH 主题（不自定义任何颜色），不透明度 0 把背景与投影淡掉，但保留边框 —— 好让新装的人一眼找到挂件在哪。
- 自定义只作用在那一行上，悬停明细与面板仍跟随主题。
- ⚠️ 恢复默认外观只改外观四项，不动「锁定位置」与「计价时段」。

显示项 → 计价时段（默认开）：控制悬停明细里要不要显示「计价时段」那一行。

⚠️ 这条时段是千问平台的口径（闲时 22:00–08:00，东八区），且只对按闲忙双档计价的模型成立—— 目前是 deepseek-v4.1-flash / deepseek-v4-pro-0813 / deepseek-v4-flash-0731 这三支。
其它模型全天同价，此时这一行只是一条时刻提示，不代表你的花费会变。用不上就关掉。

配色

全部走 DSH 主题令牌（--dsw-alias-），跟随明暗主题自动切换。

数字怎么读

- 「可用额度」不包含代金券 —— 券余额单独成区；那一行显示的是券 + 余额的合计
- 余额与券每 5 分钟刷新一次；单击那一行可强制绕过缓存
- 它们读的是 BSS 的当前存量，不是账单，也不适合反推消费：实测余额 / 券扣减有延迟，一轮对话前后的差值不可靠
- 插件不统计任何消费：不看会话事件、不做金额估算

与其它插件的关系

| | 本插件 | dsh-cost-meter |
| 回答什么 | 还剩多少 | 花了多少 |
| 数据来源 | 阿里云 BSS 当前存量（券 + 余额） | 逐轮 token × 单价 |
| 覆盖面 | 阿里云一家 | 18 个 provider、数百个模型 |

互补，不重叠。 而代金券余额与抵扣明细全市场只有本插件有 —— dsh-cost-meter 的阿里云查询把 Action 写死成 GetFundAccountAvailableAmount，改不成查券。

故障排查

界面上的报错只给中文结论（哪里错、怎么改）；阿里云的英文原文与请求细节只写进日志 —— 截图看不懂时，把日志发给 AI 就能定位。

| 现象 | 处理 |
| 装完没出现那一行 | 重开一次客户端；看 %USERPROFILE%\.dsh\.dsh-aliyun-balance.log 有无 {"event":"apply"} |
| 「未配置凭据」 | 配只读 AK；面板里「测试连接」验证 |
| 查余额报 Forbidden | RAM 子账号缺 bss:Describe / bss:Query 只读权限 |
| 报错看不懂 | 按面板上的错误码看下表的日志事件，或把日志发给 AI |
| 挂件位置乱了 | 双击那一行复位；若勾了「锁定位置」先取消锁定 |
| 想看前端跑到哪一步 | 看日志里的 client-ping（stage 见下表） |

日志事件（%USERPROFILE%\.dsh\.dsh-aliyun-balance.log，200 行环形缓冲）

| event | 什么时候出现 | 关键字段 |
| apply | 插件加载 | profile / endpoint / seq |
| overview | 每次取数（30s 节流） | ok / stale / errors[]（scope:code） |
| refresh-fail | 某个分区取数失败 | scope / code / message（原文前 200 字） |
| cred-write-fail | 凭据写盘失败 | ref / code / message |
| resolve-miss | 读不到已存凭据 | reason（no-service / empty / throw 等） / akRef |
| client-ping | 前端自报，按 stage 区分（见下） | stage / msg（原文前 800 字，带 client / tb / v 归属标记） |

client-ping 的 stage

| stage | 含义 |
| host | 启动快照：detect（顶部挡墙高度）/ vw / vh / dpr；Desktop 为 0，官方 DSH 为 40 |
| apply / booted / dom-ready | 启动各阶段，确认脚本装上了 |
| load-fail | 拉取 overview.json 失败（超时、HTTP 状态等原始异常） |
| test-fail | 「测试连接」失败：阿里云原始 message（SignatureDoesNotMatch 时含完整签名串） |
| save-fail | 保存凭据失败：宿主写盘/校验失败的原文 |
| manual-fail | 点那一行强制刷新失败 |
| top-wall | 存档位置被顶部挡墙抬高（from / to / vh） |
| positioned / positioned2 / self-heal | 定位结果与自愈（mode / was） |
| tokens | 主题令牌探针（排查配色/透明度异常） |
| drag-stale | 指针被窗口拖拽抢走后强制收尾 |
| error | 启动期未捕获异常 |

给 AI 的一句话

读 C:\Users\<用户名>\.dsh\.dsh-aliyun-balance.log，看最近一条 refresh-fail 或 client-ping 里 stage=test-fail 的 code / message，判断是凭据、权限、网络还是系统时间问题。

发版前真机验收（10 条）

布局、遮挡、Electron 非客户区这几类问题单测测不到（DOM 桩没有布局，也没有窗口系统），只能真机看。每次发版在两个客户端各跑一遍：

| # | 检查 | 通过标准 |
| 1 | 启动 | 官方 DSH 与 DSH Desktop 都能看到那一行，显示「可用合计」 |
| 2 | 顶部挡墙 | 官方 DSH 往上拖会被最小化/最大化/关闭那一栏挡住；松手后仍能点击、能再拖 |
| 3 | 拖动与复位 | 拖到任意角落不越界；双击那一行回到默认位置 |
| 4 | 缩放窗口 | 小窗 ↔ 全屏切换后，贴底的仍贴底，位置不漂 |
| 5 | 重启恢复 | 退出重开，挂件回到上次的位置；官方 DSH 的上次位置若在顶栏里会被抬回墙下 |
| 6 | 悬停明细 | 卡片内容完整、不遮挡那一行；过期券不计入面值 |
| 7 | 菜单 | 三个分区能展开/收起；「计价时段」开关立即生效 |
| 8 | 错误提示 | 输错 AK 或 SK →「测试连接」：只有一行中文结论，不出现英文原文/签名串 |
| 9 | 正常链路 | 正确凭据 → 保存 → 余额与券刷新；重启后仍能取数 |
| 10 | 主题与日志 | 深浅主题切换配色跟随；日志里有 client-ping 的 host 快照，v= 与 package.json 版本一致 |

开发

交接与维护说明见 docs/HANDOFF.md（当前状态、发版流程、排查入口、已知外部漂移）。

npm test # 全量单测（= node --test）
node test/normalize.test.mjs # 单跑一个文件

CI：.github/workflows/test.yml 在 push / PR 时用 Windows + Node 22 跑 npm test。

改动的生效方式不一样，这点很容易误判：

| 改什么 | 怎么生效 |
| assets/widget.js | 整个退出再重开客户端。宿主每次请求都重读磁盘，但渲染进程会缓存这个响应 —— 实测改完十几分钟仍有实例在跑旧代码，只刷新页面不保险 |
| lib/*.js | 必须重启内核（只重启桌面客户端外壳无效） |

调试钩子默认不挂。 挂件内部状态里含正在输入的 AK / SK 草稿，所以 window.__DSHAB__ 只在显式打开后才存在 —— 浏览器控制台里执行 window.__DSHAB_DEBUG__ = true 再刷新页面。

文件导览

- lib/index.js 宿主侧：注入行 / 三条路由 / 凭据 / 调度
- 注：ok 的语义是「凭据可用」，不是「取数全成功」；分区失败体现在 errors 里
- lib/bss-client.js 阿里云 BSS ACS3-HMAC-SHA256 签名（有黄金哈希用例）
- lib/normalize.js 余额与代金券归一化、buildOverview 组装
- lib/cache.js 新鲜度判定
- assets/widget.js 前端挂件：那一行 + 悬停卡片 + 面板（原生 DOM，无构建步骤）
- test/ 6 个测试文件；test/widget.test.mjs 用桩 DOM 直接评测真实前端文件

关于

本插件由 AI 辅助完成 —— 代码、文档与测试均在 AI 协助下迭代产出，经人工审阅与实测。

（界面上那一行显示的是你自己的阿里云数据，插件不上传任何信息。）

License

MIT