dsh-account-quota：DeepSeek Harness Web 插件，显示真实余额与用量

DeepSeek Harness（DSH）的 Web 插件生态允许开发者将功能注入到聊天界面中。dsh-account-quota 插件解决了在使用 Web 界面时难以直观查看账户状态的问题。它会在输入框下方增加一行常驻显示，展示账户的真实余额、用量百分比以及今日消耗，其排版与 DSH 自带的会话统计胶囊保持一致。

插件简介¶

这是一个 DSH Web 插件，由开发者 shxiaooo 维护，采用 MIT 许可证。

核心功能是在输入框下方的常驻行显示账户真实余额与用量。它与同一行的会话统计胶囊保持一致的排版和配色。该行显示两个胶囊：一个展示余额与今日消耗（如 ¥12.34 · 今日 -¥0.56），另一个展示使用率与重置倒计时（如 5 小时 42% · 重置于 1小时29分）。

核心功能¶

真实数据源¶

卡片上的每个数字都直接来自提供方的 API，没有任何本地推算。插件支持两种适配器：

DeepSeek 官方：通过 kind: tokens 读取 https://api.deepseek.com/user/balance，显示总余额与今日消耗。
OpenCode Go：通过 kind: plan 读取 https://opencode.ai/zen/go/v1/usage，显示滚动、每周、每月的用量百分比。

今日消耗计算¶

“今日消耗”并非简单的“当前余额 - 起始余额”。插件在 Host 端保存一条余额序列，通过计算相邻样本的差值来得出结果：
* 今日消耗 = Σ max(0, vᵢ₋₁ − vᵢ)
* 今日充值 = Σ max(0, vᵢ − vᵢ₋₁)

这种基于差值的累加方式，能正确处理充值操作，且数据落盘存储，刷新页面或重启进程后仍可读取。

展开面板¶

点击胶囊可打开详情面板，显示所有上游字段的快照。面板使用与 DSH 统计行相同的 UI 皮肤（stat-dialog），包含重置倒计时和采样次数信息。

布局整合¶

插件通过 CSS 选择器修改布局，使其与统计行并排显示，而不是另起一行。这涉及对 data-slot='conversation.composer.dock' 的特殊处理，以确保不破坏输入框卡片原有的布局。

安装与配置¶

安装¶

在终端执行以下命令：

pnpm dsh plugin --profile web add link:~/dsh-account-quota

安装后必须重启 dsh web，浏览器才能在启动时组装进 boot graph。

环境变量¶

使用前需配置环境变量：
* DEEPSEEK_API_KEY
* OPENCODEGO_API_KEY

配置示例¶

在 DSH 的配置文件中，可以调整超时、缓存时间和状态落盘路径等参数：

- id: account-quota
  config:
    # 单次上游请求超时（覆盖响应体读取）
    requestTimeoutMs: 10000
    # 上游响应体上限，边读边判
    maxResponseBytes: 65536
    # 快照新鲜度下限，同时也是 Host 半的采样周期（默认 60000ms）
    cacheMs: 60000
    # 余额序列落盘位置
    statePath: $DSH_HOME/account-quota/state.json
    # 提供方配置
    providers:
      deepseek:
        kind: tokens
        displayName: DeepSeek 官方
        apiKeyEnv: DEEPSEEK_API_KEY
        balanceUrl: https://api.deepseek.com/user/balance
        currency: CNY
      deepseek-go:
        kind: plan
        displayName: OpenCode Go
        apiKeyEnv: OPENCODEGO_API_KEY
        usageUrl: https://opencode.ai/zen/go/v1/usage
        rollingLabel: 5 小时

工作原理¶

刷新节奏¶

Host 半：每隔 cacheMs（默认 60 秒）向上游采样一次，填入缓存。
Client 半：每隔 POLL_MS（默认 60 秒）重读快照，不直接打上游。
倒计时：重置倒计时每 30 秒重算一次，显示精度为分钟。

界面上的数字最多比上游旧约 60 秒（包含一次请求耗时）。

技术实现¶

依赖：依赖 @deepseek-ai/dsh-client-ui-primitives 中的 React Hooks（如 useAnchoredPosition、useDismissOnOutsidePointer）来处理面板定位与关闭。
布局修复：利用 CSS :has() 选择器修改 conversation.composer.dock 的 display 属性为 flex，并使用 !important 覆盖宿主的 display: contents。这允许插件行与统计行共享一行，同时保持输入框卡片（width: 100%）不受影响。
数据计算：Host 端负责折叠余额序列，计算差值；Client 端仅负责渲染 Host 提供的结果。

注意事项¶

Node.js 版本：要求 Node.js >= 22。
许可证：MIT。
插件权限：插件以当前 DSH 进程的权限运行，安装前建议检查源码。

结语¶

dsh-account-quota 插件提供了一个干净、准确且与现有 UI 融合良好的方式来监控账户余额与用量。通过直接读取上游 API 和基于差值的计算逻辑，它避免了本地统计可能带来的数据偏差。