yyb16yyb-hub/dsh-deepseek-usage

English | 中文

DeepSeek Harness 插件：实时显示 DeepSeek API 用量信息。

• 💰 账户余额：轮询 DeepSeek /user/balance（默认每 30s），显示总额/赠送/充值余额与可用状态，支持多 Key 聚合（apiKeys）
• 📊 用量统计：通过 llm/stream waterfall 实时统计请求次数与 token（输入/输出/缓存读/缓存写/思考），支持「全部 / 今日 / 近 60s」三个窗口，并给出缓存命中率
• 💾 历史持久化：每日用量在重启后不丢失（~/.dsh/deepseek-usage/usage.json），支撑趋势图与 CSV 导出
• 💸 花费估算：按模型单价（内置 deepseek-chat / deepseek-reasoner 默认价目表，可配置覆盖）估算花费，三个窗口分别计算，支持峰谷分时计价（offPeakHours / offPeakDiscount）
• 🖥️ Web UI dock：输入框下方的实时统计条（conversation.composer.dock 槽位），自动刷新 + 手动刷新
• ⚠️ 余额低告警：余额低于阈值（默认 20）dock 变琥珀色、低于阈值 1/5 变红色，并在跨过阈值时发送一次浏览器通知；可开启余额不足时拦截请求（blockOnLowBalance）
• 📋 设置页用量面板（settings.section 槽位）：余额卡片 + 各 Key 明细、三窗口用量、面板内配置编辑器（写回宿主并持久化）、历史热力图与 30 天柱状图、按模型单价表、按会话用量明细表，以及 CSV 导出
• 🛠️ 模型工具：deepseek_usage，agent 可直接查询余额与用量
• ✅ 测试与 CI：vitest 单元测试 + GitHub Actions 流水线（typecheck + test + build）

安装

从 GitHub（推荐）

dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage

⚠️ 首次安装需授权构建：pnpm ≥ 10 默认拒绝运行 git 依赖的 prepare 脚本（安装时从源码构建出 lib/）。第一次 add 会失败并提示，把 pnpm 打印的包键加入该 profile 的 pnpm-workspace.yaml 后重新执行：

allowBuilds:
  dsh-deepseek-usage: true

建议锁定 commit 以获得可复现的安装：dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage#<sha>。

本地目录 / tarball

dsh plugin --profile web add /path/to/dsh-deepseek-usage   # 本地目录（预构建好 lib/）
dsh plugin --profile web add ./dsh-deepseek-usage-0.1.0.tgz # pnpm pack 产物

安装后重启 dsh web 生效（client 模块表在启动时扫描）。

卸载：

dsh plugin --profile web remove dsh-deepseek-usage

配置

API Key 按以下优先级解析（每次轮询重新解析，改动即时生效）：

1. 插件配置 apiKey
2. dsh 凭据系统（ctx.credentials）：进程环境变量 → ~/.dsh/.credentials.yaml → 项目 .env → 用户 .env。在 Web 设置页「模型」里填的 DeepSeek Key 就存在 ~/.dsh/.credentials.yaml，插件会自动找到，无需额外配置
3. 已注册的 llm-deepseek 设置节中存储的 apiKey（若有）

在 profile 的 cordis.patch.yml 中覆盖插件的行即可配置：

- id: deepseek-usage
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    apiKeys: []                # 额外 API Key，余额聚合展示
    pollIntervalMs: 60000      # 余额轮询间隔（ms，最小 5000）
    balanceTimeoutMs: 10000    # 余额请求超时（ms）
    showBalance: true
    showTokens: true
    showCost: true
    alertThreshold: 20         # 余额低告警阈值（账户货币单位；0 = 关闭）
    blockOnLowBalance: false   # 余额低于阈值时拦截 LLM 请求
    maxSessions: 200           # 会话明细保留上限（超出按最近活跃裁剪）
    offPeakHours: [0,1,2,3,4,5,6,7]  # 闲时小时（本地时间，0-23）
    offPeakDiscount: 0.5       # 闲时缓存未命中的价格乘数
    pricing:
      deepseek-chat:
        input: 2               # ¥ / 1M tokens
        output: 3
        cacheRead: 0.5
      deepseek-reasoner:
        input: 4
        output: 16
        cacheRead: 1

花费为估算值：默认价目表为常见公开定价，请以 DeepSeek 官方最新价格为准，可通过 pricing 或设置面板编辑器覆盖。峰谷计价只对缓存未命中的输入/输出价格打折（与 DeepSeek 官方策略一致），按当前小时计价。

设置面板内的改动（阈值、轮询间隔、显示开关、拦截开关、闲时窗口、单价）经宿主校验后持久化，覆盖 cordis.yml 中对应项；密钥（apiKey/apiKeys）永远不会通过编辑器写入或持久化。

Web UI

• 输入框下方统计条：余额 · 今日请求 · token（含缓存命中率）· 今日估算花费 · 更新时间，每 30s 自动刷新（跟随宿主 pollIntervalMs），点击「刷新」立即拉取。
• 余额告警：余额低于 alertThreshold 时统计条变琥珀色并显示 ⚠，低于阈值 1/5 变红色；跨过阈值时若浏览器已授权通知权限，会发送一次系统通知。开启 blockOnLowBalance 后，余额低于阈值时 LLM 请求会直接失败并给出明确原因。
• 设置页「DeepSeek 用量」面板（设置 → 侧边栏底部按钮打开后可见）：余额卡片 + 各 Key 明细（多 Key 时）、全部/今日/近 60s 三窗口用量、历史热力图与 30 天柱状图、面板内配置编辑器、按模型单价与用量表、按会话的用量明细表，以及历史/会话的 CSV 导出。

数据来自同源端点 GET /dsh-deepseek-usage（?refresh=1 强制刷新）与 POST /dsh-deepseek-usage/config（编辑器写回）。API Key 只存在宿主机侧，不会进入浏览器；每日历史持久化在 ~/.dsh/deepseek-usage/usage.json。

工具调用

agent 可调用 deepseek_usage：

• 无参数：返回全部窗口的余额 + 用量摘要
• scope：total / today / rolling 选择窗口

开发

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest 单元测试（stats + cost）
pnpm build       # esbuild → lib/index.js（宿主半）+ lib/client.js（浏览器半）

结构

src/
├── index.ts        # 宿主半：apply()、llm/stream 钩子、拦截开关、工具、HTTP 路由
├── balance.ts      # DeepSeek /user/balance 客户端与多 Key 轮询器
├── stats.ts        # 用量统计（三窗口、按模型/按会话、restore/export）
├── cost.ts         # 纯计价逻辑（峰谷分时）——单元测试覆盖
├── persist.ts      # JSON 持久化（原子写入，$DSH_HOME/deepseek-usage/usage.json）
├── config.ts       # schemastery 配置 schema
└── client/
    ├── index.ts    # 浏览器半：注册 locale + composer.dock / settings.section 槽位
    ├── api.ts      # 共享：端点类型、fetch、配置保存、CSV 导出、格式化
    ├── UsageDock.tsx            # 输入框下用量统计条（含余额告警）
    ├── UsageSettingsSection.tsx # 设置页面板（余额/账号/用量/历史/编辑器/会话）
    └── locales.ts  # 中英文案

构建要点

• 宿主半保持 @deepseek-ai/* external，从 profile 的 node_modules 解析（cordis 运行时单例）
• 浏览器半按 packages/client/web/src/platform.ts 的平台模块表 external（react、cordis、slots 等），其余全部内联；产物以 window.__ModuleLoader__.load({ id, factory }) 包装，由 Web 壳的模块加载器装载

范围说明

• 主题：UI 使用内联样式，继承应用文字颜色并自适应深浅色主题；未消费主题 CSS 变量（当前 harness 未向插件暴露公共主题 token API）。
• 截图：README 暂无界面截图，安装使用后可自行补充。
• 多供应商：刻意不做——本插件只跟踪 DeepSeek 用量；OpenCode Go / Moonshot / Kimi 监控应做成独立插件。

安全提示

余额轮询使用与 LLM 请求相同的 API Key；Key 不会发送到浏览器端，插件也不会持久化密钥（只持久化非敏感的配置覆盖项）。安装第三方插件前请自行审阅源码。