lean-ctx (LeanCTX)

核心定位#

lean-ctx 定位为 "The Context OS for AI Development"，聚焦于 AI 编码代理"读"与"听"阶段的上下文优化，不参与代码生成或执行逻辑，而是作为代理外挂或底层运行时工作。

上下文压缩引擎#

• 10 种读取模式：auto、full、map、signatures、diff、aggressive、entropy、task、reference、lines:N-M
• AST 级解析：基于 Tree-sitter 支持 18 种编程语言的签名提取
• 多策略算法：Shannon 熵分析、注意力模型（U-curve 位置加权）、TF-IDF 代码本
• 极致缓存：缓存重读降至 ~13 tokens，整体 Token 节省 60–95%

Shell 输出处理#

• 通过 Shell hook 透明拦截并压缩命令输出
• 内置 56 个模式模块，覆盖 git、npm、cargo、docker、fd、just、ninja、clang 等工具
• 支持 compound lexer 解析 &&、|| 及管道连接的多命令组合

代码属性图#

• 多边类型：imports、calls、exports、type_ref、tested_by，带权重 BFS 遍历
• 基于 git-diff 增量更新，仅重索引变更文件
• 图感知读取：每次 ctx_read 自动附带 [related: ...] 提示

混合搜索引擎#

• 三路信号融合：BM25（词法）+ Dense Embeddings（ONNX all-MiniLM-L6-v2）+ Graph Proximity（结构）
• RRF 排序：score = Σ 1/(60 + rank_i)

会话记忆与知识打包#

• 持久化任务/事实/决策，Session Survival Engine 生成 compaction snapshot
• Context Package System 将 Knowledge + Graph + Session + Patterns + Gotchas 打包为 .lctxpkg 文件
• SHA-256 完整性校验，支持跨项目/团队共享与智能合并

治理与安全#

• Context Profiles：coder/bugfix/review/exploration/hotfix/ci-debug
• Role 系统、Token 预算、SLO 评估、降级策略
• 秘密/PII 脱除、沙箱执行（ctx_execute）
• 默认无遥测，仅可选匿名统计（opt-in）

上下文场理论 (CFT)#

• 统一势函数：Φ(i,t) = relevance + surprise + graph + history − cost − redundancy
• 贪心背包编译器 + Boltzmann 视图选择

架构概要#

• 单个 Rust 二进制（93.1% Rust），同时作为 Shell Hook 和 MCP Server 运行
• 入口层：CLI（main.rs）、MCP stdio、Streamable HTTP、守护进程
• 服务层：LeanCtxServer + ToolRegistry（27 个 trait-based 工具）+ Pipeline Stages
• 智能核心：双层缓存、多 Tokenizer（o200k_base/cl100k_base/Gemini/Llama）、Property Graph、ONNX 推理、CFT 编译器
• 本地优先，代码不离开机器；前缀缓存友好的输出排序；compression_safety 语义安全检查

安装与集成#

curl -fsSL https://leanctx.com/install.sh | sh
brew tap yvgude/lean-ctx && brew install lean-ctx
npm install -g lean-ctx-bin
cargo install lean-ctx
lean-ctx setup   # 自动检测 AI 工具并配置 shell hook + MCP
lean-ctx init --agent cursor|claude|copilot

三种集成模式：CLI-Redirect（零 MCP 开销）、Hybrid（MCP 缓存 + CLI shell/搜索）、Full MCP（全部 56 工具通过 MCP 暴露）。

适用场景#

• 中大型仓库/Monorepo 的 AI 辅助开发（50+ 文件显著减少上下文噪声）
• Shell 密集型工作流（git/test/build 输出压缩）
• 跨会话连续性（长期任务的决策和发现持久化）
• 团队知识共享（Context Package 分享）
• 多代理协作（agent handoff、workflow 编排）