账户悬浮面板 namesColin/DSH-Plugin-Account-HUD

dsh-account-hud

DeepSeek 账户信息悬浮面板插件 / DeepSeek Account HUD Plugin

一个可停靠、可拖动的悬浮小部件，显示你的 DeepSeek API 余额与服务状态；若安装了 dsh-better-sidebar，还会在侧边栏注册一个「账户」Tab。
A dockable/draggable floating widget showing your DeepSeek API balance and service status; registers an "Account" tab in dsh-better-sidebar when installed.

适配 / Adapter

DeepSeek Harness v0.1

功能 / Features

- 💰 余额显示（官方 GET /user/balance 接口，服务端代理，API key 不进浏览器）/ Balance via the official API (server-side proxy - your key never reaches the browser)
- 📡 服务状态（https://status.deepseek.com/feed.rss，60s 轮询）/ Service status with 60s polling
- 📌 常驻顶栏：默认停靠在会话顶栏（【PTC 模式】旁），悬停展开详情 / Docks in the session header by default, hover to expand
- 🖱️ 自由拖拽：拖出顶栏即变成浮动窗（跟手），拖回顶部吸附 / Drag out to float, drag back to re-dock
- 🌏 中英双语界面（跟随 DSH 语言设置）/ Bilingual zh/en UI (follows the DSH locale)

📦 安装 / Install（npm 方式，推荐 / recommended）

已发布到 npm，一条命令安装（/ Published on npm, one command):

dsh plugin --profile web add dsh-account-hud

重启 DSH（/ Then restart DSH）:

dsh web
如果你是用源码 checkout 跑 DSH：/ If you run DSH from a source checkout:
pnpm dsh web

打开 DSH Web UI 并硬刷新（/ Open the UI and hard-refresh）Ctrl+Shift+R，顶栏会出现余额胶囊。

版本兼容性 / Compatibility

| DSH 版本 / DSH version | 状态 / Status |
| 0.1.5-rc.1+ | ✅ 已验证（类型检查 + 构建 + 运行）/ verified |
| 0.1.0-rc.5 | ✅ 支持（初版开发环境）/ supported |

DSH 0.1.5 把 agent preset id code 重命名为 ptc。本插件不依赖 preset id，因此不受影响；但如果你的 ~/.dsh/settings.yaml 里 agent-presets.default 仍是 code，新建会话会报 preset "code" not found，改成 ptc 或 standard 即可。
Note: DSH 0.1.5 renamed the agent preset id code to ptc. This plugin does not depend on preset ids; if your ~/.dsh/settings.yaml still has agent-presets.default: code, new sessions fail with preset "code" not found - change it to ptc or standard.

环境要求 / Requirements

安装前请确认以下环境（/ Before installing, make sure you have）:

| 依赖 / Requirement | 检查方式 / How to check | 安装方法 / How to install |
| DeepSeek Harness (DSH) 已安装且可用 / installed and working | dsh --version 输出版本号（兼容 0.1.0-rc.5 与 0.1.5-rc.1+）/ prints a version (works with 0.1.0-rc.5 and 0.1.5-rc.1+) | 见 DSH 官方文档 |
| DeepSeek API Key（可选，仅余额功能需要 / optional, only needed for balance） | https://platform.deepseek.com | 见下方「配置 API Key」 |

如果 dsh --version 报错，说明 dsh 命令不在 PATH：可全局安装 npm i -g @deepseek-ai/dsh，或把下文所有 dsh 替换为 npx -y --package @deepseek-ai/dsh dsh。
If dsh --version fails, install the CLI globally or replace every dsh below with npx -y --package @deepseek-ai/dsh dsh.

配置 API Key / Configure the API key

余额功能需要 DeepSeek API Key。DSH 从凭据系统读取——可在 DSH Web UI 的设置页配置，或在启动 DSH 的环境里导出（/ Set it in the DSH UI, or export it in the launching environment）:

export DEEPSEEK_API_KEY=sk-your-key
没有 key 时，余额区域显示「未配置 API Key」，服务状态仍正常显示。

使用说明

- 📌 停靠顶栏：启动后默认出现在会话顶栏（【PTC 模式】标签旁），显示 CNY 余额 + 状态点 + 最新状态 + ▼（▼ 表示还有更多状态）
- 🖱️ 悬停展开：鼠标放在胶囊上（不点击）即弹出完整详情面板（余额/统计/服务状态时间线），移开自动收起
- 🖱️ 拖出浮动：按住胶囊往下拖——拖动中的就是浮动窗本体（跟手移动）——松手即停在松手位置，且默认展开
- 📌 拖回吸附：把浮动窗拖回页面顶部 40px 带内，出现蓝色虚线停靠槽，松手即吸回顶栏
- 🔄 数据实时刷新：余额/状态每次请求都从官方 API 实时获取，前端 60s 轮询
- 🔌 装有 better-sidebar 时，侧边栏「+」菜单多一个「账户」Tab；未装则仅停靠/浮动窗

后端路由（参考）

| 路由 | 用途 |
| GET /api/account-hud/balance | 实时余额（每次请求实时获取） |
| GET /api/account-hud/status | 实时服务状态 |

卸载

dsh plugin --profile web remove dsh-account-hud

然后重启 DSH。

故障排查

| 现象 | 可能原因 | 解决 |
| dsh plugin 报 pnpm store 警告 | 全局 pnpm 版本与 profile 的不一致 | npm i -g pnpm@11 后重试 |
| 显示「未配置 API Key」 | 未设置 key | 配置 DEEPSEEK_API_KEY（见上文） |
| 安装后顶栏无胶囊 | DSH 未重启或浏览器缓存 | 重启 DSH + 硬刷新（Ctrl+Shift+R） |
| 报 "Failed to load plugins" 且提到 dsh-account-hud | 安装的包损坏 | dsh plugin --profile web remove dsh-account-hud 后重新安装 |

从源码开发

git clone git@github.com:namesColin/DSH-Plugin-Account-HUD.git
cd DSH-Plugin-Account-HUD
npm install
npm run build # 类型声明（tsc）+ JS bundle（tsdown）
dsh plugin --profile web add . # 本地安装

发布新版本:

npm run build
npm version patch # 0.1.0 -> 0.1.1
npm publish # 需 npm 登录；2FA 时加 --otp=

架构: 后端（src/index.ts）在 DSH 的 web server 上注册 API 路由，通过凭据服务读取 key；前端（src/client/index.tsx）用 document.body + createRoot 挂载 HUD（与 better-sidebar 同策略），跟随 DSH i18n 系统，并通过 ctx.get('betterSidebar') 可选注册侧边栏 Tab（解耦：装不装 better-sidebar 都能用）。

架构: 后端（src/index.ts）在 DSH 的 web server 上注册 API 路由，通过凭据服务读取 key；前端（src/client/index.tsx）用 document.body + createRoot 挂载 HUD（与 better-sidebar 同策略），跟随 DSH i18n 系统，并通过 ctx.get('betterSidebar') 可选注册侧边栏 Tab（解耦：装不装 better-sidebar 都能用）。

问题反馈

使用中遇到任何问题、bug 或改进建议，欢迎提 Issue：

- 🐛 Bug / 问题：https://github.com/namesColin/DSH-Plugin-Account-HUD/issues
- 💡 功能建议：同样通过上面的 Issues 页面
- 📝 反馈时请包含:
- DSH 版本（dsh --version）
- 插件版本（npm view dsh-account-hud version）
- 复现步骤或截图
- 浏览器控制台报错（如有）

本项目由 AI 辅助开发，部分细节可能不完善；你的反馈是改进的最大动力。

许可证

本项目使用 GNU Affero General Public License v3.0 (AGPL-3.0) 授权。

- 你可以自由 fork、修改、分发
- 修改后的分发版本必须同样以 AGPL-3.0 开源
- 完整协议文本见 LICENSE

GNU AGPL-3.0 简介