# 领域词汇

本文件只定义术语。不写实现方式、不写文件结构、不写待办。

## 核心概念

### 项目 Project

一个工作目录（cwd）。pi 按 cwd 隔离会话，因此项目是用量归属的天然边界。

项目的身份**由会话自己声明的 cwd 确定**，不由存储位置推断——存储目录名对 cwd 做过有损转义，无法可靠还原。

### 会话 Session

一次连续的 pi 对话。会话属于且只属于一个项目。

会话有起止时间，但**不是**用量的时间单位：一次会话可以横跨多天，其用量按每次模型响应各自发生的时刻计入对应的那一天。

### 用量记录 Usage Record

一次模型响应所消耗的 token。这是本领域**不可再分的最小事实**，携带发生时刻、所属项目与会话、以及产生它的渠道。

## 度量

token 分四类，**它们的经济价值差异极大，任何时候都不应合并成单一总数**：

### input

本次请求中新发送、未命中缓存的 prompt token。

### output

模型生成的 token。含推理（reasoning）token——推理 token 是 output 的子集，不单独计量。

### cacheRead

命中缓存、被复用的 prompt token。单价通常是 input 的几十分之一到百分之一。

### cacheWrite

写入缓存的 prompt token。部分渠道不产生此类 token。

### 新增 token

`input + output`。表示本次交互**真实新产生**的消耗，不含复用部分。是判断"用得多不多"最有意义的量。

### 命中率 Cache Hit Rate

`cacheRead / (input + cacheRead)`。

分母是 prompt 总量。**output 不参与**——它是模型的产出，不属于 prompt，把它算进分母会让这个比率失去含义。

当分母为零（该范围内没有任何 prompt token）时命中率**不存在**，而不是零。

## 计价

### 渠道 Channel

provider 与 model 的组合。计价以渠道为单位——同一个 model 经由不同 provider 使用时，价格可能不同。

### 单价 Rate

每百万 token 的美元价，对 input、output、cacheRead、cacheWrite 四类分别定义。

### 阶梯 Tier

当单次请求的 prompt 量越过某个阈值后改用的另一组单价。

阈值**按单次请求判定，不按任何汇总量判定**——把多次请求的 token 加总后再判断档位，会让本属低档的请求被按高档计价。

阈值的比较量是 input + cacheRead + cacheWrite，**cacheRead 计入其中**。

### 价格来源 Price Source

一个渠道的单价从何而来，四种，可信度依次递减：

1. **手工精确** — 用户为该渠道明确指定的单价
2. **手工通配** — 用户为该 provider 指定的默认单价
3. **目录精确** — pi 维护的模型目录中同 provider 同 model 的单价
4. **借用** — 目录中没有该 provider，转而采用其他 provider 下同名 model 的单价

前三者是**已知**，第四种是**推测**：它假设该渠道按被借用方的价格计费，这个假设可能不成立。

显式配置永远优先于自动推断。

### 金额 Cost

一条记录的 token 数乘以其渠道在当时适用的单价。

多条记录的金额是**各自计算后再相加**，而非汇总后统一计算——因为阶梯按单次请求判定。

一个渠道没有单价时，其金额**不存在**，而不是零。把未知渲染成零，等于把「不知道花了多少」说成「没花钱」。

当一组记录中只有部分渠道有单价时，该组金额是**可计价部分之和**，是一个下界而非真值。

## 维度

### 时间

**筛选器**，不是分组维度。先划定一个时间范围，再在这个范围内观察其余维度。

### 分组维度

项目与模型二者之一。选定其一为主维度后，另一者自动成为其下钻的第一层，会话恒为最末层。两种选择互为镜像。