代码库地图如何构建:符号、分层、token 预算

解析,而不是猜测

地图的好坏取决于解析器。ContextBridge 用 tree-sitter——代码编辑器使用的同一套增量解析器家族——编译你的代码,它以 WebAssembly 形式在你的浏览器标签页内运行,覆盖 15 种语言。每个符号都来自真实的语法树,所以行号范围是精确的,而不是估计的。

这种精确有刻意的边界:超过 512 KB 的文件会被截断,二进制文件被跳过,依赖树、构建产物和锁文件在解析前就被剪掉。硬上限是 4,000 个文件——这个数值是为了让分析在笔记本上几秒完成,而不是几分钟。

分层、枢纽、入口点

在符号表之上,分析器进行分类。文件聚合成层——API、服务、数据、UI、基础设施——由路径、导入和命名推断而来。被导入最多的文件浮出为枢纽;引导文件、main 和路由表浮出为入口点。这是一个真实(小型)示例项目的分层表,逐字摘自生成的地图:

| Layer         | Files | Lines | Notable                               |
|---------------|-------|-------|---------------------------------------|
| Core          | 4     | 60    | order-repo.ts, server.ts              |
| API Layer     | 3     | 53    | orders.ts, customers.ts, routes.ts    |
| Service Layer | 2     | 50    | order-service.ts, customer-service.ts |
| UI Layer      | 2     | 23    | order-list.tsx, format.ts             |
| Data Layer    | 1     | 13    | 001_init.sql                          |
| Test Layer    | 1     | 8     | order-service.test.ts                 |

token 预算决定什么能留下

每份产物都是按照你选择的 token 预算生成的——从快速草图到不设上限的完整输出。排序器根据与你所述问题的相关性(带跨语言术语扩展,所以用越南语或中文提问也能匹配英文代码)以及结构重要性(枢纽、入口点、命中符号的导入路径上的文件)给文件打分。

装不下的内容不会被悄悄丢弃:产物会列出它省略了什么,并在开头说明自身的局限。一份承认自己边界的预算地图,对你和对模型,都比一份隐藏边界的无上限输出更有价值。

静态分析无法知道的事

在这里,诚实比炫技更重要。静态地图永远看不到运行时行为:依赖注入的实现、反射、动态分派、特性开关、按环境变化的接线,对它都不可见。层标签是启发式的,而在喜欢打破约定的代码库里,启发式会出错。

所以,请把地图当作它本来的样子:定位参考,而不是绝对真相。生成的产物也围绕同一理念构建——它们指示模型根据所得结构作答、点名自己没有的文件、绝不虚构实现。一份被允许说「我不知道」的地图,才是一份你可以信任、能告诉你下一步该看哪里的地图。