# 预算管理

管理应用空间的 Token 预算策略，对成员与智能体进行配额管控

## 理解预算如何生效

「预算管理」先创建**预算策略**，再把策略绑定到具体对象，生成各自独立计量的**预算账户**。额度以「千 Token」为单位，1 千 Token = 1,000 Token。

| 概念 | 说明 |
| --- | --- |
| 预算策略 | 额度模板，定义 Token 配额、有效期、重置周期和可选的用量通知 Webhook；同一策略可被多个账户使用 |
| 成员全局预算 | 一名成员绑定一份策略，限制该成员在本应用内所有智能体上的总消耗；一名成员只能有一个全局预算账户 |
| 成员的智能体预算（共享组） | 为一名成员选定一组智能体，这些智能体共享一份额度；同一成员可以创建多组，每组选一个策略；仅在成员的预算弹窗中管理 |
| 智能体预算 | 在智能体页绑定策略，该额度由这个智能体的所有使用者共享 |
| 加油包 | 挂在某个具体账户上的一次性额度，不参与周期重置，用完即止、过期作废；解绑该账户时，其名下的加油包级联作废 |

> **生效规则**
> 
> 一次调用会同时计入成员侧和智能体侧的预算：成员全局预算、命中的成员智能体共享组、智能体预算中，**任一账户耗尽或失效，调用就会被拦截**；没有绑定预算的一侧不限额。

## 创建、编辑与删除预算策略

**功能说明**

「预算管理」页维护当前应用空间的预算策略。列表上方显示「共 N 个策略」，提供「搜索策略名称…」输入框与「创建策略」按钮。表头为：**策略名称 / Token 配额（千）/ 重置周期 / 有效期 / 备注 / 创建时间 / 重置时间 / 操作**。其中「重置时间」表示**下次重置时间**。

每行策略提供「空间成员」「智能体」两个观测链接，详见[查看策略管控账户](#policy-detail)；点击策略名称也会进入管控成员页。

**前置条件**

- 已进入目标应用空间。

**操作步骤（创建策略）**

1. 点击侧边栏「预算管理」。没有策略时显示「暂无预算策略」，并提示「点击「创建策略」添加首个预算策略」。![预算管理页空状态](/docs/images/tenant-portal/17-quota-policies.png)*图 2-23：预算管理页——右上角为「创建策略」按钮。*
2. 点击「创建策略」，在弹窗中填写：字段说明策略名称必填，最多 50 个字符Token 配额（千 Token）必填，必须大于 0；最多 1 位小数，最小 0.1 千 Token（100 Token）；下方实时换算为 Token有效期类型「永久」或「固定时间」；选择固定时间后填写「到期时间」重置周期「不重置 / 每日 / 每周 / 每月」；每周需选择「重置日（星期几，1=周一）」，每月需选择「重置日（每月几号）」备注可选，最多 200 个字符用量通知可选，见下方「配置用量通知」每月重置时，如果当月没有所选日期（如 2 月 31 日），系统会在当月最后一天重置。
3. （可选）开启「用量通知」，配置：每个账户在每个重置周期的每档阈值最多投递一次通知。
  - 「通知 Webhook」：下拉只显示触发规则为「预算配额通知」的 Webhook；没有可用项时，先在 [Webhook 管理](/docs/tenant-portal/webhooks.md#create-webhook)中创建；
  - 「通知阈值（用量百分比）」：1~100 的整数，默认 80；滑块步长 5%，也可以在输入框填写任意整数；设为 100% 表示配额耗尽时通知。
4. 点击「保存」。

**预期结果**：系统提示「策略创建成功」，新策略出现在列表中。

**操作步骤（编辑策略）**

1. 在策略行尾点击「…」→「编辑」。
2. 在「编辑策略」弹窗中修改参数；关闭「用量通知」开关会清空通知设置。
3. 点击「保存」，成功后提示「策略更新成功」。

**操作步骤（删除策略）**

1. 确认策略下已没有任何成员或智能体预算账户；若仍有账户，先在成员页或智能体页逐个解除绑定。
2. 在策略行尾点击「…」→「删除」，在「确认删除策略」对话框中点击「确认删除」。

**预期结果**：系统提示「策略已删除」，策略从列表中消失。

> 预算策略下仍有绑定账户时，后端会拒绝删除并提示「该策略下仍有绑定的配额账户，请先解绑后再删除」。删除策略不可撤销；解绑账户会级联作废该账户下未用尽的加油包，请先评估影响。

## 管理成员预算

**功能说明**

成员预算的入口在[成员](/docs/tenant-portal/members.md)页：目标成员行「…」→「预算管理」。弹窗有两个 Tab：

| Tab | 作用 |
| --- | --- |
| 全局预算 | 限制该成员在本应用所有智能体上的总消耗；一名成员只能绑定一个全局预算策略 |
| 智能体预算 | 给该成员创建一个或多个智能体共享组，每组智能体共享一份额度；与全局预算同时生效 |

成员尚未开通内核主体时，弹窗提示「该成员尚未开通内核主体，无法纳入配额管控」，不能绑定预算。

### 绑定成员全局预算

**前置条件**

- 当前应用空间已创建至少一个预算策略。

**操作步骤**

1. 进入「成员」页，在目标成员行尾点击「…」→「预算管理」，默认显示「全局预算」Tab。
2. 未绑定时，在「搜索策略名称...」中检索并单选目标策略；选项摘要显示「额度 X 千 Token · 重置周期」。列表滚动到底时自动加载更多。
3. 点击「确认绑定」。

**预期结果**：系统提示「绑定策略成功」，弹窗显示一张「全局预算」账户卡片和策略名徽标。卡片中的「本期用量」展示已用 / 总额、剩余额度（含加油包）和下次重置时间；耗尽或失效时显示对应状态徽标。

### 管理账户和加油包

账户卡片右上角「…」（提示「更多操作」）有以下操作：

| 操作 | 行为 |
| --- | --- |
| 发放加油包 | 填写额度（千 Token）、可选的失效时间和备注（最多 200 字）；不填失效时间则永久有效（用完即止） |
| 重置用量 | 将本期已用量立即清零，剩余额度恢复为策略总量；加油包余额不受影响；会记录一条不可撤销的重置流水 |
| 解除绑定 | 解除该账户的配额管控，并级联作废其名下所有加油包；历史流水保留可查 |

**操作步骤（发放加油包）**

1. 在账户卡片右上角点击「…」→「发放加油包」。
2. 在「发放新加油包」弹窗填写「额度（千 Token）」、可选的「失效时间」和「备注」，点击「发放」。
3. 加油包出现在账户卡片中，显示「加油包 · 备注」、用量进度、失效时间或「永久有效」。需要提前作废时点击「撤销」，在「确认撤销加油包」对话框中确认，剩余额度立即作废且不退还。

**预期结果**：系统提示「加油包发放成功」；撤销成功时提示「加油包已撤销」。已用尽的加油包折叠成「已用尽 N 个加油包」，点击「查看」展开。

![发放新加油包弹窗](/docs/images/tenant-portal/35-quota-recharge-dialog.png)

*图 2-29：发放新加油包——填写额度、可选失效时间和备注。*

**操作步骤（重置或解绑）**

1. 在账户卡片右上角点击「…」→「重置用量」或「解除绑定」。
2. 重置时，在「确认重置配额」对话框中点击「确认重置」；解绑时，在「确认解除绑定」对话框中点击「确认解绑」。

**预期结果**：重置成功提示「配额已重置」；解绑成功提示「已解除绑定」，弹窗回到未绑定的策略选择状态。

> 系统不支持直接换绑全局预算：要换策略，必须先解绑再绑定。解绑只作废**当前账户**下的加油包，不影响该成员的智能体共享组预算。

### 创建成员的智能体预算

**操作步骤**

1. 在成员「预算管理」弹窗切换到「智能体预算」Tab。顶部提示：「组内多个智能体共享一份额度；该预算与全局预算同时生效，任一用尽后即不可继续使用。」
2. 点击「新增」，先「选择预算策略」，再多选组内智能体（至少 1 个，最多 1000 个），点击「确认添加」。不要求先绑定全局预算。
3. 新账户显示为「N 个智能体共享」卡片，并列出最多 3 个智能体名称，多出的显示为「+N」。
4. 需要调整组内智能体时，点击卡片右上角「…」→「管理智能体」，在「管理组内智能体」面板中增删并点击「保存」。每组至少保留一个智能体。
5. 同一个「…」菜单也可对整组「发放加油包」「重置用量」「解除绑定」。

**预期结果**：系统分别提示「已添加智能体组预算」「已更新组内智能体」或「已解除该智能体组预算」。解除一组预算会级联作废该组账户下的加油包，但**全局预算不受影响**。

**注意事项 / 异常处理**

- 智能体共享组内的多个智能体共用一份已用量，不是每个智能体各有一份额度。
- 一名成员可以有多个智能体共享组，每组选不同策略；但同一个成员只能有一个全局预算账户。

## 管理智能体预算

**功能说明**

智能体预算的入口在[智能体](/docs/tenant-portal/agents.md)列表：目标智能体行「…」→「预算管理」。绑定后，额度由该智能体的所有使用者共享。

智能体弹窗没有「全局预算 / 智能体预算」Tab，也没有成员的智能体共享组功能；只管理这个智能体自己的预算账户。

**操作步骤**

1. 在智能体列表中打开目标智能体的「预算管理」。
2. 未绑定时，搜索并选择策略，点击「确认绑定」。
3. 绑定后，通过账户卡片右上角「…」执行「发放加油包 / 重置用量 / 解除绑定」，规则与[成员全局预算](#member-quota)一致。

**预期结果**：系统提示「绑定策略成功」，该智能体的全部调用都计入此账户。

**注意事项 / 异常处理**

- 成员侧与智能体侧的账户各自计量，但同时生效：任一侧耗尽都会拦截这名成员对该智能体的调用。
- 成员弹窗中的「智能体预算」指成员的智能体共享组，不是本节所说的智能体自身预算，请按入口区分。

## 查看策略管控账户

**功能说明**

预算策略列表每行提供「空间成员」「智能体」两个只读观测入口：

| 页面 | 摘要与列表 |
| --- | --- |
| 管控成员 | 摘要：每位成员 Token 配额（千）、重置周期、有效期、下次重置；表头：成员 / 作用域 / 使用情况（千Token）/ 状态 / 绑定时间 / 操作 |
| 管控智能体 | 摘要：每个智能体 Token 配额（千）、重置周期、有效期、下次重置；表头：智能体 / 使用情况（千Token）/ 状态 / 绑定时间 / 操作 |

成员页的「作用域」取值为「全局」或「N 个智能体共享」，鼠标悬停共享组可查看智能体名单。同一成员有多个账户时，会显示多行。状态取值为「正常 / 已耗尽 / 已失效 / 获取失败」。

**操作步骤**

1. 在预算策略列表中点击「空间成员」或「智能体」。
2. 查看各账户的使用进度、状态和绑定时间；点击「刷新」获取最新数据。
3. 点击某行「用量明细」，进入账户详情。

**预期结果**：没有账户时显示「暂无管控成员」或「暂无管控智能体」；有账户时显示用量进度条。

**注意事项 / 异常处理**

- 观测页为只读；绑定、解绑和发放加油包请回到成员页或智能体页操作。
- 「管控智能体」只列出在智能体页绑定的账户，不包含成员的智能体共享组。

## 查看用量明细与分析

**功能说明**

账户的「用量明细」页共用一个时间范围筛选（默认近 1 小时），下方有「流水明细 / 用量分析」两个 Tab。

**流水明细**

- 表头：流水时间 / 变动类型 / 变动量（千Tokens）/ 变动后已用（千Tokens）/ 配额上限（千Tokens）/ 智能体ID（成员账户）或身份主体ID（智能体账户）/ 备注；
- 变动类型：消耗、加油包发放、加油包撤销、周期重置、策略变更；
- 成员账户可用「全部智能体」下拉筛选；智能体账户可「按身份主体 ID 筛选」，ID 必须是正整数；
- 点击「导出 CSV」异步导出所选时间范围内的全部流水。导出暂不支持按智能体筛选。

**用量分析**

- 「消耗趋势」图可以切换指标「消耗 Tokens / 调用次数」；
- 成员账户显示「Top 消耗智能体」，智能体账户显示「Top 消耗身份主体」，列包含消耗 Tokens、调用次数、占比；
- 点击排行中的一行，会回填筛选条件并切回「流水明细」。

**预期结果**：导出完成后提示「导出完成，共 N 条流水，已开始下载」。没有数据时显示「暂无流水记录」「当前时间范围内无流水，可尝试扩大时间范围」。

**注意事项 / 异常处理**

- 「用量分析」最多查询 31 天，超过时提示「统计时间范围不能超过 31 天」，请缩小时间范围。