@xiyi123465

dsh-usage-calendar

Name: dsh-usage-calendar
Availability: InStock
Author: xiyi123465

DeepSeekAPI余额查询插件

Stars: 0
Language: JavaScript
Created: Aug 25, 2026
Updated: Sep 26, 2026

Auth

GitHub repo

Introduction

dsh-usage-calendar

DeepSeek Harness（dsh web）持久插件：侧边栏底部常驻显示 DeepSeek 账户余额，点击打开日历面板，按天查看 实际扣费、token 用量、缓存命中率。profile-bundle 安装机制，重启后依然存在。

功能

💰 账户余额：通过 DeepSeek 官方 GET {baseURL}/user/balance 接口查询（Node fetch + Bearer 认证），1 秒缓存，界面每 1 秒自动刷新，可手动强制刷新
📅 日历视图：按天聚合本机全部会话的 token 用量——活动会话走内存日志，已存档会话走 ctx.sessionQuery（listSessions() + readSession()），因此历史日期同样完整；月度网格每天显示实际扣费、tokens、缓存命中率，深浅色表示花费高低；支持月份切换与"今天"
💴 每日实际扣费（真账）：DeepSeek 没有用量/账单 API（官方只开放 GET /user/balance，OpenAI 风格的 dashboard/billing/usage 等一律 404），所以插件把每次余额读数采样落盘，把余额下降计为扣费、充值（余额上升）不计入，按天汇总 —— 这就是平台实际扣你的钱，不区分模型
🧮 本地估算（可选对照）：接口同时保留按官方价目（人民币 + 峰谷分时）逐条估算的 days[].spend，用于解释"钱花在哪个会话/模型"；它只是估算，面板不再默认显示
🎯 缓存命中率：cacheRead / (input + cacheRead + cacheWrite)（提示词侧）
🔒 本地统计：只读本机会话事件日志与余额接口，不上传任何数据；接口仅接受本机回环请求

实际扣费怎么来的（重要）

事项	说明
数据来源	每次余额读数（面板 1 秒轮询 + 后台 5 分钟刷新）采样到 `$DSH_HOME/storages/usage-calendar-balance.json`；数值未变时不重复写（30 分钟心跳兜底）
口径	相邻两次读数之间：下降 = 扣费（记在后一次读数所在的自然日），上升 = 充值（计入 `topUp`，不计入花费）
精度	金额用整数分累加，不随折叠漂移；实测与官方余额差额一致（例：09-15 22:07→09-16 00:56 模型 ¥8.63 vs 余额实际 ¥8.37）
起算点	只能从首次采样开始测量，此前的日期没有真账
显示规则	实测优先：被完整实测覆盖的日子（采样起点之后，或已回填的日子）显示不加标记的实测金额；其余日子回退到本地估算并标 ≈（灰色）。采样起点当天标注"实测 ¥x（自 HH:MM）"，因为那一天只有部分时段被测到。每个格子都有数字，不会因为没实测就空着
回填历史	两种方式：① `node scripts/import-usage-export.mjs <平台导出的zip>` —— 直接读平台 usage 页导出的 `amount/cost-.csv`，逐日写入真账并按 API key 分摊*；② `node scripts/import-actual.mjs days.txt` —— 手输每日金额。导入文件独立存放，运行中导入也安全，约 10 秒内生效，无需重启
多 key 共用一个账号	平台导出的每一行都带 `api_key_name`，所以能分辨"哪个 key 花了多少"。本机只用 `DEEPSEEK_API_KEY` 一个 key；其它 key 的用量永远不会出现在本机会话日志里，这正是"日历数字和平台对不上"的最常见原因。面板会在这些日子标 ⚠，并在明细里给出 `其中本机 key ¥x · 其它 key ¥y（key 名）`。只想把本机 key 的金额写进日历：`--local-only`
已知偏差	服务端结算有延迟，跨午夜的调用可能记在后一天；同账号多设备共用同一余额时会一并计入；赠送额度到期同样表现为余额下降（`grantedDelta` 字段可辅助判断）
对账	面板在该日实测 vs 本地估算相差 >1.5× 时标 `⚠`。差得多通常说明那天账号上还有本机日志看不到的消耗（别的程序/机器/共用同一 key）——本地估算只能统计会话日志里的调用。要确认是"用量不同"还是"单价不同"：把平台页面那天的 token 数（命中/未命中/输出）与本地对一下；若 token 数一致而金额不同，用 `node scripts/fit-rates.mjs` 反推真实价目（先 `import-actual` 回填 ≥4 天）

安装

方式 A：profile bundle（本机采用，与 dsh-usage-stats 相同）

将本仓库放到 $DSH_HOME/vendor/dsh-usage-calendar
编辑 $DSH_HOME/profiles/web/package.json：
- dependencies 增加 "dsh-usage-calendar": "file:../../vendor/dsh-usage-calendar"
- dsh.profile.bundles 增加 "dsh-usage-calendar"
在 $DSH_HOME/profiles/web 执行 pnpm install
重启 dsh web，浏览器硬刷新

方式 B：npx 安装器（分发用）

npx --yes github:xiyi123465/dsh-usage-calendar

安装器把包复制到 $DSH_HOME/profiles/node_modules/dsh-usage-calendar，并把补丁写入 $DSH_HOME/profiles/web/cordis.patch.yml。重启 dsh web 后生效。

选项：--check（校验安装）、--dry-run（预览）、--no-enable（只复制文件不改补丁）、--help。可用 DSH_HOME 环境变量覆盖安装目录。

方式 C：ZIP 离线安装（无需 npx / 网络）

将 zip 解压到 $DSH_HOME/vendor/dsh-usage-calendar（Windows PowerShell）：

Expand-Archive .\dsh-usage-calendar-0.1.3.zip -DestinationPath $env:USERPROFILE\.dsh\vendor

运行安装器并重启 dsh web：

node $env:USERPROFILE\.dsh\vendor\dsh-usage-calendar\scripts\install.mjs

配置

API Key：读取 llm-deepseek 设置命名空间的 apiKeyEnv（默认 DEEPSEEK_API_KEY），通过凭据服务在请求时解析 —— web 端「模型」页写入的 key 即可直接使用，插件不存储密钥
baseURL：默认 https://api.deepseek.com；使用兼容中转时可在 llm-deepseek 设置中指定
价目表（仅用于本地估算对照）：cordis.patch.yml 的 config.pricing（人民币 / 百万 token）：
```
pricing:
  currency: CNY
  peakMultiplier: 2          # 高峰时段倍率
  peakWindows:               # 分钟数：540=09:00，720=12:00，840=14:00，1080=18:00
    - days: [1, 2, 3, 4, 5]
      from: 540
      to: 720
  rules:                     # 按顺序匹配「provider/model」子串，最后一条 match: "" 兜底
    - match: v4-pro          # Pro 闲时价：0.15 / 4.5 / 13.5
      hit: 0.15
      miss: 4.5
      out: 13.5
    - match: ""              # Flash 系列（含已下线的旧模型名）闲时价
      hit: 0.02
      miss: 1
      out: 4
```
价目取自官方定价页 https://api-docs.deepseek.com/zh-cn/quick_start/pricing： deepseek-flash 与 deepseek-v4-pro 两档，空闲价为高峰的一半；旧模型名 deepseek-v4-flash / deepseek-v4-flash-vision-exp 由 V4.1-Flash 服务，按 Flash 计费。官方调价后改这里即可（无需改代码）。

⚠️ 这张表没有时间维度，只对"价目表生效期内"的日子准确：例如 Flash 系在 2026-09-10 12:00 降过价（0.05/1.5/4.5 → 0.02/1/4），更早的日子用现在的表算会偏低。面板显示的实际扣费不受此影响（它来自余额差额）。另外本地估算把工作日高峰按 ×2 计，未排除中国法定节假日，且峰谷与日界按本机时区判断。

开发

pnpm check   # node --check 全部文件 + 余额折叠单元测试
pnpm test    # 仅单元测试：跨日归属、充值剔除、整数分精度、回填合并
pnpm smoke   # 冒烟测试：合成事件折叠 + 桩服务启动 + 余额采样/回填路径
pnpm import-actual -- --check

冒烟测试必须先把 DSH_HOME 指向临时目录（脚本会拒绝在真实目录下运行，避免写入真实用量缓存与余额历史）：

$env:DSH_HOME = "$env:TEMP\dsh-smoke"; node scripts/smoke-host.mjs

与 dsh-usage-stats 的关系

两个插件互不依赖、可并存。dsh-usage-stats 提供热力图与多供应商余额；本插件提供余额 + 日历形式的实际扣费/token/缓存命中率视图。

数据文件

文件	内容
`$DSH_HOME/storages/usage-calendar-cache.json`	每会话增量折叠的 token 分组（本地估算用）
`$DSH_HOME/storages/usage-calendar-balance.json`	余额采样序列（实际扣费的唯一依据），保留 180 天
`$DSH_HOME/storages/usage-calendar-actual-import.json`	手工回填的历史每日金额（插件只读，可用 `scripts/import-actual.mjs` 维护）

变更

0.1.10 — 新增 scripts/import-usage-export.mjs（+ scripts/zip.mjs）：直接导入平台 usage 页导出的 zip，逐日写入真账，并用导出里的 api_key_name 给出按 key 分摊；明细面板显示 其中本机 key ¥x · 其它 key ¥y（key 名），用于解释"账号被多个 key 共用"导致的差异。renderBalance 支持 v2 回填格式（days + keys + localKeyName），向后兼容 v1
0.1.9 — 新增对账提示：已实测的日子若与本地估算相差 >1.5×（或 <0.67×），面板在该日与明细里标 ⚠ 与本地估算相差 N×（本地日志看不到的消耗？）；新增 scripts/fit-rates.mjs（+ scripts/session-log.mjs 会话日志读取器）：用平台回填的每日金额反推真实价目/峰谷倍率，输出可直接粘贴的 pricing: 配置
0.1.8 — 修复"点开面板后插件整个消失"：明细面板把"无实测"的日期当对象取字段而抛错，宿主随即卸载整个侧边栏入口；现已改为 null 安全判断，并新增客户端渲染冒烟测试（假 React 驱动 15 项断言，覆盖未实测日/采样首日/空日/旧版载荷/余额错误态）与渲染错误边界（异常只在面板内显示错误卡片，不再让插件消失）
0.1.7 — 显示规则修正：没有实测覆盖的日子不再显示"—"，而是回退到本地估算并标 ≈；采样起点当天同时标注实测部分"实测 ¥x（自 HH:MM）"；本月合计拆成"实测 / 估算"两个数；实测金额加粗、估算灰色以区分
0.1.6 — 每日花费改为余额差额实测（官方无用量 API）；新增余额采样与 180 天历史、手工回填脚本、pnpm test 单元测试、冒烟测试防误写保护；tokens 列不再重复计入 reasoningTokens（它是 output 的子集）；面板不再按模型拆分花费
0.1.5 — 修正 Pro 价目（0.15/4.5/13.5）
0.1.4 — 通过 sessionQuery 折叠历史会话；改为人民币峰谷计价
0.1.3 — 适配 snapshotEvents() 会话 API
0.1.2 — 收起后的胶囊可拖拽
0.1.1 — 修按钮点击、1 秒轮询