# 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` 仅限环回地址访问

## 安装

```sh
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 调用）

## 开发

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

## 许可证

[MIT](LICENSE)