dsh-ustc-quota

GitHub · MIT

在 DeepSeek Harness（DSH） 和 中国科大「词元工坊」TokenWorks 的左侧栏里，显示 USTC 模型额度的 3h / 12h / 24h 进度、已用额度、上限、百分比和重置时间。

卡片位于会话列表与账户/设置行之间；侧边栏收起时自动隐藏。

• DSH：按 baseURL 自动发现所有指向 USTC 网关的 @deepseek-ai/dsh-llm-pi-ai provider（provider id/显示名随便取，不需要以 ustc- 开头；/v1 会自动归一到站点根），每把 key 一行。
• TokenWorks：直接使用词元工坊内置的 tokenworksUsage Host 服务，不读取 Key，不额外请求学校网关；未登录时提示先登录。
• 只读展示：不拦截模型请求、不换 Key、不改 provider。

支持的环境

| 环境 | 版本 | 数据来源 | | --- | --- | --- | | DeepSeek Harness Web / Desktop | 0.2.0-rc.2 及以上 | llm-pi-ai provider 配置 + credentials + /key/info、/user/info | | 中国科大词元工坊 TokenWorks | 0.2.x | 内置 tokenworksUsage 服务（@ustc/tokenworks-usage） |

兼容性：已在 DSH Desktop 0.2.1-rc.5 和 0.2.2-rc.1 上验证卡片、snapshot/update 路由和 dsh-plugin-manager provider；0.2.2+ 使用热更新提示，旧版保留完整重启提示。

插件没有运行时依赖，Host 使用 Node 24 自带的 fetch，Client 只用 React 和主题 token。

安装

DSH（Web / Desktop）

在左侧栏打开 插件（Plugins） → 安装插件，填入：

github:Awenforever/dsh-ustc-quota

升级前必读：DSH Desktop 0.2.1-rc.3–0.2.1-rc.5 的 client-modules 增量扫描缓存问题需要完整重启。 在这些旧版本上从旧版本升级本插件后，必须完全退出并重新打开 DSH；仅刷新页面可能不够。若升级后启动崩溃，请使用 DSH 崩溃对话框里的 重启 或 退出。
DSH 0.2.2-rc.1 及以上已支持插件热更新。 从 v1.1.17 起，只有“宿主已安装的包版本比页面正在运行的 client 版本更新”时才提示重启；更新成功后第一次启动不会再误报。全新安装本来就不需要完整重启。

固定版本（推荐，避免默认分支后续变动）：

github:Awenforever/dsh-ustc-quota#v1.1.20

也可以直接从 npm 安装（这样 DSH 的插件页能用官方渠道检查新版本，并直接更新）：

[email protected]

或者用你已有的安装方式指定同一目录/仓库：

plugin_manager install_bundle
target = github:Awenforever/dsh-ustc-quota

安装完成后 Host、插件清单和 Client slot 会即时生效。全新安装不需要完全重启 DSH；如果页面提示刷新，刷新一次即可。从旧版本升级时，DSH Desktop 0.2.1-rc.3–0.2.1-rc.5 的 client-modules 增量扫描缓存问题要求完全退出并重新打开 DSH；页面刷新不够。DSH 0.2.2-rc.1 及以上已支持插件热更新，v1.1.17 起只在宿主包版本高于页面 client 版本时提示重启，由 DSH 热重载；只有热更新失败并返回 restart-required 时才提示完整重启。详见 docs/RELEASE_ACCEPTANCE.md 的 carrier 限制。

从 GitHub 仓库安装和从 npm 安装的区别： 两者内容相同。从 npm 安装的副本能走 DSH 官方更新通道（插件页可直接检查并更新）；从 GitHub 安装的副本没有 registry 身份，卡片会自动退回 GitHub Release 检查更新，安装动作仍由 DSH 的插件管理器执行。

TokenWorks（词元工坊）

TokenWorks 是 USTC 基于 DSH 的发行版，自带 插件 页面和 @deepseek-ai/dsh-plugin-manager：

1. 在左侧栏打开 插件 → 点右上角 + 添加插件；
2. 填入 [email protected]（npm）或 github:Awenforever/dsh-ustc-quota#v1.1.20（GitHub）；
3. 全新安装后只需让插件页加载/刷新一次；从旧版本升级则必须完全退出并重新打开词元工坊。TokenWorks 的插件页「更新」只应用 Host bundle，页面刷新不能清掉 DSH client-module 缓存；若刷新后插件仍未恢复，请完全退出并重开词元工坊；
4. 用学校统一身份登录后，卡片会自动出现。

词元工坊插件页的「官方」只列出发行版自带的插件；第三方插件（包括本插件）不会出现在「官方」里，安装后会出现在「已安装」区域。这是正常的，不是没有装上。

如果之前装过旧版本并看到「插件异常」，先在插件页移除旧条目，再安装上面的 v1.1.20；v1.1.20 已包含旧包 package.json 的 BOM 修复、额度接口错误文案修正、报警图标出现时自动加宽 Key 列、更新器令牌/重试修复、DSH 0.2.2 热更新适配、分屏焦点跟随、深色主题适配，以及官方插件更新通道。安装/刷新后若仍未恢复，请完全退出并重开词元工坊，不要只凭一次页面刷新判断安装失败。

TokenWorks 的额度来自它内置的 tokenworksUsage 服务，因此：

• 不需要在插件里配置 Key；
• 不会重复请求 /key/info、/user/info（官方服务已有 30 秒缓存和退避）；
• 未登录或模型服务被撤下时显示“词元工坊未登录/不可用”，不会误报 0。

官方自带的「剩余用量」入口仍在账户弹窗里；本插件只是把同一份额度以常驻卡片的形式放到侧边栏。

词元工坊 0.2.x 的产品组合包含 @deepseek-ai/dsh-plugin-manager 与 @deepseek-ai/dsh-client-ui-plugin-manager（即「插件」页）。如果你的版本没有这个入口，请先升级词元工坊；不要手工修改 publisher 管理的 profile。

显示效果

卡片独占侧边栏底部的一整行：TokenWorks 的「更新」按钮或 DSH 的 Cordis 按钮留在上一行，不会被并排挤压；卡片内部的三列也不会被截断。

v1.1.6 起不再依赖 <style>/:has：客户端挂载后直接找到 footerActions，折叠只包含本卡片的 slot cell，并让 footer 换行。若仍看到并排，确认装的是 v1.1.20，并刷新一次页面让新的 client bundle 生效。

每把 Key（TokenWorks 下是当前账户）一行，三列：

USTC 词元额度                    更新于 13:20:05  ↻
        3h                  12h                 24h
       15:00 · 2h 40m      00:00 · 11h 40m     00:00 · 11h 40m
key-a  14.8/30   49%      14.8/70   21%       36.4/100  36%
key-b   0.3/30    1%       0.3/70    0%        63.8/100  64%
key-c   8.7/30   29%       8.7/70   12%        11.1/100  11%

• 外观按参考图的白色卡片、更大字号、行分隔和圆角进度条：绿色 = 已用，浅灰槽 = 剩余；已用 ≥70% 变黄、≥90% 变红；条高 6px、两端圆角，0% 只留浅灰槽，极小用量至少留一个圆点；未知用量中性灰槽；单元格悬停显示精确剩余值；
• 星号表示当前打开的对话实际使用的 Key，不是全局默认 Key：插件在对话 composer dock 放一个不可见的 session probe，读取该 session 的 modelSelection 投影；切换对话或改模型时星号立即移动，不需要等 15 秒轮询。同一 provider 内只换模型时星号不会移动（还是同一把 Key），换成另一个 provider 的模型才移动；星号悬停会显示它认定的 provider。
• 列头副行是每个窗口的下一次重置时刻 + 倒计时，取该窗口第一个活跃 Key 的 reset_at；3h 每 3 小时一个边界，所以 21:00 之后、午夜之前，3h/12h/24h 都可能同时显示 00:00，这是正常的，不是三列重复取了同一个值；悬停列头可看到每把 Key 的完整重置时间。
• 列头显示重置时刻和倒计时；单元格悬停显示精确时间、数据源和完整数值；
• 额度窗口刚好重置时显示“重置中…”，不会把旧用量当成当前用量；
• 单把 Key 失败只影响该行；有 5 分钟内旧数据时保留 dimmed 数据并标记错误；
• TokenWorks 的官方服务返回错误时，保留上一次有效窗口并显示官方错误文案。

更新

• 标题「USTC 词元额度」右侧显示灰色小字版本号；点击版本号可手动检查更新；
• 启动时检查一次，之后每 24 小时自动检查一次；先问宿主 pluginManager.listVersions（npm 安装的副本可用），再读 GitHub 最新 release 作为回退——两条通道任意一条可用就能给出结果；
• 有新版本时版本号旁出现小红点，点击弹出更新确认弹窗；
• 当前 DSH 通过宿主的官方 pluginManager 更新路由直接安装最新 release 的 tarball；从 v1.1.6 起，安装成功后不自动重载，弹窗会明确要求完全退出并重新打开 DSH；如果载体仍自动刷新了页面，新 client 会在卡片上显示同样的重启提示，以避免 DSH carrier 的 client-module 启动缓存（rc.3/rc.5）；
• 已预留 pluginUpdates.applyUpdate({ id, spec, version }) 适配接口，供后续 DSH 官方插件更新预览版接入；接口不可用时回退到 pluginManager，再不可用则弹窗显示安装 spec；
• TokenWorks / 旧 Host 如果暂时没有可用更新接口，弹窗会显示可复制的 spec，仍可走插件页手动安装。

工作方式

DSH 路径

1. 用 ctx.configEditor.configuration() 读取 @deepseek-ai/dsh-llm-pi-ai 的有效配置；
2. 筛出 baseURL 属于 baseURLs 的 provider（https://api.llm.ustc.edu.cn 与 .../v1 视为同一个站点），取 apiKeyEnv；provider id/显示名不参与匹配；
3. 用 ctx.credentials.resolve(apiKeyEnv) 解析 Key（Key 不离开 Host）；
4. 并行查询 GET /key/info 与 GET /user/info；
5. 合并成固定的 3h/12h/24h 三窗口；Host 缓存 8 秒；
6. 通过 GET /plugins/dsh-ustc-quota/snapshot 返回脱敏 JSON。

3h/12h 来自 Key 级 budget_limits / budget_limits_usage；24h 可能来自 Key 级，也可能来自 /user/info 的用户级预算。合并规则和官方 @ustc/tokenworks-usage 一致：先看 metadata.platform_budget_scope，再看 Key 级、用户级和上次成功值。

请求频率：正常 10 秒、重置过渡 8 秒；2 个端点 × 每把 Key，约 12–15 次/分钟/Key，低于平台的 rpm_limit: 20。Host 缓存会对多标签页去重。

运行中新增 Key / Provider

不需要重启，也不需要在插件里重新配置：

• DSH：每次 Host 缓存过期（8 秒）都会重新读取 llm-pi-ai 的有效配置；Client 每 15 秒轮询一次。新加一个 provider + 新凭据引用后，最多约 15 秒出现新行；点卡片右上角的刷新按钮会立即绕过缓存重新发现。
• TokenWorks：插件消费官方 tokenworksUsage 快照，官方服务自己处理登录/换 Key/账号切换，官方缓存约 30 秒；卡片会随快照更新，同样不需要重启。
• 同一个凭据引用仍按一把 Key 处理；要显示成独立一行，请给新 Key 一个不同的 apiKeyEnv（DSH）或让 TokenWorks 切换到新账号。

TokenWorks 路径

Host 检测到 tokenworksUsage 服务后：

tokenworksUsage.snapshot({language})
  → 官方服务从 tokenworksBootstrap 取网关与内存 Key
  → 官方服务查询 /key/info、/user/info 并合并
  → 本插件把快照映射成 3h/12h/24h 卡片

这样 Key 始终只在 TokenWorks Host 内存中，本插件也无需重复实现登录/刷新/退避。

配置

一般情况下不需要配置。自动发现失败，或使用的适配器不是 @deepseek-ai/dsh-llm-pi-ai 时，可以在 profile 的 cordis.patch.yml 里覆盖本插件的 config：

- id: dsh-ustc-quota
  name: dsh-ustc-quota
  config:
    baseURLs:
      - https://api.llm.ustc.edu.cn
    refreshIntervalMs: 10000
    resettingRefreshIntervalMs: 8000
    requestTimeoutMs: 8000
    cacheTtlMs: 8000
    errorCacheTtlMs: 20000
    # 可选兜底：自动发现完全没有结果时才会使用
    providers:
      my-ustc-key:
        apiKeyEnv: MY_USTC_API_KEY
        label: my-key

providers 里的 apiKeyEnv 是凭据引用名（环境变量或 DSH credentials 里的名字），不是 Key 本身。baseURLs 写成 https://api.llm.ustc.edu.cn 或 https://api.llm.ustc.edu.cn/v1 都可以，插件会归一到站点根后再查 /key/info、/user/info。

安全

• Key 只在 Host 内使用：DSH 通过 credentials 解析，TokenWorks 通过官方 tokenworksUsage 读取，二者都不会把 Key 发到浏览器；
• 快照只包含 provider id、显示名、额度数值、重置时间、安全错误码；
• 不转发 key、key_alias、user_email、user_alias、platform_user_id、keys、teams；
• Web host 上路由先过 ctx.connection.requestRejection；官方 Desktop / TokenWorks 窗口从 dsh-app:// 加载，fetch 不一定携带浏览器 session，因此和 dsh-market 一样在 Desktop host 上跳过这道 fence（只读、无 Key 数据，路由仍只绑定 127.0.0.1 Web server）。

已知边界

• /key/info、/user/info 是 USTC LiteLLM 的内部接口，不是公开稳定 API；字段变化时插件显示安全错误，不会崩溃。
• 额度查询接口的 401/403 不等于模型 Key 无效或禁用。 从 v1.1.7 起，卡片显示“额度查询被上游拒绝（401/403）”，不再声称 Key 无效；实测这些 Key 的 /v1/models 仍可返回 200，模型调用可正常，问题在额度/计费查询侧。上游拒绝可能来自该接口的限流或临时故障。
• 从 v1.1.8 起，Key 列会按标签、当前标记和报警点的实际宽度自动扩展；出现红色报警图标时不再把 wmw 之类标签截成 W...。
• 从 v1.1.9 起，更新确认弹窗在“安装更新”前显示红色强制重启警告；安装后若 client 直接 import failed，插件 UI 无法显示任何提示，只能使用 DSH 崩溃对话框的重启/退出。
• 从 v1.1.11 起，这条警告明确说明问题来自 DSH Desktop 0.2.1-rc.3 的 client-modules 增量扫描缓存、当前 DSH 版本仍未确认修复；并且只在“发现新版本”的升级弹窗出现。全新安装不显示该警告，也不需要完全重启。
• 从 v1.1.11 起，警告不再硬编码 rc.4/rc.5 等具体补丁版本：它只提“0.2.1-rc.3 起、当前版本仍未确认修复”。只有 DSH 真正修复该问题时，才需要一次插件更新来移除警告，不需要每次 DSH 发版都改。
• 从 v1.1.12 起，footer 布局会在其他插件新增 action 后重新归一化：本卡片设为 order: 2147483647、独占一行，其他常规 action 尽量留在上面。这是 best-effort；DSH 目前没有共享的 footer layout group，未知插件仍可能用自己的 order/position/!important 破坏排列。
• 从 v1.1.13 起，更新令牌有效期从 5 分钟延长到 30 分钟；点击安装遇到 invalid-update-token 会自动重新检查并重试一次；同一令牌的并发/重复 apply 返回同一结果；插件管理器返回 changed:false 时显示“需要完全退出重开”，不再报 not-changed。
• 从 v1.1.14 起，客户端读取 window.__DSH_BOOT__.release.version：DSH 0.2.2-rc.1 及以上不再显示升级强制重启警告，也不再显示更新后的重启 banner，由 DSH 热重载插件；旧版 0.2.1-rc.3–0.2.1-rc.5 保持原提示。
• 从 v1.1.15 起，分屏视图中的星号跟随当前焦点 pane：每个 conversation.composer.dock 注册隐藏 session marker，按 focusin / pointerdown 和 pane 的 data-focused 解析；共享 split 容器不会误切。dsh-multiview 0.1.4 已验证；其他分屏插件采用同一通用逻辑，best-effort。
• 从 v1.1.15 起，深色主题完全跟随 DSH token：卡片、弹窗、边框、文字和状态色不写死浅色值，警告/重启底色用 color-mix 从 DSH state token 派生；不需要手动开关。
• 从 v1.1.16 起，更新检查优先走 DSH 官方通道：先问宿主 pluginManager.listVersions（只对 npm 安装的副本有效），没结果再回退 GitHub Release；安装动作也优先用 pluginManager.updateBundle，宿主拒绝时回退到 release tarball 的 installBundle，两者都不可用时才显示可复制的安装 spec。插件版本已发布到 npm（dsh-ustc-quota），每个版本由 GitHub Actions 用 OIDC 可信发布自动上传。
• 从 v1.1.17 起，升级后的重启 banner 只在“宿主安装的版本比页面已加载的 client 版本更新”时出现：更新后第一次启动不会再误报“请完全退出并重开”（旧载体 0.2.1-rc.5 上尤其明显），降级时也不会误报。
• 从 v1.1.18 起，更新检查改为 registry 优先、GitHub 回退：GitHub 不可达（或被防火墙阻断）时不再整体失败，只要 listVersions 能给出更新就照常提示；两条通道都不可用才报检查失败。
• 从 v1.1.19 起，卡片标题前增加 TokenWorks 品牌符号：按官方 logo（五个圆角方块组成 T）重绘为 24 viewBox 单色线性图标，颜色继承 currentColor，深浅主题自动适配；固定 15px 宽，不因图标宽度让标题起点漂移。
• 从 v1.1.20 起，标题前图标尺寸对齐 Memory 卡片：13px、strokeWidth 1.6、容器固定 13px；浅色/深色均单色，标题起点不因图标漂移。
• 首次从 v1.1.11/v1.1.12 升级到 v1.1.13–v1.1.20 仍由旧更新器执行。 如果自动更新失败，请在插件页直接安装 github:Awenforever/dsh-ustc-quota#v1.1.20 或 [email protected]；装到新版后，后续自动更新才使用新的令牌/重试逻辑。
• 24h 可能是用户级预算，同一用户多把 Key 会共享；24h 单元格会标注“密钥级 / 用户级 / 上次查询”。
• 12:00 / 00:00 边界上平台可能短暂返回旧用量；插件把过期窗口标成“重置中”，8 秒后重查。
• 额度数值是平台额度单位（当前 3h/12h/24h 为 30/70/100），不是 DSH token 数；插件不擅自换算。
• 侧边栏收起（rail）时卡片隐藏；展开后恢复。
• 底部操作行会换行：TokenWorks 的「更新」、DSH 的 Cordis 按钮保留在上一行，卡片拿下一整行；这是通过折叠只包含本卡片的 slot cell 实现的，不依赖按钮的 id 或顺序。
• 发现只看 baseURL：其他用户即使把 provider id 取成 my-gateway、显示名取成任意文字，只要 baseURL 指向 USTC 网关（带不带 /v1 都行）就会被识别；反过来说，如果用了自定义反代路径，请在 baseURLs 里显式加上。

开发

node --check index.js
node --check quota.js
node --check update.js
node --check client.js
node --test test/quota.test.js test/update.test.js

测试覆盖（31 个 Node 测试）：

• DSH 的 Key 级/用户级窗口合并、重置过渡、超限、缺用量；
• llm-pi-ai 配置发现、兜底、去重；
• TokenWorks 官方快照的窗口映射、同名 Key/账户窗口取约束档、错误缓存和未登录状态；
• 快照不包含 Key、邮箱、alias；
• 版本比较、GitHub release 解析、更新 provider 选择、更新缓存与降级。

更完整的 Windows 原生发布验收矩阵、命令和已知的 DSH client-module 启动限制见 docs/RELEASE_ACCEPTANCE.md。

许可

MIT，见 LICENSE。