💡 一句话：模型花掉多少钱，侧边栏里瞄一眼就知道 —— 余额来自官方 API，不是本地估算。

✨ 特性

	特性	说明
💰	真实余额	官方 GET /user/balance 端点，API key 核实，按账户币种显示
⚡	SSE 即时推送	余额一变，1 秒内上屏（EventSource 长连接 + 15s 轮询兜底）
🚨	低余额告警	低于阈值（默认 ¥5）数字变橙，悬停有提示
🌐	中英双语	文案跟随界面语言自动切换
🧹	零依赖	无 npm 运行时依赖、无构建步骤；Host 纯 ESM，Client 手写 bundle

🖥️ 界面

侧边栏底部，一行扁平原生风格（无卡片、无边框，hover 才高亮）——就一行，只有余额：

┌──────────────────────────┐
│  余额            ¥22.39  │
└──────────────────────────┘

• 余额低于警戒线 → 数字变 橙色（悬停提示警戒线）
• 数据过期（网络失败后退避期）→ 数字灰化，仍显示上次成功值
• 侧边栏折叠 → 只显示金额
• 标签页不可见 → 自动暂停轮询，省流量

📦 安装

npm（发布后推荐）：

dsh plugin --profile web add @pengpeng6845/dsh-balance

GitHub 直装：

dsh plugin --profile web add github:PengPeng6845/dsh-balance

然后确认 profile 的 package.json 的 dsh.profile.bundles 里有 "@pengpeng6845/dsh-balance"，重启 dsh web。

⚙️ 配置

在 profile 自己的 cordis.patch.yml 中按 id 覆盖：

- id: balance
  config:
    balanceEnabled: true              # 是否轮询官方余额端点
    balanceApiKeyEnv: DEEPSEEK_API_KEY # 余额 API key 的凭据引用（环境变量名）
    balanceBaseUrl: https://api.deepseek.com
    balanceRefreshMs: 60000           # 兜底轮询间隔（毫秒）
    lowBalanceAlert: 5                # 低余额警戒线（账户币种单位）

键	类型	默认	含义
balanceEnabled	boolean	true	是否轮询官方余额端点
balanceApiKeyEnv	string	DEEPSEEK_API_KEY	余额 API key 的凭据引用
balanceBaseUrl	string	https://api.deepseek.com	余额 API 基地址
balanceRefreshMs	number	60000	兜底轮询间隔；token 活动后约 20 秒也会主动刷新
lowBalanceAlert	number	5	低于该余额数字变橙

余额以账户币种显示，不做任何汇率换算。

🔄 工作原理

                ┌───────────────┐
                │   你的 API key │ (凭据环境变量，每次请求重新解析，绝不落盘)
                └──────┬────────┘
                       │ Bearer
                       ▼
   ┌──────────────────────────────┐
   │  GET /user/balance (官方)     │  每 60s 兜底轮询
   │  · token 活动停止 20s 后追查   │  · 失败指数退避 5s→5m
   │  · 并发去重 / 10s 超时         │  · 退避期继续供上次成功值
   └──────────────┬───────────────┘
                  │
                  ▼
   ┌──────────────────────────────┐
   │  余额采样 → storage 持久化     │  余额下降差 = 真实花费
   │  (schemaVersion 3, 旧数据迁移) │  (充值上涨自动忽略)
   └──────┬───────────────┬───────┘
          │               │
          ▼               ▼
  侧边栏小组件        token_usage 工具
  (SSE 即时推送)     (模型自查 tokens+余额)

❓ FAQ

为什么只显示余额，没有成本估算？ 官方没有用量明细 API，本地估算随价格表漂移（历史上曾高估 70 倍）。本插件只信 /user/balance 的账单真值：余额下降就是花费。 多久更新一次？ 模型回复结束约 20 秒后主动查一次（计费在回复后结算），查完通过 SSE 长连接 1 秒内推到页面（15 秒轮询仅作兜底）。流式输出过程中余额不动是正常的。 余额为 0 或显示"不可用"？ 检查 DEEPSEEK_API_KEY 环境变量/凭据是否配置，以及网络是否可达。悬停小组件可看详细提示。

🗺️ 路线图

• 侧边栏真实余额 + SSE 即时推送
• 低余额告警 / 中英双语 / 一键发版 / CI 加固
• 涨跌指示（▼¥0.08 每次消耗一目了然）
• 余额历史曲线
• 低余额 webhook 通知
• 多 API key / 多账户

🧑‍💻 开发与发布

npm test                        # 零安装单元冒烟测试（Node 20/22 CI）
npm pack                        # 生成可分发 tarball
npm run release -- 0.9.0 "..."  # 一键发版：bump+CHANGELOG+测试+tag+推送(+Release)
npm login && npm publish        # 发布到 npm

📄 许可

MIT © 2026 PengPeng6845

---