LeanCTX 原理拆解：本地压缩 AI 编码上下文

AI 编码助手每回答一次，都要先把仓库文件、最近的命令输出和整段对话历史重新塞进上下文窗口。同一份文件读三遍就发三遍，一条 cargo build 的日志里大半是不变的行，上一轮聊过的内容下一轮还要再发。这些重复内容按 token 计费，也占掉了本该留给推理的额度。

LeanCTX 是 Rust 写的本地上下文网关，装在 AI 编码助手旁边，压缩每次发给模型的文件与命令输出，并记账省下了多少 token。

它通过 MCP server、hook 或代理接入已有编码 agent。文件读取和 shell 调用在到达模型之前先过一遍本地处理：能复用的重读换成引用，命令输出按类型压缩，会话记忆跨对话保留，被挡下来的 token 数进入本地账本。仓库地址是 github.com/yvgude/lean-ctx，Apache-2.0 许可，主要语言 Rust，当前 3837 star、352 fork，开放 Issue 13 个。

主要功能

文件读取的 16 种模式。README 列出 full、map、signatures、diff、lines:N-M、density:X 等读取粒度，同一个文件按不同模式拿到的内容量差别很大。缓存命中的重读返回一份紧凑的确定性引用，README 给出的量级是约 13 tokens。

密度压缩。density:0.4 按行熵保留信息量最高的行，一直裁到剩余 token 约为原文的 40%。这个过程是确定性的，同样的输入得到同样的输出。

JIT 展开。signatures 模式只给签名和行号范围，需要细节时再用 lines:N-M 把那一段拉出来。先看骨架，正文按需取。

Shell 输出压缩。内置 85 条以上的命令输出模式，覆盖 git、npm、cargo、docker、kubectl、terraform 这些日常命令；另外配了 250 条以上的直通规则，遇到不匹配的输出不做处理直接放行。

Tree-sitter AST 解析。对 27 种语言做结构级理解，压缩依据来自语法结构，而不是按行数截断。

账本与度量。lean-ctx value 显示当前会话被挡在模型上下文之外的 token 数量和安全事件，--session <id> 切换会话，--all 覆盖全部会话，--json 输出 JSON。配合 Shadow Mode 基线，可以拿自己的真实工作负载做对比。

一组运维命令。lean-ctx setup 完成接入，init 初始化，doctor --fix 做诊断并尝试修复，wrap 包装 agent 进程，update 升级，dashboard 打开实时面板。遥测是 opt-in。

它怎么做到的

整条链路是这样走的：agent 发起一次文件读取或 shell 命令，被 MCP server 或 hook 截住；先查本地缓存，命中就返回确定性引用，未命中则按内容类型分派——纯文本走模式化读取或密度压缩，代码走 tree-sitter AST 解析，命令输出走模式库加直通规则；处理结果交回 agent 发往模型，本地账本同步记账。代理模式下每个请求都过一遍压缩，并且保持 prompt-cache-safe，避免把上游的提示缓存打掉。

README 提到有恢复路径和 Shadow Mode 基线，用来验证压缩结果是否可用。压缩算法内部怎么实现、缓存失效判定的完整流程，仓库未展开说明。

几个关键设计

双通道接入

MCP server 面向支持 MCP 的 agent，hook 面向不依赖 MCP 的调用路径，代理则挂在请求链路上。三条路并存，是为了覆盖不同编辑器和命令行工具的接入能力。公司环境禁用 MCP 时，还有 shell 命令这条路可走，这一点在 Issue 里被专门提出来过。

缓存加确定性引用

重复读取同一文件是上下文里最大的一块浪费。LeanCTX 把读过的内容缓存下来，重读时返回一份紧凑引用而不是原文。引用要足够精确，模型才能判断内容没变、可以沿用之前的理解。

按输出类型分派的压缩规则

命令输出格式固定，压缩可以做成规则库。模式库覆盖常见工具的常见输出，直通规则保住那些没被覆盖的部分。代码走的则是另一条路：靠 tree-sitter 语法树判断哪些是结构、哪些是细节。

本地账本与基线测量

省了多少要有数。lean-ctx value 把被挡下的 token 和安全事件列出来，Shadow Mode 提供一条对照基线。README 明确说节省量取决于工作负载和开启的模式，没有放之四海皆准的数字。

这样设计的代价

它不能单独工作，必须挂在已有编码 agent 旁边。agent 侧不支持 MCP 又跑不了 hook 的环境，接入面会明显变窄。压缩效果依赖工作负载和模式组合，别人的数字搬不到你的项目上。

版本化目录带来过真实问题。Scoop、Homebrew、npm 和 mise 都从带版本号的目录运行 lean-ctx，下一次更新会删掉这个目录；而 setup、init、doctor --fix 和 wrap 会把该目录写进各个 agent 的 MCP command 与 hooks，更新后指向就失效了。这个问题在 v3.10.5 修复。

hook 改写上下文的路径也出过事故。Claude Code 开启 interleaved thinking 时，PreToolUse 的改写会破坏思考块，会话反复报 400，该 Issue 已解决。Windows 上 PowerShell 命令被钩子拦截时，-ExecutionPolicy 被当成命令处理（v3.5.18，已解决）；ctx_impact 对没有 using 语句的 C# 不生效（3.8.2，已解决）。另一个已修复的问题是文件锁超时被误判成内容变更，也就是 issue 1780。

对你的实际影响

机器上会多一个常驻的本地进程，缓存和账本落在本地磁盘。仓库里没有给出具体的资源占用数字，选机器时别按别的项目经验外推。

上手成本主要在排查环节。lean-ctx setup 一条命令能接入，但之后要看 doctor 的输出、value 的账本和 dashboard 的面板才能判断它到底有没有按预期工作。Windows 和多窗口 VS Code 这些场景在 Issue 里出现过，首次配置留出调试时间。

它拦截的是本机文件读取和 shell 命令，权限范围需要你自己限定在自有仓库内；仓库里有一份 22 KB 的 SECURITY.md 专门讲这块，接入生产环境前值得读。

同类项目对照

LeanCTX 和下面两个项目都在做上下文层面的优化，切入角度不同。

LeanCTX 的短板在接入方式：它必须挂在已有 agent 上，环境禁用 MCP 时只能退回 shell 命令，能覆盖的面就窄了。如果你的核心需求是从大仓库里挑出关键文件，leantoken 这类专注定位的工具更直接；如果你在 macOS 上用 Homebrew 管理工具链，homebrew-pandafilter 的安装路径更贴合现有习惯。这三个项目的取舍点不在谁功能多，而在你要解决的问题落在哪一段。

适合谁，不适合谁

已经在用 Cursor、Claude Code、Copilot、Windsurf、Codex、Gemini 这类助手，仓库规模大、在意 API 账单，并且愿意让一个本地进程介入读写链路的开发者，适合评估 LeanCTX。想看清「上下文到底花在哪」的团队也合适，lean-ctx value 与 Shadow Mode 提供的是可对照的数字。

想要一个自己能写代码的 agent 的人不合适，它不提供模型，只做压缩和记账。公司环境禁用 MCP、又没条件跑 shell 钩子的团队也不合适。不希望额外进程拦截本机 shell 命令的人，同样应该跳过。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。