简体中文（默认） · English README

✨ 项目介绍

dsh-plugin-balance 是一个 DSH（DeepSeek Harness）Web 插件，在输入框正上方显示一个小悬浮窗，可以：

• 查询 LLM 账户余额 / 套餐用量：支持 DeepSeek 官方、OpenCode Go、OpenAI，以及任意自定义额度接口。
• OpenCode Go：主窗口直接显示 5h / 每周 / 每月 三个用量百分比徽章（按用量高低自动变色：绿 → 黄 → 红）。
• DSH 会话 token 用量统计：你的 DSH 对话一共消耗了多少 token，按 每天 / 每月 / 总共 累计，并按模型拆分，持久化到磁盘。
• 费用估算：按 DeepSeek（峰谷价）、Kimi、GLM 等官方价对 token 用量估算费用。

悬浮窗可拖动、自动适配亮/暗主题，折叠成小胶囊后仍保留刷新按钮。

🖼 预览

① 用量明细 —— OpenCode Go 5h / 每周 / 每月 用量与重置时间

② Token 用量统计 —— 今日 / 本月 / 总共 + 最近 7 天柱状图 + 按模型统计 + 费用估算

③ 实际效果 —— 对话框内的悬浮窗

功能一览

🚀 以插件形式安装

插件已发布到 npm（dsh-plugin-balance）并带 dsh.bundle manifest，可直接用 DSH 标准插件命令安装：

dsh plugin add dsh-plugin-balance           # 默认 profile
# 或显式指定 Web profile：
dsh plugin --profile web add dsh-plugin-balance

该命令会解析 npm 包、写入 bundle 条目并启用插件。重启 dsh web（或热重载）后刷新浏览器页面即可。

手动安装（自己改 profile）

如果自己管理 profile（如离线环境 / 无 dsh CLI）：

1. 在 Web profile 的 package.json（如 ~/.dsh/profiles/web/package.json）中加入依赖（可用 npm 版本、tarball 或本地路径）：

   "dependencies": {
     "dsh-plugin-balance": "1.2.0"
   }

2. 在 cordis.patch.yml 中启用（包内已自带同样内容的 cordis.patch.yml）：

   - insert:
       - id: plugin-balance
         name: dsh-plugin-balance

3. 安装并重启：

   cd ~/.dsh/profiles/web
   pnpm install
   # 重启 `dsh web`，然后刷新浏览器页面

需要 webServer 与 credentials 服务（web profile 的 @deepseek-ai/dsh-web-app 已提供）。主进程半依赖 credentials、webServer、llm、settings、sessions。

⚙️ 使用说明

点击开关按钮打开设置：

• DeepSeek 官方余额：Key 可留空（自动使用 DSH 的 DEEPSEEK_API_KEY），也可在浏览器填写（存于 localStorage）；支持自定义 /user/balance 基地址。
• OpenCode Go 套餐用量：无需填写，自动读取 DSH 凭据 OPENCODE_GO_API_KEY（缺省回退 OPENCODE_API_KEY）。
• 自定义额度接口：可从 DSH 模型列表选厂商（自动带出 baseURL 与 apiKeyEnv），或手动填；密钥由宿主解析，不会发给浏览器。

点击柱状图按钮打开「TOKEN 使用量」面板：今日 / 本月 / 总共 + 最近 7 天柱状图 + 按模型统计 + 费用徽章。

🧮 Token 用量与费用

主进程半监听 DSH 会话事件流（session/event），把每次请求上报的 token 用量（未命中输入 + 缓存写、缓存命中、输出）按 日期 / 月份 / 模型 折叠累计，并持久化到 ~/.dsh/storages/dsh-plugin-balance-usage.json。

• 幂等：同一 turn:step 的新样本替换旧样本；重载 / 重启后重放日志不会重复计数。
• 模型归属按每个请求的 request/header 精确记录（会话中途切换模型也不会归错桶）。
• 费用按各厂商官方价计（DeepSeek 峰谷；Kimi K2/K3、GLM 4.x/5.x 恒价，非人民币价按 ~7.2 折算），按每个样本的发生时刻精确计价（详见界面内提示）。
• 提供给前端：GET /api/dsh-plugin-balance/tokens。
• 存储为 version 9：旧版数据不再估算折算，而是从会话事件流（含磁盘归档日志）精确重放重建。

📄 许可证

BSD-3-Clause