yvgude/lean-ctx · 上手攻略
- 仓库：yvgude/lean-ctx
- 链接：https://github.com/yvgude/lean-ctx
- 分类：AI 编程工具 · 上下文工程
- 作者：Tom
- 更新：2026-09-21
是什么
LeanCTX（Lean Context 的缩写）是一个本地优先的 AI 编程代理上下文管理层，定位为"AI Value Gate"。它坐在你的 AI 编码工具和模型之间，决定代理读什么、压缩什么、记住什么、证明什么——并把 Token 消耗变成可测量的账本。
核心由三部分组成： - Shell Hook：95+ 命令输出压缩模式（git、npm、cargo、docker、kubectl 等） - MCP Server：81 个工具，含文件压缩读取、会话记忆、知识图谱、代码气味检测 - 持久项目图谱：基于 tree-sitter AST 的 27 种语言结构理解
官方 slogan：Token savings are the receipt. Intelligence is the product.
解决什么问题
用 AI 编码工具（Cursor、Claude Code、Windsurf、Copilot、Codex 等）时存在四类浪费：
| 问题 | 传统行为 | LeanCTX 行为 |
|---|---|---|
| 重复读文件 | 每次把全文重新发给模型 | 缓存重读，仅 ~13 tokens |
| Shell 输出噪音 | 全量 stdout 进 prompt | 命令专属压缩（95+ 规则） |
| 历史重发 | 每轮对话重发全部上下文 | Prompt cache 安全压缩 |
| 上下文断链 | 跨聊天窗口无记忆 | Session memory 持久化 |
此外还有成本可见性问题：团队不知道 AI 在哪里烧 Token，LeanCTX 用 CPAO（Cost per Accepted Outcome）替代单纯的 Token 计数。
快速安装
macOS / Linux（推荐 Homebrew）
brew tap yvgude/lean-ctx && brew install lean-ctx
通用安装脚本（任意平台）
curl -fsSL https://leanctx.com/install.sh | sh
npm（预编译二进制，无需 Rust）
npm install -g lean-ctx-bin
Rust / 从源码编译
cargo install lean-ctx
验证安装
lean-ctx --version
核心用法
一键对接 AI 工具
lean-ctx wrap cursor # 对接 Cursor
lean-ctx wrap claude # 对接 Claude Code
lean-ctx wrap codex # 对接 Codex CLI
lean-ctx onboard # 自动检测并对接所有已安装的 AI 工具
wrap 命令会自动：
1. 安装 Shell Hook 别名（git、npm、cargo 等 95+ 条）
2. 检测已安装的编辑器并生成 MCP 配置文件
3. 向 AI 代理注入规则，使其优先使用 ctx_read、ctx_shell、ctx_search 替代原生工具
4. 运行 lean-ctx doctor 验证
⚠️ 适用编辑器：Cursor、Claude Code、Windsurf、VS Code/Copilot、Codex CLI、Zed、Gemini CLI 等 30+ 工具（详见官方兼容性列表）。wrap 对每个工具的行为略有差异（如 Windsurf 需要绝对路径，Claude Code 有 2048 字符 MCP 指令限制需额外处理）。
文件读取（ctx_read）
AI 代理自动调用的核心工具，10 种读取模式：
| 模式 | 场景 | 典型节省 |
|---|---|---|
full |
编辑文件 | 重读 ~99% |
map |
仅结构/依赖 | ~93% |
signatures |
API 表面 | ~95% |
diff |
编辑后文件 | ~98% |
density:0.4 |
SDE 式预算压缩 | ~60%（保留高熵行至 40%） |
lines:N-M |
精确行范围 | ~90-99% |
entropy |
大文件相关行 | ~90% |
task |
任务相关行 | ~77% |
reference |
API 文档查询 | ~80-95% |
auto |
自动最优模式 | ~70-99% |
重读（文件内容未变）：~13 tokens（全量原文 → 缓存引用句柄）。
Shell 输出压缩（ctx_shell）
覆盖 270 条 passthrough 规则，压缩 git、npm、cargo、docker、kubectl、terraform 等命令输出。压缩可逆：模型可随时通过 ctx_expand / ctx_retrieve 取回原始内容。
查看节省
lean-ctx gain # 节省仪表板
lean-ctx gain --live # 实时滚动
lean-ctx gain --graph # 图表视图
lean-ctx gain --daily # 每日分解
lean-ctx savings summary # 签名的节省账本
lean-ctx shadow --latest # Shadow Mode 基线对比
⚠️ Shadow Mode 需先在 ~/.config/lean-ctx/config.toml 中设置 enabled = true，它用配置的基线对比当前行为，不改变实际工作流。
Web 仪表板
lean-ctx dashboard # 打开 localhost:3333，实时 Token 追踪 + 压缩统计
项目知识管理
lean-ctx knowledge remember <事实> # 存入项目知识库
lean-ctx knowledge recall <查询> # 跨会话检索
lean-ctx knowledge export # 导出为 .ctxpkg 包（可迁移到其他机器/模型）
代码图谱
lean-ctx graph status # 项目图谱统计
lean-ctx graph related <文件> # 查找相关文件
lean-ctx graph impact <文件> # 分析变更影响范围
上下文包（.ctxpkg）
lean-ctx compile # 将项目文件编译为可分享的 .ctxpkg 包
lean-ctx pack --pr # 生成 PR 专用上下文包（含变更文件 + 相关测试 + 影响分析）
典型适用场景
- 长期项目维护：跨多天、多聊天窗口的上下文一致性，Session Memory 记住任务事实和决策
- 大型代码库：万行级以上项目，
density:0.4或entropy模式大幅减少无关上下文 - API 成本控制：团队使用 AI 编码工具时用 CPAO 度量真实产出价值，而非 Token 总消耗
- PR 代码审查：自动生成变更上下文包，避免模型遗漏相关测试或依赖
- 多代理协作：
ctx_agent/ctx_handoff支持代理间上下文迁移
坑与注意
- Windsurf 需绝对路径：MCP 配置里
command必须写完整路径（如/opt/homebrew/bin/lean-ctx），其他工具通常lean-ctx即可 - Claude Code MCP 指令 2048 字符限制：
lean-ctx init --agent claude会额外安装~/.claude/skills/lean-ctx/Agent Skill 来绕过此限制，不要手动省略这一步 - Shell Hook 初始化方式：推荐用
eval "$(lean-ctx init bash)"（bash）或eval "$(lean-ctx init zsh)"（zsh），这样升级后 Hook 始终是最新的；传统lean-ctx init --global生成的脚本升级后可能过时 - Compression 可逆但不自动：CCR（Compression Can Retrieve）有 5 种恢复路径，但模型需主动调用
ctx_expand/ctx_retrieve，不是自动无感知 - Shadow Mode 需预热：启用后需跑一段时间才有基线数据可用，冷启动时
lean-ctx shadow --latest无结果 - Windows WSL 用户：请用 Linux 安装方式而非 Windows 原生，WSL 下会有额外路径问题
- Cookbook 需要 Node.js 22+：如想跑 Cookbook 示例，需 Node.js 22 及以上版本
与同类对比
| 工具 | 定位 | Token 压缩 | 可逆 | Session 记忆 | 图谱 | 代理支持 |
|---|---|---|---|---|---|---|
| LeanCTX | AI Value Gate / 上下文工程 | ✅ 10 种读取模式 + Shell 95+ | ✅ CCR 5 种路径 | ✅ 知识图谱 | ✅ tree-sitter 27 语言 | ✅ 30+ 编辑器 |
| Context7 | 上下文管理 | ✅ 部分 | ❌ | ❌ | ❌ | 仅 Claude |
| Aider | 本地编码代理 | 有限 | ❌ | ❌ | ❌ | 仅自有环境 |
| Continue | VS Code 编码助手 | 有限 | ❌ | ❌ | 部分 | VS Code |
LeanCTX 的差异化在于：全链路可逆压缩 + 跨工具统一上下文层 + CPAO 度量。Context7 等工具侧重单点上下文增强，而 LeanCTX 是完整的上下文工程平台。
⚠️ 以上对比基于公开文档，细节可能随版本更新变化，建议以官方最新文档为准。
一句话推荐结论
如果你重度使用 AI 编码工具且在意 Token 成本或上下文质量，LeanCTX 是目前最完整的本地上下文工程层——零配置、一键对接 30+ 编辑器，60-90% Token 节省是可测量的结果，而非宣传口号。