Token 仪表盘 juhe291/dsh-token-panel

dsh-token-panel

License: MIT
Version
Platform
Topic: dsh-plugin

实时 Token 消耗 HUD 插件 —— 为 DeepSeek Harness 提供右下角常驻的 Token 仪表盘：实时会话压力、会话花费、历史曲线、按日/按月统计，面板跟随当前对话，可拖拽、可设默认位置。

🌐 中文 ｜ English

✨ 亮点

| 💰 按模型分别计价 | flash / pro 各自套官方价表，混用模型的会话也估得准 |
| ⏱️ auto 峰谷价 | 2026-08-17 调价零时自动切换峰谷价，无需改配置 |
| 🫧 悬停即见数值 | 实时曲线 Steam 式跟随气泡，统计曲线悬停数据点弹值 |
| 🧊 毛玻璃面板 | 半透明磨砂玻璃，深浅色主题统一，胶囊最透 |
| 🎛️ 时间拖动条 | 实时回看历史曲线，统计翻查更早日期段 |
| ✏️ 点击即改预算 / 余额 | 统计视图行内编辑，余额随 token 消耗本地递减 |
| 🖱️ 拖拽 + 长按位置菜单 | 四角预设 + 自定义默认位置，位置跨刷新记忆 |
| 📊 按日 / 按月持久化统计 | JSONL 落盘，重启不丢，越用越完整 |

📷 封面中的两张面板均为真实界面截图（左：实时视图；右：统计视图）。

安装

从 npm 安装（推荐）

dsh plugin --profile web add dsh-token-panel@0.4.7

npm 包直接使用打包好的 lib/ 产物，无需本机构建。命令里的版本号请写当前最新版（发布新版本后同步更新此处，见 发布新版本）。

⚠️ 为什么要写精确版本号？ 新发布的版本（不足约 24 小时）会被 DSH 的 supply-chain 年龄校验拦截，@latest 可能被 pnpm 解析回较早版本；显式写版本号才能保证装到最新且修好的版本。包龄超过门槛后 @latest 才可靠。

⚠️ 装到了旧版本？ 若安装后版本不是最新，改用精确版本重装（如上命令），并确认 npm view dsh-token-panel dist-tags.latest 显示的是最新版。

从 GitHub 安装

dsh plugin --profile web add github:juhe291/dsh-token-panel

从本地路径安装

dsh plugin --profile web add C:\path\to\dsh-token-panel

安装完成后 重启 profile，刷新浏览器，右下角出现 TOKEN 胶囊。

⚠️ pnpm ≥ 10 拦截 Git 构建脚本：首次安装若提示 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，按提示把报错中的 allowBuilds 条目加入 profile 目录下的 pnpm-workspace.yaml，然后重跑安装命令。这是 pnpm 的安全机制（Git 依赖需要显式允许执行构建脚本），本包已自带 prepare 构建脚本与提交好的 lib/ 产物，允许后即可正常安装。

⚠️ 从 GitHub / 本地安装需要 Node ≥ 22.5：源码安装会执行 prepare 构建（pnpm 11.7 由 packageManager 字段固定，依赖 node:sqlite），Node 20 会构建失败。推荐从 npm 安装——无需构建。

⚠️ dsh 命令找不到：dsh 是 DSH 自带的 CLI。若提示"无法将 dsh 识别为命令"，先全局安装：npm install -g @deepseek-ai/dsh，然后重开一个终端再执行上面的命令。

卸载

dsh plugin --profile web remove dsh-token-panel

💡 一键卸载备用方案：刚发布的插件（发布不足约 24 小时）可能被 DSH 的 supply-chain 年龄校验拦住 dsh plugin remove。此时用随包附带的一键卸载脚本（直接调 pnpm，绕开该校验，并同步清理 bundle 注册）：
node ~/.dsh/profiles/web/node_modules/dsh-token-panel/scripts/uninstall.mjs

脚本执行完重启 profile 生效。约 24 小时后（包龄超过策略门槛）dsh plugin remove 恢复正常。

使用说明

面板交互（三种手势互不干扰）

1. 单击胶囊：打开面板（胶囊显示 压力 + ≈累计 + TPS）
2. 拖动：按住胶囊或面板头部栏拖动——可以把面板拖出屏幕边缘（上下左右都能覆盖出去），但始终留一条头部栏可见，随时能抓回来；位置自动记忆，刷新不丢
3. 长按 0.6 秒（胶囊或面板头部）：弹出位置菜单：

┌──────────────────────┐
│ ⌟ 右下角 │ ← 第一项图标/文字随默认位置自动更新 │ ✛ 位置 ▸ │ │ 取消 │ └──────────────────────┘ 位置二级菜单： ├ ⌜ 左上角 / ⌝ 右上角 / ⌞ 左下角 / ⌟ 右下角 ← 预设角落，点即设默认并跳转 └ ✛ 自定义位置… ← 之后拖动面板到任意处松手即保存

- 回到默认位置：第一项文字随已设默认动态变化（如「回到默认位置 · 右上角」「回到自定义位置」），点击跳回
- 预设角落：点即把面板移到该角并设为默认（用面板实际尺寸，精确贴边）
- 自定义位置：选择后拖动面板，松手保存为新默认，之后每次刷新都从那里出现
- 点「✕」收起面板时位置保持不变（要回默认用长按菜单）

实时视图

- 会话行：主数字 = 当前上下文压力（k 单位）；灰色 ≈ 小字 = 累计消耗（M 单位，含缓存读）；绿色 ¥ 数字 = 该会话估算花费（按会话实际使用的模型计价）
- 点会话行展开详情（输入/输出/缓存读/缓存写、压力/预计/容量、成本、占用进度条）与消耗曲线
- 曲线：Y 轴自动刻度（1/2/2.5/5×10ⁿ 取整 + 滞回，空闲时归零，单位标签常驻）+ 网格线 + 最新点虚线引导线与浮动数值标签 + X 轴时间刻度；鼠标移到曲线上任意位置，跟随气泡显示该处 token 值（Steam 下载风格）
- 曲线下方时间拖动条：向左拖动可回看历史缓冲区内更早时间段的曲线（窗口大小跟随 2m / 5m / 15m），峰值速率与最新值随窗口联动
- 顶部显示窗口内峰值消耗速率（t/s）；2m / 5m / 15m 切换曲线时间窗口
- 面板跟随当前对话；「展开全部」显示历史会话（重启后仍保留）

统计视图

- 顶部累计消耗大字单行显示（token 总数 + ≈¥ 成本）
- 本月预算 / 账户余额可编辑：点击数值行内编辑（回车保存 / Esc 取消）；余额随 token 消耗本地估算递减（刷新后保持），未设置时回退 API 拉取的官网余额
- 「按日 / 按月」切换粒度：趋势曲线 + 明细列表（默认收起，点「展开全部」查看）；曲线数据点悬停弹气泡显示该日 / 该月 token 值（当前日 / 月不弹，最新点已有标签）；曲线下方时间拖动条可查看更早的日期段（默认最近 14 天 / 6 个月）
- 数据按天持久化（JSONL），重启不丢

功能总览

右下角一枚迷你胶囊实时显示总 Token 压力，点击展开为可切换的 实时 / 统计 双视图仪表盘，配色跟随 DSH 主题（浅色 / 深色自动适配）。面板跟随当前对话：切换会话时只显示当前会话；空会话与历史会话默认隐藏，点「展开全部」才显示。

🟢 实时视图

| 能力 | 说明 |
| 会话列表 | 每个会话一行：标题 + 当前上下文压力 + 累计消耗 + 会话花费，标题来自 DSH 会话标题服务 |
| 会话详情 | 点击展开：输入 / 输出 / 缓存读 / 缓存写、压力 / 预计 / 容量、估算成本、上下文占用进度条（>85% 变红） |
| 实时曲线 | 每会话独立 SVG 面积曲线，带 Y 轴自动刻度（1/2/2.5/5×10ⁿ 取整 + 滞回，空闲归零，单位标签常驻）、X 轴时间刻度、最新点虚线引导线和浮动数值标签，支持 2m / 5m / 15m 范围切换；鼠标悬停曲线上任意位置，跟随气泡显示该处 token 值（Steam 风格）；曲线下方时间拖动条可回看更早时间段 |
| 峰值速率 | 曲线区顶部显示窗口内峰值消耗速率（t/s） |
| 跟随当前会话 | 默认只显示当前打开的对话；历史会话折叠在「展开全部」后面（重启后仍保留） |
| 空会话过滤 | 新开但 0 token 的对话完全不显示 |
| TPS | 底部栏实时显示生成速度（t/s） |

📊 统计视图

| 能力 | 说明 |
| 按日 / 按月 | 独立切换，趋势曲线 + 明细列表（默认收起，点「展开全部」查看全部日期 / 月份） |
| 趋势曲线 | 每日 / 每月消耗的 SVG 曲线，刻度显示日期（M/D），含 Y 轴刻度；数据点悬停弹气泡显示该日 / 该月 token 值；下方时间拖动条可查看更早日期段（默认最近 14 天 / 6 个月） |
| 累计消耗 | 顶部大字单行汇总：累计 token 总数 + ≈¥ 估算成本 |
| 预算与余额 | 点击数值行内编辑（回车保存 / Esc 取消）；预算显示本月已用 / 总额进度条（超支变红）；余额随 token 消耗本地估算递减，未设置时回退 API 拉取的官网余额 |
| 持久化 | 数据按天写入磁盘（JSONL），重启不丢，越用越完整 |

⚠️ 数字口径提示：统计视图的「按日 / 按月」是历史累计消耗（输入 + 输出 + 缓存读全部累加），缓存读通常是最大头，所以单日就可能上亿 token（显示 M 单位）；而实时视图的数字是当前上下文压力（此刻占用的 token，几十万级，显示 k 单位）。两个数字不是同一个量，看到「实时 400k / 统计 100M」的差异是正常的，不要担心。
会话行上的 ≈ 小字就是该会话的累计消耗，¥ 数字是该会话的估算花费，和统计视图口径一致。

💰 成本估算

- 按模型分别计价：内置 deepseek-v4-flash 与 deepseek-v4-pro 两套官方价表（缓存命中 / 未命中输入 / 输出分别计费），会话和统计都按实际使用的模型套价，切换过模型的会话不会整段按单一模型计价
- auto 价格模式（默认）：2026-08-17 零时（北京时间）前自动使用 flat 旧价，之后自动切换 DeepSeek 官方峰谷价（高峰 9-12、14-18），底部徽章同步显示「标准价 / 高峰价 / 空闲价」，无需手动改配置
- 估算仅作展示参考，实际以官网账单为准

配置

配置位于 profile 的 cordis.patch.yml（或 settings.yaml 的插件分节）：

- id: token-panel
name: dsh-token-panel
config:
pollInterval: 1500 # 实时轮询间隔 (ms) priceMode: auto # auto = 8/17 前 flat 旧价、之后自动切峰谷；flat / peak-offpeak 固定模式全局兜底价格（模型未在 modelPrices 中列出时使用；默认 = flash 价） pricePerMInput: 1 # 未命中输入价格 (CNY / 百万 token) pricePerMCacheRead: 0.02 # 缓存命中价格 (CNY / 百万 token) pricePerMOutput: 2 # 输出价格 (CNY / 百万 token) 峰谷价（priceMode 切到 peak-offpeak 或 8/17 后 auto 生效） pricePeakInput: 3 # 高峰未命中输入价 pricePeakCacheRead: 0.1 # 高峰缓存命中价 pricePeakOutput: 9 # 高峰输出价 priceOffpeakInput: 1.5 # 空闲未命中输入价 priceOffpeakCacheRead: 0.05 # 空闲缓存命中价 priceOffpeakOutput: 4.5 # 空闲输出价按模型价表（CNY / 百万 token）：会话和统计按实际使用模型套价 modelPrices: deepseek-v4-flash:
flat: { hit: 0.02, miss: 1, output: 2 }
peak: { hit: 0.10, miss: 3, output: 9 }
offpeak: { hit: 0.05, miss: 1.5, output: 4.5 }
deepseek-v4-pro:
flat: { hit: 0.025, miss: 3, output: 6 }
peak: { hit: 0.30, miss: 9, output: 27 }
offpeak: { hit: 0.15, miss: 4.5, output: 13.5 }
budgetMonthly: 0 # 月预算 (CNY)；0 = 关闭（也可在统计视图点击数值直接设置） dataDir: ~/.dsh/cache/dsh-token-panel # 持久化目录（可选）

| 键 | 默认 | 说明 |
| pollInterval | 1500 | 浏览器实时轮询间隔（毫秒） |
| priceMode | auto | 计价模式：auto 在 2026-08-17 零时自动从 flat 切到峰谷价；flat / peak-offpeak 固定 |
| pricePerM | 1 / 0.02 / 2 | 全局兜底价格（每百万 token，CNY，仅展示） |
| pricePeak | 3 / 0.1 / 9 | 高峰时段兜底价格（北京时间 9-12、14-18） |
| priceOffpeak | 1.5 / 0.05 / 4.5 | 空闲时段兜底价格 |
| modelPrices | 内置 flash + pro | 按模型价表（flat / peak / offpeak 三档），覆盖或新增模型 |
| budgetMonthly | 0 | 月预算（CNY），>0 显示预算进度条；也可在统计视图点击数值直接设置 |
| hidden | false | true 时隐藏整个面板（含右下角胶囊）；也可用长按菜单「隐藏 HUD」或 DSH 设置里的可视化开关，无需改配置 |
| dataDir | ~/.dsh/cache/dsh-token-panel | 持久化用量日志目录 |

默认内置 DeepSeek 官方价表（2026-08-17 前 flat 旧价 + 之后峰谷新价），其他模型 / 供应商请按自己的计价调整 modelPrices。

数据存储

统计日志按天追加写入（每行一条用量增量，JSON）：

~/.dsh/cache/dsh-token-panel/
├── usage-2026-08-14.jsonl # 每日用量日志（增量：输入/输出/缓存读/缓存写/模型） ├── state.json # 上次用量基线（重启续接，防重复/防丢失） └── known-sessions.json # 会话注册表（重启后「展开全部」的历史会话不丢）

记录维度：未命中输入、输出、缓存读、缓存写、模型（增量）。首次观察到会话时写入完整基线，之后记录增量——累计从真实起点算起，重启不丢不重。

工作原理

- Host 面（src/index.ts）：
- 聚合 ctx.tokenMeter.measure()（压力/表面积）+ ctx.sessionProjections.snapshot()（provider 实测用量/容量/构成）+ ctx.sessionTitle.get()（会话标题）+ ctx.credentials.resolve('DEEPSEEK_API_KEY')（官网余额）
- 注册三条 HTTP 路由：/plugins/dsh-token-panel/snapshot（实时 + 按模型价表）、/plugins/dsh-token-panel/stats（持久化统计）、/plugins/dsh-token-panel/balance（官网余额，5 分钟缓存）
- 用量增量按天持久化（崩溃安全：tmp + rename 原子写），并按会话 × 模型分桶累计，供成本分模型计价
- 过滤 0 token 的空会话
- Client 面（src/client/）：body portal 右下角面板，1.5s 轮询实时数据、10s 轮询统计、60s 轮询余额，SVG 曲线 + 设计令牌配色，中英文 locale 跟随 DSH 语言设置，通过 ctx.sessions.list 跟踪当前会话；预算/余额存 localStorage（点击数值行内编辑）

开发

pnpm install
pnpm build # tsc host + tsc client + tsdown
pnpm verify # 产物一致性检查（exports/patch/client bundle）

发布新版本

pnpm build && pnpm verify
git add -A
git commit -m "feat: ..."
git push

常见问题

Q: 实时数字和统计数字怎么不一样？
A: 实时显示的是当前上下文压力（几十万级，k 单位）；统计显示的是历史累计消耗（含缓存读，上亿级，M 单位）。两个指标口径不同，面板已同时展示（压力 + ≈累计）。

Q: 成本估算准吗？
A: 按 DeepSeek 官方价分级估算（缓存命中 / 未命中输入 / 输出分开计价，v4-flash 与 v4-pro 各有价表），仅作参考。权威账单请以 DeepSeek 官网 为准。

Q: 8/17 DeepSeek 调价后要改配置吗？
A: 不用。默认 priceMode: auto，2026-08-17 零时（北京时间）自动切换到峰谷价，底部「标准价」徽章会随之变成「高峰价 / 空闲价」。

Q: 余额数字为什么和官网对不上？
A: 点击设置余额后，本地按 token 消耗估算递减（估算价与官网计费可能有细微出入，且不包含折扣/赠送）。想对齐官网时，点余额数值重新输入官网当前余额即可校准；不设置时显示 API 拉取的官网余额。

Q: 曲线怎么只有最近几分钟？
A: 实时曲线是滚动内存窗口（600 点 ≈ 15 分钟），重启清零；统计视图的日/月曲线基于磁盘日志，长期保留。

Q: 面板里有些会话不见了？
A: 面板跟随当前对话，且隐藏 0 token 的空会话；历史会话点「展开全部」即可看到。

许可

MIT ｜ 更新记录见 CHANGELOG.md

Made with 🐋 for the DeepSeek Harness plugin ecosystem.*