Token Savior代码实现原理:tree-sitter符号索引如何让find_symbol比grep省99.9%字符
Token Savior代码实现原理:tree-sitter符号索引如何让find_symbol比grep省99.9%字符
Token Savior 是一个面向 AI 编码助手的 MCP server,它用 tree-sitter 构建符号索引(函数、类、import、调用图),让 find_symbol 一次调用只回传 67 个字符的"指针式"答案,而不用像 grep + 读文件那样吞掉数千万字符。本文带你拆开它的索引器、注解器和查询路径,看懂这 99.9% 的字符节省是怎么来的。
一、先看账本:99.9% 是怎么省的
官方基准里最直观的一组数据(见 README.md):
| 操作 | 朴素方式 | Token Savior | 减少 |
|---|---|---|---|
find_symbol("send_message") |
41M 字符(全文读) | 67 字符 | -99.9% |
get_function_source("compile") |
grep + cat 链 | 4.5K 字符 | 直达 |
配合符号索引 + 持久记忆引擎,整体任务完成度从 78.3% 提到 97.9%(188/192),单任务活跃 token 从 17 221 降到 3 395(-80%),墙钟时间 -83%。
关键不在"压缩输出",而在换了一条找代码的路:grep 是"扫全文找字符串",符号索引是"查表拿坐标"。
二、索引怎么建:索引器的三步流程
入口在 project_indexer.py,index() 方法干三件事:
- 发现文件:单次
os.walk()遍历项目,按 include/exclude glob 过滤(默认排除 node_modules 等); - 并行注解:每个文件读入源码后交给统一的 dispatch 注解器,线程池最多 32 个 worker 并行解析,同时记录
mtime供增量重索引; - 建三张全局表:
- 符号表
symbol_table:qualified_name -> file_path的映射,find_symbol的 O(1) 入口; - import 图 + 反向 import 图:文件间依赖;
- 全局依赖图:合并每个文件内部的依赖,跨文件引用通过符号表解析。
- 符号表
每个文件解析后的产物是一个 StructuralMetadata(定义在 models.py):函数列表、类列表、import、行范围、以及每个符号的 body_hash——哈希用于判断"函数体改没改过",是后续缓存与"破坏性变更检测"的基础。
三、tree-sitter 在哪:注解器分层设计
真正"看懂"代码的是注解器层。annotator.py 维护一张扩展名 → 注解器的调度表,覆盖 23+ 种语言(.py、.java、.ts、.go、.rs、.sh……)。各语言按"性价比"选了解析策略:
| 策略 | 语言 | 原因 |
|---|---|---|
| tree-sitter | Java、Ruby | 语法复杂、正则难以覆盖嵌套结构 |
| 语言原生 AST | Python | 标准库 ast 零依赖且足够完整 |
| 结构化/正则注解器 | Go、Rust、TS/JS、C、YAML、JSON、Shell 等 | 目标语言特征明显,轻量规则即可提取符号 |
以 Java 为例,java_annotator.py 的用法很典型:
- 第 21 行
Language(tree_sitter_java.language())加载语法; - 然后按节点类型(node kind)遍历语法树:
class_declaration、interface_declaration、record_declaration归为类,method_declaration、constructor_declaration归为方法; - 每个节点自带精确的行号区间,于是
FunctionInfo天然携带line_range、参数列表、装饰器/注解、docstring。
Python 走 python_annotator.py:_extract_function_info() 从 ast.FunctionDef 提取名字、限定名、行范围(含装饰器行)、参数(自动跳过 self/cls)、docstring,还会用 _detect_scaffold() 判断函数体是"桩"(pass/.../docstring)还是真实实现——这种结构信息 grep 永远给不了。
💡 tree-sitter 的核心价值是容错 + 结构化:即使文件有语法瑕疵也能尽量解析出树,且节点边界精确到字符,这是正则按行猜结构做不到的。
四、find_symbol 查询路径:名字到 67 字符
查询实现在 query_api.py 的 find_symbol(),MCP 侧入口是 code_nav.py(_q_find_symbol,支持一次批量最多 10 个名字)。路径只有三步:
- 查符号表:
index.symbol_table[name]直接命中定义所在文件,不用扫任何源码; - 在该文件的元数据里定位:遍历
meta.functions/meta.classes/cls.methods,匹配名字或限定名,取出LineRange和签名; - 按 level 裁剪输出:
level=0:完整返回{file, line, type, signature, source_preview};level=1:去掉源码预览;level=2:只剩{name, file, line, type}极简形式。
典型返回就长这样(67 字符量级):
{"name": "send_message", "file": "lib/mailer.py", "line": 142,
"type": "function", "signature": "def send_message(to, body)", "complete": true}
几个容易忽略的健壮性设计:
- 同名符号不装瞎:若同名函数在多个文件定义,返回里会带
autres_definitions和提示"请传file_path消除歧义"——实测事故(同名createSignatureRequest落在两个库里)驱动的修复; - 变量兜底:函数/类没命中时自动回落到模块级常量(
kinds未显式指定时),trouve_par: "repli sur les variables"会如实说明; - 未命中也说清楚:返回实际搜索过的项目和文件数,避免 agent 把"查错了项目"误判成"符号不存在"。
对比 grep:grep -rn "send_message" 会返回所有引用点(调用、字符串、注释),且是原始文本,agent 还得挨个 Read 文件才能分辨哪个是定义——41M 字符就是这么来的。而符号表里存的只有定义,坐标精确到行。
五、想读源码?按这条线走
| 模块 | 相对路径 | 看点 |
|---|---|---|
| 索引主流程 | project_indexer.py | 文件发现 → 并行注解 → 三张全局表 |
| 注解器调度 | annotator.py | 扩展名到解析策略的分派表 |
| tree-sitter 注解器 | java_annotator.py | 节点类型驱动的符号提取 |
| Python 原生 AST | python_annotator.py | 函数信息提取 + 桩/实现分类 |
| find_symbol 查询 | query_api.py | 符号表命中、同名歧义、变量兜底 |
| 语义检索扩展设计 | docs/design-semantic-code-tools.md | 在符号索引之上叠加向量检索的草案 |
| 依赖声明 | pyproject.toml | tree-sitter、tree-sitter-java、tree-sitter-ruby 版本约束 |
六、一句话总结
find_symbol 省掉的不是"字符",而是探索成本:索引器提前把整个仓库解析成语义结构,tree-sitter 负责从语法树里精确切出每个符号的名字、坐标和签名;查询时一次表命中直达答案,agent 拿到指针后只读那一小段。这就是"结构化导航替代全文扫描"的全部秘密。