token-optimization

令牌优化

概述

减少令牌用量很少只靠一种技巧，而是在合适的层面叠加一系列小幅优化。本技能是一张分诊图：先诊断令牌消耗在哪里（系统提示词、对话历史、工具结果、Agent 循环、输出冗长程度），再指出相应的策略。正确的优化目标是每项任务的令牌数，而非每次请求的令牌数：一次性使用 12k 个令牌的提示词解决问题，胜过需要 30 轮、每轮使用 2k 个令牌的循环。按顺序应用策略：先测量，再缓存，然后压缩、路由，最后精简输出。

何时启用

• ✅ 用户表示遇到上下文限制、账单超出预期或循环缓慢
• ✅ 用户询问如何使用提示词缓存、压缩或扩展思考预算
• ✅ 用户想选择更便宜的模型，或将工作拆分到多个模型
• ✅ Agent 本身发现长时间运行的会话上下文窗口利用率已达到约 70%（经验法则触发阈值；有精确计数时使用精确值，否则使用启发式估算——长时间运行且更需要预留空间的会话应更早触发，短任务则可更晚触发）
• ✅ 正在审查感觉「过于臃肿」的系统提示词、CLAUDE.md 或记忆文件

不要在以下情况启用：

• 主题是某个特定的分词器库（使用 tokenization-* 技能）
• 「令牌」指的是身份验证令牌、JWT、支付令牌或 UI 设计令牌
• 用户只想计算价格（引导其查看提供商的定价页面）

工作流

按以下顺序应用策略。每一层都容易尝试，且彼此独立，因此一旦达到成本或上下文目标，就应停止。

第 1 步 — 测量令牌的消耗位置

开始优化前，先找出成本所在。对于单次请求，在脑中将提示词拆分为以下五个部分并估算各自占比：

部分	包含内容	典型占比
系统／角色	静态系统提示词、CLAUDE.md、AGENTS.md、记忆文件	5 – 40%
工具定义	每轮注入的工具架构	5 – 30%
对话历史	之前的用户／助手轮次	10 – 50%
工具结果	文件读取、搜索输出、命令标准输出	20 – 70%
当前用户消息 + 输出	本轮请求和回复	5 – 20%

启发式估算（无需实际分词器）：

• 英文文本：tokens ≈ words × 1.3
• 代码或混合内容：tokens ≈ chars / 4
• CJK／多字节文本：tokens ≈ chars / 2

准确度约为 ±15%。在 Claude／Anthropic SDK 上下文中，如需精确计数，可在实际调用前使用 SDK 的 count_tokens 端点。如需详细的预算计算（输出倍数、深度层级），请参阅 references/measurement-and-budgets.md。

输出：指出占比最高的 1–2 个部分。应重点关注哪个后续步骤，由这些部分决定。

第 2 步 — 让静态前缀可缓存

重复调用时，收益最大的是提示词缓存：稳定前缀（系统提示词 + 工具定义 + 长篇参考文档）只需哈希一次，在缓存 TTL 内的后续请求中即可重复使用，并享受大幅折扣。要充分利用这一点：

• 将所有稳定内容放在提示词开头，将变化的内容（用户当前的问题、最新的工具结果）放在末尾。缓存查找会匹配完全一致的前缀。
• 在最大稳定内容块的末尾标记缓存断点。在 Anthropic SDK 中，将该前缀最后一个内容块的 cache_control: {type: "ephemeral"} 设为启用状态。
• 确保每次调用的前缀逐字节一致。重新排列工具定义、插入时间戳或打乱记忆文件顺序都会使缓存失效。
• 按固定顺序分组读取，让跨轮次复用的文件内容块命中同一个缓存条目。

当确实需要更改前缀时，切勿原地编辑较早的消息。改为追加一条携带更新后状态的新消息，这样之前每次调用的缓存前缀都仍然有效。

更改	错误做法（破坏缓存）	正确做法（保留缓存）
沙箱 / 权限模式	编辑较早的权限消息	追加一条包含新模式的 role=developer 消息
工作目录	编辑较早的环境消息	追加一条说明 cwd 更改的 role=user 消息
添加工具列表项	重新排列或改写较早的工具定义	在末尾追加；新工具从下一次调用开始缓存
MCP tools/list_changed	在对话中途热重载	将刷新推迟到对话边界，或接受缓存未命中

原地编辑会改写缓存已哈希的字节，导致之后的每次调用都未命中缓存。追加只需消耗新消息的 token。（上文的 role=developer / role=user 等角色名称采用 Anthropic 风格；其他服务商请使用对应的角色类别。）

有关服务商特定的缓存机制（TTL、最小内容块大小、计费行为），请参阅 references/prompt-caching.md。

第 3 步 — 精简始终加载的上下文

CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules 和记忆索引等文件会在每条消息中注入。一个包含 5,000 个 token 的记忆文件，在 100 条消息中就会产生 500,000 个纯额外输入 token。

目标与精简方式：

文件	目标预算	常见冗余内容
顶层指令文件（CLAUDE.md / AGENTS.md）	< 1,500 个 token	重复说明默认设置、冗长的框架列表、段落式示例
记忆索引	< 3,000 个 token	内联内容；每个条目保留一行指针即可
每项技能的指令	< 5,000 个 token	不同技能之间重复的说明

精简规则：

1. 删去默认内容。“你是一个乐于助人的助手”“编写简洁的代码”——模型本来就会做到这些。
2. 合并重叠的条目。“简明扼要” + “不要啰嗦” + “保持回复简短” → 合并为一条。
3. **将示例移至参考资料。**示例会增加始终加载的内容量；将它们放入按需加载的 references/<topic>.md 文件。
4. **使用项目符号，而非段落。**内容更短，也更容易被可靠解析。
5. **移除未使用的 Agent / 技能。**如果某条记忆在两周内都未被引用，可考虑将其移除。
6. **审查 MCP 风格的工具服务。**每个启用的服务都会在每轮对话中注入其工具定义——十个服务各含 5–10 个工具定义，很容易就会造成每轮 5,000 个以上 token 的额外开销。根据实际使用情况审查已启用的列表；在尝试更复杂的优化前，先禁用最近几次会话中未调用过的服务。每个项目启用约 10 个服务是控制开销的实用上限，但能力比数量更重要：任务需要什么就保留什么。如果存在等效的 CLI 二进制文件，优先使用它（例如，使用 gh 而非 GitHub MCP 服务）。

第 4 步 — 压缩对话历史

长会话会不断积累过时的轮次。当历史记录占用主导了第 1 步的统计结果时，应用分层压缩策略：

• 最近 3–5 轮：逐字保留。
• 第 6–10 轮：保留决策和结论，删除中间推理。
• 更早的轮次：每轮用一行概述；但如果某轮的具体推理仍是当前任务的关键依据，则逐字保留。
• 修复后不再需要的失败工具调用：删除失败噪音，保留修复内容。
• 已被编辑取代的大型文件读取：仅保留最终状态。

在任何压缩后的提示词顶部固定主要目标，确保模型在压缩过程中不会忘记目标。绝不要删减系统指令或安全提示头。结构化摘要模板和产物追踪规则，请参阅 references/context-management.md。

抗焦虑校准。 具备上下文窗口感知能力的前沿模型有时会低估剩余上下文，并开始仓促行事——过早总结、走捷径做决定，或在任务中途说“让我完成最后的整理”。请用以下方法应对：

• 长会话期间，尽量远低于窗口上限（例如，在 1M 窗口中为活动上下文预留约 200k 的预算）。这部分余量是供模型保持信心的软缓冲，而非硬性上限；如果任务确实需要更多上下文，可以增加。
• 在压缩快照开头附近加入明确的预算说明（不要放在可缓存的静态前缀中，以免破坏第 2 步的规范）：“上下文预算：剩余约 180k tokens。请继续充分深入地完成任务。”
• 如果任务尚有明显未完成的工作，却发现模型在任务中途出现收尾信号（突然开始总结、说“让我完成最后的整理”），请重申预算，而不是任由模型自行决定。如果收尾是合理的——任务已完成或上下文确实所剩无几——则让它完成收尾。

这是模型侧的行为，而非宿主侧的行为——适用于任何运行具备上下文感知能力模型的宿主。

第 5 步 — 屏蔽冗长的工具观察结果

工具输出是最大且不受限制的 token 来源。将冗长结果替换为观察结果引用，让模型按需重新获取：

• 成功读取文件 → [read src/foo.ts: 312 lines, exports: a,b,c]
• 搜索成功 → [grep "X": 7 hits in 4 files: …]
• 长命令的标准输出 → 保留开头和结尾各 5 行，以及退出代码
• 截图 / 图片 → 调整到任务所需的最低分辨率。对于 UI 截图，1280×720 通常最合适；对于密集文本 / OCR 工作，如果清晰度是关键，则提高到 1920×1080 或更高——完整的 4K 分辨率对于典型 UI 工作来说，所需 token 约多出 5 倍。

这是屏蔽，而非删除：底层文件 / 命令仍可访问，只是模型不必在每一轮都携带这些字节。

第 6 步 — 选择合适的模型

根据任务复杂度匹配模型。每次调用都使用最大模型，是最常见的单一过度支出来源。

任务	建议级别
状态检查、ping、分类、简单查询	最小 / 最便宜级别（例如 Haiku 级）
文件读取、自动补全、lint、格式化、单文件编辑	小型级别
多文件编辑、调试、测试生成	中型级别（例如 Sonnet 级）
架构设计、多步骤规划、深度重构、超长上下文	最高级别（例如 Opus 级）

设置备用链（最高级别 → 中型 → 小型），以应对速率限制或延迟退避。如果可以使用子 Agent，委派范围明确的搜索和文件扫描任务给成本更低的模型子 Agent，并且只将综合结果返回主循环——主循环无需为原始搜索输出付费。

第 7 步 — 减少 Agent 循环开销

每次循环迭代都会重新传输完整的对话上下文。减少迭代次数能带来倍增效果。

• 批量调用工具。 在同一轮助手回复中并行发起相互独立的工具调用，而不是分多轮顺序调用。
• 合并小任务。 在一次迭代中处理 N 个文件，而不是启动 N 次迭代。
• 设置迭代上限。 限制单个失败操作的重试次数（例如，约 5 次），并提供明确的“总结并停止”退出方式，同时为真正需要多步的计划留足执行空间。
• 避免推测性读取。 只读取任务所需的内容，而不是“所有相关内容”。先用 glob/grep 缩小范围，再打开文件。
• 在后台运行长任务。 不要让模型针对耗时数分钟的任务持续轮询；安排唤醒，或使用宿主的后台处理机制。

有关特定平台的模式（Anthropic SDK 中的并行工具调用、Claude Code 中的子 Agent 委派、Codex 中的 Task 工具），请参阅 references/agent-loop-patterns.md。

第 8 步 — 精简输出

输出令牌的定价通常高于输入令牌。可采用以下策略：

• 分级提供详略。 对长篇问题，先提供“精简／适中／详细／详尽”选项；默认采用用户明确暗示的最精简级别。意图不明确时，宁可提高一个级别，也不要回答不足。
• 删去填充语，保留背景信息。 跳过纯粹的开场白（“当然，以下是……”“好问题！”）。用一行说明背景（“已将 X 更新为 Y，因为 Z”）没有问题，而且通常很有帮助——目标是删去填充语，而不是剥离上下文。
• 面向机器的结构化输出。 JSON／工具调用架构通常比等效的散文更简短，也无需填充语。
• 停止序列。 如果已知终止符能界定有用输出，就设置它；模型到达后便会停止生成。
• 限制思考预算。 对于支持扩展思考的模型，设置明确的思考预算（例如，常规任务为 1k–4k 个令牌；仅为真正困难的问题预留更大的预算）。

有关详略分级模板、过渡短语删减清单、停止序列指南和思考预算校准表，请参阅 references/output-and-verification.md。

第 9 步 — 验证优化效果

在宣布成功之前，使用第 1 步中的相同分类重新测量，并报告变化：

Before: input=N1, output=M1, est cost C1
After:  input=N2, output=M2, est cost C2
Delta:  -X% input, -Y% output, -$Z per call

如果变化可以忽略不计，说明占主导的分类与优化目标不同——请使用新的测量结果返回第 1 步。

有关完整的重新测量模板（包括用于跟踪多轮优化的 CSV 版本）、变化可忽略时的故障排查矩阵、每个任务与每次调用的令牌数验证方法，以及“何时可以结束优化”的退出条件，请参阅 references/output-and-verification.md。

预期范围。 请将其作为校准参考，而非保证值：

• 压缩：减少 50–70%，质量损失低于 5%。
• 遮蔽：遮蔽观测内容减少 60–80%。
• 前缀缓存命中率：稳定工作负载下 ≥ 70%。

如果你的变化幅度处于这些范围的上限，说明对于典型工作负载，该策略已进入收益递减区间——要进一步提升，应叠加多种策略，而不是继续加大单一措施的力度。

跨 Agent 调用

上述技巧与 Agent 无关；应用这些技巧的命令因宿主运行时而异。使用此表将技巧转换为当前宿主对应的操作。

技巧	Claude Code	Codex CLI	Cursor	Gemini CLI	Copilot CLI
重置上下文（第 4 步）	/clear	/clear	新建聊天	/clear	新建会话
手动压缩（第 4 步）	/compact	仅手动摘要	不适用	不适用	不适用
自动压缩阈值（第 4 步）	CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=<pct>（环境变量）	不适用	不适用	不适用	不适用
切换模型（第 6 步）	/model sonnet|opus|haiku	--model <id> 标志	模型选择器	/model <id>	--model <id>
子 Agent／委派模型（第 6 步）	CLAUDE_CODE_SUBAGENT_MODEL=<id>（环境变量）	每个 Task 的模型参数	不适用	子 Agent 配置	不适用
限制思考预算（第 8 步）	MAX_THINKING_TOKENS=<n>（环境变量）	推理力度标志	不适用	思考配置	不适用
检查 Token 消耗（第 1、9 步）	/cost	会话页脚	状态栏	/stats	gh copilot usage
前缀缓存（第 2 步）	自动 + cache_control SDK 标志	对完全相同的前缀自动生效	自动	隐式上下文缓存	通过提供方

说明：

• 环境变量适用于宿主运行时的设置文件（例如，Claude Code 的 ~/.claude/settings.json 中的 env 区块）。其他宿主有各自的设置位置。
• n/a 表示该功能目前未在该宿主的 CLI 界面中提供——但通过直接使用提供方 SDK，底层技巧仍可能适用。
• MCP 风格的工具服务在所有支持它们的宿主上，每次都会占用工具定义 Token。启用的服务数量应适度（每个项目约 10 个是合理的工作上限）；更广泛的指令文件精简方法请参见第 3 步。

规则

硬性规则（绝不可违反）：

• 压缩期间绝不删减系统指令、安全标头或合规文本——因上下文丢失而导致的越狱是真实风险。
• 绝不意外使稳定前缀失效（例如，在开头注入时间戳或随机 ID）。如果某个值必须随每次调用变化，请将其放在末尾。
• 优化目标是每项任务的 Token 数，而不是每次请求的 Token 数。不要因为每次调用节省了 30%，却导致循环次数变为五倍，就对此感到满意。
• 如果删除某条指令会改变用户可见行为，就不要仅仅因为模型“应该知道”而将其删除。请用真实示例验证。

偏好（可覆盖）：

• 按列出的顺序应用技巧；达到目标后立即停止。
• 优先使用引用获取（模型可重新读取的文件路径），而不是内联倾倒大量内容。
• 对于重复调用，优化可缓存前缀通常胜过任何其他单一改动。
• 如果不确定该选哪种技巧，请选择能缩短提示词开头的技巧（有利于缓存），而不是缩短末尾的技巧。

输出

此技能生成诊断结果和按优先级排列的技巧列表，而不是机械式改写。预期交付内容包括：

1. 对当前 Token 用量进行分桶测量（第 1 步）。
2. 从第 2 至第 8 步中，挑选最有可能影响主要用量类别的 2–3 种技巧。
3. 提出具体的编辑建议（系统提示词差异、缓存断点位置、模型路由规则等），供用户接受或拒绝。
4. 应用更改后重新测量（第 9 步）。

抽象的使用方是承载此会话的任意 Agent 运行时（Claude Code、Codex、Cursor、Gemini CLI、Copilot）。引用提供方专属功能（cache_control、思考预算、子 Agent）的技巧，会在参考文件中标注相应的提供方。

渐进式披露

详尽内容位于子文件夹中，仅在需要时加载：

• references/measurement-and-budgets.md — 在步骤 1 中加载。启发式估算与精确估算、基于复杂度的 输出乘数、深度层级计算。
• references/prompt-caching.md — 在步骤 2 中加载。缓存断点的放置、TTL、最小块大小、 失效触发条件、缓存未命中的调试。
• references/context-management.md — 在步骤 3–5 中加载。附带示例的精简规则、用于压缩的结构化 摘要模板、观察内容掩蔽模式、图像分辨率指南。
• references/agent-loop-patterns.md — 在步骤 6–7 中加载。模型路由决策表、并行 工具调用模式、子 Agent 委派、迭代次数上限、后台 任务模式。
• references/output-and-verification.md — 在步骤 8–9 中加载。深度层级选择模板 + 默认层级 启发式、衔接短语剔除清单、结构化输出经验法则、 按使用场景整理的停止序列手册、思考预算 校准表、重新测量模板（含 CSV 变体）、 可忽略差异的故障排查矩阵、“何时可判定 优化完成”的退出条件。

v1 不附带 assets/ 或 scripts/。Token 估算采用启发式方法， 并在正文中说明；如果后续项目需要精确计数，可直接调用宿主 提供商的 count_tokens 端点。

正文预算

软性目标——不是硬性上限。若主题确实需要，可扩充正文；将超出 部分移至 references/<topic>-extras.md，而不是删减关键信息。

• description：agentskills.io 规范将其限制为 1,024 个字符；这是外部硬性限制，而非软性目标。
• 正文：以约 500 行 / 约 5,000 个 token 为宜，便于阅读。
• 文件总大小：控制在约 30,000 个字符以下，确保重新渲染为 Copilot 自定义 Agent 时，正文仍能正确解析。