dsh-balance

DeepSeek 余额徽章插件 —— 在 DeepSeek Harness（dsh）Web 界面上实时显示 DeepSeek 账户余额。 A dsh bundle that shows your live DeepSeek account balance on the DeepSeek Harness Web GUI.

✨ 功能 / Features

• 📍 实时余额徽章 — 右上角显示 DeepSeek ¥x.xx，每 60 秒自动刷新（可在配置中调整）
• 🖱️ 可拖动 — 按住拖动到任意位置，位置保存在浏览器 localStorage（每个设备各自记忆）
• 👆 点击刷新 — 单击立即重新拉取余额
• ⚡ 双击复位 — 回到默认右上角位置
• 🛡️ 最高层级 — z-index 封顶，任何弹窗/遮罩都盖不住
• 🔒 Key 安全 — API Key 只存在于服务端（从 OpenClaw 配置文件读取），绝不下发浏览器
• 🚫 无代理缓存 — index.html 响应带 Cache-Control: no-store，前端代理不再缓存旧页面

📦 安装 / Install

把本 bundle 加入 dsh profile（与 dsh-trust-proxy 等本地 bundle 相同的方式）：

# 1. 在 profile 目录安装本包（或手动 symlink 到本地开发目录）
cd ~/.dsh/profiles/web
npm install @jonathanleelx/dsh-balance   # 或手动 symlink

# 2. 在 profile 的 package.json 中把包名加入 bundles：
#    "dsh": { "profile": { "bundles": [ ..., "@jonathanleelx/dsh-balance" ] } }

或者直接用 dsh plugin add @jonathanleelx/dsh-balance（若你的 dsh 版本支持）。

然后重启 dsh web（kill -TERM <pid> 优雅重启会先落盘会话，对话不丢失），刷新浏览器即可看到徽章。

⚙️ 配置 / Configuration

插件通过 bundle patch（cordis.patch.yml）配置：

- insert:
    - id: dsh-balance
      name: @jonathanleelx/dsh-balance
      config:
        keyFile: /root/.openclaw/openclaw.json   # 读取 models.providers.deepseek.apiKey
        cacheSeconds: 60                          # 服务端余额缓存秒数
        refreshMs: 60000                          # 浏览器徽章自动刷新毫秒数
        # apiKey: sk-xxx                         # 也可直接指定（优先级最高）
        # baseUrl: https://api.deepseek.com      # 也可直接指定

| 配置项 | 默认值 | 说明 | |--------|--------|------| | apiKey | 无 | 显式 DeepSeek API Key（优先级最高） | | keyFile | /root/.openclaw/openclaw.json | OpenClaw 风格 JSON 配置文件路径 | | keyPath | models.providers.deepseek.apiKey | keyFile 中 API Key 的点路径 | | baseUrlPath | models.providers.deepseek.baseUrl | keyFile 中 baseUrl 的点路径 | | baseUrl | https://api.deepseek.com | DeepSeek API 基础地址 | | cacheSeconds | 60 | 服务端余额缓存（秒） | | refreshMs | 60000 | 浏览器徽章刷新间隔（毫秒） |

Key 解析顺序：apiKey 配置 → DEEPSEEK_API_KEY 环境变量 → keyFile。

🔌 API

| 路由 | 说明 | |------|------| | GET /api/dsh-balance | 返回 { ok, balance, error?, fetchedAt }，balance 为 DeepSeek 官方余额接口原始响应 | | GET / | SPA index.html（带 Cache-Control: no-store，经 index taps 注入徽章脚本） |

🧑‍💻 开发 / Development

npm install        # 安装 devDependencies（含 TypeScript）
npm run build      # tsc 编译 src/ → lib/
npm test           # 编译产物语法检查

📄 License

MIT © 2026 JonathanLee-LX