中科大额度卡片 Awenforever/dsh-ustc-quota

dsh-ustc-quota

GitHub · MIT

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

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

- DSH：自动发现所有 baseURL 指向 USTC 网关的 @deepseek-ai/dsh-llm-pi-ai provider，每把 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） |

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

安装

DSH（Web / Desktop）

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

github:Awenforever/dsh-ustc-quota

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

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

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

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

安装完成后刷新一次页面。没有运行 pnpm run dev:web 时，Client bundle 不会自动热替换。

TokenWorks（词元工坊）

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

1. 在左侧栏打开 插件 → 安装插件；
2. 填入 github:Awenforever/dsh-ustc-quota；
3. 按提示重启/刷新词元工坊；
4. 用学校统一身份登录后，卡片会自动出现。

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

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。

显示效果

每把 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% 红色；
- 列头显示重置时刻和倒计时；单元格悬停显示精确时间、数据源和完整数值；
- 额度窗口刚好重置时显示“重置中…”，不会把旧用量当成当前用量；
- 单把 Key 失败只影响该行；有 5 分钟内旧数据时保留 dimmed 数据并标记错误；
- TokenWorks 的官方服务返回错误时，保留上一次有效窗口并显示官方错误文案。

工作方式

DSH 路径

1. 用 ctx.configEditor.configuration() 读取 @deepseek-ai/dsh-llm-pi-ai 的有效配置；
2. 筛出 baseURL 属于 baseURLs 的 provider，取 apiKeyEnv；
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 缓存会对多标签页去重。

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 本身。

安全

- 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 数据，路由仍只绑定本机 Web server）。

已知边界

- /key/info、/user/info 是 USTC LiteLLM 的内部接口，不是公开稳定 API；字段变化时插件显示安全错误，不会崩溃。
- 24h 可能是用户级预算，同一用户多把 Key 会共享；24h 单元格会标注“密钥级 / 用户级 / 上次查询”。
- 12:00 / 00:00 边界上平台可能短暂返回旧用量；插件把过期窗口标成“重置中”，8 秒后重查。
- 额度数值是平台额度单位（当前 3h/12h/24h 为 30/70/100），不是 DSH token 数；插件不擅自换算。
- 侧边栏收起（rail）时卡片隐藏；展开后恢复。
- 该 slot 同时承载 DSH 自带的 Cordis 面板按钮；卡片通过 :has(> [data-ustc-quota-root]) 只让自己的直接父容器 flex-wrap: wrap，在 Cordis 按钮下方获得独立一整行。

开发

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

测试覆盖：

- DSH 的 Key 级/用户级窗口合并、重置过渡、超限、缺用量；
- llm-pi-ai 配置发现、兜底、去重；
- TokenWorks 官方快照的窗口映射、同名 Key/账户窗口取约束档、错误缓存和未登录状态；
- 快照不包含 Key、邮箱、alias。

许可

MIT，见 LICENSE。