Skip to main content
J

dsh-usage-ledger

jjl-2060/dsh-usage-ledger

Deepseek Harness API usage dashboard for checking token usage and price on daily, monthly, and yearly basis.

Install

dsh plugin --profile web add github:jjl-2060/dsh-usage-ledger

README

dsh-usage-ledger · API 用量看板

DeepSeek Harness 的本地 API 用量看板:在左侧边栏加入 API 用量 入口,按 日(按小时)/ 周(按天)/ 月(按天)/ 年(按月) 查看 Token 用量与估算花费,并按 开发、搜索、文档、多智能体 等用途分类。

A read-only usage and spend dashboard for DeepSeek Harness. It aggregates local session logs, prices them with DeepSeek's published rates (including peak/off-peak), and breaks usage down by time and by purpose. No network calls, no telemetry, no writes.

API 用量看板:按日视图、用途趋势、指标卡与用途/模型分布

亮点

  • 四个时间视角:按日(24 个小时柱,默认)、按周(7 天)、按月(每天)、按年(12 个月),随时切换。
  • 用途分类:每一步模型请求按它请求的工具归类,趋势图按用途堆叠,圆环展示占比。
  • 花费估算:按官方每百万 Token 单价计算,区分峰时/闲时,排除 fork 继承的历史,避免重复计费。
  • 本地只读:只读取 $DSH_HOME/sessions,不发起网络请求、不上传数据、不写盘、不采集遥测。

安装

需要 DeepSeek Harness 0.2.2 及以上(0.2.x) 的 Web 或 Desktop GUI。

方式一:GitHub(推荐)

dsh plugin --profile desktop add github:JLJ-2060/dsh-usage-ledger

固定到某个版本,避免后续提交改变行为:

dsh plugin --profile desktop add github:JLJ-2060/dsh-usage-ledger#v0.1.0

也可以在 GUI 中打开 Settings → Plugins → Add plugin,填入同样的 github:JLJ-2060/dsh-usage-ledger 地址。装好后左侧边栏出现 API 用量。

这个包是纯 JavaScript,没有 prepare/构建脚本,所以 git 安装不需要 allowBuilds,也不需要 Node 构建工具链。

方式二:Tarball

下载 Release 里的 dsh-usage-ledger-0.1.0.tgz,在 Add plugin 中选择该文件;或:

dsh plugin --profile desktop add ./dsh-usage-ledger-0.1.0.tgz

方式三:本地目录

下载/克隆仓库后,在 Add plugin 中选择包含 package.json 的目录;或:

dsh plugin --profile desktop add ./dsh-usage-ledger

desktop 是 Desktop 的 profile 名;Web 用户请换成自己的 profile(例如 web)。在 GUI 里安装不需要 --profile,会装进当前 profile。

声明了 dsh.bundle 的包会被自动加入 profile 的 bundle 列表,不需要手改 YAML。

界面与用法

打开后默认是 按日 视图:

控件作用
按日 / 按周 / 按月 / 按年切换时间维度;默认按日(每小时)
‹ / ›前后翻一个周期
最新回到最近有数据的时段
花费 / Token / 请求切换趋势图、用途圆环、模型条的指标

看板从上到下:

  1. 四个指标卡:总花费、总 Token、模型请求数、缓存命中率(当前周期)。
  2. 用量趋势:按用途堆叠的柱子;图例在标题下方;悬停或键盘聚焦柱子,下方明细显示该时段的请求数、Token、花费和用途拆分。
  3. 用途分布:圆环 + 图例,显示当前周期的用途占比。
  4. 模型分布:按模型的花费/Token/请求条形。
  5. 底部说明:计价口径、时区、未计入的按次费用。

切换周期或指标后,所有卡片和两张图会一起更新。周期内没有数据时会显示专属空态,而不是一排 ¥0。

时间维度

维度每个柱子范围
按日(默认)1 小时当日 00:00–23:00
按周1 天周一到周日
按月1 天当月 1 号到月末
按年1 个月1 月到 12 月

用途分类

每一步模型请求(assistant/message)按该步请求的工具归类;同一请求命中多个分类时,按以下优先级取第一个:

分类触发工具
语音与音频名称含 speech / voice / audio / asr / tts / transcribe 的工具
搜索与研究web_search、web_fetch
多智能体subagent、workflow、team_task_*、send_message 等
文档与办公office_*、present
开发与执行write、edit、apply_patch、bash、pwsh、terminal_*、job_*、lsp
阅读与分析read、read_image、grep、glob、session_*、skill、todo_write
对话与写作该步没有工具调用
其他未匹配的工具

分类是启发式的,反映“这一步请求了什么工具”,不做内容语义理解。

花费怎么算

  • 数据源:ctx.sessionQuery 读取本机会话日志;每条 assistant/message 的 usage 记录输入(未命中缓存)、缓存命中、缓存写入和输出 Token,按事件时间归桶。
  • Token 桶:DSH 的 inputTokens 是未命中缓存的输入;缓存命中/写入单独计。总 Token = 输入 + 缓存命中 + 缓存写入 + 输出。
  • 单价:默认按 DeepSeek 官方人民币价格(每百万 Token,闲时):
模型缓存命中缓存未命中输出
deepseek-flash0.0214
deepseek-v4-pro0.154.513.5
  • 峰谷:默认北京时间周一至周五 09:00–12:00、14:00–18:00 为峰时,价格 ×2;其余为闲时。未建模中国法定节假日。
  • fork 去重:fork 会话复制的父历史不会被重复计费。
  • 未计入:搜索/抓取、OCR、语音等按次或按时长计费的 API;失败重试、标题生成等未在会话日志中记录 usage 的调用。

实际账单以 DeepSeek 官方为准;本看板是估算。

隐私

  • 只读取本机会话日志,不调用外部 API。
  • 不上传数据、不采集遥测、不写盘、不新增会话事件。
  • 统计与计价全部在本机完成。

配置

config 可覆盖以下字段。写入 profile 的 cordis.patch.yml 时,匹配 id: usage-dashboard 的条目会整体替换 config:

- id: usage-dashboard
  config:
    timeZone: Asia/Shanghai
    currency: CNY
    currencySymbol: '¥'
    peakMultiplier: 2
    peakHours: [[9, 12], [14, 18]]
    peakWeekdays: [1, 2, 3, 4, 5]
    prices:
      deepseek-flash: { cacheHit: 0.02, cacheMiss: 1, output: 4 }
      deepseek-v4-pro: { cacheHit: 0.15, cacheMiss: 4.5, output: 13.5 }
    cacheTtlMs: 20000
    concurrency: 4
    maxSessions: 500
    includeSubagents: true
字段默认说明
timeZoneAsia/Shanghai判定峰谷时段的时区
currency / currencySymbolCNY / ¥计价与显示币种;prices 按此币种填写
peakMultiplier2峰时倍率
peakHours[[9,12],[14,18]]峰时小时区间(左闭右开)
peakWeekdays[1..5]峰时星期(1=周一)
prices见上表每百万 Token 单价,模型 id 为键;省略的字段用该模型默认值
cacheTtlMs20000服务端缓存时间;页面刷新按钮会绕过
concurrency4并发读取会话日志数
maxSessions500最近会话读取上限
includeSubagentstrue是否统计子智能体会话

已知限制

  • 只统计会话日志里记录了 usage 的模型调用;被中断、重试失败而未落盘的部分不计。
  • 图表按浏览器本地时区分桶;峰谷按 timeZone(默认 Asia/Shanghai)判定。两者不一致时页面会提示,日期边界可能对不上。
  • 读取失败的会话会被跳过,页面会提示数量;超过 maxSessions 时只统计最近的会话并提示。
  • 非 DeepSeek 官方模型(或新模型 id)按名称中的 flash / pro 匹配默认价格;可在 prices 中补充单价,未知模型会在页面提示。
  • 会话没有语音/OCR 调用记录,因此这些分类只有对应工具出现时才会显示。
  • 页面每次打开会读取所有会话日志(有 20 秒缓存);会话特别多时首次加载会稍慢。

许可

MIT,见 LICENSE。

Related plugins