Sev7een/ds-api-usage

DHS API Usage — DeepSeek Harness 插件

English | 简体中文 | Português (Brasil)

安装后，打开 DeepSeek Harness 的设置 → API用量页面，即可查看 DeepSeek API 用量。页面展示账户余额、最近 24 小时（日视图为 14 天）的估算消费金额、Token 数量与 API 请求次数，并以类似 DeepSeek 官方平台用量页的时间线柱状图呈现。

功能特性

• 💰 余额卡片 — 总余额（赠送 / 充值分项，标注 API 返回的货币代码 CNY 或 USD）+ 可用状态徽标，数据来自官方 GET /user/balance 接口。
• 📊 指标卡片 — 24h 估算消费（人民币 CNY）、Token 数量（输入 / 输出分项）、API 请求次数。
• 📈 时间线图表 — 最近 24 小时按小时聚合、或 14 天按日聚合的柱状图，可在消费 / Tokens / 请求数之间切换（悬停查看精确数值）。
• 🔄 实时刷新 — Host 端每 60 秒刷新余额；页面每 30 秒轮询，并提供手动刷新按钮。
• 🔑 无需额外配置密钥 — 复用部署中已有的 DEEPSEEK_API_KEY 凭证（通过 harness 的 credentials 服务）。

架构

┌─────────────────────────────── Host（Node.js）───────────────────────────────┐
│ src/index.js                                                                 │
│  • ctx.on('llm/stream', ...)  ← waterfall：将每次真实模型调用的               │
│      provider 上报的 TokenUsage（输入/输出/缓存命中/缓存未命中，              │
│      已是互斥分项，与 DeepSeek 计费口径一致）                                 │
│      折叠进内存中的按小时 + 按天桶                                           │
│  • fetchBalance()             ← credentials.resolve('DEEPSEEK_API_KEY')      │
│      → subprocess curl → https://api.deepseek.com/user/balance               │
│      （web.fetch 无法携带 Authorization 头，故用 curl）                       │
│  • webServer.register('/ds-api-usage/snapshot')  ← 供 Client 读取的 JSON 端点 │
└──────────────────────────────────────────────────────────────────────────────┘
                              │ fetch('/ds-api-usage/snapshot')
                              ▼
┌────────────────────────────── Client（浏览器）───────────────────────────────┐
│ client/bundle.js（web bundle；client/index.js 为动态插件源码）               │
│  • slots.inject('settings.section')  → 新增设置页（标签经 locale 服务本地化）        │
│  • 余额卡片 + 3 张指标卡 + 时间线柱状图                                      │
│      （消费 / Tokens / 请求；24h 或 14d）                              │
│  • 每 30 秒自动刷新（静态 bundle 使用原生 setInterval）                            │
└──────────────────────────────────────────────────────────────────────────────┘

数据说明

• Token 数量是真实的 — 来自每次流式模型调用的 usage chunk（StreamChunk 的 type: 'usage'、TokenUsage），与 harness 自身用于会话统计的 provider 上报数据完全一致。
• 消费金额为估算 — 人民币（CNY）按 DeepSeek 官方公开价（中文文档，模型 & 价格）在生成的 PRICING 表（src/index.js）中按模型计算：
  • 缓存命中输入 → hit 单价
  • 缓存未命中输入 → miss 单价
  • 输出 → output 单价
  • DeepSeek 不单独对缓存写入计费，故未计入。
  • 自 2026-08-16 起 DeepSeek 按高峰 / 空闲时段计费：带有 peak / offPeak 单价的模型按请求的 UTC 小时（peakHoursUtc 中的窗口：01:00–04:00 与 06:00–10:00 UTC）计费；其余模型使用 flat 单价。
• 聚合数据持久化 — 按小时桶保留 48 小时、按天桶保留 14 天，保存到 $DSH_HOME/storages/ds-api-usage.json（写入去抖：最多每 60 秒一次，插件关闭时冲刷；fail-safe：读写错误绝不会影响统计）。14 天视图可跨 web app 重启存活；删除该文件即可清零。harness 另维护其自有的按会话持久化 token 投影。

安装

通过 dsh plugin add 安装（推荐，GitHub 或 npm）

直接从本 GitHub 仓库安装：

dsh plugin --profile web add github:Sev7een/ds-api-usage

或发布到 npm 后：

dsh plugin --profile web add dsh-plugin-ds-api-usage

dsh plugin 会在 profile 目录中转发给 pnpm，并将包调和进 profile 的 bundle 列表（dsh.profile.bundles）。包内 cordis.patch.yml（经 package.json 的 dsh.bundle.patch 声明）随后把插件行插入宿主组合；dsh.client 声明则让 web 外壳加载 client/bundle.js 作为设置页。

作为动态插件（开发 / 会话级）

原版是会话级动态 Cordis 插件，通过 cordis_define / cordis_run 创建（参见 DeepSeek Harness 文档）。code.host 的函数体即 src/index.js 去掉 module.exports 包装；code.client 的函数体即 client/index.js 去掉包装。

注意：动态形态使用沙箱私有的 harness.handle / host.call 通道（client/index.js），而静态 bundle 形态（client/bundle.js）通过 HTTP 路由 /ds-api-usage/snapshot 与 Host 通信。修改协议时请保持两者同步。

作为组合插件（持久化，手动）

在你的 profile 的宿主组合（cordis.patch.yml）中添加：

- insert:
    - id: ds-api-usage
      name: 'dsh-plugin-ds-api-usage'

或不安装包、以相对路径指向本仓库。本插件属于 Host 平面：它读取 Host 的 credentials、subprocess、timer、webServer 服务，并将客户端设置页注册到根作用域的 settings.section 插槽，因此应放在宿主组合中，而不是某个 agent preset 内。

依赖要求

• 已配置 DeepSeek LLM 适配器的 DeepSeek Harness（DEEPSEEK_API_KEY 凭证可通过 credentials 服务解析）
• Host 上可用 curl（用于余额接口）
• 带设置侧边栏的浏览器客户端（用于 UI）

开发

npm run check   # 语法检查两个半端
npm test        # 离线测试套件：定价解析器（fixtures）+ peak/off-peak 计费逻辑

• 价格自动跟踪：.github/workflows/update-pricing.yml（每日 cron + 手动触发）会重新解析官方定价页，表有变化时自动开启 PR；npm run update:pricing 可本地执行同样操作（--apply 写入 src/index.js 中的生成块）。请只通过脚本修改表格——__PRICING_BEGIN__ / __PRICING_END__ 标记之间的块为生成内容。
• Client 通过 harness 的 locale 服务本地化（命名空间 settings.ds-api-usage），并跟随 harness 的当前语言：提供 harness 的 zh/en 词典及 pt-BR 条目（为将来 harness 支持预留；当前语言缺少的键会回退到 zh）。

CI / GitHub Actions

仓库自带两个工作流——无需任何密钥或 API key，唯一前提是仓库已启用 GitHub Actions（默认；可在 Settings → Actions → General → Allow all actions 确认）：

• ci.yml — 每次 push 与 pull request 都会运行：npm run check（两端语法检查）与 npm test（基于页面 fixtures 的离线测试套件）。
• update-pricing.yml — 每天（06:23 UTC cron）及手动触发（Actions → update-pricing → Run workflow）重新解析 DeepSeek 官方定价页；表格变化时自动开启 PR（工作流在默认 GITHUB_TOKEN 上声明了 contents: write 与 pull-requests: write，无需额外配置）。若文档页改版，解析校验会失败并让 job 响亮地失败，而不会开出错误的 PR。

首次 push 后，请手动运行一次 Actions → update-pricing → Run workflow 以端到端验证整个流程（价格未变时，no change 是预期的绿色结果）。

许可证

MIT