dsh-plugin-balance-hud
DSH 插件：常驻右下角的科技玄幻风 DeepSeek 余额徽章。Host 半边持有 API Key 并轮询余额，浏览器半边实时展示，密钥不进浏览器。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:jxboop/dsh-plugin-balance-hud#2e4aeb86117883f319c6593ba33d0e3f7f2467d7Plugin Balance Hud 以 dsh-plugin-balance-hud 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
常驻 DSH Web 界面上的余额徽章（shell.overlay 座位上的一格，点击穿透层里唯一接指针的条目）。Host 半边持有 DeepSeek API Key 并定时查询账户余额，浏览器半边把它渲染成一颗「能量核心」。
可以拖到任意位置，靠近边缘会自动缩进去，只留一条边在屏幕上。
git clone https://github.com/jxboop/dsh-plugin-balance-hud.git
node dsh-plugin-balance-hud/install.mjs
PowerShell（5.1 不支持 &&，用分号）：
git clone https://github.com/jxboop/dsh-plugin-balance-hud.git; node .\dsh-plugin-balance-hud\install.mjs
脚本是幂等的，做四件事：
<DSH 主目录>/plugin-src/dsh-plugin-balance-hud<profile>/node_modules 建链接（Windows 用 junction，无需管理员权限）<profile>/package.json 的 dsh.profile.bundles（只改这一个字段）然后：
Ctrl+C 停掉 dsh web，重新执行 dsh webCtrl+Shift+R 硬刷新为什么必须重启：bundle 列表与宿主路由只在进程启动时装载，热加载覆盖不到新装的插件。
装好后默认出现在右下角（小舞桌宠上方），拖到你喜欢的位置即可，位置会被记住。
常用参数：
node install.mjs --profile web # 指定 profile（默认 web）
node install.mjs --dsh-home D:\dsh-home # 自定义 DSH 主目录
node install.mjs --source ./本地目录 # 从本地目录安装（改代码时用）
node install.mjs --help
DSH 主目录默认按 $DSH_HOME → ~/.dsh 的顺序推断。
| 项目 | 要求 |
|---|---|
| DSH | 已在跑 dsh web（有 web profile） |
| Node.js | ≥ 18 |
| git | 安装时需要 |
| 凭据 | 你自己的 DEEPSEEK_API_KEY，见下方「凭据解析顺序」 |
node dsh-plugin-balance-hud/uninstall.mjs # 移除链接与 bundles 注册，保留插件目录
node dsh-plugin-balance-hud/uninstall.mjs --purge # 连插件目录一起删
重启 dsh web 生效。
≤ ¥10 琥珀、≤ ¥1 赤红。Esc 收起。error 态、状态行转红并说明原因 —— 读数已经陈旧，不会假装健康。徽章是可以摆的：
prefers-reduced-motion 下两个过渡都关闭。› 把手，点它缩进当前最近的一边（不想拖动时用）。实现要点：
transform，布局的 left/top 始终不动 —— 浏览器自己插值，滑动方向天然正确；文字用 opacity 淡出但保留盒子，所以滑到一半不会因为宽度突变而跳一下。row-reverse，露在屏幕边缘的是能量核心而不是文字尾巴。right/bottom 置 auto —— left/top 与它们并存会让 width: auto 的固定元素横向拉满整帧。localStorage（dsh-plugin-balance-hud:pos、dsh-plugin-balance-hud:tuck），分浏览器保存；旧版只存过 :collapsed，读取时按「右侧」迁移。配色沿用主题变量（--dsw-alias-label-secondary 等），深色与浅色主题下都可读；prefers-reduced-motion 下关闭全部动效。
| 半边 | 文件 | 职责 |
|---|---|---|
| Host | lib/index.js | 解析凭据、调用 GET /user/balance、在固定路径上返回 JSON |
| Browser | lib/client.js | 在 shell.overlay 座位上渲染徽章（可拖动、可靠边收缩），轮询上面的路由 |
API Key 从不进入浏览器。 浏览器半边只请求同源的 /plugin/balance-hud/balance，该路由返回的是裁剪后的余额标量。
credentials Cordis 服务（若该 composition 挂载了它）—— 它自己会叠乘环境变量与 provider 托管的存储；$DSH_HOME/.credentials.yaml 的 refs.DEEPSEEK_API_KEY。解析结果按 KEY_CACHE_MS 缓存；若上游返回 401/403，会强制重新解析一次再重试，这样轮换密钥不必重启进程。
{ "ok": true, "isAvailable": true, "source": "credentials", "at": 1730000000000,
"balances": [{ "currency": "CNY", "total": 8.14, "totalText": "8.14", "granted": 0, "toppedUp": 8.14 }] }
失败时返回 { "ok": false, "reason": "nokey|auth|network|shape|internal", "message": "…" }。message 是短中文说明，不含上游响应体，也不含密钥。
注册在 shell.overlay（frame 级叠加层里的一格），id 为 deepseek-balance-core、order 为 -10。使用自定义 id 只会新增一格，不会替换该座位里自带的条目；叠加层本身点击穿透，本条目只为自己重新打开指针事件。
由 cordis.patch.yml 插为一行 host row：
- insert:
- id: balance-hud
name: dsh-plugin-balance-hud
inject: [webServer]
这一行让 Cordis 挂载本包，从而（a）认领余额路由，（b）使本包进入 client-modules 扫描列表，其 dsh.client 声明被识别并加载浏览器半边。
inject: [webServer] 不是可选项：少了它，这一行会先于 web 载体激活、静默注册不到任何路由，浏览器就永远显示「信号中断」。
node test/run.cjs
五项检查，各自独立：
| 检查 | 验证内容 |
|---|---|
syntax | 两个半边都是合法 ES module，且为有效 UTF-8（无替换字符） |
contract | dsh.client 声明、exports["./client"]、__ModuleLoader__ 注册与 bundle patch 相互一致 |
host | 路由注册、凭据解析顺序、上游请求构造、载荷裁剪，以及成功/失败响应都不泄漏密钥 |
client | 浏览器半边能物化、只注入一份样式表、用自定义 id 占用 shell.overlay、轮询宿主路由，并从真实数据推导 ok / warn / danger / error 与收起态 |
gestures | 拖动的阈值/跟随/钳位/持久化、拖完的 click 被吞、四条边各自吸附的锚点与位移、点边缘展开回原位置 |
client 用的是带渲染循环的假 DOM：setState 会像真实 React 一样触发重渲染，因此断言读到的是最后一次轮询真正产生的树。
GET /user/balance；base URL 依次尝试 https://api.deepseek.com 与 https://api.deepseek.com/v1。exact 精确匹配，无鉴权 —— 它只暴露账户余额数值，不含任何可用凭据。若你的 Web 服务监听 0.0.0.0 且不可信网络上可达，请自行在前置代理处限制该路径。$DSH_HOME/.credentials.yaml；测试通过临时 DSH_HOME 隔离，不会触碰真实凭据。