LeanToken

LeanToken

为 Agent 提供代码智能：找到关键代码，让上下文窗口保持精简，节省令牌。

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

• MCP 注册表名称：mcp-name: io.github.morluto/leantoken

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

实测令牌节省量： 在一项受控的 60 次运行研究中，与 Agent 内置工具进行有限的仓库探索相比，LeanToken 使用的模型输入令牌减少了 20.1%；与这些工具进行广泛探索相比，减少了 37.6%。 查看测量方法，了解测量的具体方式。

快速开始

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

npx leantoken setup

重启或重新加载已配置的客户端，然后从代码仓库验证连接和首次 检索：

npx leantoken doctor

尝试一个范围较广的任务，例如：编辑前，查找与请求取消相关的代码。 LeanToken 可帮助 Agent 从 leantoken.context 开始， 同时仍可使用其常规工具进行编辑、构建和测试。

检查 LeanToken 观测到的仓库本地令牌用量统计：

npx leantoken savings

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

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

npx leantoken remove

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

npx --yes leantoken@latest setup --refresh --yes
npx --yes [email protected] 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。如果其他 Agent 需要一份 精简清单，其中包含所选哈希、变更路径、假设和已完成的验证，而不含复制的 源代码正文，请求 handoff。

这套单次调用约定适用于自主代码库分流，并不限制实现 Agent。在物化之前， 人工审查和控制平面工作流仍可通过 plan_only: true 预览成本较高或风险较大的 检索。 重复的多 Agent context 测试套件 发现，迭代式 LeanToken 配置的总输入量比精简原生方式多 50.9%，而冻结的 「一次 context 加可选的一次 search」配置节省了 20.1%，并在 20 次中有 15 次 取得路径集合成功。这些结果涵盖四项固定的分流任务，并不能证明存在普遍适用的 实现工作流。

明确的关注范围约束是一种契约。当请求提供 focus_paths、精确的 focus_symbols 和 minimum_fragments_per_focus_path 时，LeanToken 会在 文档规定的单文件范围内生成候选项；如果不同代码范围无法满足最低要求，则会 报告覆盖失败。Explain 配置文件计划和物化后的响应还会指出生成、预留、选中或 抑制每个关注候选项的有界分配边界，同时不改变排序。

为什么选择 LeanToken

大多数 Agent 一开始会广泛搜索并阅读整个文件。LeanToken 会分阶段缩小范围：

你的编码 Agent 仍负责编辑、命令、测试和对话。 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 传输封装不计入此源代码令牌预算； 测量边界请参阅令牌统计。

可用工具

目录有意保持精简，因为每个工具描述和架构定义也会占用模型上下文。

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 架构。该审计器在本地运行，范围受限，且不会修改输入。它会保留产物哈希，而不保留原始提示词、源代码、工具参数或工具输出。

npm install leantoken 会将命令安装到当前项目的 node_modules/.bin；它不会将 leantoken 添加到 shell 的 PATH。调用项目本地安装的命令时，请使用 npx leantoken、包脚本或 ./node_modules/.bin/leantoken。

通过 stdio 手动运行 MCP 服务：

leantoken --root /path/to/repo 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

安装不会运行生命周期脚本，也不会通过 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 安装的 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 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 的目标是用更少的输入词元，返回 Agent 所需的代码。

文档

许可证

可由你选择依据以下任一许可证授权：

• Apache License，版本 2.0
• MIT License