dsh-usage-lite

dsh-usage-lite

为 DeepSeek Harness Web 界面提供简洁、优雅的余额与 Token 用量面板。

Compact provider balances and local token-usage analytics for the DeepSeek Harness Web UI.

界面示意图：直观展示折叠态余额、供应商账户与聚合用量；具体文字和数据以实际运行环境为准。

为什么选择 Lite

dsh-usage-lite 只保留高频信息和必要操作：侧边栏快速查看余额，展开后查看供应商账户与近半年用量。没有独立后台、复杂配置页或遥测服务。

• 一眼查看余额：侧边栏直接显示所选供应商、当前余额和上次拉取时间。
• 自动发现供应商：读取 DSH 已配置的模型供应商并逐行展示，超出高度后在列表内滚动。
• 聚合本地用量：按日期、供应商和模型汇总 Token，并用 27 周热力图展示趋势。
• 明确能力边界：当前仅查询 DeepSeek 余额；其他供应商仍会展示并参与 Token 统计。
• 隐私优先：凭据只在服务端解析，不会返回浏览器；HTTP 接口仅接受本机回环请求。
• 中英文界面：跟随 DSH Web 的语言环境。

功能

余额

• 展示 DSH 中已配置的供应商账户。
• 查询 DeepSeek 当前余额、赠送额度和充值额度。
• 支持刷新、隐藏余额以及选择折叠态默认账户。
• 刷新失败时保留最近一次成功余额和拉取时间。
• 不支持余额查询的供应商会明确标记，且不能设为折叠态默认账户。

用量

• 汇总输入、输出、缓存读取和缓存写入 Token。
• 按供应商与模型展示 Token 和估算开销。
• 展示最近 27 周的每日用量热力图。
• 点击日期查看当日 Token 与估算开销。
• 用量视角聚合所有供应商，不受余额页默认账户选择影响。

安装

需要已安装并能够运行 dsh web 的 DeepSeek Harness 环境。

dsh plugin --profile web add dsh-usage-lite

安装后重启正在运行的 dsh web，并在浏览器中硬刷新。入口会出现在侧边栏设置项上方。

更新

dsh plugin --profile web update dsh-usage-lite

更新后同样需要重启 dsh web 并硬刷新浏览器，以避免旧客户端资源缓存。

卸载

dsh plugin --profile web remove dsh-usage-lite

配置

插件不维护独立供应商配置，而是读取 DSH 已有设置：

• 官方 DeepSeek 配置来自 llm-deepseek。
• 其他模型供应商来自 llm-pi-ai.providers。
• DeepSeek 默认凭据引用为 DEEPSEEK_API_KEY；若 provider 配置了 apiKeyEnv，则使用该引用。

例如在 DSH 凭据文件中配置：

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

不要将真实 API Key 提交到 Git、公开 Issue 或日志中。

供应商支持

能力	DeepSeek	其他 DSH 供应商
自动发现与列表展示	支持	支持
Token 用量聚合	支持	支持，取决于会话事件是否包含 usage 信息
余额查询	支持	暂不支持
折叠态默认账户	支持	余额查询适配后可用

余额查询调用 provider 配置的 baseURL 下的 /user/balance。新增供应商余额适配器是后续扩展方向，欢迎贡献。

数据来源与估算

Token 数据来自 DSH 当前会话和本地持久化会话事件，不来自供应商账单 API。插件读取事件中的 data.usage 和模型来源信息，并按 UTC 日期聚合。

开销由内置价格表估算，单位为人民币 / 100 万 Token：

模型	输入	输出	缓存读取	缓存写入
deepseek-chat	¥2	¥8	¥0.5	¥2
deepseek-reasoner	¥4	¥16	¥1	¥4

重要：开销仅为估算值。 供应商定价、缓存计费、折扣、币种和账单规则可能变化；未知模型当前按 deepseek-chat 价格估算。请始终以供应商实际账单为准。

隐私与安全

• API Key 通过 DSH credentials 在服务端解析，不会发送到插件客户端。
• 浏览器只接收展示所需的供应商状态、余额和聚合用量。
• 插件服务端接口只接受本机回环地址发起的 GET 请求。
• 除查询已配置 DeepSeek baseURL 的余额接口外，插件不向第三方服务上传数据。
• 项目不包含遥测、用户跟踪或远程分析服务。

如发现安全问题，请优先使用 GitHub 的私密安全报告功能，或在不包含凭据、地址和原始响应的前提下联系维护者。不要在公开 Issue 中披露可利用细节或任何密钥。

常见问题

DeepSeek 显示“未配置访问凭据”

确认 llm-deepseek 的 apiKeyEnv 与 ~/.dsh/.credentials.yaml 中的键一致，然后重启 dsh web。

有供应商但没有余额

当前仅 DeepSeek 支持余额查询。其他供应商会显示“暂不支持额度查询”，但仍可出现在用量聚合中。

没有供应商或模型用量

用量依赖 DSH 会话事件中的 data.usage 和模型来源字段。尚未产生对话用量、历史事件未持久化或上游未返回 usage 时，对应明细为空。

更新后界面没有变化

重启 dsh web，然后对浏览器执行硬刷新，确保客户端没有继续使用旧插件资源。

开发

git clone https://github.com/ericw0315/dsh-usage-lite.git
cd dsh-usage-lite
npm install
npm test
npm run check

• npm test：验证 bundle 声明、服务端聚合与客户端渲染行为。
• npm run check：检查 JavaScript 语法。

核心文件：

• lib/index.js：供应商发现、余额查询、Token 聚合和本机 HTTP 接口。
• lib/client.js：侧边栏入口、余额列表、用量详情和交互状态。
• cordis.patch.yml：DSH bundle 注册声明。

贡献

Issue 和 Pull Request 都欢迎。提交改动前请：

1. 保持实现聚焦，避免为少量信息引入复杂配置或大型依赖。
2. 为行为变化补充测试，并运行 npm test 与 npm run check。
3. 在 PR 中说明用户可见变化、验证方式和兼容性影响。
4. 不提交真实凭据、个人用量、供应商原始响应或本地 DSH 配置。

问题反馈请使用 GitHub Issues。

路线图

• 增加更多供应商余额适配器。
• 让估算价格表更易维护和扩展。
• 在不增加使用负担的前提下完善异常状态与兼容性。

路线图不代表交付承诺；具体优先级以社区反馈和实际维护成本为准。

License

MIT © dsh-usage-lite contributors