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。