前言¶

在 DeepSeek Harness（DSH）里选模型，通常只能知道「接下来走哪条路由」，看不到 OpenCode Go、Grok、Command Code 等订阅窗口还剩多少，也看不到这一轮对话到底消耗了多少 token。社区插件 dsh-quota（维护者 xuluoluo，GitHub 仓库 xuluoluo/dsh-quota）把这两块补到客户端：直接向各厂商自己的计费 / 用量接口拉快照，并在本地拦截 llm/stream 汇总 usage。实现思路参考 yetone/magpie 的 provider 层与 Usage 页，但嵌入 DSH 的 composer、设置页与凭据体系。

DSH 生态主张「一切皆插件」；SkillHub 目录页 是社区收录站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行阅读源码与许可证（仓库 package.json 标明 MIT，当前版本 1.6.0）。

这是什么¶

dsh-quota 是分类为「客户端」的 DSH 插件：在 Web 客户端注入 composer 窄条、工作区信息、设置里的「额度」页，并在 Host 侧注册额度查询、凭据写入与用量统计。它不替你在 llm-pi-ai 里接模型路由——加供应商只写额度配置与 key（Grok 登录除外），模型清单仍在 DSH 的 Models 页维护。

没有内置默认供应商：未配置时设置页只有「还没有供应商」和添加入口，避免界面出现模型选择器里并不存在的卡片。

核心功能¶

界面上的五块¶

1. Composer 下方窄条（conversation.composer.dock）：常驻显示各 provider 最紧窗口或余额摘要，例如 OpenCode Go 35% · Grok ⚠100% · 今日 ≈$0.42；超阈值带 ⚠，点击可刷新。鼠标悬停用原生 title 展开各滚动窗口与重置时间。Composer 右侧 chip 与窄条同源，默认关闭，需 showChip: true 才显示。
2. Composer 左侧两格（conversation.input.left）：当前工作文件夹与 git 分支（非仓库则提示「不在 git 仓库里」）；约 15 秒向 Host 同步，换会话会重查。
3. 设置 → 额度：三栏——额度（卡片、进度条、凭据保存 / 清除 / 测试）、用量（近 7 天 token、缓存命中、推理 token、按模型明细与估算花费）、输入预测（开关、模型、提示词）。
4. + 添加供应商：选预设、可选显示名与 API key（Grok 需在卡片内设备码登录）；写入 profile 的 cordis.patch.yml（插件 id dsh-quota），重启仍保留。
5. 卡片头路由状态（只读）：已接入模型 / 未接入模型 / 仅额度（Command Code 无可用聊天接口，只盯额度）。

额度数据来源¶

插件按 preset 调用厂商接口，例如：

告警默认：alertAt 90、alertCriticalAt 97 按最紧窗口；余额卡用 balanceFloor（默认 5，同币种单位）。

用量与花费¶

插件包装 llm/stream waterfall：chunk 原样下游传递，在成功结束前记录最后一个 usage chunk 与 provider / model。数据写入 $DSH_HOME/.quota-usage.json（默认 ~/.dsh/.quota-usage.json），保留 30 天，页面展示近 7 天与今天。

花费由 build/prices.js 价目表按 USD / 百万 token 估算，订阅制 provider 的 dollar 数仅作横向参考，不是账单。可在配置里用 prices 覆盖单价。

凭据¶

秘密不落插件私有文件，走 DSH ctx.credentials：

• Grok：设备码 OAuth，写入 ~/.dsh/.credentials.yaml 的 llm-pi-ai/xai，与 dsh-llm-pi-ai 同形——在此登录后 DSH 内可选 Grok 模型对话。
• OpenCode Go / Command Code：POST /quota/key 写入凭据库；Command Code 无 key 时可只读 ~/.commandcode/auth.json。
• DeepSeek API：使用 DEEPSEEK_API_KEY，与 DSH 账号余额页是两套账单。

七种预设：opencode-go、xai-billing、commandcode、deepseek-api、bailian、chatgpt、claude。

输入预测（可选）¶

参考 dsh-prompt-suggestion 思路：在一轮回答结束且输入框为空时，经 debounce 调用模型，在输入框以灰字显示下一行建议；Tab 或 → 填入，不自动发送。预测本身算一次真实模型调用，计入用量与花费。

安装与启用¶

从 GitHub 安装（命令来自仓库 README「六、安装」；--profile 按你实际 profile 替换，文档示例为 desktop）：

dsh plugin --profile desktop add github:xuluoluo/dsh-quota

生效规则：客户端 build/client.js 改动后刷新页面即可；Host 侧（index.js、providers.js 等）改动需重启 DSH。

启用后打开 设置 → 额度，用 + 添加供应商 按需添加 preset；无配置则保持空页。

典型用法¶

1. 添加 OpenCode Go 或 DeepSeek API preset，在卡片凭据区粘贴 key 并保存，点「测试」确认 Host 能打到厂商接口。
2. 添加 Grok（xai-billing） 后，在卡片点「登录 Grok」，在浏览器完成设备码授权；窄条与额度页会显示订阅窗口。
3. 使用 ChatGPT / Claude preset 时，确保本机已有 Codex / Claude Code 登录文件；插件只读额度，不写 API key。
4. 在 用量 栏查看近 7 天 token 与 ≈$ 估算；composer 窄条看「今日」估算。
5. 需要 composer 右侧 chip 时，在 cordis.patch.yml 的 dsh-quota 配置中加 showChip: true（完整可选字段见 README「七、配置」）。

可选配置片段（节选）：

- id: dsh-quota
  name: 'dsh-allowance'
  config:
    enabled: true
    refreshMs: 60000
    alertAt: 90
    alertCriticalAt: 97
    showChip: true
    predict:
      enabled: true
      debounceMs: 700

适用场景与注意¶

适合：同时在 DSH 里混用多种订阅或 API，希望在对话界面一眼看到额度余量、本地 token 用量，并在接近上限时收到 ⚠ 提示；需要在 composer 旁看到当前目录与 git 分支的开发者。

务必注意：

• 插件以当前 DSH Host 进程权限运行，会读写在凭据库、调用外网计费接口、读取 ~/.codex/auth.json 等本机文件。安装前应审阅 源码 与 README「八、HTTP 面」中的同源与安全说明：/quota/* 路由由 Host 直接注册，本机其它进程理论上可读额度数字（与「本机可读 ~/.dsh/.credentials.yaml」同一威胁模型）。
• 添加供应商不会自动接入 Models 路由；卡片标「未接入模型」时需到 Models 页自行配置。
• Grok 登录会写入 llm-pi-ai/xai 凭据；「退出登录」会删除该记录。
• 阿里云百炼仅存储 DASHSCOPE_API_KEY；要在该网关调模型需自己在 Models 页加 OpenAI 兼容路由。

结尾¶

dsh-quota 把「还剩多少额度」和「已经用了多少 token」从厂商控制台和日志里搬到 DSH 界面，并与本地凭据、patch 配置对齐，避免模型选择器与额度视图各说各话。进一步细节（HTTP 路由表、测试命令、test/live-probe.mjs）见仓库 README。

• 目录页：https://www.skillhub.cn/plugins/xuluoluo/dsh-quota
• GitHub：https://github.com/xuluoluo/dsh-quota