> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 用量统计

> 按时间、Agent、项目、供应商和模型查看本地用量。

**用量统计** 用来查看 Vibex 已记录的 Agent 用量。它是观测工具，**不是账单页面**——实际价格、额度和发票仍由供应商决定。Vibex 不记录费用，也没有价格字段。

入口：侧栏的 **用量统计** 按钮，或输入框上的 token 圆环（**打开用量统计**）。

## 选择时间范围

工具栏提供四个范围，并据此自动决定分桶粒度：

| 范围       | 含义         | 分桶 |
| -------- | ---------- | -- |
| **今天**   | 按系统时区查看今天。 | 小时 |
| **7 天**  | 最近七天。      | 天  |
| **30 天** | 最近三十天。     | 天  |
| **全部**   | 本地保留的全部记录。 | 月  |

没有可用记录时页面显示空状态，不会把未知值当成零。

## 筛选和分组

可以组合五个筛选器：**Agent**、**模型供应商**、**模型**、**项目**、**会话**。

结果可以按五个维度分组，也就是表格上方的标签：**时间**、**Agent**、**项目**、**模型供应商**、**模型**。

<Note>
  **项目** 维度对应侧栏里的项目，一个项目下可能包含多个工作区。**会话只作为筛选器**，不能作为分组维度。
</Note>

## 读取指标

汇总区显示六个指标：

| 指标              | 含义                                      |
| --------------- | --------------------------------------- |
| **总 Token**     | 各类 Token 的合计。                           |
| **API 请求数**     | 已观测的 API 请求数；适配器不提供逐请求数据时改为显示 **对话轮次**。 |
| **输入** / **输出** | 输入与输出 Token。                            |
| **缓存读取**        | 缓存读取 Token。                             |
| **缓存命中率**       | 缓存读取相对于可计算分母的比例。                        |

分组表的列为：维度名称、**请求**、**总计**、**输入**、**输出**、**缓存**、**命中率**、**最近活动**、**上报覆盖**。

### 上报覆盖的含义

**上报覆盖** 说明这一行的数据可信到什么程度：

| 显示             | 含义                 |
| -------------- | ------------------ |
| **已上报**        | 适配器完整上报。           |
| **由输入 + 输出推导** | 总量由输入加输出推导，而非直接上报。 |
| **部分上报**       | 只上报了一部分。           |
| **未上报**        | 没有数据。              |

鼠标悬停还可以看到更细的分布（complete / partial / baseline only / unreported / unsupported）。

<Warning>
  **不要把 `Not reported` 或 `Partial` 解读为零**，也不要用它推算供应商账单。缺少供应商字段时 Vibex 会保留未知状态，而不是填充猜测值。
</Warning>

## 趋势视图

| 视图     | 说明                                                                                |
| ------ | --------------------------------------------------------------------------------- |
| **趋势** | 堆叠柱状图，可在 **总计** / **输入** / **输出** / **缓存** 之间切换，图例可点击过滤。                          |
| **热力** | 365 天日历热力图，展示每日活动密度；没有年度数据时显示不可用。                                                 |
| **模型** | 按天展示各模型占比（100% 堆叠），取前 10 个模型，其余归入 **其他** 和 **未知**。可在 **对话轮次** 和 **总 Token** 之间切换。 |

刷新期间页面保留上一份结果并标记为过期；加载失败时优先使用上一份权威结果，并提示 **刷新失败，正在显示上次数据**。

## 数据边界

* 用量来自权威运行时记录的 Agent 执行和适配器上报。**权威运行时是统计的权威来源。**
* 用量统计 **不读取**完整提示词、文件内容、终端输出或供应商密钥。
* **移动端不显示用量明细**——移动端的用量页只显示会话数量，并提示 "Usage details are available on the desktop host."
* 单次查询有行数上限（100000 行），超出会返回 `agent_usage_query_too_large`。

导出诊断资料时请遵守[隐私与恢复](/docs/privacy-and-recovery)中的脱敏要求。