前言¶
在 DeepSeek Harness（DSH）里切换 DeepSeek、GLM Coding Plan、OpenRouter、Kimi 等路由时，额度往往分散在各家控制台，本机实际跑了多少 token 又要翻会话或猜。订阅套餐按窗口计费、余额按充值扣费，把用量折成「大概花了多少钱」也容易误导。社区插件 dsh-model-usage（npm：@ponydev/dsh-model-usage，维护者 PonyDevAI）面向 DSH Web 用户：额度走服务商接口，用量跟本机会话日志里的 usage 字段对齐，并在侧边栏与设置页集中展示。
这是什么¶
dsh-model-usage 是 DSH 的 Web UI 插件，分类属于模型推理相关能力。它在界面中实时展示各模型供应商的额度/余额与本机统计用量，支持 DeepSeek、GLM（Z.ai）、Kimi、OpenRouter、MiniMax、OpenCode 等内置适配，也可通过 customQuota 接任意余额或窗口式额度接口。数据原则在 README 里写得很明确：只用真实数据，不做金额估算。
核心功能¶
侧边栏与弹窗¶
- 侧边栏底部显示当前供应商的额度/余额卡片；点击可打开全部供应商弹窗（README 描述为 Codex 式交互）。
- 配置项
footer默认为true，可控制是否显示该入口。
设置页¶
- 设置 → 模型用量：KPI、趋势图、按供应商/模型聚合、请求日志、CSV 导出；右上角提供「检查更新」（对比 npm 最新版，可复制更新命令）。
- 设置 → 模型：页面底部展示各供应商额度。
供应商与 Logo¶
README 列出官方 Logo 覆盖 DeepSeek、GLM(Z.ai)、Kimi、OpenRouter、MiniMax、OpenCode、OpenAI、Anthropic、Gemini、xAI、Qwen、Mistral、Groq、GitHub Copilot 等 25+ 标识。具体接口与凭据环境变量见仓库 docs/providers.md 与 README 表格，例如：
| 供应商 | 数据接口（节选） | 凭据引用（节选） |
|---|---|---|
| DeepSeek API | api.deepseek.com/user/balance |
DEEPSEEK_API_KEY |
| GLM Coding Plan | open.bigmodel.cn / api.z.ai 额度接口 |
ZAI_CODING_CN_API_KEY / ZAI_API_KEY |
| OpenRouter | openrouter.ai/api/v1/credits |
OPENROUTER_API_KEY |
| Kimi Coding Plan | api.kimi.com/coding/v1/usages |
KIMI_CODING_API_KEY 等 |
| 自定义 | customQuota（URL + JSON 路径） |
自定义 keyRef |
DeepSeek 账号还可通过 Host deepseekAccount 服务（登录态）取数，不依赖 API Key 环境变量。
数据口径¶
- 用量：来自
assistant/message事件中服务商回传的 usage（input / cacheRead / cacheWrite / output），与本机会话日志逐 token 一致。 - 额度/余额：服务商接口返回的真实值。
- 真实消耗观测：刷新时比对余额或套餐额度变动，记录当日实际支出与充值（分开记、不冲抵）。
- 统计范围：本机、安装后写入会话日志的调用；旁路调用（如标题生成、压缩摘要）与其他设备不计入。
- 账本路径：
$DSH_HOME/model-usage/ledger.json（按日聚合，保留 120 天；首次启动回填近 30 天）。
安装与启用¶
要求宿主 DSH 版本为 >= 0.2.0-rc.2 < 0.3.0（见 package.json 的 engines.dsh）。
1、通过 CLI 安装：
dsh plugin --profile web add @ponydev/dsh-model-usage
2、或在 Web「插件」页搜索 @ponydev/dsh-model-usage 安装。
3、安装后重启 Web 宿主并刷新页面。README 给出的 macOS 示例：
launchctl kickstart -k gui/$(id -u)/local.deepseek-harness.web
本地开发可链接目录（需自行准备源码路径）：
dsh plugin --profile web add link:/path/to/dsh-model-usage
配置示例¶
在 cordis.patch.yml 中对应 model-usage 行的 config 下调整。常用键如下：
| 键 | 默认 | 说明 |
|---|---|---|
refreshSeconds |
60 | 额度刷新间隔（秒） |
footer |
true | 是否显示侧边栏底部入口 |
credentials |
{} |
按路由覆盖凭据引用 |
glm |
{} |
GLM 的 organization / project / planType |
customQuota |
{} |
通用额度适配器 |
余额式自定义适配示例：
config:
customQuota:
mycoder:
url: https://api.example.com/quota
auth: bearer
keyRef: MYCODER_API_KEY
balance:
path: data.balance
currency: CNY
窗口式（如 5 小时滚动额度）示例：
config:
customQuota:
mycoder:
url: https://api.example.com/quota
windows:
- key: rolling
label: 5h
usedPath: data.used
limitPath: data.limit
resetAtPath: data.resetAt
resetAtUnit: ms
按路由覆盖 Key 引用时，可在 credentials 中写类似 { "deepseek-official": "MY_DEEPSEEK_KEY" } 的结构（字段名以你当前 DSH 路由 id 为准）。
安全与适用注意¶
README 说明：API Key 仅在 Host 内存中解析，不进入浏览器；RPC 不返回密钥；只请求白名单域名；账本仅存用量聚合，不含对话内容；错误信息会对 sk-*、Bearer * 等脱敏。
插件以当前 DSH 进程权限运行，会向各服务商配置的官方接口发起请求。安装前建议在 GitHub 仓库 查看源码与 MIT 许可证，并确认本机已配置相应环境变量或 Host 登录态。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
若你已经在 DSH Web 里接多家模型路由，dsh-model-usage 把额度卡片、用量面板和请求日志收进同一套界面，并坚持「接口真额度 + 日志真用量」。可从目录页了解收录信息，或直接在 GitHub 查看完整供应商矩阵与架构文档：https://github.com/PonyDevAI/dsh-model-usage。
