---

name: manage-token-budget description: > 监控、上限控制并从智能体系统的上下文积累中恢复。涵盖每次循环的成本追踪、 上下文窗口审计、带执行策略的预算上限、接近限制时的紧急修剪，以及集成 渐进式披露以最小化路由时的 token 消耗。适用于运行长时间智能体循环 （心跳、轮询、自主工作流）、上下文窗口在循环间不可预测地增长、API 成本超出预期基线、设计需要从一开始就有成本护栏的新智能体工作流， 或成本事件发生后的事后分析时。 locale: zh-CN source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: general complexity: intermediate language: multi tags: token-management, cost-optimization, context-window, budget, progressive-disclosure

管理 Token 预算

通过追踪每次循环的 token 使用量、审计上下文空间消耗、执行预算上限、在压力下修剪低价值上下文，以及在加载完整流程之前通过元数据路由，来控制智能体系统的成本和上下文占用。核心原则：上下文窗口中的每个 token 都应该赚得它的位置。为决策提供信息的 token 留下；占用空间但不影响输出的 token 被修剪。

社区案例：一个 37 小时的自主会话花费 13.74 美元，原因是 30 分钟的心跳间隔加上冗长的系统指令和不受控制的上下文积累。修复方案是将心跳改写为 4 小时间隔，切换到仅通知模式，并从循环中消除订阅浏览。此技能固化了防止此类事件的模式。

适用场景

• 运行长时间智能体循环（心跳、轮询周期、自主工作流），成本随时间复利增长
• 上下文窗口在执行循环间不可预测地增长
• API 成本超出预期基线，需要事后分析
• 设计新的智能体工作流并希望从一开始就内置成本护栏
• 成本事件发生后审计出错原因并防止再次发生
• 系统提示、记忆文件或工具模式变得足够大，主导了上下文窗口

输入

• 必需：要预算的智能体系统或工作流（运行中或计划中）
• 必需：预算上限（每个周期的美元金额，或每次循环的 token 限制）
• 可选：当前成本数据（API 日志、计费仪表板导出）
• 可选：目标模型的上下文窗口大小（默认：查阅模型文档）
• 可选：可接受的降级策略（达到限制时可以丢弃什么）

步骤

第 1 步：建立每次循环的成本追踪

在每个执行边界记录 token 使用情况的智能体循环工具。

对于每次循环（心跳、轮询、任务执行），捕获：

1. 输入 tokens：系统提示 + 记忆 + 工具模式 + 对话历史 + 新用户/系统内容
2. 输出 tokens：模型响应（包括工具调用）
3. 总成本：输入 tokens × 输入价格 + 输出 tokens × 输出价格
4. 循环时间戳：循环运行的时间
5. 循环触发：什么触发了它（定时器、事件、用户操作）

将这些存储在结构化日志中（JSON lines、CSV 或数据库）——而非上下文窗口本身：

{"cycle": 47, "ts": "2026-03-12T14:30:00Z", "trigger": "heartbeat",
 "input_tokens": 18420, "output_tokens": 2105, "cost_usd": 0.0891,
 "cumulative_cost_usd": 3.42}

若系统没有工具，从 API 计费估算：

• 总成本 / 循环次数 = 每次循环平均成本
• 与预期基线对比（模型定价 × 预期上下文大小）

预期结果： 显示每次循环 token 数量和成本的日志，足够细粒度以识别哪些循环昂贵及原因。日志本身位于上下文窗口之外。

失败处理： 若无法获得精确 token 数量（某些 API 不返回使用元数据），使用计费仪表板推导平均值。即使是粗略追踪（每日成本 / 每日循环次数）也能揭示趋势。若完全无法追踪，进入第 2 步从上下文审计入手——你可以从上下文大小估算成本。

第 2 步：审计上下文窗口

测量上下文窗口中消耗了什么，并按大小排名消耗者。

将上下文分解为其组成部分并测量每个：

1. 系统提示：基础指令、CLAUDE.md 内容、个性指令
2. 记忆：MEMORY.md、通过自动记忆加载的主题文件
3. 工具模式：MCP 服务器工具定义、函数调用模式
4. 技能流程：为活跃技能加载的完整 SKILL.md 内容
5. 对话历史：当前会话中的先前对话轮
6. 动态内容：当前循环中的工具输出、文件内容、搜索结果

生成上下文预算表：

Context Budget Audit:
+------------------------+--------+------+-----------------------------------+
| Component              | Tokens | %    | Notes                             |
+------------------------+--------+------+-----------------------------------+
| System prompt          | 4,200  | 21%  | Includes CLAUDE.md chain          |
| Memory (auto-loaded)   | 3,800  | 19%  | MEMORY.md + 4 topic files         |
| Tool schemas           | 2,600  | 13%  | 3 MCP servers, 47 tools           |
| Active skill procedure | 1,900  |  9%  | Full SKILL.md loaded              |
| Conversation history   | 5,100  | 25%  | 12 prior turns                    |
| Current cycle content  | 2,400  | 12%  | Tool outputs from this cycle      |
+------------------------+--------+------+-----------------------------------+
| TOTAL                  | 20,000 | 100% | Model limit: 200,000             |
| Remaining headroom     |180,000 |      |                                   |
+------------------------+--------+------+-----------------------------------+

标记相对于其决策价值不成比例大的组件。当前任务从未引用的 4,000 token 记忆文件是纯开销。

预期结果： 排名表格，显示每个上下文消耗者、其大小和占窗口的百分比。至少一个组件将作为减少候选脱颖而出——最常见的是对话历史或冗长的工具输出。

失败处理： 若无法获得每个组件的精确 token 数量，使用字符数 / 4 作为英文文本的粗略近似。对于结构化数据（JSON、YAML），使用字符数 / 3。目标是相对排名，而非精确测量。

第 3 步：设置带执行策略的预算上限

定义硬限制和软限制，并指定达到每个限制时会发生什么。

1. 软限制（警告阈值）：通常为硬限制的 60-75%。触发时：

   • 记录带当前使用量和剩余预算的警告
   • 对最低价值上下文开始自愿修剪（第 4 步）
   • 若适用则降低循环频率（例如心跳间隔从 30 分钟到 2 小时）
   • 以降级上下文继续操作

2. 硬限制（停止阈值）：绝对最大支出或上下文大小。触发时：

   • 立即停止自主操作
   • 向人工操作员发送警报（通知、邮件、日志条目）
   • 保存当前状态摘要以便恢复
   • 在人工审查和授权之前不开始另一个循环

3. 每次循环上限：任何单次循环的最大 token 或成本。防止单个失控循环消耗整个预算：

   • 若循环会超过上限，截断工具输出或跳过低优先级操作
   • 记录截断以供事后分析

在工作流配置中记录上限：

token_budget:
  soft_limit_usd: 5.00        # warn and begin pruning
  hard_limit_usd: 10.00       # halt and alert
  per_cycle_cap_usd: 0.50     # max per individual cycle
  soft_limit_pct: 70           # % of context window triggering pruning
  hard_limit_pct: 90           # % of context window triggering halt
  enforcement: strict          # strict = halt on hard limit; advisory = log only
  alert_channel: notification  # how to notify the operator

预期结果： 在三个级别（软限制、硬限制、每次循环）有记录的预算上限，每个都有明确的执行操作。策略回答"达到限制时会发生什么？"在达到限制之前。

失败处理： 若设置精确美元限制为时过早（成本状况未知的新工作流），先仅设置上下文百分比限制（软限制 70%，硬限制 90%），在 24-48 小时的成本追踪数据后添加美元限制。在校准期间，建议模式（记录但不停止）是可接受的。

第 4 步：实施紧急修剪

接近限制时，系统性地丢弃低价值上下文以保持在预算内。

修剪优先顺序（先丢弃最低价值的）：

1. 旧工具输出：来自已做出决策的先前循环的冗长搜索结果、文件内容或 API 响应。决策持续存在；证据可以丢弃。
2. 冗余对话轮：被后来的修正或改进所取代的早期轮次。若第 3 轮要求 X，第 7 轮将其修改为 Y，第 3 轮是多余的。
3. 冗长格式：工具输出中的表格、ASCII 艺术、装饰性标题。用一行描述输出包含的内容来替代。
4. 已完成子任务的上下文：对于多步骤任务，已完全完成且输出已在摘要或文件中捕获的子任务上下文。
5. 不活跃的技能流程：若某技能是为先前步骤加载的但不再被遵循，其完整流程文本可以丢弃。
6. 与当前任务无关的记忆部分：关于不相关项目或过去会话的自动加载记忆。

对每个修剪的项目，保留一行墓碑：

[PRUNED: 2,400 tokens of npm audit output from cycle 12 — 3 vulnerabilities found, all patched]

墓碑花费约 20 个 token，但保留了与决策相关的结论。

预期结果： 修剪后上下文窗口使用量降至软限制以下。每个修剪的项目都有保留其结论的墓碑。没有关键决策信息丢失——只有已做决策背后的证据。

失败处理： 若修剪到第 4 优先级后使用量仍超过软限制，工作流从根本上对当前循环频率来说上下文太重。向人工操作员升级："在修剪后上下文使用量为 N%。选项：(a) 增加循环间隔，(b) 减少每次循环范围，(c) 拆分为子工作流，(d) 接受更高成本。"

第 5 步：集成渐进式披露以加载技能

在加载完整技能流程之前通过注册表元数据路由——在路由上花费 token，而非在阅读上。

该模式：

1. 先路由：当任务需要技能时，从 _registry.yml 读取技能的注册表条目（id、描述、领域、复杂度、标签）——大约 3-5 行，约 50 个 token
2. 确认相关性：注册表描述是否符合当前需求？若不，检查下一个候选。每次未命中花费约 50 个 token，而非加载错误 SKILL.md 的约 500-2000 个 token
3. 匹配时加载：仅在注册表条目确认相关性时，加载完整的 SKILL.md 流程
4. 使用后卸载：技能流程完成后，完整文本可以修剪（第 4 步，优先级 5）——只保留完成内容的摘要

对其他大型上下文有效载荷应用相同模式：

• 记忆文件：先读取 MEMORY.md 索引行；仅在主题相关时加载主题文件
• 工具文档：使用工具名称和一行描述路由；仅为正在调用的工具加载完整模式
• 文件内容：先读取文件列表和函数签名；仅为正在修改的函数加载完整文件内容

不使用渐进式披露：
  加载 5 个候选技能 → 5 × 1,500 tokens = 7,500 tokens → 使用 1 个技能

使用渐进式披露：
  通过 5 个注册表条目路由 → 5 × 50 tokens = 250 tokens
  加载 1 个匹配技能 → 1 × 1,500 tokens = 1,500 tokens
  总计：1,750 tokens（减少 77%）

预期结果： 技能加载遵循两阶段模式：通过元数据进行轻量级路由，然后仅在确认匹配后完整加载。相同模式应用于记忆、工具模式和文件内容（在适用时）。

失败处理： 若注册表元数据不足以路由（描述太模糊，标签缺失），改进注册表条目而非放弃渐进式披露。修复方案是更好的元数据，而非更多的上下文加载。

第 6 步：设计成本感知的循环间隔

根据成本数据设置执行间隔，而非任意计划。

1. 计算当前循环间隔的每小时成本：

   • cost_per_hour = avg_cost_per_cycle × cycles_per_hour
   • 示例：每小时 2 次循环，每次循环 $0.09 = 每小时 $0.18 = 每天 $4.32

2. 与预算对比：

   • hours_until_hard_limit = (hard_limit - cumulative_cost) / cost_per_hour
   • 若 hours_until_hard_limit < 预期运行时间，延长循环间隔

3. 确定最小有效间隔：

   • 被监控系统中变化的最快速率是多少？若数据源每 4 小时更新一次，每 30 分钟轮询会浪费 7/8 的循环
   • 将循环间隔与数据的刷新速率匹配，而非对错过事件的焦虑
   • 对于事件驱动的系统，尽可能用 webhook 或推送通知替代轮询

4. 应用间隔：

之前：30 分钟心跳，冗长处理
  → 每天 48 次循环 × $0.09/循环 = 每天 $4.32

之后：4 小时心跳，仅通知
  → 每天 6 次循环 × $0.04/循环 = 每天 $0.24
  → 减少 94% 成本

预期结果： 循环间隔由成本数据证明合理，并与被监控系统的刷新速率匹配。间隔-成本权衡已记录，以便未来调整有基准。

失败处理： 若系统需要低延迟响应且无法承受更长间隔，改为降低每次循环成本（更小的系统提示、更少的工具模式加载、摘要历史）。预算方程有两个杠杆：频率和每次循环成本。

第 7 步：验证预算控制

确认所有控制都在工作，系统在预算内运行。

1. 追踪验证：运行 3-5 次循环，验证每次循环日志记录了准确的 token 数量
2. 软限制测试：临时降低软限制，验证警告触发且修剪开始
3. 硬限制测试：临时降低硬限制，验证系统停止并发出警报
4. 每次循环上限测试：注入大型工具输出，验证它被截断而非超出上限
5. 渐进式披露测试：追踪技能加载序列，确认它在加载完整 SKILL.md 之前通过注册表路由
6. 成本预测：从验证数据，预测：
   • 当前设置下的每日成本
   • 当前消耗速率下到达硬限制的天数
   • 预期月度成本

Budget Validation Report:
+-----------------------+----------+--------+
| Check                 | Expected | Actual |
+-----------------------+----------+--------+
| Per-cycle logging     | Present  |        |
| Soft limit warning    | Fires    |        |
| Hard limit halt       | Halts    |        |
| Per-cycle cap         | Truncates|        |
| Progressive disclosure| Routes   |        |
| Daily cost projection | < $X.XX  |        |
+-----------------------+----------+--------+

预期结果： 五个控制（追踪、软限制、硬限制、每次循环上限、渐进式披露）全部验证工作正常。成本预测在预期预算内。

失败处理： 若控制未触发，检查执行机制是否接入了实际执行循环，而非只是记录在文档中。没有执行的配置只是计划，不是控制。若成本预测超出预算，返回第 6 步调整循环间隔或每次循环成本。

验证清单

• 每次循环成本追踪为每次循环记录输入 tokens、输出 tokens、成本和时间戳
• 上下文窗口审计识别所有消耗者及大致 token 数量和百分比
• 预算上限在三个级别定义：软限制、硬限制和每次循环上限
• 每个上限都有明确的执行操作（警告、修剪、停止、警报）
• 紧急修剪遵循优先顺序并保留墓碑
• 渐进式披露在加载完整内容之前通过元数据路由
• 循环间隔由成本数据证明合理，并与被监控系统的刷新速率匹配
• 验证测试确认所有控制正确触发
• 成本预测在定义的预算内
• 事后分析：已识别根本原因，有具体的预防措施

常见问题

• 在上下文窗口中追踪：将每次循环日志存储在对话历史中会膨胀你试图控制的东西。在外部记录（文件、数据库、API），上下文中只保留当前摘要。
• 没有执行的软限制：没有人看到的警告不是控制。软限制必须触发可见操作——修剪、间隔延长或操作员通知。若系统可以静默超过软限制，它就会这样做。
• 在决策之前修剪数据：在决策做出之前丢弃工具输出会丢失信息。在告知决策的证据被使用之后修剪，而非之前。墓碑模式在丢弃证据的同时保留结论。
• 将循环间隔与焦虑匹配，而非数据刷新：每 30 分钟轮询一个每 4 小时更新的源会浪费 87.5% 的循环。在设置间隔之前测量数据源的实际刷新速率。
• 为路由加载完整技能：读取 400 行 SKILL.md 以决定"这是正确的技能吗？"比读取 3 行注册表条目贵 10-20 倍。先通过元数据路由；仅在确认匹配后加载流程。
• 忽略系统提示：系统提示、CLAUDE.md 链和自动加载的记忆是不可见的成本——它们在每次循环都会支付。一个 5,000 token 的系统提示在每天 48 次循环的循环中，仅指令就花费每天 240,000 个输入 tokens。先审计和裁剪这些。
• 没有人工升级的预算上限：达到预算限制并静默降级（而非警报人工）的自主系统可能积累损害。硬限制必须包含人工通知渠道。

相关技能

• assess-context — 评估推理上下文的结构健康；补充第 2 步中的上下文窗口审计
• metal — 从代码库提取概念本质；渐进式披露模式适用于 metal 的探勘阶段
• chrysopoeia — 价值提取和死重量消除；在代码层面应用相同的每 token 价值思考
• manage-memory — 组织和修剪持久化记忆文件；直接减少上下文预算的记忆组件