jahala/tilth

tilth – 为人类和AI智能体打造的智能代码阅读工具

它是什么 – tilth 是一个单二进制的命令行工具（也是一个MCP服务器），它使用 tree‑sitter 解析源代码，并允许你在不构建索引的情况下查询代码库的结构。它可以显示符号在哪里定义、谁调用了它们、文件依赖什么，甚至可以显示提交之间的函数级差异。

为什么对AI智能体很重要 – 大型语言模型通常依赖一系列廉价工具（glob → grep → read）来定位函数，然后必须阅读许多文件才能发现调用者或依赖关系。tilth 一步到位：它理解语法树，因此智能体可以立即获得精确的定义、调用图和文件级大纲，减少了工具调用次数和纯文本搜索产生误报的可能性。

---

核心能力

功能	获得的内容
文件大纲 / 节视图	小文件整体输出；大文件返回带有行范围块的结构化大纲。使用 --section 获取特定范围或 markdown 标题。
符号搜索	tilth <符号> --scope <目录> 首先查找定义，然后是使用位置，显示周围代码片段。--expand 添加顶部匹配项的来源；--full 提高匹配限制。
调用者和被调用者	--callers 列出所有调用点（结构上，不仅仅是文本匹配）。展开的定义包括 -- calls -- 页脚，显示它们调用的函数。
文件级依赖关系	tilth <文件> --deps 报告文件导入/使用的内容以及哪些其他文件导入它 – 在重构前非常方便。
grok	一次性命令，返回符号的签名、文档注释、主体、其被调用者、调用者、兄弟和相关测试。
结构化差异	tilth diff <提交> 显示添加/删除/更改的函数及行号，而不仅仅是原始差异。
MCP 服务器模式	通过 MCP 协议公开相同的功能，使 AI 智能体（Claude‑code、Cursor、Gemini 等）可以直接从其工具链调用 tilth_search、tilth_deps、tilth_grok 等。
编辑模式	使用 --edit，服务器还提供 tilth_write/tilth_read，可以使用哈希锚定的行引用来安全地编辑文件。

---

典型用例

• AI 辅助工具 – 将 tilth 插入 Claude‑code、Cursor 或任何兼容 MCP 的智能体，让模型无需编写自定义脚本即可询问“谁调用了 ServeHTTP？”或“recovery.go 中发生了什么变化？”。
• 开发人员导航 – 从终端快速定位函数定义、查看其调用图或了解文件的外部依赖关系。
• 代码审查和重构 – 生成提交之间的函数级差异，或验证重命名不会破坏调用者。
• 大型代码库 – 由于并行遍历语法树，在具有数千个文件（FastAPI、Gin）的项目上可在几十毫秒内工作。

---

安装和入门

# 通过 Rust 的包管理器
cargo install tilth
# 或使用 npm 的一次性二进制（捆绑编译后的二进制文件）
npx tilth

预构建的二进制文件也可在 GitHub 发布页面获得。

作为 MCP 服务器运行（大多数智能体使用的模式）：

tilth --mcp            # 启动服务器
# 为智能体安装客户端配置，例如：
tilth install claude-code   # 写入 ~/.claude.json

服务器可以用 --edit 启动以启用安全的文件编辑功能。

---

架构概览

• 语言解析 – 使用 tree‑sitter（支持17种语言）为每个文件构建内存中的语法树。没有类型解析，仅进行结构分析。
• 搜索引擎 – 将 tree‑sitter 查询（用于定义、调用者、被调用者）与 ripgrep crates 结合，用于纯文本/正则表达式/glob 搜索。
• 并行处理 – 目录遍历（ignore crate）和符号查找通过 rayon 并行化，在中型仓库上提供亚100毫秒的响应时间。
• 缓存 – 大纲缓存（通过 DashMap）在文件修改时间更改时失效，保持重复查询快速。
• 零运行时依赖 – 二进制文件是纯 Rust（约 3.5 万行），不进行网络调用，确保所有代码保持本地。

---

限制

• 无类型推断 – tilth 纯粹基于语法工作；它无法解析泛型类型或重载。
• 仅按名称匹配调用者 – 如果不同模块中有两个同名的函数，调用者可能不明确。
• 语言覆盖范围 – 只有具有 tree‑sitter 文法的语言得到完全支持；其他语言回退到纯文本搜索。
• 动态分发 – 通过反射或运行时代码生成调用的函数不会被检测到。

---

许可证和社区

• 许可证： MIT – 宽松许可，适合商业和开源项目。
• 支持： 作者接受通过 Buy‑Me‑A‑Coffee 捐款；问题和功能请求在 GitHub 上处理。

---

TL;DR

tilth 为 AI 智能体（和开发人员）提供快速、无索引、语法感知的代码库视图：搜索定义、追踪调用图、检查文件依赖关系，并查看函数级差异——全部来自一个小型 Rust 二进制文件或 MCP 服务器。它弥合了原始 grep 风格工具和重量级语言服务器之间的差距，使代码理解工具更加高效和可靠。