token-optimizer

Token 优化器

一套全面的工具集，可减少 Token 消耗并降低 AI 成本，适用于 Claude Code 用户（文件组织、CLAUDE.md、上下文管理）和 API 开发者（提示词缓存、Batch API、effort 调优、提示词架构）。建议基于真实实验数据和 Anthropic 当前定价。

适用章节：

• 使用 Claude Code？→ 阅读第 1–5 节和快速优化清单。
• 直接调用 Anthropic API？→ 还需阅读 references/api-optimization-guide.md。最大的节省空间就在这里（提示词缓存 = 省 90%，Batch API = 省 50%，可叠加）。

安装

npx skills add amunozdev/token-optimizer

或手动安装：

cp -r token-optimizer ~/.claude/skills/

核心功能

1. 文件组织优化

影响最大的单项优化。小而精简的文件可使 Token 消耗减少 18.2%，并使聚焦任务中的噪声减少 92%（聚焦任务占日常开发工作的多数）。

核心规则：

• 每个文件最多 150 行——超出时按职责拆分
• 单一职责——每个文件只处理一个关注点
• 使用描述性 kebab-case 名称——文件名应让 AI 准确了解文件内容

真实示例： 修复电子邮件验证错误时，在单体文件中需要阅读 814 行（49,466 个 Token），而在模块化结构中只需阅读 67 行（40,447 个 Token）——节省 18.2%，噪声减少 92%。

关于命名规范、应避免／推荐的做法对照表以及项目结构模板，请参阅 references/file-organization-guide.md

2. CLAUDE.md 优化

结构良好的 CLAUDE.md 可减少 50–70% 的 Token 消耗。大多数项目的 CLAUDE.md 都过于臃肿，每次交互都会加载不必要的上下文。

关键原则：

• 控制在 500 行以内——只保留必要内容
• 描述具体——写“PostgreSQL with Prisma”，而不只是“数据库”
• 包含项目结构和命令——避免让 AI 猜测
• 使用触发条件，而非完整文档——详细信息请引用技能／文件，不要把所有内容都内联

可直接使用的优化模板，请参阅 references/claude-md-template.md

3. 上下文管理

Token 浪费通常源于累积了无关上下文，而不是单次操作本身。

常用命令：

命令	使用时机	效果
/clear	切换任务、重大纠正后	完全重置上下文
/compact	对话较长时（>50 轮）	压缩历史记录，保留必要内容
/context	排查 Token 使用量过高的问题	显示 Token 的消耗情况

延迟加载： 不要预先加载所有信息。一个项目通过仅在 CLAUDE.md 中保留触发条件、按需加载详细信息，使初始 Token 减少了 54%（7,584 → 3,434）。

关于高级策略、子 Agent 模式和 MCP 管理，请参阅 references/context-management-guide.md

4. 战略性模型选择

根据任务类型选择合适的模型，是最容易实施的成本优化方法之一。

任务类型	模型	原因
80% 的日常任务	Sonnet	性价比最高
复杂架构设计	Opus	需要更深入的推理
简单／快速任务	Haiku	成本最高可比 Opus 低 18 倍

默认使用 Sonnet。只有面对真正复杂的问题时才切换到 Opus。简单任务、测试和搜索则使用 Haiku。

5. MCP 与子 Agent 优化

MCP 管理：

• 同时最多启用 10 个 MCP（工具总数最多 80 个）
• 停用当前任务不需要的 MCP
• 每个未使用的 MCP 仍会因工具描述而消耗 Token

使用子 Agent 处理冗长任务： 对于会生成大量输出的操作（测试运行、构建、搜索），请使用 Task 工具。冗长输出会保留在子 Agent 的上下文中，主对话中只会返回摘要。

6. 提示词架构（Claude Code 和 API）

提示词的写法会直接、显著地影响令牌用量——无论是增加还是减少。

• 直接表达，把需求放在最前面，只说一次。 重复不会提高遵循度，只会增加费用。
• 明确限制输出。“少于 50 个词”“最多 3 个要点”“使用包含 X、Y、Z 键的 JSON，不要解释。”开放式提示词会产生开放式（且昂贵的）回答。
• 使用 XML 标签（<instructions>、<context>、<output_format>）来减少歧义。
• 只包含相关上下文。 一个函数就够时，不要粘贴 500 行内容。

7. 仅限 API 的优化

如果你直接调用 Anthropic API（SDK、自定义 Agent、生产应用），以下是影响最大的优化手段——使用 Claude Code 时大多用不到，因为运行框架会替你处理。

技术	节省	备注
提示词缓存	缓存读取可节省 90%	缓存写入费用为 1.25 倍，读取费用为 0.1 倍。第 2 次调用即可回本。
批处理 API	所有令牌节省 50%	延迟小于 24 小时。与缓存叠加后，总节省最高可达 95%。
effort: low	大幅减少	对分类／提取任务跳过深入推理。
budget_tokens 上限	按比例减少	对大多数任务来说，8K-16K 已足够。不要为了格式化日期而使用 100K。
预填助手轮次	移除开场白	{"role": "assistant", "content": "{"} 可跳过“当然！以下是……”。
令牌高效工具	平均减少约 14% 输出	Claude 4 中默认启用。对 3.7 添加 token-efficient-tools-2025-02-19 标头。
动态工具加载	随工具数量扩展	每个工具架构都会随每次请求发送。只包含任务需要的工具。
令牌计数端点	调试	在运行推理前获取准确费用。

缓存的重要注意事项：

• 图像会破坏缓存。 在提示词中的任何位置添加或移除图像都会使缓存失效。如果你的流程有时会发送图像，请将其视为单独的请求模式。
• 缓存断点之前的内容必须保持稳定。 时间戳、会话 ID 或放在断点之前的用户消息都会彻底破坏缓存——每次都要支付 1.25 倍的写入附加费，却没有任何读取。
• 并发陷阱。 缓存条目只有在第一个响应开始流式传输后才可用。一次性并行发送 10 个即发即弃请求 → 9 次缓存未命中。先发送一个请求，等待流开始，再分发其余请求。
• 注意每个断点的最低令牌阈值（Sonnet 4.6 为 2,048；Opus 4.6 和 Haiku 4.5 为 4,096）。低于阈值时不会缓存，也不会报错。请检查响应中的 cache_creation_input_tokens。

完整详情、定价计算、TTL 权衡和设置检查清单：references/api-optimization-guide.md

快速优化清单

按影响从大到小依次应用：

1. 先运行 /context → 在进行任何更改前建立基准
2. 拆分大型文件（>150 行），整理成聚焦的模块 → 节省 18% 以上的令牌
3. 优化你的 CLAUDE.md → 可减少 50-70% 的消耗
4. 在任务之间使用 /clear → 清除无关上下文
5. 在较长的对话中使用 /compact → 压缩历史记录
6. 对输出冗长的任务使用子 Agent → 测试输出、构建日志和搜索结果保留在子 Agent 上下文中，不会污染主对话
7. 使用合适的模型 → 日常工作默认使用 Sonnet，简单任务使用 Haiku（比 Opus 便宜 18 倍），只有真正复杂的架构决策才使用 Opus
8. 将活跃 MCP 数量限制在 ≤10 → 每个未使用的 MCP 每轮仍会消耗令牌，因为每次请求都会发送其工具描述
9. 使用 /cost 跟踪费用 → 查看每个会话的花费；配置状态栏以持续显示费用
10. API 用户：启用提示词缓存 → 在系统提示词和工具上设置 cache_control，可让重复输入费用降低 90%；参见 references/api-optimization-guide.md

预期节省

我们使用一个包含 814 行代码的 TypeScript 电商应用进行受控实验，结果如下：

优化项	影响
模块化文件（专注任务）	-18.2% token
减少噪声（处理的行数）	-92%
优化 CLAUDE.md	-50-70% 消耗
延迟加载上下文	-54% 初始 token
Haiku 相较于 Opus（简单任务）	-94% 成本

关键洞察： 专注任务（修复 Bug、特定修改——约占日常工作的 80%）能从模块化代码中获益良多。小规模下，跨领域任务的差异很小（+1-5%），但在代码达到 5,000 行以上时，模块化的优势就十分明显。

关于规模的说明： 这些结果来自一项针对 814 行代码库的受控实验。在更大规模（5,000 行以上）下，模块化架构节省的资源会更加显著，因为单体文件开始触及上下文窗口限制，而模块化文件的大小保持恒定（每个 35-146 行）。

如需查看完整的实验方法和原始数据，请参阅 references/metrics-report.md

诊断工作流

激活后，按以下流程操作：

0. 先进行测量： 始终先让用户运行 /context。没有基准数据，就无法证明优化是否有效。此步骤不可省略。
1. 阅读用户的代码： 在提出任何建议之前，先查看用户的实际文件和项目结构。扫描超过 150 行的文件，检查 CLAUDE.md 的大小，并统计活跃 MCP 的数量。基于实际代码库提出的建议远比泛泛而谈有用。
2. 找出问题： 确定最大的浪费来源（大文件、臃肿的 CLAUDE.md、累积的上下文、MCP 过多）
3. 提出建议： 从快速优化清单中选出影响最大的优化项
4. 验证效果： 修改后，让用户重新运行 /context，衡量改进情况

重要指南：

• 始终先诊断——不要一次性列出所有优化项
• 修改前后都要测量——每项优化都应通过 /context 验证
• 聚焦用户的具体问题——优先找出影响最大的修改
• 坦诚说明权衡——模块化文件可让专注任务节省 18% 以上，但小规模下对跨领域任务影响不大

使用示例

“我的 Claude Code 会话越来越贵”

1. 运行 /context，查看当前 token 消耗明细
2. 检查 CLAUDE.md 的大小——如果超过 500 行，就精简到必要内容
3. 检查超过 150 行的文件——找出适合拆分的文件
4. 统计活跃 MCP 的数量——禁用未使用的 MCP
5. 检查模型使用情况——将常规任务切换到 Sonnet/Haiku

“帮我整理代码库以便 AI 使用”

1. 扫描项目，找出超过 150 行的文件
2. 找出通用文件名（utils.ts、helpers.ts、包含逻辑的 index.ts）
3. 按职责提出文件拆分方案，并提供新的描述性名称
4. 建议采用符合组织指南的项目结构

“我的上下文窗口总是被填满”

1. 运行 /context，找出 token 的消耗来源
2. 检查 CLAUDE.md 中是否有应改为引用其他文件的内联文档
3. 建议在任务之间使用 /clear，并在长会话中使用 /compact
4. 建议将冗长内容移至被引用的文件（延迟加载）

故障排查

问题	原因	解决方案
优化后没有改善	未进行基线测量	每次更改前后都运行 /context
不知道自己用了多少 Token	默认不显示 Token 消耗情况	使用 /context 查看完整明细
/compact 压缩效果不够	会压缩内容，但保留必要信息	如果之前的上下文无关，请使用 /clear
拆分后，跨领域任务变慢	需要多次读取（Token 增加 1-5%）	这是预期的轻微开销——聚焦任务（占工作量的 80%）仍可节省 18% 以上
API：缓存似乎不起作用，每次调用都会写入	断点前的内容每次请求都会变化（时间戳、会话 ID、用户消息），或 Token 数低于最低要求，或图像被添加/移除	检查 cache_creation_input_tokens——将易变内容移到断点之后，并满足各模型的最低要求
API：并行请求都未命中缓存	缓存条目只有在第一个响应开始流式传输后才会存在	先发送第一个请求，等待流式传输开始后，再分发其余请求
API：思考 Token 导致请求成本高昂	默认的 budget_tokens 可能高达数万	将 budget_tokens 限制在 8K-16K，或设置 effort: low，或在格式整理/查询任务中禁用思考

参考资料

• references/file-organization-guide.md — 命名规范、项目结构模板和实现检查清单
• references/context-management-guide.md — 延迟加载、子 Agent、MCP 管理和模型选择策略
• references/metrics-report.md — 完整的实验数据、方法和原始数值
• references/claude-md-template.md — 可直接使用的优化版 CLAUDE.md 模板
• references/api-optimization-guide.md — 面向直接使用 API 的用户，介绍提示词缓存、Batch API、工作量/思考预算、预填充、Token 高效工具和监控