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

文章目录一、翻车现场AI 不是不会写是不知道自己在动哪二、GitNexus 到底是啥说人话版没索引时AI 眼里就是碎文件索引之后至少能问这些一张图看懂分工CLI 还是网页三、它背后在干啥不用背知道个大概就行索引流水线举个最小例子为啥我说普通 RAG 搞不定 Activity 启动聚类和执行流省得 AI 在图里瞎逛四、Android 大项目怎么接我实际就这么干的就两条命令起步多模块 App 大概长这样我自己仓库上的真实数据安装踩坑我遇到过五、我用的最多的三个场景场景 1新人问「登录流程从哪进、从哪出」场景 2改公共接口前先问「会炸谁」场景 3啃 Framework 源码六、和普通 RAG 比差在哪七、啥情况值得上、啥情况别折腾八、最后唠两句附录面试/讨论时可能被问的相关推荐先说结论如果你项目已经大到 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 靠片段猜调用关系 ↓ 开改三个坑我反复踩隐藏依赖找不到。反射、接口实现、EventBus、跨模块 import关键词根本串不起来。调用链拼不对。搜到startActivity≠ 知道 Activity 怎么一路启动到入栈。改之前不问影响面。没有「动这里会波及谁」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一张图看懂分工你Cursor / Claude CodeMCPGitNexus解析 · 抽符号 · 建依赖 · 追执行流代码知识图谱你的仓库你负责拍板AI 负责改码GitNexus 负责把仓库里的「结构真相」摊开。底层具体用啥存储版本可能会变别和某个产品名绑太死就行。CLI 还是网页方式我咋用备注CLI MCP日常开发就用这个本地索引大图谱能留着Agent 直接调工具Web UI偶尔演示、快速瞄一眼gitnexus.vercel.app免安装超大仓浏览器可能扛不住我基本不用 Web UI 写代码。下面第四、五章讲怎么接、怎么用。三、它背后在干啥不用背知道个大概就行索引流水线Git 仓库 ↓ Tree-sitter 解析多语言 AST ↓ 抽符号类、函数、import… ↓ 建依赖图CALLS、IMPORTS、EXTENDS… ↓ 聚类 追执行流 ↓ 本地知识图谱 ↓ MCP 暴露给 Cursor / Claude Code语法分析靠 Tree-sitterJava、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 analyzerun.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.mdSkillsWrite — 170 symbols, 168 relationships里面写了改符号前先impact提交前detect_changes。没图谱时这规则就是摆设有图谱才能和 Rules、MCP 对上。安装踩坑我遇到过坑咋解npm 11 装npx崩了全局npm i -g gitnexus或 pnpm dlx见 #1939MCP 启动超时全局安装 setup写绝对路径别让冷启动 npx 拖死索引落后代码context提示 stale 就重新 analyze只要结构不要语义默认别开--embeddings五、我用的最多的三个场景场景 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 比差在哪能力普通 RAGGitNexus文本/语义搜✅✅谁调谁CALLS 等❌✅调用链❌✅ trace改动影响面❌✅ impact执行流❌✅ Processdiff 波及分析❌✅ detect_changes跨文件重命名❌✅ rename大仓多模块片段碎本地持久图谱代码隐私看你怎么部署CLI 默认本地一句话RAG 告诉你「哪段话像你的问题」GitNexus 告诉你「这些类怎么连、改谁会跟着坏」。两者不冲突。产品文档、PRD 继续 RAG仓库结构交给 GitNexus。我现在的栈是 Cursor MCP Rules SkillsGitNexus 管的就是「少误改」那一块。七、啥情况值得上、啥情况别折腾值得上十万行以上的多模块 Android App / 后端工程团队已经在用 Cursor、Claude Code、Windsurf你真需要影响分析、链路追踪不是只要补全代码不能出公司电脑别硬上几百行脚本grep够了纯配置仓装完从不更新索引过期图谱比没有还坑——AI 会信错的结构想拿它替 CodeQL / Sonar我自己坚持的几条写进AGENTS.md了改符号前先impact提交前detect_changes大重构用rename别裸 find-replace索引定期跑别信 stale 的图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 GitHubGitNexus npmCursor 实战用 grill-me Skill 把 AI 写的 PRD 拷问到能写代码