token-saving-methods

三种互补的 Token 优化方法论，分别作用于 LLM 交互管线的输入侧（RTK）、检索侧（CodeGraph）、输出侧（Caveman）。三者代表 Token 优化的三种基本范式——压缩、索引、约束——可在同一工作流中分层部署。

---

一、RTK

1.1 定位

RTK（Rust Token Killer）是部署在 Shell 与 Agent之间的 CLI 代理层。在命令输出抵达 LLM 上下文窗口之前进行有损压缩——保留语义负载，丢弃格式噪音。延迟开销 < 10ms。

1.2 核心机制

四种策略：

1. 智能过滤：去除注释、空行、样板代码、ANSI 控制字符
2. 分组聚合：文件按目录分组、错误按类型归并、测试结果按模块折叠
3. 截断保底：保留头尾关键信息，压缩中间冗余
4. 去重计数：重复日志行折叠为 “同样信息重复 N 次”

无 RTK：  Claude ──git status──→ Shell ──→ 原始输出（~2000 tokens）──→ LLM
有 RTK：  Claude ──git status──→ RTK ──→ 过滤输出（~200 tokens）──→ LLM

RTK 重写命令调用，执行后压缩 stdout。stderr 和退出码完整保留，确保 AI 不会因输出压缩误判命令状态。

1.3 使用

brew install rtk
rtk init --global       # 为 Claude Code 安装 Hook，后续命令自动优化
rtk gain                # 查看节省统计

安装 Hook 后，git、grep、cargo 等命令输出自动压缩。也可直接调用：

rtk git log -n 10       # 压缩 Git 日志
rtk cargo test          # 仅保留测试失败信息（节省约 90%）
rtk discover            # 分析历史会话，发现可优化命令

典型节省：cargo test / pytest 约 90%，git diff 约 75%，ls / tree 约 80%。30 分钟 Claude Code 会话，总 Token 从 ~118K 降至 ~24K。

1.4 适用边界

适用于命令输出驱动的场景：编译、测试、文件操作、Git、Docker、日志查看。不适用于需要逐字节精确理解原始输出的场景。对高度领域化的命令输出，可编写自定义 TOML 过滤规则。

---

二、CodeGraph

2.1 定位

将代码库静态结构预索引为知识图谱，AI 直接查询图谱而非原始文件。以一次性离线索引开销，换取每次交互时的检索效率跃升。

2.2 核心机制

四个阶段：

1. AST 解析：Tree-sitter 将源码解析为 AST，识别函数、类、方法调用、继承、导入等结构化信息。支持 20+ 语言。
2. 图结构存储：解析结果存入本地 SQLite。两类实体——节点（函数、类、接口、变量、枚举、路由）和边（调用、继承、实现、导入、引用）。FTS5 全文索引支持即时符号搜索。
3. 引用解析：跨文件引用通过名称匹配和导入链路分析解析。同时识别框架级路由绑定（Django URL → View、Express 路由 → Handler）。
4. 增量同步：通过 OS 原生文件事件监听（FSEvents / inotify / ReadDirectoryChangesW）自动增量更新，约 2 秒防抖窗口。

传统检索：
  Claude ──grep "UserService"──→ 返回 50 个文件
        ──Read file1.ts────→ 扫描
        ──Read file2.ts────→ 扫描
        ──... 10-20 次工具调用 ...

CodeGraph 检索：
  Claude ──codegraph_context("UserService")──→ 符号定义 + 调用者 + 被调用者
        ──codegraph_explore("UserService.getUser")──→ 相关源码
        ──完成（2-3 次调用，零文件读取）

通过 MCP 协议暴露工具接口给 Agent。

2.3 使用

npx @colbymchenry/codegraph
cd your-project && codegraph init -i
# 重启 Agent 后自动使用图谱检索

Claude Code、Cursor、Codex CLI 等 Agent自动使用 codegraph_context、codegraph_explore、codegraph_trace 等工具。CLI 手动查询：

codegraph context "How does a request reach the database"
codegraph callers "UserService.getUser"
codegraph impact "src/auth.ts"
codegraph trace "AuthMiddleware" "Database.query"

7 个真实项目基准测试：平均降低 35% 成本、57% Token、46% 响应时间、71% 工具调用次数。Tokio 项目（约 790 文件）工具调用减少 92%。

2.4 适用边界

最适中型以上代码库的结构理解：架构分析、调用链追踪、变更影响评估、符号定位。以下场景效果有限：运行时动态行为（反射、动态代理）、极小项目、文件修改极频繁的 Monorepo。索引消耗数十 MB 至数百 MB 磁盘。

---

三、Caveman

3.1 定位

通过系统提示词工程，向 LLM 注入表述约束，在保持技术信息完整的前提下压缩回复长度。与 RTK 对称——RTK 压缩输入，Caveman 紧缩输出。

3.2 核心机制

四层机制：

1. 表述模板：去掉冠词和系动词，短语替代完整句子，符号（→、=、≠）替代文字连接
2. 强度分级：lite（仅去填充词）、full（默认，省略冠词/系动词）、ultra（电报体）、wenyan（文言文）
3. 自动激活：SessionStart Hook 注入紧缩指令，UserPromptSubmit Hook 注入注意力锚点，防止长会话中模式滑回
4. 自动回退：安全警告、不可逆操作确认、多步骤关键流程、用户困惑时，自动恢复完整表述

无 Caveman：
  LLM: "The reason your React component is re-rendering is likely because..."（69 tokens）

有 Caveman：
  LLM: "New object ref each render. Inline object prop = new ref = re-render."（19 tokens）

仅影响输出 Token，不影响推理 Token（thinking 过程）。2026 年 3 月论文显示，表述约束在特定基准中将准确率提升 26 个百分点。

3.3 使用

curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

会话内控制：

/caveman              # 默认紧缩模式（full）
/caveman ultra        # 极限紧缩
normal mode           # 恢复正常表达

配套工具：

/caveman-commit              # ≤50 字符 Conventional Commit
/caveman-review              # 一行式 PR 审查意见
/caveman-compress CLAUDE.md  # 压缩记忆文件（节省约 46%）
/caveman-stats               # 会话 Token 节省统计

10 个典型编程任务平均减少 65% 输出 Token。“实现 React Error Boundary” 节省 87%，复杂架构讨论节省约 30%。

3.4 适用边界

最适高频、低歧义编程交互：代码审查、commit message、Bug 诊断、简短问答。大段架构文档、面向非技术读者的解释、新手引导需谨慎使用。

---

四、分层部署

三种方法攻击面不同，可无缝叠加：

方法论	作用阶段	优化目标	典型节省
RTK	输入侧（命令输出）	压缩 CLI 输出	60-90%
CodeGraph	检索侧（代码理解）	减少检索工具调用	57% Token / 71% 调用
Caveman	输出侧（AI 回复）	压缩 LLM 回复	65% 输出 Token

完整优化管线：RTK Hook 压缩命令输出 → CodeGraph MCP 从图谱获取代码结构 → Caveman 指令紧缩 AI 回复。三者叠加，典型会话 Token 从 ~118K 降至 ~20-30K（节省 >70%）。

4.1 部署建议

• 个人开发者：RTK 或 Caveman 单用即有显著收益。RTK 更适合编译/文件操作驱动的场景；Caveman 更适合对回复效率有要求的场景。
• 团队项目：CodeGraph 的持久化索引在团队中共享价值最大。建议配合 RTK，检索和输入两端同时优化。
• 全量部署：三者分层优化，互不冲突。输入噪音、低效检索、回复冗余各自处理。