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）。所以：

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

---

配置凭据

1. 建一个 RAM 子账号

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

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

2. 只给只读权限

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

面板里可以改 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 输入、保存凭据、测试连接、立即刷新，以及一行只读的自动刷新节奏提示。

外观与挂件：

• 出厂默认是「只留文字 + 细描边」：颜色跟随 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 的 阿里云查询把 Action 写死成 GetFundAccountAvailableAmount，改不成查券。

---

故障排查

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

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

client-ping 的 stage

给 AI 的一句话

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

---

发版前真机验收（10 条）

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

---

开发

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

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

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

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

调试钩子默认不挂。 挂件内部状态里含正在输入的 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