关于 lean-ctx
lean-ctx 是面向现有 Agent 的上下文管理 Skill，在内容交给模型前进行选择、控制与压缩，并支持从缓存或归档恢复源内容。它通过组合检索、针对性读取和压缩命令输出来减少往返，同时保留上下文操作证据。
主要功能
- 01组合任务与源代码
- 02符号、语义及文本搜索
- 03按签名、行或差异读取
- 04压缩 Shell 输出并恢复内容
- 05跨会话记录任务与决策
适用场景
- 01一次查询理解陌生代码区域
- 02定位符号定义及调用关系
- 03检查编辑前后文件内容
- 04恢复被截断的命令输出
MCP 相关
通过 MCP 工具向 Agent 提供上下文检索、读取、Shell 和会话操作；也可通过 CLI 在不使用 MCP 时运行。
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/lean-ctx确认已加载。
附带文件scripts/install.sh
详细介绍
LeanCTX — AI 系统的上下文网关
控制 AI 可以看到什么。LeanCTX Engine 为现有 Agent 提供本地上下文选择、受支持的访问与内容控制，以及已观察到的上下文操作证据：选择 → 控制 → 学习 → 证明。这里的学习指本地任务和知识连续性，而非模型训练。恢复取决于源文件或归档是否可用，以及访问权限。LeanCTX SDK 是面向应用的独立集成接口。
lean-ctx 会在上下文到达你之前对其进行处理：缓存读取、压缩 shell 输出、聚焦搜索、精确恢复到源文件。两条规则胜过所有细节：
- 减少往返次数胜过缩小输出。 一次调用就回答问题，比三次小调用更省。绝不要只为了节省几百个令牌而增加一次调用。
- 绝不要通过轮询等待。 不要循环执行
sleep+ 状态检查（见下文）。
意图 → 工具
| 你想要…… | 调用 |
|---|---|
| 了解某个功能的工作原理（位置未知） | ctx_compose(task) — 一次调用即可获取排序后的文件和源码；优先使用它，而不是依次执行 search→read→read |
| 查找某个符号的确切定义 | ctx_search(action="symbol", name=…) |
| 按含义查找代码 | ctx_search(action="semantic", query=…) |
| 查找文本/正则表达式模式 | ctx_search(pattern=…, path=…) |
| 谁调用了 X / X 调用了什么 | `ctx_callgraph(action="callers" |
| 读取将要编辑的文件 | ctx_read(path, mode="anchored") → 使用宿主原生编辑工具进行编辑，或调用 ctx_call(name="ctx_patch", arguments={…}) |
| 仅为了解上下文而读取文件 | `ctx_read(path, mode="signatures" |
| 编辑后重新检查文件 | ctx_read(path, mode="diff") |
| 运行命令（构建、测试、git 等） | ctx_shell(command) — 输出会经过压缩 |
| 列出文件 / 目录结构 | ctx_glob(pattern) / ctx_tree(path, depth) |
| 跨会话记忆 | `ctx_session(action="finding" |
不要通过 ctx_shell（cat、sed -n、grep、rg）读取或搜索：
这会绕过读取缓存和符号索引。请使用 ctx_read / ctx_search。
延迟加载工具（ToolSearch）
如果宿主仅按名称列出 lean-ctx 工具（Claude Code 的 ToolSearch），请在一次调用中加载任务所需的工具，例如：
select:mcp__lean-ctx__ctx_compose,mcp__lean-ctx__ctx_search,mcp__lean-ctx__ctx_read。
不要因为 ctx_shell 恰好已加载，就什么事都退回用它处理。
如果你的工具列表中没有此处列出的工具（默认配置文件仅显示少量核心工具），仍可调用它：ctx_call(name="ctx_knowledge", arguments={…})。
ctx_call(name="ctx_discover_tools", arguments={"query": "…"}) 会列出所有工具。
长时间运行的命令
- 优先使用宿主自带的后台执行功能，并在完成时发送通知
（Claude Code：使用
run_in_background的Bash，或Monitor）。启动后， 继续其他工作或结束本轮 — 完成时你会收到通知。 ctx_shell(run_in_background=true)作业不会自动发送通知。只有在确实需要结果时才检查一次作业；绝不要循环执行sleep。
输出被截断
压缩或归档的输出末尾会附带恢复句柄。仅获取所需片段：ctx_expand(id, search=… | head=N | json_path=…)，或使用 ctx_read(path, raw=true) 获取精确字节。不要重新运行命令。
不使用 MCP（CLI）
lean-ctx read <file> -m signatures # or map | diff | lines:N-M
lean-ctx grep <pattern> [path]
lean-ctx -c "<command>" # only where the shell is not already wrapped
lean-ctx raw "<command>" # exact, uncompressed output
设置
which lean-ctx || curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash
lean-ctx setup # editor wiring, hooks, rules, this skill
lean-ctx doctor # verify