额度余量仪表 ShangshanHuiliyi1/dsh-token-gauge

额度 / 上下文余量（@local/dsh-token-gauge）

两处显示，各自独立：

| 位置 | 内容 | 形态 |
| 左侧栏「设置」上方（sidebar.footer.action） | 上次充值后已用额度 ÷ 上次充值后的总额度 | 蓝色进度条卡片 |
| 输入框上方（conversation.input.dock） | 当前会话上下文已用量 | 纯文字，无进度条、无占比、不显示剩余 |

安装

这是一个 DSH bundle（package.json 里声明了 dsh.bundle.patch 与 dsh.client），装进某个 profile 后两端同时生效：Host 半边是空壳，界面全在 Client 半边。

方式一：从仓库安装（公开仓库，无需凭据）

在 DSH 的插件页安装这个仓库地址，或让 Agent 用 install_bundle 指向它：

git+https://github.com/ShangshanHuiliyi1/dsh-token-gauge.git

安装动作会同时写两处，缺一不可：profile package.json 的 dependencies，以及 dsh.profile.bundles（只有列进 bundles 才会被组合加载）。

方式二：本地目录安装

git clone https://github.com/ShangshanHuiliyi1/dsh-token-gauge.git
然后把这个目录作为安装目标（Plugin Manager 的 install_bundle 支持目录路径）

验证：装好后侧栏底部「设置」上方应出现额度卡片；若没有，确认 profile 的 cordis.patch.yml 里有这一行（bundle 自带的 patch 会插入它）：

- insert:
- id: token-gauge
name: '@local/dsh-token-gauge'

依赖：客户端半边声明了 slots、locale、remote、remote.account、remote.session。后两个是点号 Remote 命名空间，Cordis 对未声明的点号服务会抛异常而不是返回 undefined，所以缺账户域（dsh-api-account-controller）的 profile 里这个插件不会激活。

额度进度条（设置上方）

- 分母 = 上一次充值之后账户上的全部剩余额度（余额 + 赠送余额，取账户主币种）。
- 分子 = 上次充值之后到目前为止用掉的额度。
- 充值即重置：只要账户余额比上次采样值变高（> 0.005），就当成一次充值，把当时的余额直接作为新的分母，进度条重新从 0% 开始。
- 悬停卡片可看到精确数字、占比与充值时间；把鼠标停在「已用」或「剩余」的金额上，提示会显示这笔钱相当于多少 tokens（见下）；点击卡片立即刷新余额。
- 填充色用 --dsw-alias-brand-primary（蓝色品牌色），到 75% 转警告色、90% 转错误色。
- 侧边栏折叠成 56px 竖条时，卡片自动收窄为「百分比 + 细进度条」；此时若桌面版把折叠态的底部区域整体隐藏，则不会显示。

为什么它不会压住工作区列表

早期版本把卡片做成「浮在页脚之上」的浮层，会盖住会话/工作区列表的最后几行。现在改成占真实高度：

- 注册项是一个零宽（但 min-height 撑高）的锚点，卡片贴在这段预留空间的底部，位置在 Cordis 徽标与 Settings 行之间；
- 侧栏的 regionArea（列表容器）本身是 flex:1; min-height:0; overflow:hidden，页脚变高它就让出对应高度，所以列表只是变短，不会被覆盖；
- 预留高度可用 CSS 变量调整，不用改代码：--dsh-token-gauge-reserve（展开态，默认 120px = Cordis 行 50px + 卡片约 63px + 间隙）、--dsh-token-gauge-reserve-rail（折叠态，默认 76px）。Cordis 徽标尺寸（height:42px; margin-top:8px）如因版本更新变化，调这两个值即可；
- 卡片保持自然三行高度（数字 / 进度条 / 占比·充值时间）。曾经试过把高度压到 40px 并把占比与充值时间挪进悬停提示，结果进度条被裁掉、时间也不显示，已回退——宁可列表少 60px，也不牺牲这两个读数。

「相当于多少 tokens」是怎么算的

没有硬编码价目表，而是自校准：分子（本次充值后花掉的钱）÷ 同期观察到的计费 tokens = 账户实际均价，再用它换算「已用」和「剩余」两个数字。

- 计费 tokens 取自系统自带的 tokenUsage 投影：session.list 的缓存列已经把每个会话的 uncachedInput + output + cacheRead + cacheWrite 算好，插件只做求和（跨会话，和账户计费口径一致），不折叠日志。
- 充值会同时重置价格窗口的两端（钱和 tokens 都从充值那一刻重新起算）。
- 还没有可测量的消费时，提示会写「暂无法换算成 tokens」，而不是显示 0。
- 因为缓存命中的输入便宜得多，这是一个账户级均价，不是某个模型的标价；把它当量级参考即可。
- 旧版本存下的基准（没有 tokens 字段）会在第一次采样时把当前 tokens 总量作为窗口起点：此前的消费无法再对应到 tokens，所以均价从那一刻开始重新积累。

数据来自已完成注册的账户接口 ctx.remote.account.getBalance（与「设置 → 账户」页同一个调用）。每 2 分钟轮询一次（页面隐藏时跳过），并在窗口重新获得焦点时刷新。

基准值存在浏览器 localStorage（键 dsh.token-gauge.credit），所以刷新页面不会丢失基准。

若读不到余额，卡片会缩成一行文字告诉你原因：「额度不可用」（账号未登录 / 平台暂时不可用）或「额度服务不可用」（界面里没有账户服务）；鼠标悬停还能看到具体的失败代码（例如 gateway/internal: ...）。
实现要点：客户端半边的 inject 必须同时声明 remote 和点号命名空间 remote.account。Cordis 对未声明的点号服务是抛异常而不是返回 undefined，所以只写 remote 时 ctx.remote.account 会直接失败。官方账户插件同样是 ["slots","locale","remote","remote.account","remote.session", ...]。

上下文一行（输入框上方）

直接读 contextPressure 投影的 projectedTokens，显示「上下文已用 ~235.7K tokens」，没有进度条、没有占比、也不显示剩余量；数值带 ~ 是因为它含有启发式估算成分。把鼠标停在这一行上，悬停提示里仍能看到窗口总量与占比（~235.7K tokens / 1.0M (24%)）。

单位文案走 locale（context.unit），中英文都写作 tokens。

已知边界

- 「已用额度」只能靠余额差值推出来：余额下降即视为消费。赠送额度过期等非消费变动也会被算作已用。
- 页面关闭期间的充值：重新打开页面后第一次采样余额变高，会被正确识别为充值（新基准 = 当前余额），但顶部那段时间里已经花掉的部分无法追溯，会从 0 开始重新计。
- 通过 API Key（而非登录账号）计费时账户余额不变，进度条会停在原处。
- 额度单位是账户货币（¥ / $），不是 token 数；token 用量只在上下文那一行体现。
- 卡片固定 216px 宽（侧栏内容宽度 264–420px），在页脚里占真实高度而非浮层，因此不随侧栏拖拽改变宽度、也不会遮住工作区列表。

License

MIT © shangshanhuiliyi