代码检索精简器 morluto/leantoken

LeanToken

给智能体的代码智能：找到真正重要的代码，让你的上下文窗口和 token 保持精简。

语言： English · 简体中文 · 日本語 · 한국어

- MCP Registry 名称：mcp-name: io.github.morluto/leantoken

安装 · 为什么选 LeanToken · 工具 · 命令行 · 工作原理 · 文档

实测 token 节省： 在一项 60 次运行的对照研究中，LeanToken 比智能体内置工具少用 20.1% 的模型输入 token（仓库探索范围有限时），比这些工具少用 37.6%（探索范围较广时）。具体测量方式见测量方法。

快速开始

把 LeanToken 加到 Claude Code、Cursor、OpenCode、Codex、Gemini CLI 或 Antigravity：

npx leantoken setup

安装行为与安全性

当前版本在写入前会先检查：如果 npx 解析到的是过期的项目本地安装或上级目录安装，安装会停下，并提示改用 npx leantoken@latest setup。早于这项检查的旧版本，可以直接用这条带版本号的命令引导安装。

交互式安装向导会预选它检测到的受支持客户端；继续之前你可以改掉这个选择。
随后向导会显示确切的配置路径和 MCP 启动器，并要求你再做一次最终确认。自动化流程从不把检测结果当作同意。基于 npx 的安装会锁定执行安装的那个确切 LeanToken 版本，因此重启客户端不会悄悄切到更新的版本。

全局安装从不记录安装时所在的仓库。OpenCode 拿到的是相对于工作区的工作目录；其他受支持客户端由宿主选定的工作区 cwd 启动 LeanToken。如果宿主改从主目录或文件系统根目录启动， LeanToken 默认拒绝索引这么宽的根目录。

重启或重新加载已配置的客户端，然后在某个仓库里验证连接和第一次检索：

npx leantoken doctor

试一个宽泛的任务，比如：在编辑前找到与请求取消相关的代码。 LeanToken 会帮智能体从 leantoken.context 起步，而它的普通工具仍可用于编辑、构建和测试。

查看 LeanToken 记录的仓库本地 token 用量：

npx leantoken savings

默认本地运行源码在你自己的机器上建立索引，存进本地数据库。LeanToken 只做只读的发现与检索层。

明确的 token 预算每次响应都有明确的 token 上限，大文件不会占满整个请求。

为智能体工作流而建用一组聚焦的工具查找文件、搜索代码、查看结构、读取精确范围、追溯历史、查询 JSON、跟踪 token 用量。

高级安装与版本管理

跳过向导，直接指定客户端，或配置所有受支持的客户端：

npx leantoken setup --claude --codex --yes
npx leantoken setup --all --yes

日常使用推荐 --private-runtime 启动方式：它把包内原生的可执行文件复制到应用数据目录，目录名由版本号和完整的 BLAKE3 摘要组成。这样客户端直接启动一个经过校验的进程，不必常驻 npm/Node 包装层。同一版本的不同源码构建可以共存。setup --refresh --private-runtime 会固定当前这个确切的产物，其他被引用的产物仍可继续使用。该选项默认关闭，免安装路径因此不会额外写入应用数据。用 --dry-run 预览它的路径和摘要。

自动化流程绝不把检测当作同意：--yes 必须配合显式的客户端参数、--all，或针对 LeanToken 已管理条目的 --refresh。想预览同一份解析后的方案而不改动文件：

npx leantoken setup --codex --cursor --dry-run

安装只在所选宿主用到的目录里添加 leantoken MCP 条目和一个自有的小型发现技能：Claude Code 用 ~/.claude，Codex 和其他受支持的宿主用 ~/.agents。该技能只声明路由元数据，不复制工具 schema，不添加规则，也不安装 shell 钩子。安装会把新的 MCP 启动器标记为已管理；遇到同名的手动条目会拒绝替换，除非你先查看 dry-run 结果并传入 --force-unmanaged。移除自有集成：

npx leantoken remove

升级 private-runtime 之后，先查看保留的产物，预览一次引用安全的清理，再执行：

npx leantoken runtime list
npx leantoken runtime prune --dry-run
npx leantoken runtime prune --yes

明确选定新版本后，只刷新已有的 LeanToken MCP 条目；或用旧版本回滚：

npx --yes leantoken@latest setup --refresh --yes
npx --yes leantoken@0.1.8 setup --refresh --yes --allow-outdated

常见智能体工作流

LeanToken 最好当作一个小型证据循环来用，而不是一次性把仓库倒出来：

1. 一次调用完成自主分诊的定位。 面对不确定的宽泛任务，先用 context 加 plan_only: false 起步，然后直接使用物化出来的证据。只有当覆盖结果指出某个具体缺失的实现或回归测试负责人时，才做至多一次聚焦的追问。
2. 继续时不要重发源码。 在下一次 context 调用里传入之前的 receipt_id，或者把返回的片段哈希作为 known_hashes 传入。响应会报告精确遗漏和重叠遗漏，而不是悄悄对同一份证据重复计费。
3. 排查已观察到的失败。 使用 investigation 工作流，在 workflow_evidence 里只提供直接观察到的 failure_traces、路径、符号或测试意图。随后针对证据指出的负责人，做精确的 search、outline 或 read 调用。
4. 审查变更。 使用 review 工作流，把 base_revision 设为 BASE..HEAD，并设 strict_changed_paths: true。当另一个智能体需要一份紧凑清单，包含选中的哈希、变更路径、假设和已完成的验证，且不要复制源码正文时，请求 handoff。

这个一次调用的约定针对自主仓库分诊，并不限制实现类智能体。人工审查和控制面流程仍可先用 plan_only: true 预览昂贵或高风险的检索，再物化。 repeated multi-agent context suite 发现，迭代式 LeanToken 配置的总输入比精简原生方案多 50.9%，而冻结的「一次上下文加可选一次搜索」配置节省了 20.1%，路径集成功数为 15/20。这些结果覆盖四个固定的分诊任务，并不能证明存在通用的实现工作流。

显式的聚焦约束就是契约。当请求提供 focus_paths、精确的 focus_symbols 和 minimum_fragments_per_focus_path 时，LeanToken 会在文档规定的单文件边界内生成候选；当不同区间无法满足最小值时，会报告覆盖失败。explain-profile 计划和物化响应还会指出有界分配边界，说明每个聚焦候选是在哪里生成、预留、选中或抑制的，同时不改变排序。

为什么选 LeanToken

多数智能体一上来就大范围搜索、整文件通读。LeanToken 把这项工作分阶段收窄：

| 典型的仓库探索 | 使用 LeanToken |
| 扫描宽泛的目录列表 | 在紧凑的树里找到相关路径 |
| 读整个文件来摸清结构 | 不加载整个文件就能看到定义和导入 |
| 每轮之后重发同一份代码 | 避免重复未变的证据 |
| 让大文件塞满请求 | 把返回的源码控制在精确的源码 token 预算内，并单独报告响应开销 |
| 猜哪些文件重要 | 为任务排序可能相关的代码 |

你的编码智能体仍然负责编辑、命令、测试和对话。
LeanToken 找出并返回这些任务需要的代码。

LeanToken 不会生成一个巨大的提示词文件。它按智能体的需要，回答聚焦的搜索和读取请求。

示例

对于 fix request cancellation during shutdown 这样的任务，一个示意性的有界结果可能长这样：

Budget: 1,200 source tokens

Selected evidence:
src/services/executor.rs lines 137-147, 251-259
src/services/reconciliation.rs lines 148-175, 257-272

智能体收到的是这些行范围，而不是两个完整文件。如果预算太小，响应还会说明哪些内容被省略。路径、分数、回执、JSON 和 MCP 传输包装都不计入这个源码 token 预算；测量边界见 token accounting。

可用工具

| 工具 | 用途 |
| leantoken.context | 自主广泛分诊时默认物化的首次调用；供人工或控制面审查时可选预览。 |
| leantoken.search | 排序搜索优先用它，而不是 grep/rg；穷举式文本/正则调用可以显式记录或复用完整查询覆盖。 |
| leantoken.files | 紧凑、感知忽略规则的路径发现优先用它，而不是 find/ls/glob。 |
| leantoken.outline | 不用整文件读取，就能查看定义、签名、导入和范围。 |
| leantoken.read | 读取单个精确符号或闭区间行范围时优先用它，而不是 cat/head/sed。 |
| leantoken.history | 跨不可变 Git 修订读取、批量 diff 或追踪解析出的符号。 |
| leantoken.json | 用分页键和带类型的诊断信息，查询、汇总或比较有界的实时 JSON。 |
| leantoken.receipt_rebase | 只把同路径、同坐标、同哈希的证据显式带入更新的已完成代次。 |
| leantoken.savings | 报告观测到的响应记账、哈希抑制、失败和显式观测限制。 |

高级检索控制

每个基于索引的检索工具（包括 receipt_rebase）都接受 consistency: "reconcile_working_tree"，用于在查询前必须先归并已完成的编辑。默认值 "indexed_generation" 返回最新的已完成索引代次，不扫描也不等待文件系统变化；它不是 Git 修订边界。
leantoken.history 读取不可变 Git 对象，leantoken.json 读取精确的实时文件，所以两者都不接受索引一致性模式。要把上下文限制在不可变历史内，请把 BASE..HEAD 作为 leantoken.context.base_revision 传入，并设置 strict_changed_paths: true。

自主广泛分诊时，设置 plan_only: false，直接使用物化的证据。plan_only: true 留给人工或控制面审查，用在昂贵或高风险的检索之前：它返回有界排序的候选元数据，不含源片段，也不改动回执。批准后，用 plan_only: false 重复同一请求。把 response_profile 设为 "compact"，得到最小的 fail-loud 响应；保持默认的 "balanced" 形态；或用 "explain" 查看有边界的逐项省略、facet 和 diff 证据。响应会以 effective_response_profile 报告最终选定的值。

目录刻意保持精简，因为每条工具描述和 schema 同样会消耗模型上下文。

命令行用法

通过 npx 直接运行 LeanToken：

npx leantoken status
npx leantoken savings
npx leantoken doctor
npx leantoken --root /path/to/repo search handle_request

或使用全局安装的可执行文件：

npm install --global leantoken@latest

leantoken --root /path/to/repo index
leantoken --root /path/to/repo search handle_request --mode identifier --max-tokens 800
leantoken --root /path/to/repo context \
--task "fix request cancellation during shutdown" \
--budget 2000

审计已有的脱敏实验或宿主报告，无需打开仓库索引：

leantoken episode audit \
--adapter multi-agent-suite-v1 \
--input benchmarks/reports/multi-agent-context-suite-v1-codex-0.144.1.json

默认输出 Markdown；加上全局 --json 可得到稳定的规范化 JSON schema。审计器在本地运行，范围有界，对其输入只读。它保留产物哈希，不保留原始提示词、源码、工具参数或工具输出。

npm install leantoken 会把命令装到当前项目的 node_modules/.bin，不会把 leantoken 加进 shell 的 PATH。要调用项目内安装的版本，请用 npx leantoken、package script，或 ./node_modules/.bin/leantoken。

手动通过 stdio 运行 MCP 服务器：

leantoken --root /path/to/repo mcp

手动配置 MCP 客户端

{
"mcpServers": {
"leantoken": {
"command": "leantoken",
"args": ["--root", "/path/to/repo", "mcp"]
}
}
}

若使用 Cargo 分发，安装已发布的 crate，再让 MCP 客户端指向生成的可执行文件：

cargo install leantoken --version VERSION
leantoken --root /path/to/repo mcp

官方 MCP Registry 条目是 io.github.morluto/leantoken。支持 Cargo 包的 Registry 客户端可以安装对应版本的 leantoken，并使用上面展示的 mcp 命令。

安装选项

npm 包内置以下平台的原生二进制：

- ARM64 和 x64 上的 macOS
- ARM64 和 x64 上的 glibc Linux
- x64 上的 Windows

安装过程不运行 lifecycle script，也不通过 postinstall 钩子下载可执行文件。其他目标平台（包括 musl Linux）必须从源码构建。安装 Rust 1.95 或更高版本以及原生 C/C++ 工具链，然后运行：

cargo install --locked --git https://github.com/morluto/leantoken leantoken

更新

通过 npx 创建的 MCP 条目会固定到配置它们时所用的 LeanToken 版本，不会自动跟随。要更新已有的客户端集成，需要显式执行：

npx --yes leantoken@latest setup --refresh --yes

如果命令行是全局安装的，或者用 Cargo 安装：

leantoken upgrade --check
leantoken upgrade --yes

update 是 upgrade 的别名。如果 npm 包安装在项目本地：

npm install leantoken@latest

固定的 MCP 条目不会悄悄切到 @latest。本地和线上都找不到这个确切版本时，启动会直接失败，不会改选其他版本。更新命令行不会改动已有的 MCP 条目。回滚、缓存管理和版本细节见使用指南。

缓存管理

先查看本地仓库缓存，或在清理前预览结果：

leantoken cache list
leantoken cache list --summary
leantoken cache list --incompatible-with-current
leantoken cache prune --incompatible-with-current
leantoken cache compact --id v15-0123456789abcdef --dry-run
leantoken cache prune --older-than 30 --dry-run
leantoken cache prune --max-total-bytes 1073741824 --yes

缓存状态、分页和清理的安全规则见使用指南。

工作原理

repository
│
▼
file discovery ──► code structure extraction ──► local search index
│
▼
agent request ──► ranked / exact retrieval ──► focused code within a token budget

LeanToken 只索引一次源码，之后按需返回紧凑路径、排序后的匹配、结构大纲、精确源码区间和任务相关上下文。它不会在多轮对话中反复发送没有变化的证据。

依赖繁多的工程可以额外启用一个独立的、带缓存标识的第一方索引，默认的整仓库行为保持不变：

leantoken --index-include 'src/' --index-include 'tests/' index

状态输出和每次检索都会说明当前索引是完整索引还是限定范围索引，因此限定范围索引返回空结果时，绝不会被当成整仓库中不存在。范围边界、缓存标识和 MCP 注册示例见使用指南。

LeanToken 的目标是用更少的输入 token，返回智能体真正需要的代码。

文档

| 指南 | 内容 |
| 使用与工具参考 | 命令、MCP 工具、请求选项和示例 |
| 架构与可靠性 | 组件、数据流、存储和故障行为 |
| 路线图 | 当前方向和计划中的工作 |
| 开发与测试 | 本地环境搭建、验证和发布流程 |
| 基准测试方法 | token 经济性的测量与解读 |
| 测量工具集 | 实验、wire-cost 与性能分析工具 |

许可证

你可以任选以下一种许可证：

- Apache License, Version 2.0
- MIT License