dsh-balance-widget

中文 | English

DeepSeek Harness (DSH) Web GUI 的余额与成本小部件：侧边栏底部常驻卡片显示账户余额与今日花费，点击弹出五层级成本明细（余额 / 最近提问·标注会话名 / 今日·本会话 / 今日·本工作区 / 今日·所有工作区）。

效果预览

| 侧边栏卡片（左下角常驻） | 点击弹出五层级成本 | | --- | --- | | | |

与同类插件的区别

| 特点 | 本插件 | 同类插件（dsh-balance / dsh-token-price 等） | | --- | --- | --- | | 零外部依赖 | ✅ 不 import 任何 @deepseek-ai/* 包，无原生模块 | ❌ 多数依赖 dsh SDK 包 | | Node 24 兼容 | ✅ 天然兼容（零依赖设计），任何 profile 布局可加载 | ⚠️ 不少社区插件在 Node 24 下报错 | | 启动稳定性 | ✅ 用官方 ctx.webServer 注册路由，不与 apiproxy 冲突 | ⚠️ 有的自建 HTTP 服务导致 dsh web 启动崩溃 | | 常驻自动刷新 | ✅ 侧边栏卡片每 60s 自动刷新余额与成本，弹框点击即强刷 | 有的常驻徽章定时刷新 | | 峰谷定价 | ✅ 内置官方 2026-09-10 峰谷价表，启动时与每 12h 自动从官方页刷新 | 部分支持 | | 安全性 | ✅ API key 仅在宿主进程，loopback-only 守卫 | 参差不齐 |

一句话：零依赖、Node 24 就绪、永不拖垮 dsh web 启动的余额/成本小部件。

功能

• 账户余额 — 点击图标时经宿主代理查询 DeepSeek 官方 GET /user/balance，展示 ¥ 余额；余额数字按阈值自动变色（充足 / 低于 lowThreshold 变黄 / 低于 criticalThreshold 变红）；API key 只在宿主进程内读取（凭据服务），浏览器不接触密钥。
• 最近一次提问成本（估算） — 从最近活跃会话文件解析最后一个 turn 的 token 用量 × 单价，回答"刚才那条提问花了多少"；下方标注该会话的会话名。
• 今日·本会话成本（估算） — 当前会话今天（自然日）产生的 token 用量 × DeepSeek 官方峰谷定价表计算，随当前会话模型（默认 deepseek-v4-flash，可在配置中改为 deepseek-v4-pro）与北京时间高峰/空闲时段自动切换。
• 今日·本工作区成本（估算） — 遍历当前工作区（由当前会话锚定）下的所有会话，累加今天的 token 用量 × 单价。
• 今日·所有工作区成本（估算） — 遍历 ~/.dsh/sessions/ 下所有工作区的所有会话，累加今天的 token 用量 × 单价。
• 峰谷状态标签 — 卡片与弹框边框按当前时段着色（峰时橙色 / 谷时绿色），弹框标题旁显示「峰时/谷时」标签，悬停可查看当前价格档位（输入/输出单价）。
• Token 用量 — 同时展示输入（含缓存命中）/ 输出 token 数。
• 一键充值 — 弹层底部「去充值」链接直达 DeepSeek 官方充值页（platform.deepseek.com/top_up），新窗口打开。
• 侧边栏常驻卡片 — 侧边栏底部（设置上方）显示余额 + 今日花费，全局可见；每 60 秒自动刷新（余额走官方接口、成本为本地会话解析），打开弹框时也会立即刷新一次，无需手动操作。
• 余额数字变色预警 — 余额数字按三档着色：充足（默认色）→ 琥珀（低于 lowThreshold）→ 红色（低于 criticalThreshold），一眼判断余额健康度。
• 官方价格自动同步 — 启动时 + 每 12 小时抓取 DeepSeek 官方定价页，改价自动跟进；失败回退内置价目表。
• 模型工具查询 — 新增 deepseek_billing 工具，可直接问模型"余额多少/今天花了多少"。

架构

host 半区 (lib/index.js)
  ctx.webServer.register:
    GET /api/dsh-balance/balance     → 官方 /user/balance（loopback-only 守卫）
    GET /api/dsh-balance/active-cost → 最近活跃会话的最近提问 + 今日·本会话（含会话名）
    GET /api/dsh-balance/today-cost  → 今日成本（双值：当前工作区 + 所有工作区）
  依赖：零外部 @deepseek-ai/* import，任何 profile 布局均可解析
  另有 deepseek_billing 工具供模型直接查询余额/成本

client 半区 (lib/client.js)
  ctx.slots.inject("sidebar.footer.action")
    → 侧边栏底部常驻卡片（余额 + 今日花费，峰/谷时段描边着色）
    → 点击弹出五层级成本明细 + 峰谷标签 + ⓘ 名词解释

安装

npm 安装（发布后）：

dsh plugin --profile web add dsh-balance-widget

GitHub 仓库安装（开发调试）：

git clone https://github.com/LL-cmyk-so/dsh-balance-widget.git
cd dsh-balance-widget
dsh plugin --profile web add "link:$(pwd)"

装完重启 dsh web 生效。

配置

配置文件在哪

DSH 的插件配置统一放在这个文件里：

~/.dsh/profiles/web/cordis.patch.yml

说明：~ 是你的用户主目录（macOS 是 /Users/你的用户名）。

全部配置项

在 cordis.patch.yml 中追加以下内容（只改你需要的那几行，其余保持默认即可）：

- id: balance-widget
  name: dsh-balance-widget
  config:
    balanceBaseURL: https://api.deepseek.com   # 官方余额接口（一般不用改）
    balanceApiKeyEnv: DEEPSEEK_API_KEY          # 凭据服务中的密钥 ref（一般不用改）
    requestTimeoutMs: 5000                      # 余额查询超时（毫秒）
    modelId: deepseek-v4-flash                  # 成本计价模型（可改 deepseek-v4-pro）
    lowThreshold: 5                             # 余额低于此值（¥）图标变黄提醒
    criticalThreshold: 1                        # 余额低于此值（¥）图标变红警告

示例：调整余额预警阈值

默认余额 低于 ¥5 变黄、低于 ¥1 变红。想改成"低于 ¥10 提醒、低于 ¥3 警告"：

- id: balance-widget
  name: dsh-balance-widget
  config:
    lowThreshold: 10
    criticalThreshold: 3

改完重启 dsh web 生效。

示例：成本按 V4-Pro 计价

如果主要使用 DeepSeek-V4-Pro 模型，把计价模型改掉，成本估算更准：

- id: balance-widget
  name: dsh-balance-widget
  config:
    modelId: deepseek-v4-pro

注意：官方已公告 V4-Pro 将于北京时间 2026-09-14 12:00 下线——此后 V4-Pro 请求会被路由到 V4.1-Flash 并按 Flash 计费。若在这之后仍配置 deepseek-v4-pro，估算会偏高，建议使用默认的 Flash 档。

提示：cordis.patch.yml 可能有其他插件的配置行，追加时注意不要改动已有的行，只加新内容。

定价说明

内置 DeepSeek 官方 2026-09-10 峰谷定价（元 / 百万 tokens），高峰时段为北京时间周一至周五 09:00–12:00、14:00–18:00（周末全天为空闲时段），价格为空闲时段两倍：

| 模型 | 时段 | 缓存命中(输入) | 缓存未命中(输入) | 输出 | | --- | --- | --- | --- | --- | | V4.1-Flash | 空闲 | 0.02 | 1.0 | 4.0 | | V4.1-Flash | 高峰 | 0.04 | 2.0 | 8.0 | | V4-Pro | 空闲 | 0.15 | 4.5 | 13.5 | | V4-Pro | 高峰 | 0.30 | 9.0 | 27.0 |

官方页当前只列 deepseek-flash 与 deepseek-v4-pro 两列；deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-chat 等旧名仍可调用，按 Flash 价计费。插件在启动时与每 12h 从官方页重新解析，只有解析失败才回退上表。成本为估算值，实际以官方账单为准。

搜索调用（估算）

每次 web_search 的每个查询都会被 DSH 当作一次独立的辅助模型调用（@deepseek-ai/dsh-web-search-deepseek，默认 deepseek-v4-flash，每个请求最多 maxUses 次）。而会话日志只记录派发前的 web/deepseek-search-llm-request 事件——不含 usage 字段，本地任何文件都查不到这些调用的真实 token 数。

插件因此按「请求次数 × 标定常数」计入：每次搜索 ≈ 6k 缓存未命中输入 + 2k 输出 token，即谷时 ¥0.014、峰时 ¥0.028（2026-09-22 用余额差标定：14 次搜索实测 ¥0.0133/次）。搜索会归到它所属的会话、工作区与「今日·全部」，但单次金额是估算值（±30% 量级）。

安全与权限边界

本节面向 DSH Store / 插件审计，列出依赖、运行时权限、外部服务与失败边界。

依赖与兼容

• 零运行时依赖：不 import 任何 @deepseek-ai/* 包，宿主端无第三方依赖
• peerDependencies["@deepseek-ai/dsh"]: >=0.1.2-rc.1 <0.2.0（DSH 兼容范围）
• engines.node: ^22.19.0 || >=24.0.0
• peerDependencies["react"]: ^18.2.0（仅浏览器端渲染）

运行时权限

• files：只读 ~/.dsh/sessions/ 下的会话 JSONL（成本统计）；不写入、不修改任何会话文件
• network：仅请求 DeepSeek 官方端点——api.deepseek.com（GET /user/balance 余额）与 api-docs.deepseek.com 定价页（每 12h 抓取）；不走任何第三方代理
• commands：spawn zstd -d -c 解压会话文件（macOS 需 brew install zstd）；不执行其他命令
• credentials：读取 DEEPSEEK_API_KEY（经宿主凭据服务解析），仅宿主进程使用、loopback-only 路由守卫；浏览器不接触密钥
• 所有 host 路由均绑定 load 回环地址，外部不可达

外部服务

• DeepSeek 官方余额接口 GET /user/balance（点击/60s 刷新时调用）
• DeepSeek 官方定价页（启动时 + 每 12h 抓取，用于峰谷单价）

失败边界

• 余额接口失败：面板提示失败信息，保留上次成功快照（不中断）
• 定价页抓取失败：回退内置 2026-09-10 价目表，pricingSource 标记为 default（解析成功则为 synced）
• zstd 缺失：返回可读错误提示（指引安装），而非静默失败
• 会话文件缺失/损坏：跳过该会话，不影响其他会话统计
• 所有成本为估算值，实际以官方账单为准

版本历史

v0.5.5 — 修复 README 在 npm 包页面上的显示

• 🐛 修复：README 的截图与语言切换此前用相对路径（docs/screenshot-corner.png、README.en.md）。npm 包页面只渲染 README 正文、不解析仓库内的相对路径，所以在 npm 上两张截图和语言链接都是坏的。现改为绝对 URL：截图走 raw.githubusercontent.com，语言切换走 GitHub blob 链接
• 📦 范围：仅文档，代码无变化

v0.5.4 — 计入搜索调用（此前全部漏算）

• 🐛 修复：web_search 的辅助模型调用完全不计入成本。DSH 对每次搜索只写一个派发前的 web/deepseek-search-llm-request 事件（无 usage），所以按会话日志计价的实现系统性漏算——实测 2026-09-22 一天 1073 次搜索全部没进账。现按「请求次数 × 标定常数」计价，并归入该搜索所属的会话 / 工作区 / 当日及当轮
• 📏 标定：单次搜索 ≈ 6k 缓存未命中输入 + 2k 输出 token（谷时 ¥0.014、峰时 ¥0.028）。2026-09-22 用余额差实测：同一窗口 14 次搜索、余额差 ¥0.28、扣掉日志可算的对话成本 ¥0.094，得 ¥0.0133/次
• ⚠️ 口径：搜索部分是估算值（±30% 量级），会话正文部分仍是按日志精算

v0.5.3 — 修复周末被误判为峰时

• 🐛 修复：峰/谷判断只看小时、不看星期，导致周末 09:00–12:00、14:00–18:00 被误判为峰时并按 2× 计价，"今日花费"最多翻倍。官方规则为周一至周五 09:00–12:00、14:00–18:00（其余含周末全天为空闲时段），现按北京时间的星期先行排除周六/周日
• 📄 文档：定价说明与峰谷 tooltip 补上"周一至周五"限定

v0.5.2 — 适配 DSH 0.1.5：新会话格式与新定价页

• 🐛 修复：DSH 0.1.5 将会话日志改为代数命名 session.v3.jsonl.zstd，插件此前只认 session.jsonl.zstd，导致升级后新建的会话全部不可见——查看这类会话时弹层出现红色报错，今日成本也漏算（实测少约 36%）。现按「每个会话目录取最高代」发现日志；迁移会话保留的旧文件是新代的子集，因此只读最高代，避免整个会话被重复计算
• 🐛 修复：官方定价页将 Flash 列改名为 deepseek-flash 并下调价格，插件按模型名定位价格块的锚点因此落到页面脚注，同步"成功"却静默沿用旧高价，成本被高估约 1.7 倍。现改为按价格表行标签锚定，并把该列价格套用到全部 Flash 系名称
• 💰 价目：内置兜底价目表更新为 V4.1-Flash 价（空闲 0.02 / 1.0 / 4.0，高峰 0.04 / 2.0 / 8.0，元/百万 tokens）；V4-Pro 档位保留
• 📄 文档：更正 pricingSource 取值为 default / synced（此前误写为 builtin）

v0.5.1 — 冷启动提速与代码清理

• 🚀 性能：今日成本冷启动从 ~5.4s 降至 ~0.01s——只解压当天活跃的会话文件（按 mtime 过滤）+ 解压结果按 (path, mtime) 长期缓存 + 并行解析
• ⏰ 轮询口径：README 与代码统一——常驻卡片每 60s 自动刷新（此前文档"无轮询"表述自相矛盾，已更正）
• 🌏 峰谷时区修正：峰/谷判断改为显式按北京时间（UTC+8）计算，不再依赖宿主机时区
• 🧹 清理：移除客户端一套从未调用的死计价代码（PRICING/priceSession），计价统一走宿主
• 📐 定价解析加固：峰价改为从官方页面显式解析（不再硬编码"谷价 ×2"）；解析不到缓存命中价时整表回退内置价目表，避免静默按 0 计价
• 🏷️ 卡片语义：卡片底部"今日"改为"今日·全部"，明确是全局（所有工作区）口径
• 🎨 外观：💰 换 SVG 钱包图标、弹框/卡片微交互动画、层级弱化（详情见 v0.5.1 diff）

v0.5.0 — 五层级成本与峰谷状态

• ✨ 新增：成本明细改为五层级——余额 / 最近一次提问 / 今日·本会话 / 今日·本工作区 / 今日·所有工作区
  • 最近一次提问下方标注会话名（基于最近活跃会话）
  • 「今日·本会话」= 当前会话今天产生的费用；「今日·本工作区」= 当前工作区今天所有会话合计（由当前会话锚定工作区）；「今日·所有工作区」= 全部工作区今天合计
• ✨ 新增：峰/谷时段状态可视化——卡片与弹框边框按时段着色（峰时橙色 / 谷时绿色），弹框标题旁显示「峰时/谷时」标签，悬停查看当前价格档位
• 🎨 调整：移除余额剩余比例条，改为余额数字按阈值直接变色（充足 / 黄 / 红）
• 🗑️ 移除：弹框中的「本会话成本」（会话全程累计）行

v0.2.0 — 最近一次提问与今日总成本

• ✨ 新增：弹层增加「最近一次提问成本」与「今天总成本」两项
  • 最近一次提问：解析当前会话最后一个 turn 的 token 用量 × 单价
  • 今天总成本：遍历 ~/.dsh/sessions/ 下所有会话，累加今天（自然日）用量
• 🐛 修复：last-cost 路由的 session-id 前缀重复问题（带/不带 session- 前缀均可解析）

v0.1.0 — 初始版本

• 🎉 账户余额（官方 /user/balance）+ 本会话成本（估算）+ Token 用量
• 按需刷新：无轮询，点击才查询，不消耗 token

验证

• 配置树：dsh --profile web --dump-config 应出现 balance-widget 条目
• 余额路由：重启 dsh web 后 curl -s http://127.0.0.1:3080/api/dsh-balance/balance 应返回 { ok, balance_infos, modelId }
• 会话成本：curl -s http://127.0.0.1:3080/api/dsh-balance/active-cost 应返回 { lastPrompt, todaySession, title, sessionId, peak, workspaceName, ... }；加 ?session=SESSION_ID 可指定会话
• 今日成本：curl -s http://127.0.0.1:3080/api/dsh-balance/today-cost 应返回 { workspace: { cost, ..., cwd }, all: { cost, ... }, modelId }
• 兼容旧路由：curl -s "http://127.0.0.1:3080/api/dsh-balance/last-cost?session=SESSION_ID" 仍可用，返回 { cost, inputTokens, outputTokens, modelId }

License

MIT