TokenMeter 上下文用量

一段会话正在占用多少上下文窗口。

适用场景：在有上下文上限的模型上做聊天界面时。不显示用量的客户端一开始都正常，直到某天开始失败：每一轮都会带上完整历史，请求只增不减，最终超过上限被服务端拒绝。这个组件把这个增长过程显示出来。

快速开始

基础用法

<r-token-meter limit="65536" used="12800"></r-token-meter>

const meter = document.createElement('r-token-meter');
meter.limit = 65536;
meter.used = 41200; // 下一次请求会携带的上下文
meter.spent = 128431; // 整段会话累计计费的 token，可选
composer.append(meter);

进度条填充到 used / limit，并按三档升级：ok、warn（达到上限的 80% 起）、over。level 会反射到宿主元素上，页面可以对同一次升级作出反应：

r-token-meter[level='warn'] ~ .composer-hint {
  display: block;
}

`used` 和 `spent` 是两个数

used：下一次请求会携带的量，是历史，不是整段会话。上限约束的是这个数，进度条画的也是它。
spent：整段会话累计计费的量。它只增不减，也不受窗口大小约束。

截断会话会降低 used，但不影响 spent。只显示其中一个，就只回答了用户两个问题里的一个（「下一条还发得出去吗」和「这段对话花了我多少」）。

没有上限时

limit 未设置或为 0 时，进度条消失，只保留计数，这在窗口大小未知时很有用。

改写标签

<r-token-meter label="上下文" limit="65536" used="41200"></r-token-meter>
<!-- label="" 则只剩计数 -->

API 参考

属性

属性值	属性	类型	默认值	说明
`limit`	`limit`	`number`	`0`	上下文窗口大小（token）。为 0 或缺省时隐藏进度条。
`used`	`used`	`number`	`0`	下一次请求会携带的 token 数。
`spent`	`spent`	`number`	`0`	整段会话累计计费的 token 数。
`label`	`label`	`string`	`'Context'`	读数前缀；设为 `''` 则只剩计数。
`level`	`level`	`'ok' \| 'warn' \| 'over'`	推导得出	窗口的拥挤程度。由组件写入：外部赋值会在下次更新时被覆盖。
`sheet`	`sheet`	`string`	`''`	注入 shadow root 的 CSS。

计数格式便于快速阅读：一千以下显示精确值（847 这样的数字足够短，能一眼读全），一千以上用缩写（41.2k、128k）；128,431 的第三位数字不会改变读者的任何判断。

Part

Part	元素
`meter`	整个元素
`track`	进度条底槽
`fill`	已填充部分
`text`	标签与计数

无障碍

元素始终带有陈述具体数字的 title，因此颜色永远不是唯一载体：进度条变琥珀色是第二重信号，而不是唯一信号。重新设计配色时请保持这一点。

自定义样式

<r-token-meter> 自身暴露了 9 个 CSS 自定义属性，另外还会读取主题里的语义令牌。令牌设在任何能继承到的地方都有效，比如 :root、外层容器，或元素本身：

r-token-meter {
  --ran-token-meter-fill-background: var(--ran-color-bg-subtle);
}

Part：fill · meter · text · track

完整清单见样式令牌；该选哪个令牌见设计系统。

最佳实践

在构造请求的地方更新 used，而不是在渲染流程里：人们信任的那个数，是下一次请求真正会发出去的量。
升级提示放在组件外面。 level="over" 时真正有用的 UI 是一个建议（做摘要、另起会话），那属于应用。
不要给填充加会在主题切换时触发的过渡，详见设计规范。