godpanzz / dsh-usage

dsh-usage

DSH plugin — today's token usage & cost, priced per model with DeepSeek peak/off-peak (峰谷) billing. Ships a Web sidebar panel (above Settings) plus a /usage command.

DSH 插件 — 统计今日（或指定日期）的 token 用量与费用，按模型价格与峰谷计费（DeepSeek 官方峰谷定价）计算。含 Web 左侧栏「今日费用」面板（设置按钮上方）与 /usage 命令两种使用方式。

---

Features / 功能

English

• Scans every session log under $DSH_HOME/sessions (default ~/.dsh/sessions, JSONL / zstd compressed) and folds each model call's usage:
  • input · cache miss (inputTokens)
  • input · cache hit (cacheReadTokens)
  • output (outputTokens; reasoning tokens are part of output and are not billed again)
• Prices per model and splits billing by peak / off-peak windows (DeepSeek peak/valley pricing effective 2026-08-17):
  • Peak hours (Beijing time): 09:00–12:00, 14:00–18:00
  • Off-peak: all other hours, at half price
• Web sidebar panel: registers the usageToday session projection unit, so each session's "today" usage & cost rides session.list / session.history projections to the browser. The client plugin renders a "今日费用" card at the bottom of the sidebar (above the Settings row), aggregated across sessions, auto-refreshing every 20 s (click to refresh). A compact ¥ icon shows when the sidebar is collapsed.
• Registers the /usage command (no model turn involved — costs zero tokens).

中文

• 扫描 $DSH_HOME/sessions（默认 ~/.dsh/sessions）下所有会话日志（JSONL / zstd 压缩），折叠每次模型调用的用量：
  • 输入 · 缓存未命中（inputTokens）
  • 输入 · 缓存命中（cacheReadTokens）
  • 输出（outputTokens，含 reasoning tokens，不再重复计费）
• 按模型归集，并按高峰 / 空闲时段分开计费（DeepSeek 峰谷定价自 2026-08-17 起生效）：
  • 高峰时段（北京时间）：09:00–12:00、14:00–18:00
  • 空闲时段：其余时间，价格为高峰的一半
• Web 侧栏面板：注册 usageToday 会话投影单元，每个会话「今日」的用量与费用随 session.list / session.history 的 projections 下发到浏览器；client 插件在侧栏底部（设置按钮上方）渲染「今日费用」卡片，跨会话汇总、每 20 秒自动刷新，点击可手动刷新。侧栏折叠时显示紧凑的 ¥ 图标。
• 注册 /usage 命令（Web 端直接输入），无需模型参与，不消耗 token。

---

Install / 安装

English

Install into the DSH web profile:

# Option A: dsh plugin (recommended — writes the profile dependency)
dsh plugin --profile web add /path/to/dsh-usage

# Option B: manual placement
#   copy (or symlink) this package to ~/.dsh/profiles/node_modules/dsh-usage/
#   and register it in ~/.dsh/profiles/web/package.json dependencies

Dependency: the host side needs zod resolvable (the profile's shared node_modules already has it; for a manual install, symlink node_modules/zod inside the package if missing).

Then append to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-usage
      name: 'dsh-usage'
      config:
        timezone: 'Asia/Shanghai'
        includeWorkspaces: 'all'

Restart dsh web (HMR is disabled in the Web profile, so config changes are not hot-reloaded). After the restart:

• the "今日费用" card appears at the bottom of the sidebar, above Settings;
• type /usage for the detailed report.

中文

在 DSH 的 web profile 中安装：

# 方式一：dsh plugin（推荐，自动写入 profile 依赖）
dsh plugin --profile web add /path/to/dsh-usage

# 方式二：手动放置
#   将本包复制（或软链）到 ~/.dsh/profiles/node_modules/dsh-usage/
#   并在 ~/.dsh/profiles/web/package.json 的 dependencies 中登记

依赖：宿主端需要 zod 可解析（profile 共享 node_modules 已有；手动安装时如缺失，在包内 node_modules/zod 放置软链即可）。

然后编辑 ~/.dsh/profiles/web/cordis.patch.yml，追加：

- insert:
    - id: dsh-usage
      name: 'dsh-usage'
      config:
        timezone: 'Asia/Shanghai'
        includeWorkspaces: 'all'

重启 dsh web 使插件生效（当前 Web profile 的 HMR 处于关闭状态，配置热更新不可用）。重启后：

• 左侧栏底部、设置按钮上方出现「今日费用」卡片；
• 输入 /usage 可查看详细报表。

---

Usage / 使用

Sidebar panel / 侧栏面板

English

Bottom-left, above the Settings row:

今日费用          08-17
¥10.72
空闲 ¥3.22 · 高峰 ¥7.51
输入 327K · 输出 389K

Auto-refreshes every 20 s (data comes from the host-side projection, including cold sessions); click the card to refresh immediately.

中文

左下角（设置上方）显示：

今日费用          08-17
¥10.72
空闲 ¥3.22 · 高峰 ¥7.51
输入 327K · 输出 389K

每 20 秒自动刷新（数据来自宿主端投影，含冷会话）；点击卡片立即刷新。

/usage command / 命令

Command / 命令	Meaning / 说明
/usage	Today (Beijing time) usage & cost / 今日（北京时）
/usage today	same / 同上
/usage yesterday	Yesterday / 昨日
/usage 2026-08-17	A specific date / 指定日期
/usage all	All history / 全部历史

Example output / 示例输出：

📊 DSH Token 用量与费用
统计范围：2026-08-17（Asia/Shanghai，今日）
峰谷计费：高峰 09:00–12:00、14:00–18:00；其余为空闲时段（半价）
会话日志：扫描 2 个，其中 2 个含用量事件

模型/时段                 输入未命中     输入命中       输出      费用(CNY)
deepseek-v4-flash
  空闲(半价)                80,554    26,083,968    108,070      1.91
  高峰                     179,462    51,227,648    205,075      7.51
  小计                     260,016    77,311,616    313,145      9.42

合计（今日）                                               ¥9.42
  空闲 ¥1.91 · 高峰 ¥7.51

---

Configuration / 配置

All keys are optional; defaults match the official DeepSeek peak/valley pricing (effective 2026-08-17):

Key / 键	Type / 类型	Default / 默认值	Description / 说明
timezone	string	'Asia/Shanghai'	Billing timezone (peak hours are Beijing time) / 计费时区（峰谷以北京时间为准）
peakHours	[number, number][]	[[9,12],[14,18]]	Peak windows (whole hours, [start, end)) / 高峰时段（整点、左闭右开）
priceTable	object	see below / 见下	Model prices, CNY per million tokens / 模型价格表，元/百万 tokens
sessionsRoot	string | null	$DSH_HOME/sessions	Session log root / 会话日志根目录
includeWorkspaces	'all' | 'current' | string[]	'all'	Which workspaces to count ('current' = only the current cwd; array = cwd prefix match) / 统计哪些工作区（'current' 仅当前 cwd；数组按 cwd 前缀匹配）

Default price table (CNY per million tokens, [off-peak, peak]):

priceTable:
  deepseek-v4-flash:
    inputCacheHit:  [0.05, 0.1]    # input · cache hit / 输入 · 缓存命中
    inputCacheMiss: [1.5, 3.0]     # input · cache miss / 输入 · 缓存未命中
    output:         [4.5, 9.0]     # output / 输出
  deepseek-v4-pro:
    inputCacheHit:  [0.15, 0.3]
    inputCacheMiss: [4.5, 9.0]
    output:         [13.5, 27.0]

Prices can change — always check the official DeepSeek pricing page. Override per model via config.priceTable. Models not in the table still count tokens but are marked unpriced in reports.

价格可能变动，请以 DeepSeek API 官方定价页 为准；在 config.priceTable 中按模型名覆盖即可。未在表中配置的模型会照常统计 token，费用标记为未计费，并在报告中提示。

---

Billing notes / 计费口径

English

• Consistent with dsh-token-meter: only the last reported usage sample per (turn, step) counts (retries/final messages are not double-counted).
• Usage is bucketed by the event's actual timestamp, converted to the configured timezone, then split into peak/off-peak.
• reasoningTokens are part of output and are not billed again; DeepSeek does not charge for cache writes, so cacheWriteTokens are excluded.
• Uses real provider usage from session logs (never heuristic estimates).

中文

• 与 dsh-token-meter 一致：同一 (turn, step) 只取最后一次报告的用量样本（重试/最终消息不重复计费）。
• 用量按事件发生时间（epoch ms）换算到配置时区，判断高峰/空闲。
• reasoningTokens 属于输出，不额外计费；DeepSeek 暂不对缓存写入（cache write）收费，故 cacheWriteTokens 不参与计费。
• 统计的是会话日志中的真实 provider usage（而非启发式估算）。

---

Development / 开发

English

npm install     # install zod + react (dev)
npm test        # unit + fixture-based integration + client-bundle tests

Tests are self-contained and date-independent (synthetic session logs are generated at runtime); no ~/.dsh data is required. Locally you can also run DSH_USAGE_REAL=1 node test/test-usage.mjs to cross-check against your real session logs.

中文

npm install     # 安装 zod + react（dev）
npm test        # 单元 + 夹具集成 + client bundle 测试

测试完全自包含、与日期无关（运行时生成合成会话日志），不需要 ~/.dsh 数据。本机可用 DSH_USAGE_REAL=1 node test/test-usage.mjs 额外与真实会话日志交叉核对。

---

Known limitations / 已知限制

• A session log whose tail frame is still being written is decoded frame-by-frame and the incomplete tail is tolerated (matching DSH's crash-recovery semantics); the report shows a "数据截至" (as of) time.
• A corrupt log is skipped with a warning in the report; it never breaks the whole summary.
• The command result is plain text; richer charts/panels can be built on top of the usageToday projection.

---

License / 许可证

MIT