代码检索精简器morluto/leantoken

LeanToken

面向智能体的代码智能：找到关键代码，让你的上下文窗口和 token 保持精简。

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

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

npm
npm downloads
Rust 1.95+
License: MIT OR Apache-2.0

安装 · 为什么选择 LeanToken · 工具 · CLI · 工作原理 · 文档

实测 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 是推荐的启动器：它会将
包原生的可执行文件精确复制到 LeanToken 的版本化应用程序数据
目录中，以便客户端直接启动一个经过验证的进程，而无需持久化的
npm/Node 包装器。它仍然是可选的，因此零安装路径不会增加
应用程序数据写入。使用 --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. 无需重新发送源代码即可继续。 在下次上下文调用时传入之前的 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 预览昂贵或高风险的检索。
重复多代理上下文套件发现，迭代式 LeanToken 配置比精简原生配置多使用了 50.9% 的总输入，而冻结的单上下文加可选单次搜索配置节省了 20.1%，并取得了 15/20 的路径集成功率。这些结果覆盖四个固定的分诊任务；它们并不能证明存在通用的实现工作流。

显式焦点约束是契约。当请求提供 focus_paths、精确的 focus_symbols 和 minimum_fragments_per_focus_path 时，LeanToken 会在文档化的每文件边界内生成候选，并在不同范围无法满足最小值时报告覆盖失败。Explain-profile 计划和已物化响应还会识别出有界分配边界，该边界生成、保留、选择或抑制了每个焦点候选，而不改变排名。

为什么选择 LeanToken

大多数代理会先广泛搜索并阅读整个文件。LeanToken 分阶段缩小这项工作：

| 典型的仓库探索 | 使用 LeanToken |
| --- | --- |
| 扫描宽泛的目录列表 | 在紧凑树中查找相关路径 |
| 阅读整个文件以查找结构 | 查看定义和导入，而无需加载整个文件 |
| 在每一轮之后再次发送相同代码 | 避免重复未更改的证据 |
| 让大文件填满请求 | 将返回的源代码保持在精确的源令牌预算内，并单独报告响应开销 |
| 猜测哪些文件重要 | 为任务对可能相关的代码进行排名 |

你的编码代理仍然负责编辑、命令、测试和对话。LeanToken 查找并返回这些任务所需的代码。
LeanToken 不会创建一个巨大的提示文件。它按需回答聚焦的搜索，并供 agent 读取。

示例

对于像修复关闭期间的请求取消这样的任务，一个有界的示例结果可能如下所示：

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

agent 接收这些范围，而不是两个完整文件。如果预算太小，响应还会说明被省略的内容。路径、分数、回执、JSON 和 MCP 传输包装器不属于此源 token 预算；有关测量边界，请参见token 核算。

可用工具

| 工具 | 用途 |
| --- | --- |
| leantoken.context | 用于自主广泛分诊的默认物化首次调用；供人工或控制平面审查的可选预览。 |
| leantoken.search | 优先于 grep/rg 进行排序搜索；穷尽式文本/正则调用可以显式记录或复用完整查询覆盖。 |
| leantoken.files | 优先于 find/ls/glob 进行紧凑、感知忽略规则的路径发现。 |
| leantoken.outline | 无需读取整个文件即可检查定义、签名、导入和范围。 |
| leantoken.read | 优先于 cat/head/sed 读取一个精确符号或包含端点的行范围。 |
| leantoken.history | 跨不可变 Git 修订读取、批量差异比较或追踪已解析符号。 |
| 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 也会消耗模型上下文。

CLI 用法

通过 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、包脚本或 ./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 包的注册表客户端可以安装匹配的 leantoken 版本，并使用上面显示的 mcp 命令。

安装选项

npm 包包含适用于以下平台的原生二进制文件：

- macOS（ARM64 和 x64）
- glibc Linux（ARM64 和 x64）
- Windows（x64）

安装过程不会运行生命周期脚本，也不会通过 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

对于全局安装的 CLI 或使用 Cargo 安装的 CLI：

leantoken upgrade --check
leantoken upgrade --yes

update 是 upgrade 的别名。对于项目本地的 npm 安装：

npm install leantoken@latest

固定版本的 MCP 条目绝不会静默切换到 @latest。如果本地或在线均无法获取该确切包，启动会失败，而不是选择其他版本。更新 CLI 不会改变现有的 MCP 条目。有关回滚、缓存管理和版本详情，请参阅使用指南。

缓存管理

在应用清理之前，检查本地仓库缓存或预览清理操作：

leantoken cache list
leantoken cache list --summary
leantoken cache list --incompatible-with-current
leantoken cache prune --incompatible-with-current
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 返回 agent 所需的代码。

文档

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

许可证

根据以下任一许可证授权，由您选择：

- Apache License, Version 2.0
- MIT License