dsh-usage-calendar

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)（提示词侧）
• 🔒 本地统计：只读本机会话事件日志与余额接口，不上传任何数据；接口仅接受本机回环请求

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

安装

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

1. 将本仓库放到 $DSH_HOME/vendor/dsh-usage-calendar
2. 编辑 $DSH_HOME/profiles/web/package.json：
   • dependencies 增加 "dsh-usage-calendar": "file:../../vendor/dsh-usage-calendar"
   • dsh.profile.bundles 增加 "dsh-usage-calendar"
3. 在 $DSH_HOME/profiles/web 执行 pnpm install
4. 重启 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 / 网络）

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

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

2. 运行安装器并重启 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/缓存命中率视图。

数据文件

变更

• 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 秒轮询