dsh-tokenworks-usage

在词元工坊（TokenWorks）的账户弹窗里显示学校网关剩余用量的插件。

它显示什么

点击左下角账户入口（「姓名 · 学校」那一行）弹出的菜单里、「设置」上面，多一条剩余用量折叠条目：

• 收起：一行摘要——约束档（剩余最少、最先耗尽的一档）的剩余，如 3h 剩 ¥12.30。
• 展开：
  • 每档一条进度条（典型 3h / 12h / 24h）：剩 ¥12.30 / ¥50.00 与重置倒计时； 条画的是剩余（越短剩得越少），已用 ≥90% 转告警色；
  • 上游没给窗口内用量的档显示「未提供」；超出上限显示「超出 ¥X / ¥Y」；
  • 短档把额度卡住、长档重置前花不完的「作废额度」，用红斜纹画在剩余段内部（悬停有说明）；
  • 容量限额一行（RPM / 并发 / TPM；显式 null 显示 ∞，缺失显示 —），最后一行是 Key 别名与更新时间。

弹窗每次打开都会取一次新数据（宿主侧 30 秒缓存）。

适用范围

• 给登录了的 TokenWorks 客户端用：Key 是登录后从学校 bootstrap 拉取的个人 Key，与模型请求用的是同一个，插件不需要手填 Key。
• 需要 tokenworks-bootstrap 插件（随 TokenWorks 0.2.4 及以上版本内置）提供运行时服务；未登录、刚启动、服务端撤下时条目暂不显示。
• 通用 DSH（手动填 Key 的 provider）用姊妹插件 @unchen/dsh-ustc-usage。

安装

用 tgz 安装（完全退出应用后执行），再启动应用：

dsh plugin --profile <profile> add <tgz 绝对路径>

发布到 npm 后也可以用：应用里「插件」→ 添加插件 → 填 @unchen/dsh-tokenworks-usage；或命令行 dsh plugin --profile <profile> add @unchen/dsh-tokenworks-usage@<版本>。

升级方式：卸载后装新版。刚发布时镜像源可能尚未同步，安装源选 npm 官方源。

配置（可选）

在 profile 的插件条目里可覆盖：

| 字段 | 默认 | 含义 | | --- | --- | --- | | routeId | ustc-llm | 向宿主取 Key 的路由 ID，与 tokenworks-bootstrap 的路由一致 | | baseURL | https://api.llm.ustc.edu.cn | 学校网关地址；默认强制 https，只允许白名单主机 | | allowInsecureDevelopment | false | 仅本机联调：额外放行回环地址（127.0.0.1 / localhost）与 HTTP |

工作原理

宿主 tokenworks-bootstrap（登录后持有个人 Key，只在内存）
  → 本插件 host 半经 ctx.tokenworksBootstrap.resolveCredential(routeId) 取当前 Key
  → GET {site}/key/info 与 GET {site}/user/info（Bearer Key，site 由 baseURL 派生）
  → 解析、合并、缓存，经插件自建的 Remote 命名空间发给界面

界面侧：账户弹窗是 tokenworks-bootstrap 内部渲染的（没有对外扩展槽位），插件用 MutationObserver 认出弹窗（锚点：弹窗里的「大模型公共服务平台」链接），把折叠 条目插到姓名行之后、「设置」之前，再用 React portal 渲染内容。

• Key 只用于向学校网关发这两个请求，只在内存中传递；界面与错误提示只包含状态文案。
• 探测失败时保留上一次有效数据并标注错误。

已知限制

• DOM 注入与宿主耦合：锚点依赖 tokenworks-bootstrap 的弹窗结构（平台链接、菜单项）； 将来宿主调整弹窗时，条目可能静默消失，需要跟随修复（test/client.test.mjs 的锚点用例按宿主结构写死，宿主变更时一起改）。
• 剩余用量是该 Key 在网关上的口径；同一账号在网页端等处的消耗也计入。
• 上游接口不提供「已用 RPM / 并发」，容量一行只显示限额。
• 作废额度按「重置即回满」估算；缺重置时刻、重置时刻已过、时长写法认不出的档不参与估算。

开发

npm install
npm test        # 构建 + 类型检查 + 单测（44 项）
npm run build   # 只构建

产物 lib/ 不入库；lib/client.js 是 window.__ModuleLoader__ 形态，由 DSH 客户端加载。

单元测试覆盖产物形态、锚点逻辑与 host 半的数据路径；界面与端到端行为在真实应用里验证（登录 → 打开账户弹窗 → 展开条目）。

许可

MIT。界面口径与姊妹插件 dsh-ustc-usage 一致。