GitNexus + MCP 实战记录理解整个项目

先说结论：如果你项目已经大到 AI 经常「改对文件、改错影响面」，值得花十分钟把 GitNexus 接上。不是又一个 Copilot 插件，是给 Cursor / Claude Code 补一层「仓库结构感」。

下面是我这段时间用下来的体会，结合 Android 多模块场景写的。安装命令会写，但重点不在这——我更想聊它到底解决了什么、和普通 RAG 差在哪。

一、翻车现场：AI 不是不会写，是不知道自己在动哪

我自己用 Cursor 改小函数，体验一直不错。直到仓库上到几十万行，开始频繁出现这种对话：

我：帮我把 UserService 的返回值改一下。 AI：好的，已修改 UserService.java。 但它根本不知道： UserService ├── 被 23 处直接调用 ├── 影响 5 个对外接口 ├── 改返回结构会让 3 个页面挂 └── 还有个定时任务偷偷依赖它的副作用

编译过了，合码了，测试漏了一角，线上才炸——维护过大型 App 或多模块项目的应该不陌生。

我后来想明白了：这不一定是模型变笨了，是上下文给错了。多数 AI IDE 默认就这么干：

你的问题 ↓ 搜关键词 / 向量（grep、BM25、embedding） ↓ 捞一堆「看着像相关」的片段 ↓ LLM 靠片段猜调用关系 ↓ 开改

三个坑我反复踩：

1. 隐藏依赖找不到。反射、接口实现、EventBus、跨模块 import，关键词根本串不起来。
2. 调用链拼不对。搜到startActivity≠ 知道 Activity 怎么一路启动到入栈。
3. 改之前不问影响面。没有「动这里会波及谁」，PR 里就容易出现「本地能编、线上炸」。

所以我现在觉得：生成代码已经够用了，真正缺的是对整个仓库的结构理解。这也是我 Agent 工程系列里一直在补的 Knowledge 层——跟 Rules、Skills、MCP、Workflow 是一套的，不是多装个插件就完事。

二、GitNexus 到底是啥（说人话版）

官方叫 Code Intelligence Engine。我翻译成人话就是：

在你电脑上把 Git 仓库「读透」，建成一张可查询的关系网，再通过 MCP 塞给 AI，让它改代码前先搞清楚谁调谁、改动会波及哪。

索引和查询都在本地，代码默认不上传——这点对我很重要。

它也不是「帮你自动生成仓库 Wiki」那路子。文档生成解决的是「读得懂」；GitNexus 解决的是「改之前心里得有数」：谁调用它、改签名会炸哪、某条业务链路从哪进从哪出。

没索引时，AI 眼里就是碎文件

A.java B.kt C.go ↓ ↓ ↓ 一坨扁平文本片段

索引之后，至少能问这些

UserRepository | UserController ---- UserService ---- Database | PaymentService

除了「有个 UserService.java」，还能查：

• 谁调它（upstream）
• 它调谁（downstream）
• 改它的影响面（blast radius）
• 它在哪条执行流里（Process）

一张图看懂分工

你负责拍板，AI 负责改码，GitNexus 负责把仓库里的「结构真相」摊开。底层具体用啥存储，版本可能会变，别和某个产品名绑太死就行。

CLI 还是网页？

我基本不用 Web UI 写代码。下面第四、五章讲怎么接、怎么用。

三、它背后在干啥（不用背，知道个大概就行）

索引流水线

Git 仓库 ↓ Tree-sitter 解析（多语言 AST） ↓ 抽符号（类、函数、import…） ↓ 建依赖图（CALLS、IMPORTS、EXTENDS…） ↓ 聚类 + 追执行流 ↓ 本地知识图谱 ↓ MCP 暴露给 Cursor / Claude Code

语法分析靠 Tree-sitter，Java、Kotlin、Go、TS、Python 这些我都见过能扫。落成本地图谱，本地查。存储实现以后可能会换，但「符号 + 关系 + 本地能查」这层意思不会变。

举个最小例子

classUserService{UsergetUser(Stringid){returnrepository.findById(id);}}

索引完图谱里大概长这样：

Class: UserService └── Method: getUser(String) └── CALLS → repository.findById

常见边就记几个：CALLS（调用）、IMPORTS（导入）、EXTENDS/IMPLEMENTS（继承实现）、STEP_IN_PROCESS（在某条执行流里）。

OrderController → OrderService → PaymentService这种关系，索引时就建好了，不是聊天时让 AI 猜的。

为啥我说普通 RAG 搞不定 Activity 启动？

这事 Android 老手应该特别有共鸣。你问启动流程，RAG 经常给你：

搜 ActivityTaskManager 返回： ActivityTaskManager.java ActivityStarter.java ActivityRecord.java …再来几个「看着像」的 然后 AI 自己猜顺序、猜跨进程边界。

GitNexus 用trace/ Process 能拉出类似这样的链：

Activity.startActivity │ CALLS Instrumentation.execStartActivity │ CALLS ActivityTaskManagerService.startActivity │ CALLS ActivityStarter.execute │ CALLS ActivityRecord（创建与入栈）

一边是「文本像不像」，一边是「调用方向指没指对」。Framework 这种跨进程链路，我信后者。

顺带一提：索引可以加--pdg，给explain、pdg_query用。但别指望它当 CodeQL 使——GitNexus 主业还是关系图谱、影响分析、给 Agent 补上下文。安全审计顶多辅助，日常 Android 开发我压根不开--pdg。

聚类和执行流：省得 AI 在图里瞎逛

符号一多（几万、十几万），把裸图扔给 LLM 自己逛，又慢又漏。

所以索引时还会：把强耦合模块打成 Cluster；把跨文件的入口到出口串成 Process。

你问 Agent 的时候，它拿到的往往是现成的结构，比如：

• impact(...)→ 谁调用了你、风险大概多高
• query("用户登录")→ 按 Process 分组的相关符号
• trace(Activity.startActivity → ActivityRecord)→ 最短调用路径

跟普通 Graph RAG 的差别：结构提前算好，问的时候一次给齐，少几轮「你再帮我搜一下 XXX」。

四、Android 大项目怎么接（我实际就这么干的）

电商 App、音视频、自家中间层——共同点都是模块多、链路深。我现在习惯先建图谱，再放 Agent 进场，比一上来@codebase全仓扔进去稳多了。

就两条命令起步

仓库根目录：

npx gitnexus analyze# 建索引；Claude Code 还会顺带生成 AGENTS.md / hooksnpx gitnexus setup# 写 MCP 配置给 Cursor / Claude Code

跑完会有.gitnexus/目录，根目录多AGENTS.md、CLAUDE.md，告诉 Agent 该怎么用这些工具。

以后改了大批代码，增量索引：

node.gitnexus/run.cjs analyze

run.cjs会自动选全局 gitnexus、pnpm dlx 或 npx，省得每次手敲一长串。

多模块 App 大概长这样

下面是一个常见的 Android 分层示意（类名模块名为通用结构，不是某个具体项目）：

app-root/ ├── feature/ # 各业务功能模块（登录、订单、个人中心等） ├── core/ # 公共基础能力 ├── data/ # Repository、本地存储 ├── network/ # API、Retrofit 封装 └── ui/ # 共享 UI 组件、主题

索引完node .gitnexus/run.cjs status看一眼符号数、关系数，确认没过期。

我自己仓库上的真实数据

写作用的 SkillsWrite 仓库，索引结果写在AGENTS.md：

SkillsWrite — 170 symbols, 168 relationships

里面写了：改符号前先impact，提交前detect_changes。没图谱时这规则就是摆设；有图谱才能和 Rules、MCP 对上。

安装踩坑（我遇到过）

五、我用的最多的三个场景

场景 1：新人问「登录流程从哪进、从哪出？」

以前搜login/auth，几十上百条命中，各 Feature、ViewModel、网络层全混在一起，新人得自己拼。

现在有图谱，常见链路能拉成：

LoginActivity ↓ LoginViewModel ↓ UserRepository ↓ AuthApi / TokenManager ↓ SessionStore（本地会话）

query("用户登录")或读processes资源，按执行流分组，不是甩一堆文件名。

我一般会接着问 Agent：要是改UserRepository的登录回调签名，会波及哪些 Feature 和页面？改之前让它跑impact(UserRepository, upstream)，心里有数再动刀。

场景 2：改公共接口前先问「会炸谁」

impact({ target: "UserService", direction: "upstream" })

返回大意：

- N 个直接调用方 - M 个 Cluster - 有 Web 层的话可能还有 Route 消费者 → 改返回类型？多半 HIGH 风险

这是调用图上的可达性，不是「语义上有点像」的片段。合码前再跑detect_changes()，对照 diff 看实际波及，PR 自检够用。

场景 3：啃 Framework 源码

问 Activity 启动，普通搜索给你堆startActivity。要是给 Framework / AOSP 子树建过索引：

trace({ from: "Activity.startActivity", to: "ActivityRecord" })

或者读process/{name}一步步跟。跨进程、链路长的时候，我比对着碎片文本瞎猜省心多了。

六、和普通 RAG 比，差在哪？

一句话：RAG 告诉你「哪段话像你的问题」；GitNexus 告诉你「这些类怎么连、改谁会跟着坏」。

两者不冲突。产品文档、PRD 继续 RAG；仓库结构交给 GitNexus。我现在的栈是 Cursor + MCP + Rules + Skills，GitNexus 管的就是「少误改」那一块。

七、啥情况值得上、啥情况别折腾

值得上：

• 十万行以上的多模块 Android App / 后端工程
• 团队已经在用 Cursor、Claude Code、Windsurf
• 你真需要影响分析、链路追踪，不是只要补全
• 代码不能出公司电脑

别硬上：

• 几百行脚本，grep够了
• 纯配置仓
• 装完从不更新索引（过期图谱比没有还坑——AI 会信错的结构）
• 想拿它替 CodeQL / Sonar

我自己坚持的几条，写进AGENTS.md了：

1. 改符号前先impact
2. 提交前detect_changes
3. 大重构用rename，别裸 find-replace
4. 索引定期跑，别信 stale 的图
5. Cursor 看 MCP 绿没绿；Claude Code 可以把 hooks 用起来

八、最后唠两句

写代码这件事，AI 已经挺能干了。后面拼的，多半是改之前对系统有多熟。

GitNexus 在我这儿就干三件事：把仓库索引成图谱；通过 MCP 给 Agent 查 impact、trace、query；跟 AGENTS.md、Rules 配合，让「先搞清楚再动手」能落地。

你要是维护大型 Android 工程，可以试试就两条命令：

npx gitnexus analyze npx gitnexus setup

然后在对话里扔一句：用 GitNexus 查一下，改这个类上游还有谁调。文本搜索给不了这条链，结构查询可以。

有问题欢迎评论区聊，我后面可能还会补一篇「AGENTS.md 规则怎么和 GitNexus 配」的实战。

附录：面试/讨论时可能被问的

和向量库有啥区别？
向量库答「像什么」；GitNexus 答「连到哪、动谁会坏」。

Activity 启动为啥适合图谱？
跨类跨进程，关键词噪声太大，CALLS + Process 能给有序链。

impact 和 detect_changes？
一个改前看波及，一个改后对照 diff。

能替 CodeQL 吗？
不能，别多想。

代码上传吗？
CLI 默认本地。Web UI 在浏览器跑，大仓注意内存。

和现有向量库冲突吗？
不冲突，各管各的。

—

相关推荐

GitNexus GitHub

GitNexus npm

Cursor 实战：用 grill-me Skill 把 AI 写的 PRD 拷问到能写代码