---
url: /wave-agent/specs/ui/context-usage-indicator.md
description: >-
  输入工具栏的上下文用量指示器：圆环 + 百分比、悬停气泡说明、纯展示元素不进 Tab 序、用量为 0 或未推送时整块不渲染；三端（desktop /
  VSCE / JetBrains）共用
---

# 功能规格说明：上下文用量指示器

> 本规格描述聊天输入工具栏上的上下文占用展示，三端共用同一实现。压缩本身见 [message-compact.md](../core/message-compact.md)。

## 用户场景与测试

### 用户故事：上下文用量指示器（优先级：P2）

作为用户，我希望在输入工具栏看到当前上下文已用百分比（圆环进度 + 数字），以便了解上下文占用情况并在接近上限时通过 `/compact` 主动压缩。

**为什么是这个优先级**：压缩是 CLI 已有能力（`/compact` 命令与自动压缩），webview 需新增用量推送与展示，是批次 2 的原型功能之一；用量展示为纯展示元素（非按钮、无点击行为），压缩入口不依赖该元素。

**独立测试**：三端（desktop/VSCE/JetBrains）打开会话并发送消息后验证工具栏出现上下文用量指示器与百分比；悬停指示器弹出含「上下文」字样的气泡（与「发送/停止」同一种气泡）；指示器非按钮（不在 Tab 序、点击无行为）；输入 `/compact` 触发压缩并在完成时更新百分比；欢迎页（新会话未发送消息）验证指示器不显示；用量为 0 或宿主尚未推送用量时验证指示器整块不渲染（工具栏无占位、不出现空提示框）。

**验收场景**：

1. **假设**会话已开始（非欢迎页）且输入工具栏可见，**当**用户查看工具栏，**则**权限模式按钮左侧必须显示「上下文用量」指示器（**用量为 0 时整块不渲染**，与「宿主尚未推送用量」同语义，见场景 4），视觉形态为圆环进度图标 + 百分比数字（对齐原型，如仅显示「24%」，环的填充比例与百分比一致）；**悬停**指示器必须弹出设计系统统一的气泡提示（复用 `Tooltip` 组件、`role="tooltip"`，与「发送/停止」同一种气泡，贴指示器上方弹出），文案为「上下文已使用 24%」——点明该数字是**上下文用量**，同一文案同时作为 `aria-label` 供屏幕阅读器读取；指示器本体为纯展示元素（`span`，非按钮），不在 Tab 序中、点击无任何行为，气泡仅随鼠标悬停出现、不引入新的可聚焦控件。
2. **假设**用户需要手动压缩上下文，**当**用户在输入框输入 `/compact` 并确认时，**则**触发与 CLI 等效的上下文压缩（压缩入口为斜杠命令与自动压缩，不依赖工具栏指示器）；压缩完成后指示器百分比随最新用量更新。
3. **假设**会话处于欢迎页（新对话未发送消息），**当**用户查看输入区，**则**不得显示上下文用量指示器（对齐原型：仅非欢迎态显示）。
4. **假设**宿主尚未推送用量信息，**当**会话内容渲染完成，**则**不得渲染上下文用量指示器——圆环、百分比数字、气泡与 `aria-label` 一并消失，工具栏不留占位、不出现空提示框（**用量为 0 时同样整块不渲染**：0 是宿主可达值，用量按 `Math.round(tokens / max × 100)` 计算（`packages/code/src/stdio/agentBridge.ts`），极低占用即得 0；2026-09-16 拍板：`0` 与「未知」同语义，取代此前「未推送用量 → 显示空圆环」的写法）；收到用量推送后显示圆环填充与百分比及对应气泡文案。
5. **假设**会话上下文用量随对话增长，**当**用量推送到达，**则**指示器百分比实时更新（含压缩后回落）。
6. **假设**用户切换到已有上下文用量的历史会话，**当**会话恢复完成，**则**指示器显示该会话上次的用量百分比（对齐 CLI：用量随会话恢复加载，无需等待新一轮对话或新消息）。
7. **假设**宿主 Webview 被重建（窗口重载、面板重新打开），**当**会话内容重新渲染完成，**则**指示器同样立即显示该会话的用量百分比（重建不产生新的用量推送，宿主在会话内容拉取时一并取回百分比并补发）。

## 边界情况

## 非目标（明确排除）

* **上下文压缩的自动触发**：压缩仅由用户点击按钮或 `/compact` 命令触发，不引入自动压缩策略；用量百分比仅展示，不做压缩建议弹窗。