Token Saver

---
name: token-saver
description: >
  Claude Code token optimization advisor. Analyzes current session/project for
  token waste and applies proven cost-reduction strategies. Use when:
  (1) user asks about saving tokens, reducing cost, or optimizing Claude usage,
  (2) user complains about high token consumption or rate limits,
  (3) before starting a large multi-file task (proactive optimization check),
  (4) when session context is growing large and /compact might help,
  (5) when reviewing CLAUDE.md or .claudeignore configurations.
  Triggers: "省token", "save tokens", "太贵了", "token太多", "优化成本",
  "reduce cost", "token optimization", "缓存命中", "cache hit",
  "compact建议", "省钱", "save money", "token budget".
user_invocable: true
---

# Token Saver — Claude Code 省钱工具箱

基于 Claude Code 源码分析和缓存架构，提供可立即执行的 token 优化策略。

---

## 核心原理

Claude Code 每轮对话将以下内容完整打包发送给 API：
1. 系统指令（角色定义、行为准则）
2. ~40 个工具的完整定义
3. CLAUDE.md 项目上下文
4. Git 状态快照
5. 完整对话历史
6. 本轮消息

**第 N 条消息的实际输入 = 前 N-1 条全部内容 + 新消息**（线性增长）

### 提示缓存机制（以 Sonnet 4.6 为例）

| 计费类型 | 价格 / 百万 token | 相对正常价 |
|---------|-----------------|-----------|
| 正常输入 | $3.00 | 100% |
| 缓存写入 | $3.75 | 125%（首轮建缓存） |
| 缓存读取 | $0.30 | **10%**（后续命中） |

系统提示占每轮输入的 60-80%，缓存命中后只付一折。

### 缓存断点位置

Claude Code 每个请求放置 3 个缓存断点：
- **断点 1-2**：系统提示内部（identity + CLAUDE.md/Git/环境信息）
- **断点 3**：最新一条消息（历史消息无断点，旧工具调用结果替换为轻量引用）

### Pro 用户缓存 TTL

- 默认：5 分钟过期
- Pro/Max 订阅未超额：**1 小时**有效期
- 超过 5 分钟不操作 → 缓存失效 → 系统提示重新付写入费

---

## 四大缓存杀手

缓存基于严格的字符级哈希，前缀任意字节变化即失效。

### 杀手 1：会话中切换模型
缓存绑定具体模型。Sonnet → Opus = 缓存清零，系统提示重新付写入费。
- 20,000 token 系统提示：切模型前 $0.006/轮 → 切后 $0.075（**12 倍惩罚**）
- **做法**：需要换模型就开新会话

### 杀手 2：会话中修改 CLAUDE.md
CLAUDE.md 合并在系统提示的第二个断点里，改内容 = 缓存立即失效。
- **做法**：开会话前写好 CLAUDE.md，开始后不动

### 杀手 3：注入精确时间戳
CC 只注入精确到天的日期。精确到秒 = 每次请求哈希不同，缓存永远无法命中。
- **做法**：通过 API 集成时不要往系统提示塞每秒变化的内容

### 杀手 4：工具描述里的随机路径
工具描述混入随机 UUID 路径 → 每次请求不同 → 12 倍成本惩罚。
- CC 内部已改用内容哈希路径规避

---

## 优化策略速查

### 架构层（节省 50-80%）

1. **一个会话一个任务**
   话题切换后，旧对话历史 = 每轮付费的噪音。新任务开新会话。

2. **主动 /compact + Auto-Compact 调参**
   完成子任务即手动压缩，附定制保留指令：
   ```
   /compact 保留 API 设计决策和文件修改记录
   ```
   压缩时 CC 自动：去除图片和冗余内容、重新注入最近 5 个文件、保留 Plan 和 Skills 上下文。
   **压缩请求与主对话共享缓存前缀**，不浪费已积累的系统提示缓存。

   Auto-Compact 环境变量（加到 ~/.zprofile）：
   ```bash
   # 默认 83.5% 太晚，上下文已膨胀，每轮成本已经很高
   export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60   # 60% 时自动压缩
   # 或用绝对值：
   # export CLAUDE_CODE_AUTO_COMPACT_WINDOW=100000
   ```

3. **固定模型，不中途切换**
   需要换模型就开新会话，保留当前所有缓存。

4. **开会话前写好 CLAUDE.md**
   会话中改 CLAUDE.md = 主动让系统提示缓存失效。

### 提示词层（节省 20-50%）

5. **一次说完 > 分多条追问**
   3 条消息 = 3 次完整上下文加载。1 条消息 = 1 次。
   ```
   ✅ "总结这个文件，列出要点，建议标题"
   ❌ "总结这个文件" → "列出要点" → "起个标题"
   ```

6. **编辑消息 > 发新消息纠正**
   每条新消息永久追加进历史，后续每轮都要为它付费。
   CC 支持 **两次 Esc** 回滚历史消息重新编辑。

7. **给精确路径 > 让 AI 搜索**
   模糊描述触发 Explore Agent 多轮搜索（每轮一次 Haiku 调用）。
   ```
   ✅ "读 src/services/auth.ts"
   ❌ "帮我找处理登录的文件"
   ```

8. **简单任务关闭 Thinking**
   文件编辑/格式化/搜索替换等不需要扩展思考。Thinking token 与输出 token 同价。

### 文件层

9. **CLAUDE.md 的 ROI**
   5,000 token CLAUDE.md × 20 轮对话：
   - 有 CLAUDE.md：首轮写入 + 19 轮读取 ≈ 0.4 RMB
   - 无 CLAUDE.md 每轮手工提供：20 轮正常输入 ≈ 2 RMB
   - **节省 ~90%**
   用 `/init` 功能生成初始 CLAUDE.md，精简但完整。

10. **排除 JSON Token 黑洞**
    JSON token 密度是普通代码 2 倍。在 `.claudeignore` 排除：
    - `package-lock.json`、`yarn.lock`、`uv.lock`、`Cargo.lock`
    - `node_modules/`、`dist/`、`target/`、`__pycache__/`
    - `*.map`、`*.min.js`、`*.min.css`

---

## 子智能体省钱技巧

### Explore Agent（代码搜索）
- 自动用 **Haiku**（比 Sonnet 便宜 73%，比 Opus 便宜 95%）
- 跳过 CLAUDE.md 加载
- **不共享缓存**，长对话看 subagent 更省 token
- 描述越精确，轮数越少，花费越少

### Plan Agent（架构设计）
- 继承主对话模型
- 跳过 CLAUDE.md，专注设计不涉及执行

---

## 诊断检查清单

当 Agent 检测到以下情况时，应主动建议优化：

- [ ] 对话超过 15 轮 → 建议 `/compact`
- [ ] 用户分多条消息提同一个需求 → 建议合并
- [ ] 用户描述模糊让搜索文件 → 建议给精确路径
- [ ] 项目无 `.claudeignore` → 建议创建
- [ ] 项目无 `CLAUDE.md` → 建议用 `/init` 生成
- [ ] 用户要求切换模型 → 提醒开新会话更省
- [ ] 简单编辑任务开了 Thinking → 建议关闭

---

## 三条核心原则

1. **保持前缀稳定**：固定模型、固定 CLAUDE.md、避免动态内容注入
2. **用好缓存杠杆**：常用上下文写入 CLAUDE.md，10× 折扣从第二轮起生效
3. **控制历史增长**：一任务一会话，主动 /compact，批量提问

> 同样的 Max 套餐，操作习惯不同，实际可用量差距可达 3-5 倍。