dsh-quota 💰

功能

• 融入原生侧边栏：宽栏时余额位于「设置」右侧；收起侧边栏后自动切换为紧凑胶囊。
• 余额组成：右键打开卡片，查看总余额、充值余额、赠送余额和更新时间，并可前往 DeepSeek 官方充值页。
• 官方用量入口：从明细卡片直接打开 DeepSeek Usage 页面，查看官方统计的 Token 与费用明细。
• 单轮消耗提示：检测到余额下降时，显示类似 -¥0.03 的上浮提示，2.6 秒后自动消失。
• 余额状态预警：人民币余额低于 ¥5（美元低于 $1）时显示橙色；余额为零、欠费或不可用时显示红色。
• 隐私模式：双击余额或点击卡片中的「隐藏」，将金额替换为 ¥ ****；偏好保存在浏览器本地。
• 智能刷新：会话结束后自动刷新；前台每 60 秒、后台每 5 分钟轮询；回到前台时按需补刷。
• 窄栏智能格式化：根据金额范围保留适当精度，并对千位金额使用 k 缩写，避免文本溢出。
• 版本可见：明细卡片显示当前插件版本，方便排查与更新。
• 中英文界面：自动跟随 DeepSeek Harness 的语言设置，支持中文与 English；切换语言后界面实时更新。

快速开始

环境要求

• DSH Web；
• Node.js 20 或更高版本；
• 已在 DSH 中配置 DeepSeek API Key，或已设置 DEEPSEEK_API_KEY 环境变量。

安装（推荐）

从 npm 安装已发布版本：

dsh plugin --profile web add deepseek-harness-quota

本地开发安装

在本仓库目录执行本地链接安装：

dsh plugin --profile web add "$PWD"

也可以传入插件目录的绝对路径：

dsh plugin --profile web add /path/to/dsh-quota

首次添加 bundle 后，停止并重新启动 dsh web。后续修改 lib/client.js 时，dsh-client-hmr 会自动更新浏览器端代码，通常无需再次重启。

验证安装

将 3000 替换为当前 DSH Web 端口：

DSH_QUOTA_PORT=3000
curl -i "http://127.0.0.1:${DSH_QUOTA_PORT}/plugins/deepseek-harness-quota/client.js"
curl -s "http://127.0.0.1:${DSH_QUOTA_PORT}/dsh-quota/balance"

客户端地址应返回以 window.__ModuleLoader__.load 开头的 JavaScript；余额地址应返回 JSON。

使用方式

| 操作 | 结果 | |:---|:---| | 左键单击余额 | 立即刷新；刷新图标至少显示 350ms，避免闪烁 | | 左键双击余额 | 显示或隐藏金额，且不会选中余额文本 | | 右键单击余额 | 展开或收起账户余额明细卡片 | | 触屏长按余额 | 打开账户余额明细卡片 | | 先点击页面，再按 Tab 聚焦余额按钮，按 Shift+F10 / ↑ | 通过键盘展开或收起明细卡片 | | 点击卡片外部 / 按 Esc | 关闭明细卡片 | | 点击「充值」 | 在新标签页打开 DeepSeek 官方充值页 | | 点击「用量」 | 在新标签页打开 DeepSeek 官方 Usage 页面 | | 对话结束 | 延迟 800ms 自动刷新；余额下降时显示本轮消耗 |

隐私模式通过浏览器 localStorage 中的 dsh-quota:privacy 保存，仅影响界面展示，不改变服务端返回的数据。

用量查看

明细卡片中的「用量」会直接打开 DeepSeek 官方 Usage 页面。插件不在本地自行累计 Token 或推算历史费用，原因是余额差值可能同时包含其他设备或 API Key 的调用、充值、赠金变化和延迟结算，无法替代官方账单。

余额接口仅用于当前余额、充值余额和赠送余额展示；需要按 API Key 或月份核对详细用量时，请以官方 Usage 页面及其导出数据为准。

刷新策略

| 触发场景 | 行为 | |:---|:---| | 首次挂载 | 立即请求一次余额 | | 任一会话从运行中变为结束 | 800ms 后请求余额，等待上游计费落库 | | 页面位于前台 | 每 60 秒请求一次 | | 页面位于后台或最小化 | 每 5 分钟请求一次 | | 页面回到前台 | 若距离上次定时请求已超过 60 秒，则立即补刷 | | 用户手动点击 | 立即请求；连续刷新期间忽略余额胶囊上的重复点击 |

只有新余额低于上一次成功读取的余额时才会显示消耗提示。免费额度、缓存命中或上游尚未结算时，不会出现该动画。

配置

默认配置可直接使用：

| 字段 | 默认值 | 说明 | |:---|:---|:---| | baseURL | https://api.deepseek.com | DeepSeek API 基础地址；末尾的 / 会自动移除 | | apiKeyEnv | DEEPSEEK_API_KEY | 交给 DSH credentials.resolve() 解析的凭据引用 | | timeoutMs | 10000 | 上游余额请求超时，单位为毫秒，最大 60 秒 |

如需代理 DeepSeek API 或改用其他凭据引用，可在 Web profile 的 Cordis patch 中覆盖配置：

- patch:
    - id: dsh-quota
      config:
        baseURL: https://api.deepseek.com
        apiKeyEnv: DEEPSEEK_API_KEY
        timeoutMs: 10000

apiKeyEnv 必须是合法的环境变量名称，例如 DEEPSEEK_API_KEY 或 MY_DEEPSEEK_KEY。

安全与数据流

• API Key 只在 DSH Host 端通过 credentials.resolve() 解析，不会注入浏览器 bundle。
• Client 仅请求同源地址 /dsh-quota/balance。
• Host 使用 Bearer Token 请求 ${baseURL}/user/balance，再将上游 JSON 包装后返回。
• 本地路由响应带有 Cache-Control: no-store，避免余额被浏览器或中间缓存保存。
• Host 和 Client 均设置 10 秒请求超时；并发刷新会合并为同一个在途请求。
• 插件不引入额外的第三方 npm 运行时依赖；Host 使用 Node.js 内置 fetch。

DSH Client
  └─ GET /dsh-quota/balance（同源，不含 API Key）
       └─ DSH Host + credentials.resolve()
            └─ GET https://api.deepseek.com/user/balance

余额字段遵循 DeepSeek 官方查询余额 API 的 is_available 与 balance_infos 结构。

响应与错误

Host 路由始终返回 JSON。上游请求成功时，格式为：

{
  "ok": true,
  "status": 200,
  "data": {}
}

无法解析凭据或请求失败时，ok 为 false，并返回可读的 error.code 与 error.message。为便于 Client 统一处理，这类应用层错误当前仍使用 HTTP 200 返回。

版本与更新

插件版本会显示在余额明细卡片右上角，并由测试确保与 package.json 保持一致。npm 包名、Cordis loader name 与浏览器 ModuleLoader id 均为 deepseek-harness-quota；配置树短 id、Host 路由前缀和侧边栏 slot id 仍为 dsh-quota。

已发布到 npm 的版本可通过 DSH plugin 命令安装、更新或移除：

dsh plugin --profile web add deepseek-harness-quota
dsh plugin --profile web update deepseek-harness-quota
dsh plugin --profile web remove deepseek-harness-quota

更新后请重启 dsh web，然后打开余额明细卡片确认右上角版本号已变化。插件不会在运行时自行下载或安装更新。

如果当前 DSH 版本不支持 update 子命令，可以使用重新安装方式：

dsh plugin --profile web remove deepseek-harness-quota
dsh plugin --profile web add deepseek-harness-quota

当前最新版本可在 npm 查看：

npm view deepseek-harness-quota version

常见问题

为什么显示 ¥ ?？

将鼠标悬停在余额上查看错误详情，并直接请求 /dsh-quota/balance 排查。常见原因是未配置 API Key、凭据引用名称错误、上游网络不可达或 DeepSeek API 返回异常。

为什么添加插件后界面没有变化？

确认使用的是 web profile，并在首次添加插件后重启 dsh web。随后检查客户端 bundle 地址是否能正常返回 JavaScript。

安装后 dsh web 报 Cannot find package 'dsh-quota'

这是 0.1.4 及更早版本的问题：DSH 会按 npm 包名导入插件，当时错误地写成了内部短名。请升级到 0.1.5 或更高版本：

dsh plugin --profile web update deepseek-harness-quota

如果当前 DSH 版本不支持 update，先 remove 再 add，然后重启 dsh web。

为什么没有显示本轮消耗？

消耗提示只在连续两次成功读取之间检测到余额下降时出现。如果该轮尚未结算、没有实际扣费或余额接口返回失败，则不会触发提示。

API Key 会发送到浏览器吗？

不会。浏览器只访问同源余额路由，Bearer Token 仅由 Host 端添加到发往 DeepSeek 的请求中。

开发与验证

修改代码后先进行语法检查：

npm test
npm run check

运行 DSH Web 后，建议依次检查：

1. 宽栏余额是否与「设置」同行并靠右对齐；
2. 左键刷新、双击隐私模式、右键明细卡片是否正常；
3. 卡片是否能通过外部点击和 Esc 关闭；
4. 收起侧边栏后金额是否以紧凑格式完整显示；
5. 前后台切换和会话结束后是否触发预期刷新；
6. API Key 未配置时，Tooltip 是否显示可诊断的错误信息。

项目结构

dsh-quota/
├── .github/workflows/ci.yml        # Node.js 20/22 持续集成检查
├── docs/
│   └── assets/
│       └── dsh-quota-overview.png  # README 功能展示图
├── lib/
│   ├── index.js                    # Host：凭据解析、余额代理路由
│   └── client.js                   # Client：侧边栏组件、交互与刷新逻辑
├── cordis.patch.yml                # Cordis Host 插件挂载声明
├── package.json                    # 导出、DSH bundle 与 Web Client 声明
├── test/                           # Client 解析、Host 路由与包校验测试
├── AGENTS.md                       # 项目架构与维护约束
├── CLAUDE.md                       # 与 AGENTS.md 同步的项目约束
├── CHANGELOG.md                    # 版本变更记录
├── LICENSE                         # MIT License
└── README.md

License

本项目基于 MIT License 开源。