前言¶
DeepSeek Harness（DSH）的插件化架构允许开发者根据需要扩展功能。在使用 DeepSeek API 进行开发或部署智能体时，实时掌握账户余额、Token 消耗量以及预估成本是控制成本和保障服务连续性的基础。dsh-deepseek-usage 是由 yyb16yyb-hub 维护的插件，它通过 Web UI Dock 和模型工具，为 DSH 提供了实时的用量监控能力。
核心功能¶
该插件主要解决 DeepSeek API 的用量与成本监控问题，具体能力包括：
- 账户余额与多 Key 聚合：插件会定期轮询 DeepSeek 的
/user/balance接口，默认每 30 秒一次。它支持聚合多个 API Key 的余额，显示总余额、已用余额及充值情况。 - 实时用量统计：通过
llm/stream流水线追踪请求，提供输入/输出/缓存读写/推理 Token 统计。支持三种时间窗口：总计、今日、最近 60 秒，并包含缓存命中率。 - 成本估算：基于内置的
deepseek-chat和deepseek-reasoner定价表（可通过配置覆盖）计算成本。支持平峰定价策略，可配置非高峰时段的折扣。 - Web UI Dock：在对话编辑器下方提供悬浮显示，实时展示余额、今日请求数、Token 数量和预估成本，支持自动刷新和手动刷新。
- 低余额提醒与阻断：当余额低于阈值时，Dock 界面会变色（琥珀色/红色）并触发浏览器通知。可配置在余额过低时阻断 LLM 请求。
- 设置面板：提供完整的配置编辑器，支持修改阈值、轮询间隔、定价表和阻断策略。面板内包含历史热力图、30 天柱状图以及 CSV 导出功能。
- 模型工具：提供
deepseek_usage模型工具，允许 Agent 在对话中主动查询余额和用量摘要。
安装与启用¶
安装该插件需通过官方安装命令执行。由于依赖 pnpm >= 10，首次安装时可能需要构建授权。
1、执行安装命令：
dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage
2、处理首次安装的构建授权问题：
如果安装时提示 pnpm >= 10 拒绝运行 prepare 脚本，需将包名添加到对应 profile 的 pnpm-workspace.yaml 文件中，或者使用特定的 commit SHA 进行安装以获得可重现的构建结果。
3、重启服务：
安装完成后，必须重启 dsh web 服务，客户端模块表会在启动时扫描并加载该插件。
配置说明¶
插件通过以下顺序解析 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 文件。关键配置项包括：
* pollIntervalMs：余额轮询间隔（毫秒，最小 5000）。
* alertThreshold：低余额告警阈值。
* blockOnLowBalance：是否在余额不足时阻断请求。
* offPeakHours：非高峰时段的小时数列表。
* offPeakDiscount：非高峰折扣比例。
* pricing：自定义各模型的输入、输出及缓存读写价格。
使用示例¶
1、通过模型工具查询：
在对话中调用模型工具 deepseek_usage。
* 无参数：查询所有窗口的余额和用量摘要。
* 参数 scope：指定 total、today 或 rolling（最近 60 秒）。
2、通过 Web UI 查看与配置：
启动 dsh web 后，在对话编辑器下方即可看到实时用量 Dock。点击侧边栏的“DeepSeek usage”设置面板，可以查看详细的历史图表、编辑配置或导出 CSV 数据。
注意事项¶
- 首次安装：如前所述，
pnpm >= 10环境下首次安装可能需要额外配置pnpm-workspace.yaml。 - 成本估算：插件显示的成本是基于常见公开定价的估算，并非官方实时账单。建议定期核对官方定价表。
- 安全性：API Key 仅存储在主机端，不会发送到浏览器，也不会通过 Web UI 编辑器接受或持久化存储。
- 浏览器通知：浏览器通知权限需要手动授予，插件本身不会主动弹窗请求。
- 数据持久化：每日历史数据持久化在
~/.dsh/deepseek-usage/usage.json文件中。
总结¶
dsh-deepseek-usage 适合需要在 DeepSeek Harness 环境中精细化控制 API 成本和监控调用状态的开发者。通过 Dock 实时反馈和设置面板的深度分析，它能够有效提升开发与运维效率。
