deepseek-balance-dsh

dsh plugin --profile web add deepseek-balance-dsh

deepseek-balance-dsh


仓库与 npm 包同名：deepseek-balance-dsh · npm。

（npm 上的 dsh-deepseek-balance 是另一个无关项目，与本插件无关。）

主题：dsh-plugin · deepseek-harness · deepseek

DeepSeek Harness 的 DeepSeek 余额与用量实时监控插件 —— 右下角悬浮小组件，

附高峰/空闲时段（梁文峰 / 梁文谷）价格提醒。

中文 · [English](README.md)

---

安装只需一步： 把 https://github.com/OwlNjust/deepseek-balance-dsh

发给您的 agent，它就知道如何自动安装本插件。手动安装步骤如下。

安装

本插件零运行时依赖，已发布到 npm：deepseek-balance-dsh。

提供两条安装路线——组合层安装（npm 包名或本仓库）与补丁层安装（本地克隆，改源码调试用）。

同一 profile 只能选一条：两条都用会让插件 id 被插入两次（见「agent 注意事项」）。

路线 A（推荐）：作为「组合包」安装（deepseek-harness ≥ 0.2.0）

本包声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，所以 harness 的插件管理器

可以直接把它当作组合包（profile 层）安装并自动激活——无需手改任何文件。两种装法等价：

• npm 包名（已发布）：

  dsh plugin --profile <profile> add deepseek-balance-dsh

• Git 仓库（源码为准）：

  dsh plugin --profile <profile> add https://github.com/OwlNjust/deepseek-balance-dsh

• 桌面端：菜单栏 →「管理插件 / Manage plugins」→ 填入

deepseek-balance-dsh 或 https://github.com/OwlNjust/deepseek-balance-dsh

管理器会把包加入 profile 的 dsh.profile.bundles，包内的 cordis.patch.yml（含激活插件的

insert 行）随之作为组合层生效。重载/重启 profile 后右下角即出现小组件。

路线 B：本地克隆 + 用户补丁层（离线 / 改源码调试用）

# 1. 克隆/复制仓库到任意可访问路径
git clone https://github.com/OwlNjust/deepseek-balance-dsh.git /tmp/deepseek-balance-dsh

# 2. 安装到 web profile（file: = 快照；link: = 源码符号链接，改代码即生效）
cd ~/.dsh/profiles/web
dsh plugin --profile web add link:/tmp/deepseek-balance-dsh

3. 把下面这段追加到 ~/.dsh/profiles/web/cordis.patch.yml（profile 的用户补丁层）：

- insert:
    - id: deepseek-balance-dsh
      name: deepseek-balance-dsh

4. 重启 profile：

dsh web

5. 可选验证：确认 web 服务器响应

curl -s http://127.0.0.1:3080/dsbal/state

强制刷新页面（Ctrl+Shift+R）后右下角出现小组件。让用户点击小组件 → 「配置」→

粘贴 DeepSeek API key（可选再填平台 userToken）→「保存」。

agent 注意事项

• npm 包名是 deepseek-balance-dsh；不要用仓库名 dsh-deepseek-balance 发布——该名字在 npm 上属于一个无关项目。
• 两条路线别混用：路线 A 已由组合层插入插件行，若再手工追加同一 insert 行，插件 id 会被

插入两次（cordis 按 id 折叠成一份，所以不会报错，只是组合树里多出一行、日后极易误判）。

切换路线时先确认 dsh.profile.bundles 与 profile 的 cordis.patch.yml 只有一边生效；

一条命令自检，结果必须是 1：

  dsh --profile web --dump-config | grep -c 'id: deepseek-balance-dsh'

若输出 2：删掉 cordis.patch.yml 里手写的那段（保留 dsh.profile.bundles 里的包，

组合层交给插件管理器维护），重启 dsh web 生效。反向切换（改回手写行）则先从

dsh.profile.bundles 移除本包。

• 配置与余额历史保存在 ~/.deepseek-balance.json（0600），切勿回显其内容。
• 卸载：删除 cordis.patch.yml 中的行、删除

~/.dsh/profiles/web/node_modules/deepseek-balance-dsh，重启 dsh web。

前置条件

• deepseek-harness 的 web profile（dsh web）；Node.js ≥ 20

（本插件在 v0.1.2-rc.1 上适配验证，并已复检至 v0.2.0-rc.2，四个版本零改动可用）。

• DeepSeek API Key（platform.deepseek.com → API keys）。
• 可选：平台 userToken（platform.deepseek.com → F12 → Application → Local Storage），

用于精确统计消耗/Token；未配置时自动回退为余额快照估算。

功能

• 余额 —— 总余额 / 充值余额，官方 GET /user/balance，每 5 分钟刷新。
• 时间段消耗 —— 今天 / 近24小时 / 近7天 / 自定义起始日期，含按模型明细（/usage/cost）。
• Token 消耗 —— 输入（命中缓存）/ 输入（未命中缓存）/ 输出，与平台用量页一致（/usage/amount）。
• 价格时段提醒 —— 🔴 梁文峰（高峰：北京时间周一至周五 09:00–12:00 与 14:00–18:00，

不含中国法定节假日，价格 ×2）与 🟢 梁文谷（空闲：其余时段，含周末与法定节假日全天，半价），

实时倒计时，高峰红色高亮，法定节假日显示 🎉 标识。

时段依据官方定价文档。

• 中英双语 —— 界面文案集中于 lib/client.js 的文案表；语言跟随宿主设置 → 浏览器语言，

面板内可一键切换；插件卡片标题/描述见 locale/zh.json、locale/en.json，图标 icon.svg。

• 可拖动定位 —— 右键按住药丸拖动即可移到任意位置，位置自动记忆；左键只负责点击展开面板。

药丸上右键不弹浏览器菜单（药丸即拖拽手柄）；展开面板时自动避让屏幕边缘，

窗口缩放后药丸也会自动夹回可视区域。面板底部提供「重置位置（右下角）」按钮，

一键恢复默认位置。

使用

项目 · 位置

API Key / userToken · 小组件 → 配置

时间窗口 · 小组件按钮（今天 / 24h / 7天 / 自定义）

刷新 · 「刷新」按钮（或自动：按配置的 pollIntervalMs，默认 5 分钟；标签页隐藏时暂停）

语言 · 跟随宿主设置的语言 → 否则浏览器语言；面板标题栏的 EN/中 按钮可手动切换（记忆在本机）

药丸摘要 · 右下角：当前价格时段 + 余额 + 时段消耗

架构

宿主 lib/index.js      仅装配：config 校验 → 建 store/service → 注册四条已认证路由 → 定时轮询
  ├─ lib/service.js    操作实现（getState / refresh / setConfig / setWindow / poll）
  ├─ lib/config.js     可调项 DEFAULTS + 校验（profile 的 config: 覆盖，整体替换语义）
  ├─ lib/store.js      状态文件：原子写（临时文件 + rename）、串行化、schemaVersion 信封、损坏隔离
  ├─ lib/deepseek.js   余额/用量 HTTP 客户端（浏览器头 + 15s 超时）与载荷解析
  ├─ lib/phase.js      时段/法定节假日算法（梁文峰/梁文谷）
  ├─ lib/window.js     窗口区间、快照估算、按天聚合计费与 Token
  ├─ lib/validate.js   /dsbal/* 请求校验（含 fromMs 范围、凭据长度与 key 形态）
  └─ lib/i18n.js       读取宿主语言偏好
客户端 lib/client.js   window.__ModuleLoader__ 产物：shell.overlay 悬浮小组件 + 文案表（zh/en）

认证：四条 /dsbal/* 路由都先过宿主自己的门禁 ctx.connection.admit(req)

（与 /api 通道同一套 Host/Origin 信任栅栏 + 浏览器 cookie 认证）。

未携带会话 cookie 的请求返回 401，跨源请求返回 403，方法不符返回 405，

非法请求体返回 400 且不改动任何状态。写入凭据的接口只对已登录的本机浏览器开放。

配置

在 profile 的补丁层按 entry id 覆盖（config: 是整体替换，未写的字段回落默认值）：

- id: deepseek-balance-dsh
  config:
    pollIntervalMs: 900000     # 轮询周期，30s ~ 24h，默认 5 分钟
    historyDays: 180           # 余额快照保留天数 / 自定义窗口上限，1 ~ 400，默认 90
    usageTtlMs: 1800000        # 用量接口成功缓存，1min ~ 24h，默认 1 小时
    usageErrorTtlMs: 600000    # 用量接口失败缓存，1min ~ 24h，默认 10 分钟
    maxSnapshots: 5000         # 快照条数上限，100 ~ 100000
    requestTimeoutMs: 15000    # 单次请求超时，1s ~ 120s

后端地址（balanceUrl / usageCostUrl / usageAmountUrl）也可覆盖，必须是 https。

任何非法值都会让插件激活失败并打印字段名，而不是静默用默认值。

模型访问（只读 agent tool）

插件通过可选注入注册一个只读工具（没有 tool 运行时的 profile 仍能正常激活小组件）：

工具 · 参数 · 返回

deepseek_balance · window（today/24h/7d/custom，可选）、fromMs（毫秒时间戳，仅 custom 用） · 当前价格时段、余额、该时段消耗与 Token 三类计数、配置状态、最近一次错误

只读是结构保证：工具只能触达 service.getState({ window })

…(truncated)