dsh-account-hud

Readme

# dsh-account-hud

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

一个可停靠/可拖动的悬浮小部件，显示你的 DeepSeek API 余额与服务状态；若安装了 [dsh-better-sidebar](https://github.com/omdsh-dev/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](https://github.com/omdsh-dev/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):

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

重启 DSH（/ Then restart DSH）:

```sh
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 官方文档](https://github.com/deepseek-ai/deepseek-harness) |
| **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）:

```sh
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

```sh
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

```sh
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**:

```sh
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](LICENSE) / Full license text: [LICENSE](LICENSE)

[GNU AGPL-3.0 简介](https://www.gnu.org/licenses/agpl-3.0.html)