一个关于“看懂代码”的小工具

最近做了一个开源项目，叫 RepoMind。

一开始做它的原因其实很简单：我发现现在很多 AI 编程工具都在帮我们“写代码”，但在真实开发里，很多时候更痛苦的不是写代码，而是先把一个陌生项目看懂。

尤其是接手老项目的时候，打开仓库第一眼经常是懵的。

目录很多，配置很多，业务代码也很多。README 可能写得很简单，甚至已经过期。你想知道这个项目到底是干什么的，接口在哪里，数据库模型在哪里，核心流程怎么走，可能要翻很多文件。

这个过程很耗时间。

所以我就想，能不能做一个工具，让开发者第一次进入一个项目时，先快速拿到一份“项目理解报告”。

这就是 RepoMind 的出发点。

我真正想解决的问题

现在大家都在用 Codex、Claude Code、Cursor 之类的 AI Coding 工具。

这些工具很强，但我自己用下来有一个感受：如果它们没有足够好的项目上下文，回答就容易变得很泛。

比如你问：

订单是怎么创建的？

它可能会去猜，也可能会找错文件。

但如果你先告诉它：

• 项目有哪些模块
• API 路由在哪里
• 数据库模型有哪些
• 哪些函数之间有调用关系
• 哪些文件更可能是核心业务

那它的回答质量会好很多。

所以我不想再做一个聊天框，也不想做一个“自动帮你改代码”的 Agent。

我更想做的是中间这一层：

先把仓库看懂，再让人或者 AI 去处理问题。

这也是 RepoMind 的核心定位。

它不是为了生成代码，而是为了理解已有代码。

为什么叫 RepoMind

我给它取名 RepoMind，是因为我希望它像是一个仓库的“大脑索引”。

你给它一个本地项目，或者一个 GitHub 仓库，它能尽量快速地告诉你：这个项目大概是什么，技术栈是什么，API 在哪里，数据库模型有哪些，调用链是什么样的，哪些文件值得优先看。

最理想的体验是：

repomind analyze .

然后几十秒内得到一份可以读的报告。

不需要先打开一堆文件，也不需要先问 AI 很多轮问题。

为什么用 Go 做

这个项目我选择用 Go 来写。

主要原因不是 Go 有多“高级”，而是它很适合做这种 CLI 工具。

我希望 RepoMind 最后是一个很简单的命令行工具。用户下载之后，不需要安装复杂环境，也不需要启动服务，直接执行就能用。

Go 编译出来是单文件，跨平台也方便，Windows、macOS、Linux 都能比较容易分发。

另外，仓库扫描对速度也有要求。如果一个工具本身启动很慢，扫描又慢，那“30 秒理解项目”这个目标就没有意义了。

所以 Go 在这里比较合适。

做的过程中，我逐渐明确了一件事

刚开始想做 RepoMind 的时候，很容易想到“要不要直接接 AI，让 AI 总结整个仓库”。

但真正开始做之后，我发现不能完全依赖 AI 总结。

因为 AI 总结如果没有结构化信息支撑，很容易变成看起来很顺，但不一定准。

所以 RepoMind 现在的思路是：

先做静态分析，再做总结。

它会先扫描仓库，识别配置文件、依赖、目录结构、路由、数据库模型、调用关系，然后再生成报告。

也就是说，AI 可以参与总结和问答，但底层最好还是要有来自源码的证据。

这也是我觉得这个项目比较重要的地方。

它不是简单地把代码丢给大模型，然后让模型随便总结一下。

它更像是先把代码仓库拆开，整理成结构化上下文，再交给人或者 AI 使用。

最终实现了什么

目前 RepoMind v1.0 已经做到了一个相对完整的第一版。

它可以分析本地仓库：

repomind analyze .

也可以分析 GitHub 仓库：

repomind analyze https://github.com/owner/repo.git

分析完成后，会生成一份报告，包括：

• 项目总结
• 技术栈识别
• API 路由
• 数据库模型
• 调用图
• Mermaid 图
• HTML 报告
• 给 AI Coding 工具用的上下文文件

同时也支持中文和英文输出。

除了分析之外，还做了几个辅助命令。

比如 ask，可以问项目里的问题。

比如 trace，可以看一个函数后面调用了什么。

比如 diagnose，可以围绕一个问题去找可能相关的状态修改、数据库写入和调用点。

这些能力不是为了替代开发者，而是为了帮开发者更快定位代码。

我比较看重的一个边界

RepoMind 有一个边界我一直想守住：

它默认不生成业务代码。

现在很多工具都在强调“让 AI 帮你写代码”，但我觉得在已有项目里，写代码之前更重要的是理解。

你不知道项目怎么组织，不知道业务流程怎么走，不知道数据在哪里改，直接让 AI 改代码其实风险很高。

所以 RepoMind 更像是给开发者和 AI 工具准备上下文。

它可以帮你更快知道项目是什么样子，但最终怎么改，还是应该由开发者判断。

这个边界对我来说挺重要。

和 Codex、Claude Code、Cursor 的关系

我并不觉得 RepoMind 要替代这些工具。

相反，它更适合配合这些工具使用。

我的想法是：

RepoMind 先把仓库整理清楚。
Codex、Claude Code、Cursor 再基于这些上下文去回答问题或者辅助修改。

这样会比直接把一个陌生仓库丢给 AI 更稳定。

比如 RepoMind 可以生成：

• architecture.md
• api-map.md
• db-schema.md
• context.md

这些文件本身就是比较好的 AI 上下文。

v1.0 做到什么程度

为了验证它不是只能跑 demo，我给 v1.0 做了一轮比较完整的 release gate。

里面包含了：

• 本地仓库分析
• GitHub 仓库分析
• 中英文报告
• API、数据库模型、调用图检查
• ask、trace、diagnose 检查
• 20 个真实开源仓库评估
• 安全边界检查
• CI 和 release workflow
• 多平台 release 包

目前代表性仓库的分析时间都远低于 30 秒。

这说明至少第一版的方向是跑通了。

当然，它还不是完美的。

不同语言、不同框架的项目写法太多了，Parser 覆盖肯定还需要继续增强。

但作为 v1.0，我觉得它已经完成了最核心的闭环：

输入一个仓库，输出一份有用的项目理解结果。

后面还想继续做什么

后续我比较想继续加强几个方向。

一个是 PHP、Java、Go 这些项目的解析能力。

这些语言在真实业务系统里很多，框架和写法也比较复杂。

另一个是调用链和业务流程分析。

比如支付成功之后发生了什么，订单状态在哪里改变，余额在哪里扣减，这些问题如果能回答得更准，会很有价值。

还有就是和 AI Coding 工具的结合。

不是做成一个新的聊天工具，而是把 RepoMind 生成的上下文变得更适合 Codex、Claude Code、Cursor 使用。

最后

做 RepoMind 的过程，其实也是我重新思考 AI Coding 工具链的过程。

现在大家都很关注“AI 怎么写代码”。

但在我看来，真实开发里还有一个更基础的问题：

AI 和人都需要先看懂项目。

如果项目没看懂，后面的修改、重构、排 Bug 都容易出问题。

RepoMind 想做的就是这一步。

它不是一个很炫的工具，也不是万能 Agent。

它只是想把一件朴素但重要的事情做好：

帮开发者更快理解一个陌生代码仓库。

项目地址：

https://github.com/patrick892368/RepoMind

希望有大佬和小伙伴们可以提一些issue、建议