---

一、现象描述

1.1 总体数据

指标	数值
总消费	$13,603.43
总会话数	300
总 Token 数	3.9B
平均消费/会话	$45.34

1.2 Token 分解

类型	数量	占比
输入	42.7M	1.1%
输出	9.5M	0.2%
缓存写入	622.0M	15.9%
缓存读取	3.3B	84.8%

1.3 头部会话异常

排名	会话 ID	日期	模型	Tokens	费用
1	3d0e69b0	4/21	opus-4-7	301.6M	$1,573
2	6d900f57	6天前	opus-4-7	125.2M	$670
3	d7d5b0fa	4/21	opus-4-7	179.2M	$638
4	478b4e2a	4/20	opus-4-6	63.0M	$521
5	77523f53	6天前	opus-4-7	130.9M	$465

关键发现：前 20 会话占总费用的 60%+，单会话最高达 301M tokens。

---

二、根因分析

2.1 缓存读取 3.3B 的本质

Claude Code 使用 Prompt Caching 机制：

• 历史上下文存入缓存
• 每次请求重复读取缓存
• 缓存读取按 token 计费，不是免费的

输入:缓存比 = 1:77，每输入 1 个 token，附带 77 个缓存 token。

2.2 三大核心问题

问题 1：AI Agent 死循环

• 无终止条件，自动自查、改代码、重试
• Agent 来回调用工具，无限消耗 token
• 典型模式：出错 → 重试 → 再错 → 再试…

证据：会话 3d0e69b0 仅 36 条历史记录，却消耗 301M tokens，说明单轮携带上下文极大，存在内部循环。

问题 2：超长上下文不重置

• 一个会话使用多天，历史不断累积
• 每次提问携带全部历史 + 项目上下文
• 单轮输入可达几万 token

证据：

• 会话 3d0e69b0：36 条消息 → 301M tokens（单条平均 8M+）
• 缓存读取 3.3B vs 实际输入 42.7M = 77:1

问题 3：全局代码库永久加载

• 项目自动索引，每次请求注入全仓库代码
• node_modules/、target/ 等依赖目录被索引
• 项目 750MB，实际源码仅 275KB

证据：

• 7161 个文件被索引，排除依赖后仅 428 个（94% 是垃圾）
• CLAUDE.md + 项目规范 + 记忆 MCP 每次全量注入

2.3 模型选择加剧费用

模型	缓存读取单价	前 20 会话出现次数
opus-4-7	最高	6 次
opus-4-6	高	14 次
sonnet-4-6	中	少量

opus-4-7 缓存单价是 sonnet-4-6 的 3-5 倍，但 6 个会话却占总费用 40%+。

---

三、诊断过程

3.1 本地数据排查

# 检查历史会话数
grep -c "sessionId" ~/.claude/history.jsonl
# 结果：3258 条记录

# 找出最活跃的会话
grep "sessionId" ~/.claude/history.jsonl | sort | uniq -c | sort -rn | head
# 结果：最高单会话 58 条记录，但 token 消耗极高

# 检查计划任务（死循环嫌疑）
cat ~/.claude/scheduled_tasks.json
# 结果：无计划任务

# 检查记忆 MCP
ls ~/.claude/projects/*/memory/
# 结果：3 个项目有记忆文件，总计 32KB

3.2 项目规模分析

# 总项目大小
du -sh .
# 750MB

# 源码文件数
find . -type f \( -name "*.java" -o -name "*.ts" -o -name "*.vue" \) | wc -l
# 7161 个

# 排除依赖后
find . -type f ... -not -path "*/node_modules/*" ... | wc -l
# 428 个（排除 94%）

3.3 RTK 状态检查

where rtk
# RTK not in PATH

rtk gain
# No tracking data yet

rtk discover
# No hook installed

结论：RTK 已安装但未启用 hook，无法自动压缩上下文。

---

四、解决方案（可直接照搬）

4.1 立即生效（今天完成）

步骤 1：创建 .claudeignore（项目根目录）

文件路径：{项目根目录}/.claudeignore

# Dependencies
node_modules/
target/
dist/
build/
*.jar
*.war

# IDE
.idea/
.vscode/
*.iml

# Logs
logs/
*.log

# OS
.DS_Store
Thumbs.db

# Large generated files
*.min.js
*.min.css
*.map

# Docker volumes
data/

效果：排除 94% 无关文件，索引从 750MB 降至 ~200KB。

步骤 2：配置 settings.json（全局）

文件路径：C:\Users\{用户名}\.claude\settings.json

在根对象下添加：

{
  "contextWindow": {
    "maxTokens": 100000,
    "autoClearThreshold": 0.85
  },
  "session": {
    "maxDurationMinutes": 120,
    "warnBeforeClear": true
  }
}

效果：

• 单会话上限 100K tokens
• 子代理默认使用 sonnet 模型（性价比最高）
• 2 小时强制重置会话

步骤 3：禁用 memory MCP

在 settings.json 中：

{
  "disabledMcpServers": ["memory"]
}

效果：每次请求减少 ~8K tokens 注入。

步骤 4：启用 RTK Hook

前提：已安装 RTK（rtk --version 有输出）

4.4.1 确保 RTK 在 PATH（Windows 关键步骤）

Claude Code 的 Bash 环境不继承系统 PATH，必须在 settings.json 中显式配置：

{
  "env": {
    "PATH": "C:\\nvm4w\\nodejs;D:\\rtk;%PATH%"
  }
}

注意：D:\rtk 是 rtk.exe 所在目录，不是文件路径。多个路径用 ; 分隔。

验证：

which rtk
# 应输出 /d/rtk/rtk

4.4.2 初始化 RTK

# 如果 rtk 在 PATH
rtk init -g

# 或绝对路径
D:\rtk\rtk.exe init -g

4.4.3 添加 Hook 到 settings.json

在 hooks.PreToolUse 数组最前面添加：

{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "rtk hook claude"
    }
  ]
}

常见陷阱：rtk init -g 可能生成嵌套结构，需手动修正：

// ❌ 错误 — 嵌套了一层 hooks
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "rtk hook claude"}]
    }]
  }
}

// ✅ 正确 — 平级结构
{
  "matcher": "Bash",
  "hooks": [
    {"type": "command", "command": "rtk hook claude"}
  ]
}

4.4.3 验证 RTK

重启 Claude Code 后执行：

git status
rtk gain

应显示节省统计。

效果：自动压缩 Bash 命令输出，节省 60-90% tokens。

---

4.2 工作流调整（本周养成习惯）

原则 1：短会话

反模式	正模式
一个会话改 10 个文件	10 个会话，每会话 1-2 个文件
会话运行 8 小时	每 30-60 分钟 /clear 或重启
依赖历史上下文	每轮显式声明关键信息

操作：

• 大任务拆分为子任务
• 每子任务一个会话
• 会话结束后 /clear 或退出重进

补充（v1.1）：单日 compaction ≥5 次为红线
触发后当天暂停非紧急开发任务。单日高 compaction 通常是"多个 Agent 会话并发 + 每个会话内部又有子 Agent"的叠加效应，应优先合并任务，而不是开更多会话分摊。

原则 2：显式上下文

反模式	正模式
“看看代码库”	@file src/api/module.ts
“帮我改下登录”	“修改 AuthController.login 方法，添加验证码校验”
让 AI 自己找文件	直接提供文件路径

操作：

• 使用 @file 精确引用
• 提供具体的类名、方法名
• 减少 AI 的搜索范围

原则 3：模型降级

任务类型	推荐模型	理由
改配置、格式化、简单问答	haiku-4-5	最便宜
代码生成、重构、Debug	sonnet-4-6	性价比最高
复杂架构设计、深度推理	opus-4-7	必要才用

操作：

• 默认使用 sonnet-4-6
• 明确需要深度推理时才用 opus-4-7
• 简单任务用 haiku-4-5

原则 4：产物驱动

会话 1：设计 API
  → 输出 `docs/api-design.md`

会话 2：实现后端
  → 读取 `docs/api-design.md`
  → 输出 Java 代码

会话 3：实现前端
  → 读取 `docs/api-design.md`
  → 输出 Vue 组件

操作：

• 每会话产出文件
• 下会话读取产物而非历史
• 减少上下文依赖

原则 5：并行模式选择

独立任务并行时，选择正确的并行模式：

模式	工具	适用场景	不适用
subagent 并行	Agent 工具，同消息发多个	后端/前端/SQL 同时改	需要代理间协作
team 协作	TeamCreate + 任务列表	大型重构、多阶段项目	简单独立任务
多终端并行	开多个 Claude Code 窗口	完全独立的模块开发	同文件修改

经验：

• 简单并行（A改后端、B改前端、C写SQL）→ 用 subagent，同一条消息发多个 Agent 调用
• 复杂项目（10+文件重构，需代理间协调）→ 用 team 模式，共享任务列表
• 避免多会话同时改同一个文件，防止冲突

示例 — subagent 并行：

// 同一条消息中并行启动
{"description": "后端接口", "prompt": "实现 License 多 MAC 后端..."}
{"description": "前端页面", "prompt": "实现 License 多 MAC 前端..."}
{"description": "SQL脚本", "prompt": "写数据库迁移脚本..."}

原则 6：失败即停（v1.1 新增）

同一命令或工具连续失败 2 次，立即停止，主动向用户说明错误原因，等待指令。禁止"换个参数再试"的循环重试。

典型高风险场景：

• 命令不在 PATH（如 command not found）
• 权限不足（如 Access Denied）
• 网络超时（如 API 请求失败）
• 文件不存在（如 No such file or directory）

依据：检测到 AI 在 to-model-route 命令缺失时连续重试 4+ 轮，消耗大量无效 token。熔断策略可完全避免此类浪费。

---

4.3 项目级优化（可选，效果最佳）

创建 PROJECT_SUMMARY.md

文件路径：{项目根目录}/PROJECT_SUMMARY.md

# {项目名} 摘要

## 架构
- 前端: {技术栈}
- 后端: {技术栈}
- 构建: {工具}

## 关键目录
- `src/api/` - API 层
- `src/views/` - 页面
- `src/service/` - 业务逻辑

## 常用命令
npm run dev      # 启动开发
npm run build    # 构建

## 最近改动
- {简要描述}

效果：替代自动索引，每次请求减少 20-50K tokens。

RTK 高效 vs 低效场景（v1.1 补充）

RTK 并非对所有命令均等有效，实测数据（508次调用，总节省 400.9K tokens）显示：

命令类型	节省率	典型命令
测试运行	99%+	vitest run、jest run
编译检查	93%	tsc --noEmit
git 提交	94%	git commit
git diff	82%	git diff
目录列表	44-76%	ls -la
文件读取	4%	cat / read 大文件

操作建议：

• 大文件读取改用 Claude Code 内置 Read 工具（非 Bash cat），RTK 不介入，避免低效调用
• RTK 重点覆盖：测试、编译、git 操作这三类输出密集型命令，节省率最高

---

五、验证清单

完成所有配置后，逐项检查：

• .claudeignore 存在于项目根目录
• settings.json 包含 contextWindow.maxTokens: 100000
• settings.json 包含 disabledMcpServers: ["memory"]
• settings.json 的 env.PATH 包含 D:\rtk（或实际安装目录）
• settings.json PreToolUse 第一个 hook 是 rtk hook claude（平级结构，非嵌套）
• RTK 版本正常（rtk --version）
• which rtk 能找到二进制
• 重启 Claude Code 后 git status 输出格式变化（如 clean — nothing to commit）
• rtk gain 显示统计（非 No tracking data）
• 新会话开始时上下文在 10-30K 范围内

v1.1 补充检查项：

• 单日 compaction 次数 < 5（超过则当天暂停非紧急任务）
• Agent 会话用户消息 < 15 条（超过立即 /clear 拆分）
• 大文件读取使用 Read 工具，非 Bash cat
• 命令失败2次未再重试（观察 AI 行为）

---

六、预期效果

指标	优化前	优化后（v1.0 预期）	近10天实测（v1.1）
月均费用	$13,603	~$3,000-5,000	待月度汇总
缓存读取/请求	50-100K	10-30K	单会话 JSONL 最大 0.98M（vs 原 22M+）
单会话最大 tokens	301M	<10M	实测 <1M，超预期
项目索引大小	750MB	~200KB	codebaseIndexing=false + .claudeignore 已落地
RTK 节省率	0（未启用）	60-90%	实测 52%（508次，400.9K tokens）
死循环会话	严重（301M/会话）	显著减少	轻度1次（命令重试4轮），无大规模死循环

---

七、常见问题

Q1: RTK 安装后不在 PATH？

A: 分两步解决：

1. 在 settings.json 的 env.PATH 中添加 RTK 目录：

{
  "env": {
    "PATH": "C:\\nvm4w\\nodejs;D:\\rtk;%PATH%"
  }
}

2. hook 中直接用 rtk（不用绝对路径）：

{
  "matcher": "Bash",
  "hooks": [{"type": "command", "command": "rtk hook claude"}]
}

原因：Claude Code 的 Bash 环境不继承 Windows 系统 PATH，必须通过 settings.json 的 env.PATH 注入。

Q2: 禁用 memory MCP 后如何查看历史？

A: 手动读取记忆文件：

Read ~/.claude/projects/{项目}/memory/MEMORY.md

Q3: 会话被强制清理怎么办？

A: 这是预期行为。大任务拆分为多会话，用产物文件交接。

Q4: 如何确认 .claudeignore 生效？

A: 执行：

find . -type f -name "*.js" | wc -l
# 应大幅减少（排除 node_modules 后）

Q5: RTK 节省率只有 50% 左右，正常吗？（v1.1 新增）

A: 正常。实测 52% 是因为 rtk read 调用占比大（87% 体量），而读取大文件节省率仅 4%。

提升方法：

• 大文件读取改用 Claude Code 内置 Read 工具替代 Bash cat
• RTK 重点覆盖测试运行、编译检查、git 操作，节省率均 80-99%
• 排除 read 命令后，实际高效命令的平均节省率 > 85%

Q6: Agent 会话消息超了怎么处理？（v1.1 新增）

A: 超过 15 条消息立即 /clear，用以下模板开新会话：

继续上个任务：[任务名称]
当前进度：[已完成的部分]
下一步：[具体要做什么]
相关文件：@file [路径]

产物文件优先于历史上下文，新会话直接 @file 引用，无需复述历史。

---

八、相关文件

文件	路径	说明
本指南	docs/token-optimization-guide.md	优化完整方案
项目摘要模板	PROJECT_SUMMARY.md	按需创建
忽略配置	.claudeignore	项目根目录
全局配置	~/.claude/settings.json	Claude Code 配置
RTK 文档	~/.claude/RTK.md	RTK 使用说明