dsh-api-usage

DeepSeek Harness (DSH) 插件：实时 DeepSeek API 余额与用量面板。

在 DSH Web 界面的**侧边栏底部（设置按钮上方）**提供一个常驻小部件：当前余额、今日消费（余额实测）、今日 Tokens、请求数、24h 消费柱状图，点击展开/收起，一键直达 DeepSeek 充值页。

特色

• 余额差值计费：每 60 秒查询一次 /user/balance，相邻两次余额之差即真实消费（不再依赖价格表估算），精度 ¥0.01
• 刷新即同步：点「↻」强制刷新余额的同时，立即结算差值更新今日消费（无需等下一个轮询周期）
• 持久化：今日消费 / Tokens / 请求数 / 余额基准全部落盘（$DSH_HOME/.ds-api-usage-state.json），跨进程重启与插件重挂载都不清零；仅本地 0 点按"今日"语义归零
• 响应式小部件：侧边栏宽/折叠（rail）两态自适应；窄窗口（<768px）自动精简
• 失败兜底：余额查询失败时显示最近一次余额（缓存标记），10 秒内自动重试，不显示吓人的报错
• 充值直达：蓝色实心「充值」按钮，直接调用 window.open 打开 DeepSeek 充值页（绕过侧边栏的链接拦截）
• 路由保护：/ds-api-usage/snapshot 仅限环回地址访问

安装

dsh plugin --profile web add github:chenzhexii/dsh-api-usage

重启 dsh web 后，刷新页面即可在侧边栏底部看到小部件。

功能

• 💰 余额 — 总余额 + 可用状态徽标，每 60 秒自动刷新，来源：官方 GET /user/balance
• 📊 今日消费 — 本地 0 点起，按余额差值实测（误差 ≤ ¥0.01），非估算
• 🔢 今日 Tokens / 请求 — 来自每次模型调用的 usage 上报（输入/输出分项）
• 📈 24h 柱状图 — 按小时汇总的真实消费（悬停看精确值）
• 🎨 响应式 — 折叠成 56px 窄栏时只显示余额；窄屏隐藏"今日"文字
• 🔄 手动刷新 — 同步更新余额与今日消费
• 💳 充值 — 蓝色实心按钮直达 https://platform.deepseek.com/top_up

工作原理

Host (Node.js)                              Browser
  llm/stream 瀑布监听 → 小时/天 token 桶 ─┐
  每 60s 轮询 /user/balance              │  fetch('/ds-api-usage/snapshot')
  相邻余额差 → 今日消费 + 按小时归集 ────┤→  侧边栏小部件渲染
  状态落盘（token 桶 + 消费 + 基准）──────┘  （每 60s 自动轮询 + 手动刷新）

• Token 计数：来自 provider 上报的 usage chunk（输入/输出/缓存命中/缓存未命中已是互斥分项）
• 消费金额：余额实测（上次余额 − 当前余额 累加），价格表估算保留为 estimatedCny 参考
• 数据保留：小时桶 48h、天桶 14 天，自动滚动淘汰

配置

无需配置，开箱即用（复用部署已有的 DEEPSEEK_API_KEY 凭据）。可选调整：

• 轮询间隔：改 src/index.js 中 ctx.interval(..., 60000)
• 状态文件位置：$DSH_HOME/.ds-api-usage-state.json

环境要求

• DeepSeek Harness Web profile（dsh web），dsh plugin 可用 pnpm
• Node ≥ 20（宿主侧）
• 已配置 DEEPSEEK_API_KEY 凭据
• Host 上可用 curl（用于余额接口，经 subprocess seam 调用）

开发

npm run check   # 语法检查宿主与客户端两端

许可证

MIT