dsh-plugin-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，顶栏会出现余额胶囊。

---

环境要求 / Requirements

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

依赖 / Requirement	检查方式 / How to check	安装方法 / How to install
DeepSeek Harness (DSH) 已安装且可用 / installed and working	dsh --version 输出版本号	见 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」，服务状态仍正常显示（/ Without a key, the balance area shows "No API key configured"; status still works）。

---

使用说明 / Usage

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

后端路由（参考）/ Backend routes (for reference)

路由 / Route	用途 / Purpose
GET /api/account-hud/balance	实时余额（每次请求实时获取）/ Live balance
GET /api/account-hud/status	实时服务状态 / Live status
POST /api/account-hud/refresh	强制刷新两者 / Force refresh both

---

卸载 / Uninstall

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

然后重启 DSH（/ Then restart DSH）。

---

故障排查 / Troubleshooting

现象 / Symptom	可能原因 / Likely cause	解决 / Fix
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 后重新安装

---

从源码开发 / Development

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 .   # 本地安装

发布新版本 / Publishing:

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

架构 / Architecture: 后端（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 都能用）。

架构 / Architecture: 后端（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 都能用）。

---

问题反馈 / Feedback

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

• 🐛 Bug / 问题：https://github.com/namesColin/DSH-Plugin-Account-HUD/issues
• 💡 功能建议 / Feature request：同样通过上面的 Issues 页面
• 📝 反馈时请包含 / Please include when reporting:
  • DSH 版本（dsh --version）/ DSH version
  • 插件版本（npm view dsh-account-hud version）/ Plugin version
  • 复现步骤或截图 / Steps to reproduce or screenshots
  • 浏览器控制台报错（如有）/ Browser console errors (if any)

本项目由 AI 辅助开发，部分细节可能不完善；你的反馈是改进的最大动力。 This project is AI-assisted; your feedback is the biggest driver of improvement.

许可证 / License

本项目使用 GNU Affero General Public License v3.0 (AGPL-3.0) 授权 / This project is licensed under the GNU Affero General Public License v3.0.

• 你可以自由 fork、修改、分发 / You may freely fork, modify, and redistribute
• 修改后的分发版本必须同样以 AGPL-3.0 开源 / Modified distributions must be open-sourced under AGPL-3.0
• 完整协议文本见 LICENSE / Full license text: LICENSE

GNU AGPL-3.0 简介