先说三个备选标题，你挑顺眼的
写之前我一般会先把标题列几个，方便自己判断到底要讲什么。这次给代码仓建索引这个话题，我排了三个：
- AI改老代码总瞎猜文件位置？给代码仓建索引这步别省
- 给代码仓建索引，我劝你先别急着上 ai-ready
- 让AI改老项目前先看懂目录：给代码仓建索引的最小可跑方案
下面正式聊。
那天我把一个陌生老仓库丢给 AI，它开始瞎编
上个月我接手一个别人写了两年多的后端仓库，想加一个不算复杂的功能：给登录流程补一段风控校验。我图省事，直接把需求丢给 AI，让它「找到登录逻辑，加个校验」。
结果它先是猜文件——张口就说逻辑在 `auth/login.py`，可这个仓根本没有 `auth` 目录，登录是散在 `services/user_service.py` 和一个叫 `middleware/gate.py` 的中间件里的。它不知道，于是新建了一个文件，把一套它自己想象的登录逻辑重新写了一遍。
风格也对不上，人家全项目用的是依赖注入，它给我塞了一堆全局单例。
我当时的第一反应是「模型太笨」，后来想明白了：不是它笨，是它压根没看过这个仓库长什么样。它看到的只有我给的那几句话，剩下全靠猜。
你让一个新人不看代码就改代码，他也这样。
这件事逼着我去想一个更前置的问题：**能不能先让 AI 把仓库看懂，再让它动手。**
社区那个提问，其实戳中了同一个痛点
我不是唯一被这事卡住的人。前几天刷到有人问「有没有 skill 或者 AI 工具对代码仓建立索引」，说想让 AI 根据仓库结构建个索引或知识库，多人开发时更新新代码就建新索引，问新功能时直接用索引快速生成符合仓库结构的代码。
他也提到搜到了 ai-ready、reposummary 这类现成东西，在纠结用哪个。
楼下有人回了个 sense codegraph（这几个工具的具体能力我没逐一验证，属于待核实）。但我看到这个提问的第一感觉是：**这哥们儿要的东西，比他以为的简单。
**
他真正想解决的，不是「有没有一个牛逼工具」，而是「AI 动手前先知道这个仓库里什么在哪、谁调谁、风格怎么样」。这个需求，独立开发者自己拼一个最小版本,反而比上一套重工具更顺手。
我的判断：别急着上重工具，先拼一个能跑的
说个可能有点反直觉的观点：对独立开发者和小团队来说，ai-ready、reposummary 这类现成方案往往「太重了」。
重工具的问题不在于差，而在于它替你做了一堆决定——按它的规则切块、按它的格式存、按它的接口查。你的仓库结构一旦有点非主流,它给出的索引就不一定贴合你要问的问题。
而且你还得先学它、配它、伺候它更新，活没干先交一遍配置税。这点我特别有共鸣,社区里那个做 Neovim 子会话插件的作者也吐槽过类似的事——「要提前配好一堆模板才能开工,活还没干先交配置税」。
代码索引这东西的内核其实就三步：遍历仓库、切块解析、存起来能语义检索。这三步用 VicroCode 上已经有的能力就能拼齐,而且每一步你都看得见、改得动。
我更信「自己拼的、能肉眼核对的最小方案」,而不是「一个我不知道它内部怎么切块的黑盒」。
下面是我实际的落地路径,顺便说清楚哪些是平台确认能做的,哪些是我自己的判断。
第一步：遍历仓库 + 按文件和函数切块
第一件事是把仓库「拆开」。用脚本递归遍历所有源码文件,再按文件和函数两个粒度切块——一个文件是一块,文件里每个函数、每个类也各自成块。
切块的时候顺手把元数据记下来:文件路径、所属模块、函数名、大概在第几行。
这一步我是直接在平台里跑的。 VicroCode 的Python在线运行能力可以让你不用在本地折腾环境,写个遍历加解析的脚本当场就能验证切出来的块对不对。
我第一版切得很糙,函数体太长的直接被截断了,是跑了几次看输出才慢慢调好的粒度。这种边写边看的调试,在线跑比来回配本地环境省心不少。
提醒一句边界:平台确认支持的是 Python 在线运行,以及用 Python 构建站内工具和后端能力。所以我这套遍历解析脚本是用 Python 写的。
如果你的仓库要靠某个特定语言的语法树工具才能精确解析,那部分能不能在平台内完成,你得先自己确认,别默认它啥语言都能跑。
第二步：元数据写进 SQLite，方便肉眼核对
切完块,我把每一块的元数据——路径、模块、函数名、行号、块类型——写进一张表。这一步很多人会跳过,直接把所有东西塞向量库。
我踩过这个亏:全塞向量库之后,一旦检索结果不对,你根本不知道是切块错了、还是元数据错了、还是检索本身的问题,黑箱一团。
所以我坚持先落一张结构化的表。 VicroCode 提供 SQLite 数据库和数据库编辑能力,我用SQLite编辑器直接把表打开,一行行看:登录相关的块到底被归到哪个模块了、路径对不对、有没有整段函数丢失。
肉眼扫一遍表结构,比盲信检索结果踏实太多。
这张表还有个好处:它本身就是一份「仓库地图」。哪怕不做语义检索,光是能一眼看到「登录逻辑分布在这三个文件里」,就已经能帮 AI 少猜很多。
第三步：语义向量塞进 LanceDB，问「登录逻辑在哪」能直接命中
光有元数据表还不够,你没法用自然语言去问它。真正让 AI「看懂」的是语义检索这一层——把每个代码片段转成向量存起来,之后你问「登录逻辑在哪几个文件」,系统靠语义相近度把最相关的几块捞出来,而不是靠关键词硬匹配。
这一层我用的是平台的LanceDB知识库。把切好的代码片段连同它的语义向量存进去,查询的时候用一句话就能命中。
我实测下来,问「风控校验在哪做的」,它能把那个中间件 `gate.py` 捞出来,这是关键词搜根本搜不到的,因为文件名里压根没有「风控」两个字。
社区里那个做本地 Markdown 知识库工具的作者也走了类似的路子——内置语义检索做全局内容检索。思路是相通的:结构化数据负责精确核对,语义向量负责模糊命中,两条腿走路。
把这三步拼起来,一个最小可跑的代码索引就成了。之后再让 AI 改代码,我会先用它把相关文件和函数捞出来喂过去,再让它动手。
**「先看懂仓库、再动手」这一步,是整套方案里最值钱的部分**,前面那些遍历、切块、存储,本质都是为这一步服务的。
多人协作:别每次全量重建,做增量更新
社区那个提问里还有句话我很认同:多人开发时,更新新代码就建新索引。但「建新索引」不等于「每次全量重建」——仓库大了之后全量重建又慢又费。
我的做法是做增量:每次提交后,只对改动过的文件重新切块、更新元数据表里对应的行、替换掉向量库里那几块的向量。判断哪些文件变了,可以靠文件的哈希值或修改时间,存在 SQLite 那张表里比对就行。
这个增量思路,跟社区里那个照片备份工具讲的「自动增量传输」是一个道理:只动变化的部分,别每次推倒重来。
多人协作还有个隐藏好处:索引一旦建好,新来的同事让 AI 改代码时,AI 也能借这份索引快速摸清仓库结构,不用每个人都在心里重建一遍地图。
一个你今天就能做的小动作
如果你手上正好有个结构陌生的老仓库,别急着让 AI 大改。今天可以先做一件小事:写个几十行的 Python 脚本,只遍历仓库、把每个文件的路径和它导出的函数名列出来,存成一张表看看。
就这么一步,你会立刻发现自己对这个仓库的结构其实一知半解——而这恰恰就是 AI 之前一直在瞎猜的原因。把这张最基础的地图先做出来,后面的语义检索是自然而然的延伸。
先让它看懂,再让它动手,顺序别反了。