Token 优化与成本管理
Token 优化与成本管理
学习目标
本章要解决什么问题：理解 ECC 如何从多个维度同时优化 Token 消耗和成本。
读完本章后，你将了解：
- ECC 的推荐模型选择策略及成本影响
- MAX_THINKING_TOKENS 控制的原理
- 战略压缩 vs 自动压缩的差异
- Stop 钩子中的成本追踪机制
前置知识
本章涉及模型适配和上下文管理的通用原理，建议先阅读：
- 多模型适配架构 — Token 成本优化策略
- 上下文压缩与 Token 优化 — 截断、压缩、摘要策略
下文假设你已理解上述概念，直接聚焦 ECC 的具体实现。
项目实践
多维成本优化矩阵
ECC 的成本优化不是单一策略，而是从 6 个维度同时入手：
| 优化维度 | 具体操作 | 成本影响 | 实现方式 |
|---|---|---|---|
| 默认模型降级 | Sonnet 替代 Opus 作为日常编码 | ~60% 降低 | settings.json 中 model: "sonnet" |
| 子代理模型降级 | Haiku 用于文件读取/探索 | ~80% 降低 | CLAUDE_CODE_SUBAGENT_MODEL=haiku |
| 思考 Token 控制 | MAX_THINKING_TOKENS=10000 | ~70% 降低隐藏成本 | 环境变量 |
| 战略压缩 | 逻辑断点手动 /compact | 减少上下文浪费 | strategic-compact 技能建议 |
| 上下文监控 | 耗尽/范围蔓延/循环警告 | 避免无意义消耗 | ecc-context-monitor.js 钩子 |
| 成本追踪 | 每会话 Token/费用标记 | 可见性 | cost-tracker.js Stop 钩子 |
推荐设置组合
ECC 在 docs/token-optimization.md 中给出一组推荐设置：
{ "model": "sonnet", "env": { "MAX_THINKING_TOKENS": "10000", "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" }}这组设置的累积效果：
- Sonnet 日常编码（~60% 成本降低 vs Opus）
- 思考 Token 上限 10000（~70% 隐藏成本降低 vs 默认 31999）
- 子代理使用 Haiku（~80% 子代理成本降低）
战略压缩技能
ECC 的 strategic-compact 技能建议在逻辑断点手动执行 /compact，而非依赖自动压缩：
何时压缩：
- 探索完成后，开始实现之前
- 完成一个里程碑后
- 调试完成后，继续新工作之前
- 重大上下文切换之前
何时不压缩：
- 任务进行到一半（会丢失中间状态）
- 刚刚完成规划（规划结果还在上下文中）
ECC 的 suggest-compact.js 钩子在 PreToolUse 阶段（Edit/Write 事件）检查工具调用次数，大约每 50 次工具调用后建议手动 /compact。
成本追踪 Stop 钩子
ECC 在 Stop 阶段运行 cost-tracker.js 钩子：
每次 Stop → cost-tracker.js → 轻量标记标记内容：会话 ID、工具调用次数、估算成本输出：追加到本地成本日志文件设计特点：
- 异步执行（不阻塞响应）
- 轻量标记（不记录完整 Token 计数）
- 订阅用户可以关闭 API-rate 成本估计警告（
ECC_CONTEXT_MONITOR_COST_WARNINGS=off），但保留上下文耗尽警告
问题与规避
自动压缩在任务中触发
问题：Claude Code 的自动压缩可能在任务中间触发，丢失关键上下文。
ECC 的规避：
- 战略压缩技能建议在任务边界手动压缩，而非依赖自动压缩
suggest-compact.js钩子在逻辑断点提醒用户- 部分用户报告
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE的行为与预期相反（降低阈值反而更早压缩），ECC 文档建议移除此覆盖
成本估计不准确
问题：ECC 的上下文监控从本地钩子遥测估算 API-rate 成本，订阅用户的实际账单与此不同。
ECC 的规避：
- 订阅用户可通过
ECC_CONTEXT_MONITOR_COST_WARNINGS=off关闭成本估计警告 - 保留上下文耗尽、范围蔓延、循环警告（这些与账单无关）
过度优化导致体验下降
问题：同时应用所有优化（Sonnet + Haiku 子代理 + 低 Thinking + 频繁压缩）可能导致 Agent 表现明显下降。
规避方案：
- 使用 Profile 思维：简单任务用最小成本配置，复杂任务通过
/model opus临时升级 - 不要将
MAX_THINKING_TOKENS设为 0（完全禁用扩展思考），而是设为合理值（10000）
设计取舍
环境变量 vs 配置文件
ECC 的成本优化设置主要通过环境变量而非配置文件实现：
- 优势：可以在不同会话中动态切换（如今天用 strict profile，明天用 minimal）
- 代价：需要用户在 shell 配置文件中持久化这些变量
- 替代方案：在
settings.json中内置优化配置。ECC 选择环境变量因为settings.json的env字段也支持环境变量引用
战略压缩 vs 自动压缩
ECC 推荐手动战略压缩而非依赖自动压缩：
- 手动压缩的优势：在逻辑断点执行，不丢失任务上下文
- 自动压缩的优势：不需要用户干预
- ECC 的判断：自动压缩的触发时机不总是最优的，手动压缩在关键断点执行效果更好
成本可见性 vs 隐私
ECC 的成本追踪将标记写入本地日志文件：
- 优势：用户可以了解自己的成本模式
- 代价：本地文件可能包含敏感的会话元数据
- 规避：仅写入轻量标记（会话 ID、工具调用次数），不写入实际 Token 内容
参考来源
- 源码验证:
docs/token-optimization.md— 完整优化指南 - 源码验证:
scripts/hooks/cost-tracker.js— 成本追踪 Stop 钩子 - 源码验证:
scripts/hooks/ecc-context-monitor.js— 上下文监控 - 源码验证:
scripts/hooks/suggest-compact.js— 战略压缩建议 - 源码验证:
skills/strategic-compact/— 战略压缩技能 - 多模型适配架构 — 通用模型路由与成本优化