dsh-usage-dashboard

一句话定位

给 DSH Web 装上一对「眼睛」：一个可拖拽的悬浮额度窗告诉你还剩多少、按近 7 天日均还能撑多久；会话顶栏多一个「额度」标签，把今日 / 本月 / 累计花销、按模型与按会话的成本排行、缓存替你省了多少钱、以及 2026-08-17 峰谷调价前后的账单预估，都摊在 GUI 里。

核心能力

• 账户余额与可用天数：悬浮窗与「额度」页同时显示实时余额，并按近 7 个自然日（含没用的日子）的日均消耗折出「预计可用 X 天」，不足 3 天会转红
• 今日 / 本月 / 累计花销三档概览：今日带「较昨日」、本月带「较上月同期」环比，展开后可看实际套用的价目表，估算不是黑箱
• 峰谷账单预估：DeepSeek 自 2026-08-17 起按北京时区 09:00–12:00 与 14:00–18:00 实行峰谷两档定价；生效前就会把你的历史用量重算为新价让你看清涨幅，生效后改为「把高峰挪到闲时能省多少」
• 缓存命中省了多少：每条用量记录按「未命中价 vs 缓存命中价」算差额，汇总成「缓存替你省下 X 元」；命中率掉到 60% 以下时给出恢复建议
• 模型与会话费用排行 + 当前会话即时消耗：模型 Top N（按费用降序，带输入 / 输出 / 缓存三栏拆分），会话 Top 6 一眼定位烧钱的对话；进入任一会话顶部「额度」标签时先单独显示「本会话已经花多少」，每条助手消息旁带本轮消耗
• 用量时间分布与本机可视化：近 30 天逐天柱图、0–23 点逐小时柱图（可多选模型叠成分组柱）、近 12 周热力图，全部支持键盘探索与触屏点按；数据范围 / 损坏记录等覆盖度也会在仪表盘底部显式披露

技术实现

• 语言: TypeScript（host 端 ESM、client 端 React 18.2 + TSX，esbuild 单文件闭包打包）
• 关键依赖: @deepseek-ai/cordis ^4.0.0（宿主服务发现与插件运行时）、react ^18.2.0（客户端 UI）、@deepseek-ai/dsh-client-runtime / dsh-client-locale / dsh-client-ui-conversation（client 启动图 inject 项）、esbuild ^0.25.0 + typescript ^5.6.0（构建）
• 架构模式: DSH 标准双半体（bundle + client）。Host half 通过 ctx.inject(['webServer','credentials','sessionPersistence']) 注册前缀路由 /api/dsh-usage-dashboard/{balance,usage,session}：余额调用 DeepSeek 官方 /user/balance，用量遍历本机全部 DSH 会话日志把 assistant/message.usage 按模型（从最近一条 request/header.config 读取）× 北京时间窗口折算后入桶；5 分钟服务端记忆化避免反复重放。Client half 在加载时即并行触发 fetchBalance/fetchUsage 预取，挂到 shell.overlay（悬浮窗）、conversation.view（「额度」tab）、conversation.chat.assistant-actions（消息行费用）三个 slot；样式全部走 DSH 的 --dsw-alias-* 主题变量，跟随宿主主题
• 入口文件: 宿主端 src/index.ts（路由注册 + 记忆化）；客户端 src/client/index.tsx（三 slot 注册 + 预取 + locale 注册）；价格表集中在 src/pricing.ts，聚合与计费集中在 src/usage.ts；构建产物 lib/index.js + lib/client.js

适用场景

当你在用 DSH 跑一些会持续烧 token 的 agent 任务，想知道「这个月到底花了多少、是哪几个会话和模型贡献的、缓存帮我省了多少、DeepSeek 8 月 17 号那波涨价对我影响多大」时——它把所有数字从本机会话日志里翻出来配上估算公式，让你在 GUI 里就能回答。适合对 DeepSeek 账单开始焦虑、正在调预算或要给团队做成本复盘的重度用户。

前置依赖与兼容性

安装方式

dsh plugin --profile web add @cassius0924/dsh-usage-dashboard

安装完成后需重启 dsh web：路由注册在 host 进程，仅刷新浏览器不会让 /api/dsh-usage-dashboard/* 上线；启动后右下角出现悬浮窗，进入任一会话即可在顶部 Chat / Trajectory / 额度 三标签中点开「额度」。

也可以从 GitHub checkout 或本地路径安装：

dsh plugin --profile web add github:Cassius0924/dsh-usage-dashboard
dsh plugin --profile web add ./path/to/dsh-usage-dashboard

配置项

本插件在「额度」tab 末尾的「设置」卡片内暴露所有可调字段，全部持久化到浏览器 localStorage（带版本后缀，旧值失效时安全降级到默认值）。下面是人话版的字段说明：

自带的端口、价目表、缓存 TTL（余额 60 秒、用量 5 分钟）、记忆化重置等行为参数不在用户配置面，详见 src/usage.ts、src/pricing.ts、src/index.ts 顶部注释。

常见问题

Q: 安装后看不到「额度」标签怎么办？

A: 「额度」tab 挂在单个会话顶栏（不是 New Session 首页）。先打开任意一个已有会话再刷新即可看到 Chat / Trajectory / 额度 三标签；右下角的悬浮窗不受这条限制，任何页面都会出现。

Q: 余额不对或显示「未配置 DEEPSEEK_API_KEY」？

A: 余额走官方 https://api.deepseek.com/user/balance 端点，依赖 DSH 已有的那把 DeepSeek API Key。请在 DSH「设置 → 模型」里把 Key 填好（也可以放在 $DSH_HOME/.credentials.yaml 的 DEEPSEEK_API_KEY），重启 dsh web 后即可拉到余额；端点被硬绑定官方域名，自建 baseURL 时余额会被拒。

Q: 显示的「费用」为什么和 DeepSeek 官方账单对不上？

A: 这是估算，不是计费依据。所有规则集中在 src/pricing.ts：按每条用量记录的「模型 + 是否落在北京时区高峰窗口（09:00–12:00、14:00–18:00）」逐条计价；2026-08-17 之前的用量按旧固定价，之后按峰谷两档（闲时为高峰的一半）。未识别的模型按 deepseek-v4-pro 较贵一侧估算，保守不低估。不计入平台折扣、赠金消费顺序等不可见项，以官方账单为准。

Q: 第一次打开仪表盘要等很久？

A: 「用量」需要遍历本机全部 DSH 会话日志聚合，本机实测约 5 秒。为避免反复重放做了两件事：服务端把这次结果记忆化 5 分钟；客户端在加载时即并行触发余额与用量预取，等到用户真正点 tab 时大概率已经把数据预取进缓存，首屏立即刷出。无数据时界面显示骨架占位而不是空文案。需要立刻看到最新数字时点右上「↻」刷新按钮即可（带 ?refresh=1 绕过记忆化）。

Q: 这里显示的是本机数据，那多设备 / 多账号会一起算进来吗？

A: 不会。覆盖度卡（仪表盘底部）明确写出数据范围是「当前设备上的 DSH 会话日志」，不含其他设备、DeepSeek 平台直接调用或已被删除的本地日志。它会同时显示扫描了多少会话、跳过多少条损坏记录、最早 / 最近一次有效记录的时间，让用户对照口径评估这个估算值。

Q: 余额预警线怎么调？什么时候会响？

A: 在「额度」tab 末卡「设置」里改预警阈值，默认 ¥10，填 0 即关闭。跌破时同时在仪表盘顶部出现带「还能撑 X 天 + 去充值」的警示条、悬浮窗圆点与余额数字同步转警示色；阈值改了之后两侧告警状态同步更新，不会各说各话。

Q: 月度预算到 100% 会不会自动停掉模型调用？

A: 不会，本插件的预算与超支提示仅提醒、不阻拦。≥80% 时进度条变黄、≥100% 变红并在仪表盘显示按当前速率月底预计超支多少金额。需要硬性上限请自行在模型层处理。

Q: 卸载要注意什么？

A: dsh plugin --profile web remove @cassius0924/dsh-usage-dashboard 之后重启 dsh web 即可，路由与服务全部撤销。插件不写自己的文件、不引后台进程；唯一残留是浏览器 localStorage 里以 dsh-usage-dashboard:pref: / dsh-usage-dashboard:balance / :usage 为前缀的偏好与缓存，需要时手动清除或下一次重装会再次出现。

Q: 改了内置价格表能跟上 DeepSeek 再调价吗？

A: DeepSeek 调价时只改 src/pricing.ts 的两张表（LEGACY_RATES 与 PEAK_RATES，按 pro / flash 两个档位 × 缓存命中 / 未命中 / 输出三栏）即可。本插件没有「一键抓取官方定价页」功能，手动维护一次后跑 pnpm run build 即生效。

上手难度

入门 — 一行 dsh plugin --profile web add @cassius0924/dsh-usage-dashboard 加重启 dsh web，重启后零配置即可看到悬浮窗与「额度」tab。

已知问题与限制

• 数据范围仅限本机：覆盖度卡明示仪表盘统计的只是「当前设备上的 DSH 会话日志」，不包括其他设备、DeepSeek 平台直调或已删除的本地日志
• 费用为估算：不含 DeepSeek 平台的折扣、赠金消耗顺序等不可见项，与官方账单的口径不完全一致；峰谷时段按北京时区判定，不随浏览器所在时区变化
• 首次冷启动要重放全部会话日志：服务端把结果记忆化 5 分钟以避免每次切 tab 都重放，期间仍可强制刷新（?refresh=1 / 悬浮窗 ↻）
• 未识别模型按 deepseek-v4-pro 较贵一侧估算：刻意保守，界面会同时提示「未知模型按 deepseek-v4-pro 计价」（src/pricing.ts:47 / src/client/locales.ts:55）
• 单接口口径：余额只信任 DeepSeek 官方域名（api.deepseek.com），指向非官方域名时余额请求返回错误，不会为配置错误去重定向或回退
• 客户端偏好与缓存存在浏览器 localStorage（带版本后缀）：跨设备不同步；隐私模式 / 配额耗尽时静默降级（不报错），用户察觉时可能有「突然忘记设置」的现象
• 悬浮窗「点击直达额度 tab」能力：DSH 公开 client API 不暴露 view 切换入口，避免使用 DOM 文案点击做脆弱绑定；当前以拖动 / 收起到四角来定位，主入口仍在会话顶栏的「额度」tab（TODO.md:9-10）
• 安装 / 更新插件后必须重启 dsh web 生效：路由注册发生在 host 进程启动时，仅刷新浏览器不会让 /api/dsh-usage-dashboard/* 上线

在 DSH（DeepSeek Harness）的 Web GUI 里，随时看得见 DeepSeek 的钱花在哪： 余额还能撑几天、今天花了多少、哪个模型最贵、缓存替你省了多少，以及 2026-08-17 峰谷定价之后账单会变成什么样。

装上之后 GUI 里多两样东西：右下角一个可拖动的悬浮额度窗，顶部栏多一个**「额度」tab**。 界面支持中文与 English，直接跟随 DSH 全局的「Settings → Language」设置；切换无需刷新，选择由 DSH 持久化。

---

为什么需要它

用 DSH 跑 agent，钱是一点一点漏掉的，而 DSH 自己不会告诉你：

这个插件把这些问题逐个翻译成一眼能看懂的数字。费用全部为估算，算法与单价公开可查（见费用是怎么算的）。

---

悬浮额度窗

常驻右下角，不打断你干活：

• 余额 + 今日消耗，一眼就够。
• 可拖动，松手自动吸附四角；边界避开侧边栏、右侧详情面板、会话顶栏和输入框——不会挡住发送按钮。
• 可收起成一行；显示/隐藏、所在角落、收起状态都会记住，刷新页面后原样回来。
• 余额跌破预警线时，状态点和余额数字一起转成警示色。
• 60 秒自动刷新余额。今日消耗读共享缓存，点 ↻ 同时刷新两者。
• 插件加载时就把余额和用量预取到缓存里，所以打开「额度」tab 通常是秒开， 不用等那几秒的会话日志重放；预取失败不报错，交给各自挂载时再取。

「额度」仪表盘

余额：还能撑几天

「还剩多少钱」不解决余额焦虑，「还能用几天」才行。按近 7 个自然日（含没用的日子）的日均消耗折算，hover 能看到估算口径；不足 3 天转红。

今日 / 本月花了多少 —— 以及这个数怎么来的

今日、本月、累计三个窗口，今日带「较昨日」、本月带「较上月同期」环比（上月同期而不是上月整月，免得月初总是显得便宜）。

展开计价说明能看到费用估算实际套用的单价表——估算不该是个黑箱。

涨价之后会变成多少

DeepSeek 从 2026-08-17 00:00 起改峰谷定价，高峰（北京时间 09:00–12:00、14:00–18:00）价格是闲时的两倍。

这张卡告诉你用量落在峰谷两侧的比例，并且在新价生效前就把账单重算一遍：上图这份用量现价 ¥14.64，新价下是 ¥45.84（+213%）。生效之后，这里会换成「把高峰用量挪到闲时能省多少」。

缓存替你省了多少

前缀缓存的命中价只有未命中价的百分之一量级，是 DSH 这类高重复 prompt 负载上最大的省钱杠杆——上图这份用量实付 ¥14.64，缓存省下了 ¥458.15。

命中率掉到 60% 以下时，文案会换成怎么把它救回来的建议。

钱花在哪个模型上

按费用降序，带占比条和输入/输出/缓存拆分。模型配色在排行、下拉选择器和图表图例三处一致。

哪个会话最烧钱

按模型、按天的视图告诉你「花在什么上」和「什么时候花的」；这张告诉你是哪一次跑掉的——对 agent 用户来说，这是唯一能直接动手改的东西：一个特别贵的会话，通常意味着一段值得看看的 prompt 或一个没收住的循环。上图里一个会话就占了总花费的 77.8%。

会话标题直接从会话日志里读（session/title 事件），跟用量重放搭同一趟车，不额外读盘。

用量的时间分布

近 30 天逐天、0–23 点逐小时（可按模型多选过滤，叠成分组柱状图），外加近 12 周热力图。hover 立刻出 tooltip，不用等系统那一秒。

余额预警

在「设置」里定一条预警线（默认 ¥10，填 0 关闭）。跌破时仪表盘顶部出现警示条——带上还能撑几天和充值入口——同时悬浮窗一起转警示色，两边不会各说各话：

---

安装

标准 DSH 插件包（bundle + client 双面包），用 dsh plugin 装：

# 从 npm 安装
dsh plugin --profile web add @cassius0924/dsh-usage-dashboard

# 或从 GitHub（git 依赖会跑 prepare 脚本现场构建）
dsh plugin --profile web add github:Cassius0924/dsh-usage-dashboard

# 或本地 checkout
dsh plugin --profile web add ./path/to/dsh-usage-dashboard

然后重启 dsh（dsh --profile web）生效。

前提：

• 已配置 DEEPSEEK_API_KEY（「设置 → 模型」里填，或放在 $DSH_HOME/.credentials.yaml）——余额接口要用。
• 本机有 pnpm（dsh plugin 是 pnpm 的转发器）。

装好后打开 GUI，进入任意一个会话（「额度」tab 挂在 conversation.view 上，New Session 首页没有 tab 栏），顶部就能看到 Chat / Trajectory / 额度。

费用是怎么算的

费用是估算，不是账单。规则都在 src/pricing.ts 一个文件里：

• 逐条用量记录按「模型 + 是否落在高峰时段」计价，而不是全局一套价。
• 2026-08-17 00:00（北京时间）之前的记录按旧的固定价；之后按峰谷价，闲时为高峰的一半。
• 高峰时段按北京时间判定，不随机器时区漂移。
• 未识别的模型按 deepseek-v4-pro（较贵的一侧）计价。

单价（CNY / 百万 tokens）：

DeepSeek 再调价时，只改这张表。

开发 / 构建

pnpm install
pnpm test           # Node 内置测试运行器：计价、缓存、信任围栏与用量聚合
pnpm run build      # esbuild 出 lib/index.js（host）+ lib/client.js（client），再 tsc 出类型
pnpm run typecheck

产物：

• lib/index.js —— Host 半（ESM，Node），注册 /api/dsh-usage-dashboard/* 路由。
• lib/client.js —— Client 半（CJS 闭包），通过 window.__ModuleLoader__ 注册进 web 启动图。

改动生效方式不同：只改 src/client/** 时，浏览器硬刷新（Ctrl/Cmd+Shift+R）即可；改了 src/index.ts 等 host 端要重启 dsh。

src/
├── index.ts        # Host 半入口（webServer 路由 + TTL 记忆化）
├── usage.ts        # 余额 + 用量聚合（按天/小时/模型/峰谷分桶）
├── pricing.ts      # 价目表与费用估算（唯一改价的地方）
├── contract.ts     # host ↔ client 的 wire 类型
├── trust-fence.ts  # 浏览器信任校验
└── client/
    ├── index.tsx   # Client 半入口（slots 注册）
    ├── widget.tsx  # 悬浮额度窗
    ├── dashboard.tsx # 「额度」tab
    ├── charts.tsx  # 柱状图 / 热力图 / tooltip
    ├── locales.ts  # 中英文完整词典
    ├── i18n.tsx    # DSH locale 桥接与翻译上下文
    ├── styles.ts   # 全部样式
    ├── api.ts      # fetch + 客户端缓存
    ├── cache.ts    # TTL 缓存（含 localStorage 持久化）
    ├── prefs.ts    # 用户设置持久化
    └── store.ts    # 两个界面共享的设置

样式全部走 DSH 自己的 --dsw-alias-* CSS 变量，跟随宿主主题，不引入独立配色。

已知限制

• 用量数据来自本机 DSH 会话日志，不含其它机器/账户的用量。
• 费用是估算：不含 DeepSeek 侧的折扣、赠金消耗顺序等因素，以官方账单为准。
• 首次加载用量需要重放全部会话日志（本机实测约 5 秒），因此有 5 分钟的服务端记忆化；界面在此期间显示骨架屏。

License

MIT