前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

https://github.com/jnMetaCode/superpowers-zh

一、当前 AI 编程的致命痛点

1、 所有 AI 编程助手的“通病”

无论是对话式助手、IDE 插件、还是 Agent，几乎都逃不开这条链路：

• 你让 AI 改一个功能，它先说“我理解了项目结构”，然后开始改；
• 改完跑不通，你指出错误，它道歉、再改；
• 你再指出第二个错误，它又道歉、再改；
• 最后你发现：你花在“教 AI 读项目”的时间，比自己动手定位问题还久。

2、传统工作流：AI 靠暴力读文件 → Token 爆炸

用户：帮我理解整个项目，并改一个功能

工具：扫描目录 → 读 N 个文件 → 全部塞进 Prompt → 让模型总结 → 让模型修改

问题是：你把“工程理解”这个任务，错误地翻译成了“把文本喂给模型”。

于是后果非常熟悉：

• Token 爆炸：输入里充满重复代码、重复上下文、重复历史对话；
• 速度慢：模型每轮都在重复阅读；
• 漏改：改了 A 忘了 B，动了接口没动调用方；
• 幻觉：模型为了“补齐”它没看到的部分，开始编故事；
• 成本失控：越大项目越离谱。

3、LLM 的本质缺陷：它不能天然理解大型工程

大型工程的“理解”，不是阅读，而是关系推理：

• 谁调用谁（Call Graph）
• 谁依赖谁（Dependency Graph）
• 谁定义了接口，谁实现了它（Symbol Resolution）
• 改动会影响哪些路径（Blast Radius / 影响分析）
• 一个功能分散在哪些模块（Module Clustering / Feature Slice）

4、什么是代码知识图谱？

传统 RAG 解决的是“检索文本”，而图谱解决的是“理解关系”。

核心思想：把“代码实体”作为节点，把“确定性关系”作为边，让工程本身变成可查询的图结构。

图谱路线真正强的地方在于：它的底座是 AST（抽象语法树） 与静态分析，属于“确定性事实层”。

这意味着：

• 结构可验证：函数在哪里定义、调用发生在哪里，原则上能做到 100% 可追溯；
• 关系可推理：图遍历天然适配影响分析、路径搜索、模块聚类；
• 不会向量漂移：结构关系不会因为语义相似而“误召回”。

5、新时代解法：代码结构化图谱引擎

真正能从根上解决 Token 爆炸与短期记忆的方案，是给 AI 一个“外置大脑”：把代码与项目知识预先结构化成图谱（Graph），让 AI 用查询拿到最小必要上下文。

1）CodeGraph（编译器派 / 极速索引）：定位为 AI 代理的“结构索引引擎”。

• 定位是「代码库的结构化目录卡」，纯静态解析代码符号与关系
• 主打「少读文件、省 Token、快查询」，解决 AI 反复遍历文件的效率痛点。
• 场景：
  • 日常编码写功能：用 CodeGraph 快速查符号、找调用链，省 Token、提速度；
  • 如果你只是想让 Cursor/Claude Code 少读文件、省 Token、加快代码探索速度 → 优先 CodeGraph

2）Graphify（LLM 派 / 多模态语义）：定位为“多模态项目知识图谱”。

• 定位是「全项目的认知网络」，覆盖代码 + 文档 + 图片 + PDF，结合结构化解析与 LLM 语义推断
• 主打「架构理解、知识沉淀」，解决 AI 对项目全局认知不足的问题。
• 场景：
  • 接手新项目、梳理架构：用 Graphify 生成全局图谱与架构报告，快速建立项目认知；
  • 如果你需要梳理项目架构、沉淀团队知识、让 AI 回答业务与架构级问题 → 优先 Graphify

3）GitNexus（Agent 数据库底座）：定位为 AI 代理的“上下文神经系统”。

• 定位是「企业级代码智能引擎」，基于完整嵌入式图数据库，预计算执行流、影响半径、功能社区
• 主打「深度分析、执行决策」，为 AI Agent 提供代码层面的决策支撑能力。
• 场景：做重构、改核心模块、评估变更风险：用 GitNexus 做影响分析、生成变更方案，保障代码改动的准确性。
• 如果你在做企业级编码 Agent、解决深度分析、管理大型代码库、需要精确的改动影响分析 → 优先 GitNexus

6、使用场景对比

• CodeGraph：日常开发快速找代码、查调用

• Graphify：看懂业务、搞懂架构、对接文档
• GitNexus：但凡改动核心代码，前置做影响风险分析

1）CodeGraph 【日常编码工具】

核心定位：轻量代码索引，纯AST静态解析，全程0Token

适合做：

• 查找函数/类/接口定义、快速跳转代码
• 查看静态调用方、基础依赖关系
• 小功能开发、写业务接口、修复bug
• 日常高频查询，追求速度、低成本

禁止做：业务架构梳理、变更风险评估

增量/切分支：自动增量，切分支自动同步，无需重建

优缺点速记：省70%-90%查询Token，缺点抓不到JS/Python动态反射代码关系

2）Graphify 【业务认知工具】

核心定位：代码+文档+流程图联动知识库，前期一次性消耗Token建图，后续查询省80%Token

适合做：

• 新项目接手、新人快速吃透业务
• 梳理完整业务流程、业务模块划分
• 匹配：架构文档、流程图、注释 和 对应业务代码
• 输出可读性极强业务架构报告、流程说明

禁止做：修改底层代码、评估改动影响风险

增量/切分支：切分支只需增量更新，不开–semantic则0Token；仅更新业务语义才耗Token

关键通俗规则：

• 投入：第一次全量建图，花一笔一次性Token
• 回报：后续几个月查业务、看文档、链路复盘，极致省Token
• 短板：算法不会风控，分不清修改代码的影响大小

3）GitNexus 【改动决策风控工具】

核心定位：代码图算法决策底座，建图+增量+分析 全程0付费Token（本地小向量模型，无API计费）

适合做：

• 修改公共工具类、底层函数、核心接口
• 项目重构、模块拆分、版本迭代风险核验
• 精准区分：必受影响代码 / 分支才触发代码 / 无关代码
• 输出风险分级、测试范围、改动影响专业报告
• 多微服务、多仓库跨仓依赖排查

禁止做：看业务文档、解读业务含义（纯算法，不懂业务语义）

增量/切分支：切分支执行增量分析即可，仅超大差异分支才需要全量重建

核心答疑：不靠大模型识别模块——靠文件夹路径、代码互相调用拓扑、聚类算法、框架注解判定模块，纯本地算法。

7、Graphify 和 GitNexus

• 精准代码问题用 GitNexus。比如：「修改这个函数的返回类型会影响哪些模块？」
• 语义知识问题用 Graphify。比如：「这段 attention 实现和 Transformer 论文的哪个部分对应？」
• 复杂混合问题两个一起开。比如：「重构 Auth 模块前我需要知道所有依赖它的代码路径，以及当初选择 OAuth 的原因。」

8、Token消耗对比

二、CodeGraph

1、基本介绍

CodeGraph 诞生的核心痛点是：AI 编码 Agent（Claude Code、Cursor 等）在探索代码库时，高度依赖「关键词搜索 → 逐文件读取 → 人工拼接关系」的模式，存在三大问题：

• Token 浪费严重：为了找一个函数的调用关系，往往需要读取十几个完整文件，大量无关代码占用上下文窗口；

• 工具调用冗余：一次链路追踪需要多次 grep、多次 read 文件，响应速度慢；

• 信息易遗漏：纯文本搜索无法精准识别语法关系，容易漏掉隐式调用、继承实现等结构关联。

CodeGraph 的本质是提前对代码做结构化索引，用「一次图查询」替代「N 次文件遍历」。它通过纯静态语法解析，把代码的符号、关系提前抽取并存入本地数据库，让 AI 像查地图一样精准定位代码结构，全程不依赖 LLM，零额外 Token 成本，所有数据完全本地处理。

2、核心原理

1）技术架构与核心模块

CodeGraph 采用四层轻量化架构，整体无外部服务依赖，单文件二进制即可运行：

2）核心数据模型

CodeGraph 采用「节点 - 边」的图数据模型，所有数据均为结构化的确定性关系，无非结构化语义数据。

a、 节点类型（Nodes）

所有从代码中提取的可定位实体：

• 文件节点：源码文件，包含路径、语言、修改时间等元信息；
• 符号节点：函数、类、接口、枚举、类型别名、常量、全局变量；
• 成员节点：类方法、类属性、对象属性。

b、边类型（Edges）

节点之间的确定性结构关系：

• 调用边：函数 A 调用了函数 B；
• 依赖边：文件 A import 了文件 B，或符号 A 引用了符号 B；
• 继承 / 实现边：类 A 继承类 B、类 A 实现接口 B；
• 归属边：函数 / 类归属于某个文件、方法归属于某个类。

c、附加元数据

每个节点都附带精准的位置：文件路径、起始行号、结束行号、代码片段，支持AI 查询后直接定位到代码范围，无需再通读整个文件。

4）核心工具能力集

不需要手动去敲这些命令。 它们是通过 MCP协议集成在 AI 编程助手内部的。你只需要用自然语言向 AI 提问，AI 就会在后台自动调用对应的工具

5）CLI 常用命令（人工操作使用）

2、实战案例

1）CodeGraph 安装

1. 安装：npm install -g @colbymchenry/codegraph

2. 项目初始化构建索引：codegraph init

3. 查看索引统计信息：codegraph status

   └─[$] codegraph status                                                                                                                   [17:03:12]
      
   CodeGraph Status
      
   Project: /Users/zhangyujin1/Desktop/HealerJean/A_Company/JD/code/baoxian-merchant-route
      
   Index Statistics:
     Files:     228
     Nodes:     4,474
     Edges:     6,787
     DB Size:   11.73 MB
     Backend:   node:sqlite — built-in (full WAL)
     Journal:   wal
      
   Nodes by Kind:
     import          1,632
     constant        1,079
     method          664
     field           436
     file            200
     namespace       179
     class           151
     enum_member     86
     interface       30
     enum            17
      
   Files by Language:
     java            179
     yaml            28
     xml             21
      
   ✓ Index is up to date
      
   

4. 查询验证：codegraph query route

2）接入 AI 代理

工具会自动检测本机已安装的 AI 代理，自动写入 MCP 配置，无需手动修改文件。

codegraph install

└─[$] claude                                                                                                                             [17:09:28]

────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  New MCP server found in this project: codegraph

  MCP servers may execute code or access system resources. All tool calls require approval. Learn more in the MCP documentation.

  ❯ 1. Use this MCP server
    2. Use this and all future MCP servers in this project
    3. Continue without using this MCP server

3）AI 搜索方式

我要验证下你的搜索能力 ，如果搜索一个名字路由， 你会用的什么工具进行搜索                                                                          

  Thought for 16s (ctrl+o to expand)

⏺ 好问题！搜索"路由"这类关键词时，我有一套优先级分明的搜索工具链：

  我的搜索工具优先级

  🥇 首选：CodeGraph（代码图谱）

  工具： codegraph_explore / codegraph_search / codegraph_node

  这是我的第一选择，因为本项目已建立 .codegraph/ 索引。它的优势：

  ┌────────────┬─────────────────────────────────────────────────────────────┐
  │    能力    │                            说明                             │
  ├────────────┼─────────────────────────────────────────────────────────────┤
  │ 语义搜索   │ 输入自然语言"路由规则分配算法"，直接返回相关源码 + 调用链   │
  ├────────────┼─────────────────────────────────────────────────────────────┤
  │ 符号搜索   │ codegraph_search("RouteInsuranceRule") 精准定位类/方法      │
  ├────────────┼─────────────────────────────────────────────────────────────┤
  │ 源码直达   │ 一次调用返回完整源码 + 谁调用了它 + 它调用了谁，无需再 Read │
  ├────────────┼─────────────────────────────────────────────────────────────┤
  │ 亚毫秒响应 │ 索引预构建，比 grep + Read 循环快几十倍                     │
  └────────────┴─────────────────────────────────────────────────────────────┘

  搜索"路由"的典型调用：
  codegraph_explore("路由 route insurance rule findSupplier")
  → 一次性拿到 RouteInsuranceRule 相关所有类源码 + 调用路径

  🥈 备选：Bash grep / find

  当 CodeGraph 没有覆盖的场景（如中文注释、配置文件、非代码文件）：

  # 搜索中文"路由"
  grep -rn "路由" --include="*.java" .

  # 搜索文件名含 route
  find . -name "*route*" -o -name "*Route*"

  🥉 补充：Read + Glob

  确认具体文件内容时使用，但不会作为搜索起点，太慢且需要多轮猜测。

  🏴 并行搜索：Agent（Explore 类型）

  需要大范围扫描时，我会派出 Explore 子代理并行搜索多个维度。

  ---
  实际搜索"路由"的决策路径

  搜索"路由"
    ↓
  CodeGraph 已索引？ ── 是 ──→ codegraph_explore / codegraph_search

  需要大范围扫描时，我会派出 Explore 子代理并行搜索多个维度。

  ---
  实际搜索"路由"的决策路径

  搜索"路由"
    ↓
  CodeGraph 已索引？ ── 是 ──→ codegraph_explore / codegraph_search
    ↓ 否
  需要搜中文注释？ ── 是 ──→ grep -rn "路由"
    ↓ 否
  知道大概类名？ ── 是 ──→ codegraph_search("RouteInsurance") 或 find
    ↓ 否
  范围大/不确定？ ── 是 ──→ 派出 Explore Agent 并行扫描

  ---
  一句话总结： 有 CodeGraph 索引的项目，我会优先用 codegraph_explore 一步到位拿到源码 + 调用关系；没有索引或搜中文注释时才退回到 grep/Read。

  要我实际演示一下搜索"路由"看看效果吗？

4）CodeGraph 遗漏了怎么办

CodeGraph 的遗漏是少报、不错报：解析不出来的动态关系直接不输出，绝不编造假关系，和 AI 幻觉的 “错误信息” 性质完全不同，整体不会误导 AI。

a、实际影响是什么

• 遗漏的内容：仅覆盖不到非显式语法的调用关系，比如 JS 动态属性、Python 反射 / 元编程、事件总线回调、配置化路由、依赖注入动态绑定等。
• 影响的场景：仅在严格全量影响评估场景有明显局限 —— 修改底层公共函数、做大型架构重构、要求 100% 覆盖所有调用方时，会少算一部分隐式调用路径，不能单独作为唯一决策依据。
• 绝对不会出现的问题：不会产生错误引导。所有输出的关系都 100% 有语法依据，不会把 AI 带向错误方向，和 AI 幻觉编造虚假关系的性质完全不同。

b、 什么完全不影响

• 日常符号定位：找函数 / 类定义、搜相关代码、看文件结构概览；
• 常规业务开发：主流静态写法的调用链查询、主流程梳理、普通改动的影响预估；
• 核心收益不受影响：减少文件读取、节省 Token、提升代码探索速度的效果完全成立。

c、为什么遗漏不会严重干扰 AI

• 宁漏勿错的机制：只输出有明确语法依据的关系，不猜测、不编造，信息缺了但不会错，AI 不会被误导；
• AI 自带兜底逻辑：当它发现索引信息不足以支撑推理时，会自动降级用全文搜索、逐文件读取的方式补全信息
• 实际场景占比低：绝大多数业务项目的核心逻辑都是静态显式写法，动态特性集中在底层框架，日常开发场景的覆盖率足够用。

d、彻底规避的方法：

• 重要场景提问时加一句约束即可，比如：查完索引后，再用全文搜索确认动态调用、事件回调的场景，不要遗漏。
• 涉及核心底层代码改动、大型重构时，主动提醒不要只依赖静态索引结果。
• 日常普通开发无需额外处理，工具带来的效率收益远大于潜在影响。

3、适用场景与局限性

• 最佳适用场景：日常开发的高频代码导航、快速定位调用链、修改代码前的影响评估、以及需要极低延迟响应的 AI 辅助编程场景。
• 局限性：CodeGraph 是一个纯粹的“结构索引”工具，它只解析代码的客观事实（AST），不读取任何文档、设计图或业务说明。因此，它无法理解代码背后的“业务语义”和“设计意图”，在需要跨模态推理的复杂遗留系统重构中，能力会有所欠缺。

1）核心使用场景

1. 日常 AI 编码提效：让 AI 直接通过索引查询代码结构，减少 60% 以上的文件读取操作，显著降低 Token 消耗与响应时间；
2. 大型仓库快速导航：面对不熟悉的模块，先通过符号搜索、调用链追踪定位核心逻辑，再针对性读文件；
3. 代码变更风险预评估：修改核心函数前，一键查询所有调用方，快速判断改动影响范围；
4. 新成员项目上手：通过路由列表、文件符号概览快速建立项目结构认知。

2）最佳实践

• 配置忽略规则：在项目根目录创建 .codegraphignore，将生成代码、第三方依赖、静态资源等目录加入忽略，减少无效索引；
• 调整防抖阈值：高频编辑场景可适当调大防抖时间（如 5000ms），降低后台更新频率；
• 先结构后细节：引导 AI 先用 CodeGraph 确定代码范围，再读取具体文件，避免无意义的全文遍历；
• 配合 Git 钩子：在 post-checkout、post-merge 钩子中添加 codegraph sync，切换分支后自动同步索引。

3）能力边界

作为轻量级索引工具，CodeGraph 有明确的能力边界，避免过度使用：

1. 纯结构解析，无语义理解：只能识别语法层面的关系，无法理解函数的业务含义、逻辑相似度，也无法判断语义层面的关联；
2. 动态语言支持有限：对于 JavaScript 动态属性、Python 元编程、反射调用等动态特性，无法完整解析，会存在部分关系遗漏；
3. 仅支持单仓库：无法做跨仓库的依赖追踪与联合分析；

4、常见问题与排查

1）修改代码后查询结果没更新

• 先执行 codegraph status 查看是否有待同步文件；
• 手动执行 codegraph sync 强制同步一次；
• 确认文件不在 .codegraphignore 或 .gitignore 中；
• WSL/Docker 环境设置了 CODEGRAPH_NO_DAEMON=1 时，需手动同步。

2）如何增量更新

# 增量同步自上次索引后的所有变更（最常用）
codegraph sync

# 查看当前索引状态，可看到待同步的文件数量与索引概况
codegraph status

# 强制全量重建索引（索引异常时使用，大项目耗时较久）
codegraph index --force

# 启动后台文件监听，实时增量更新索引
codegraph watch

3）增量更新的缺点

1. 跨文件依赖联动更新不足：仅重解析被修改的文件，若被依赖的符号发生变更（如函数重命名），未修改的引用文件不会同步更新关系，可能残留无效的调用 / 依赖边，需全量重建才能彻底清理。
2. 防抖窗口存在数据延迟：默认 2000ms 防抖期内查询会拿到旧数据，虽有过期标记但仍存在短时间的数据不一致，高频修改场景下同步滞后更明显。
3. 特殊环境监听易失效：WSL、Docker 容器、网络共享盘等场景下，系统文件事件 API 无法正常工作，自动增量会失灵，只能依赖手动同步。
4. 大规模批量变更性价比低：切换差异极大的分支、批量重构上百个文件时，逐文件增量处理 + 事务开销的总耗时，反而接近甚至超过全量重建。

4）切了分支之后的图也需要重建吗？

• 常规切分支：无需全量重建：
  • 开启 MCP 服务时，文件监听会自动捕获批量文件变更，防抖窗口结束后自动完成增量同步；
  • 想立刻生效，手动执行 codegraph sync 即可。

• 必须全量重建的极端场景

  • 切换前后分支文件差异极大（如主干切到完全独立的开发分支，文件变动超过 50%）；

  • 切换后查询出现大量无效符号、调用关系错乱。

  • 命令：codegraph index --force

5）增量更新会消耗大量 token 吗

无论分支差异多大，都只是本地 AST 解析 + 数据库更新，没有 LLM 调用。

6）省 Token 比例：70%～90%

原理：不用整文件读取，直接返回精简结构化符号列表，不用反复拉源码。

• 原生无工具：查一个函数调用链要读取十多个文件，几千～上万 Token；
• CodeGraph：一次工具调用返回名称 + 行号极简数据，仅几百 Token；
  • 适用：找函数、查静态调用、定位类，日常编码高频场景，省 Token 效果最稳定。
  • 短板：动态代码漏关系，AI 偶尔兜底读文件，没法做到 100% 节省。

三、Graphify

1、基本介绍

Graphify 是多模态项目语义知识图谱，定位是「全项目的认知网络」。如果说 CodeGraph 是「代码的结构化目录」，Graphify 就是「整个项目的知识地图」，它把代码、文档、图片、PDF、配置文件等所有项目资产，通过结构关系 + 语义关联连成可推理的知识网络。

CodeGraph 解决了「找代码慢、费 Token」的效率问题，但 AI 依然面临三个更深层的认知难题：

1. 不懂业务语义：知道函数名和调用关系，但不知道这个函数对应什么业务、解决什么问题；
2. 看不到全局架构：只能看到零散的文件和函数，无法理解模块划分、分层架构、核心链路；
3. 知识碎片化：业务说明在文档里、实现在代码里、流程图在图片里，AI 无法把零散信息关联起来。

Graphify 的核心价值就是打通这些信息孤岛，让 AI 不仅能找到代码，还能理解代码的业务含义、掌握项目的整体架构。

2、底层核心原理

Graphify 采用「结构化提取 + 语义化推断」双路径建图机制，这也是它和 CodeGraph 最核心的技术区别。

多模态资产（代码/文档/图片/PDF）→ 分模态结构化解析 → 实体节点提取 → 双路径关系生成 → 图谱融合构建 → 对外提供查询/可视化能力

1）两大核心技术路径：

• 确定性结构路径复用 AST 解析能力提取代码的结构关系（函数、类、调用、依赖），同时解析文档的标题层级、目录结构、链接关系，生成 100% 准确的确定性边。这部分和 CodeGraph 的逻辑同源，但覆盖范围从代码扩展到了所有文本资产。
• LLM 语义推断路径这是 Graphify 的核心增量能力：通过 LLM 对代码、文档的语义进行理解，提取业务概念、功能标签，挖掘代码与文档、模块与模块之间的隐性语义关联，生成带置信度的语义边。比如它能推断出「UserController 和用户登录文档是强关联的」「订单模块和支付模块存在业务依赖」，这些关系无法通过纯语法解析得到。

2）为什么需要双路径

• 纯结构路径（CodeGraph 路线）：准确但没有语义，只能回答「是什么关系」，回答不了「为什么相关」；

• 纯语义路径（纯 RAG 路线）：有语义理解但不准确，容易出现幻觉关联，也无法精确到代码符号级别；

• 双路径结合：用结构关系保证基础准确性，用语义推断补充业务认知，兼顾精准度和理解深度。

3）整体分层架构

Graphify 采用五层架构，相比 CodeGraph 增加了语义处理层和可视化层：

4）核心数据模型

相比 CodeGraph 纯代码结构的节点边模型，Graphify 的节点类型更丰富、边类型更多元，新增了大量语义类、多模态类元素。

a、节点类型（Nodes）

分为四大类，覆盖全项目资产：

• 代码类节点：文件、模块、类、函数、接口、常量（和 CodeGraph 基本一致）
• 文档类节点：文档文件、章节、业务概念、术语定义、功能说明
• 资产类节点：图片（架构图 / 流程图）、PDF 文档、SQL 表、接口定义、配置项
• 聚合类节点：业务模块、功能域、技术组件（由算法自动聚类生成）

b、边类型（Edges）

分为确定性边和语义边两大类：

确定性结构边（100% 准确）

• 代码结构边：调用、依赖、继承、归属（同 CodeGraph）

• 文档结构边：章节归属、文档引用、链接跳转

• 资产关联边：文档引用代码、文档引用图片、代码对应 SQL 表

语义推断边（带置信度）

• ·语义相似边：两个函数 / 文档语义高度相似

• 业务关联边：两个模块 / 节点属于同一个业务域

• 实现对应边：文档里的业务描述，对应到具体的代码实现

• 流程衔接边：两个节点在业务流程上存在前后衔接关系

c、附加属性

每个节点都附带元信息：来源文件、位置、语义标签、业务描述、置信度，AI 可以根据置信度判断信息的可靠程度。

5）核心工具能力集

a、MCP 核心工具（AI 代理使用）

b、人工侧核心能力

• 交互式图谱可视化：生成可拖拽、可缩放的 HTML 图谱，直观查看项目架构与关联；

• 架构报告生成：一键输出 Markdown 格式的项目架构分析报告；

• 知识导出：支持导出 Neo4j、GraphML、JSON 等多种格式的图谱文件；

• 差异对比：对比两个版本的图谱差异，快速了解架构变更。

2、实战案例

1）安装 Graphify

1. 推荐通过 pip 安装：pip install graphify-cli

2. 验证安装：graphify --version

3. 项目建图：graphify build

4. 启动可视化预览：graphify view
5. 接入 Claude Code：graphify install mcp

3、典型场景

1）核心使用场景

1. 新项目快速上手：新人接手项目时，先通过架构总览、模块划分建立全局认知，再深入具体代码；
2. 架构梳理与复盘：自动识别模块边界，生成架构图和说明，替代人工梳理架构文档；
3. 业务级问答：用自然语言问业务问题（比如 “用户退款的完整流程是什么”），AI 可以关联代码、文档、流程图给出完整答案；
4. 知识沉淀与传承：把零散的文档、代码、设计图沉淀成结构化知识网络，降低人员流动带来的知识损失。

2）最佳实践

• 先整理文档再建图：项目内的核心文档、架构图越规范，建出来的图谱语义质量越高；
• 核心模块优先标注：可以在配置里指定核心业务目录，让 LLM 重点做语义提取，兼顾成本和效果；
• 搭配 CodeGraph 使用：全局架构、业务理解用 Graphify，具体代码查询、调用链分析用 CodeGraph，形成互补；
• 定期更新图谱：项目大版本迭代后重新建图，保证知识不陈旧。

3）能力边界与局限性

1. 语义推断存在误差：语义关联边带有置信度，可能出现弱关联、误关联的情况，核心结论需要人工校验；
2. 建图有时间和 Token 成本：大项目全量建图需要调用 LLM，会产生 Token 费用和时间成本，不适合高频增量更新；
3. 动态特性同样存在遗漏：代码结构部分的解析和 CodeGraph 同源，动态调用的关系同样无法通过结构解析获取；
4. 图片识别精度有限：复杂的架构图、流程图的识别可能存在遗漏和偏差，只能作为辅助参考；
5. 增量更新能力弱：目前主要靠全量重建，增量更新仅支持文件级别的简单更新，大版本变更后建议全量重建。

4、常见问题与排查

1）如何增量更新

代码结构部分秒级增量更新，语义关联默认不自动重算（避免频繁消耗 Token），可按需手动开启。

a、Git 钩子自动更新（官方推荐）

安装后在代码提交、切分支、合并时自动触发，仅更新代码结构关系，零 Token 成本。

安装命令：graphify hook install

b、手动增量更新（日常主流）

仅处理有改动的文件：

• 仅更新结构：graphify update .
• 同步更新语义关联（产生 Token 消耗）：graphify update . --semantic
• 强制全量重建：graphify update . --force

c、实时监听模式

后台常驻监听文件变更，仅实时同步结构，语义不自动重算：

graphify watch . --debounce 3000

2）增量更新的缺点

1. 结构与语义更新脱节，一致性差：默认增量仅更新代码结构边，不重算语义关联、社区聚类，导致图谱结构和语义信息脱节，业务语义查询的准确性下降；若开启语义增量，又会产生 Token 消耗且速度大幅变慢。
2. 局部语义重算存在碎片化问题：增量模式下仅对变更节点做局部语义匹配，全局的语义关联、模块聚类会逐步出现偏差；多次增量后容易出现关系断裂、社区划分混乱，最终仍需全量重建校准。
3. 非文本资产变更检测覆盖不全：对图片、PDF、Word 等多模态资产的变更检测灵敏度低，文档内容修改后常无法触发增量识别，需手动强制更新。
4. 文件移动 / 重命名会产生脏数据：增量机制将文件移动识别为「删除旧文件 + 新增新文件」，旧文件对应的语义节点、关联边不会自动迁移，会残留大量无效幽灵节点，只能全量重建清理。

3）切了分支之后的图也需要重建吗？

• 常规切分支：无需全量重建：安装 Git 钩子后，切分支会自动触发结构增量更新；手动执行 graphify update . 也可快速同步代码结构，需同步语义就加 --semantic 参数。

• 建议全量重建的场景

  • 分支间有大量文件移动、重命名、目录重构（增量机制会残留无效幽灵节点）；

  • 多次增量后，社区划分、语义关联出现明显混乱。

  • 命令：graphify update . --force

4）增量更新会消耗大量 token 吗

• 默认结构增量：零 Token，仅处理有差异的文件；

• 开启语义增量：

  • 普通功能分支（改动 5%~20% 文件）消耗极低；
  • 只有分支差异极大（过半文件改动）时，消耗才会接近全量建图，这类场景极少。

5）省 Token 比例：60%～85%，但自身生成图谱要消耗一次性 Token

1. 查询阶段极度省 Token：不用批量读取文档、架构图、多模块源码，直接返回业务关联摘要，省去大量文档 / 代码读取开销；
2. 成本短板：
   • 建图、增量更新、生成架构报告会消耗额外 Token，属于「前期投入，长期查询省钱」；
   • 适合新人熟悉项目、梳理业务流程，长期使用整体依然节省，但短期有 Token 成本。
3. 原因：
   1. 搜索噪音 — grep 返回的中间结果（文件路径、匹配行）是”废 token”，你读了但不做决策
   2. 走弯路 — 传统方式可能先 grep 到一个不相关的同名类，Read 之后发现不对，再回头搜。图谱 直接返回精确匹配
   3. 推理轮次 — 每多一次工具调用，我就多一轮”分析结果 → 决定下一步”的推理，这部分模型输出 token 才是大头。8 次调用 vs 2 次调用，推理开销差 3-4 倍

最容易被低估的，往往是后两项。

1. 工具往返成本的问题在于：你以为自己只是“让它查个文件”，但模型其实经历的是：理解工具定义 → 生成参数 → 接收返回值 → 再结合返回值继续思考。对人来说只是一个动作，对系统来说可能是多段上下文交换。

2. 重试成本更隐蔽。真正烧钱的，常常不是第一次调用太长，而是第一次不合格——格式不对、结构错、找错文件、推理过度——于是又来一轮。

四、GitNexus

1、基本介绍

1）核心定位与设计初衷

GitNexus 是面向编码 Agent 的企业级代码智能图数据库底座，定位是「代码世界的关系型大脑」。

• CodeGraph 是「索引工具」：解决「找得到代码」的问题；
• Graphify 是「知识网络」：解决「读得懂项目」的问题；
• GitNexus 是「计算引擎」：解决「算得清影响、做得了决策」的问题。

它以嵌入式图数据库为核心，在代码结构图谱的基础上做大量预计算与图算法分析，把原本需要 AI 反复推理、逐文件排查的分析工作，变成一次工具调用即可返回的结构化结论，是企业级编码 Agent 的核心能力基座，默认无需 LLM 参与，不消耗 token。

3）解决的核心痛点

前两款工具覆盖了代码探索与项目认知，但 AI 在深度改动代码时仍存在三大无法突破的瓶颈：

1. 影响分析不精确：纯静态调用链查询只能列出所有调用方，无法区分「直接影响 / 间接影响」「必达路径 / 分支路径」，
2. 缺乏全局计算能力：AI 无法快速识别模块边界、计算依赖复杂度、定位核心链路，做架构重构时只能靠人工经验；
3. 多仓库管理空白：微服务、多仓库、公共组件库的场景下，跨仓库的依赖追踪、变更传导完全无法通过单仓库索引完成。

GitNexus 的设计目标就是填补这一层空白，让 Agent 具备和资深开发同等的代码全局分析能力。

2、底层核心原理

和前两者最核心的区别是：建图只是第一步，预计算与图分析才是核心价值。CodeGraph 和 Graphify 的查询是「实时遍历图谱」，而 GitNexus 的大部分复杂分析是「查询预计算好的物化结果」，性能与深度都不在一个量级。

多代码仓库 → 多语言 AST 深度解析 → 控制流/数据流提取 → 图数据库原生存储 
→ 多维度预计算物化 → 混合检索引擎 → MCP/API 对外输出分析能力

1）三大技术支柱

• 原生图数据库存储：采用嵌入式图数据库（内置 Kuzu / 自研 LadybugDB），原生支持属性图模型与 Cypher 风格图查询，复杂链路查询、多跳遍历的性能比 SQLite 模拟图查询高数十倍，支持亿级节点规模的大型代码库。
• 多阶段预计算体系将高频分析场景（影响半径、执行链路、模块社区、依赖层级）提前计算并物化为视图，Agent 查询时直接返回结果，无需实时遍历计算。这是 GitNexus 能做到「秒级返回全链路影响分析」的核心原因。
• 混合检索引擎：融合「全文关键词检索 + 向量语义检索 + 图结构检索」，支持自然语言到复杂图查询的自动转换，Agent 用自然语言描述需求即可触发深度分析，无需手动编写图查询语句。

2）整体分层架构

GitNexus 采用五层架构，整体偏重底层计算能力，是典型的「重底座、轻上层」设计：

3）核心数据模型

GitNexus 同样采用属性图模型，但节点粒度更细、边类型更丰富，且携带大量预计算属性。

a、节点类型

分为基础实体与聚合实体两类：

• 基础实体节点：仓库、文件、类、函数、接口、变量、数据库表、API 接口
• 聚合实体节点：业务模块、功能社区、依赖层级、风险分组（预计算生成）

b、边类型

在基础结构边之上，新增了大量细粒度的流程与语义边：

• 结构类边：调用、依赖、继承、实现、归属（同 CodeGraph）
• 流程类边：控制流跳转、数据流传递、异常抛出、分支条件
• 跨仓类边：跨仓库依赖、跨服务 API 调用、公共组件引用
• 元数据类边：提交关联、负责人归属、变更历史关联

c、核心预计算属性

每个节点都会附带提前计算好的分析属性，Agent 可直接读取使用：

• impact_radius：影响半径，即修改该节点会波及的节点数量与层级
• complexity：圈复杂度与依赖复杂度评分
• community_id：所属功能社区 ID
• layer_level：架构分层级别（入口层 / 业务层 / 数据层等）
• risk_level：变更风险等级，综合调用量、复杂度、历史故障记录计算
• core_degree：节点在系统中的核心度（中心度算法计算）

3、核心差异化机制

1）多阶段预计算体系

把 AI 以前需要临时去“翻箱倒柜”找答案的繁重工作，提前在本地算好，做成一张“代码知识图谱”。 这样当 AI 真正需要回答问题时，只需“看一眼”就能拿到完整结果，而不是像无头苍蝇一样去搜几十次

不需要去手动触发这四个级别的计算！ GitNexus 的设计初衷就是“零服务器、自动化”。你只需要做极其简单的初始化配置，剩下的脏活累活全由它在后台完成。

GitNexus 将分析能力分为「实时查询」和「预计算物化」两类，高频、复杂的分析全部提前算好：

• 一级预计算（实时）：符号搜索、单跳邻居查询，和 CodeGraph 能力一致，实时响应；
  • 意思：当你问“某个函数在哪”时，系统能瞬间告诉你。
  • 你的感知：就像在 IDE 里用 Ctrl+F 搜索，秒出结果。
• 二级预计算（小时级）：功能社区划分、依赖拓扑排序、核心度计算、模块边界识别，每天或每次大版本更新后计算一次；
  • 意思：系统会在后台自动把你的代码分门别类（比如识别出哪些是用户模块，哪些是支付模块），并理清它们之间的依赖关系。
  • 你的感知：当你问 AI “帮我梳理一下项目的整体架构” 时，它能给出非常清晰的模块划分，而不是东拼西凑。
• 三级预计算（分钟级）：全链路执行流、节点影响半径、变更风险评分，代码变更后增量重算；
  • 意思：系统会追踪代码的执行流，并计算“如果我改了这段代码，会有多大风险”。
  • 你的感知：当你问 AI “修改 UserService 会影响哪些地方？” 时，AI 能直接列出受影响的上下游模块，甚至告诉你风险等级，防止“改一处，崩全局”。
• 四级预计算（按需）：跨仓库影响传导、全系统架构合规检查、技术债务全局盘点，按需触发。
  • 意思：涉及跨仓库或者全系统的深度检查。
  • 你的感知：通常在你需要重构整个系统，或者排查极其复杂的跨服务 Bug 时，手动触发 AI 去执行深度分析。

2）精确影响分析引擎

这是 GitNexus 最核心的能力，和 CodeGraph 的基础影响分析有本质区别：

• CodeGraph：递归向上查找所有调用方，返回完整列表，无区分度；
• GitNexus：结合控制流与数据流，区分直接影响、间接影响、必达路径、分支路径，按影响概率与风险等级排序，甚至能给出「推荐测试用例范围」。

例如：修改一个底层工具函数，它会自动识别出哪些调用方是一定会走到该逻辑的，哪些是条件分支下才会触发的，最终输出分级的影响清单，而不是一个扁平的列表。

3）多仓库跨仓依赖追踪

支持将多个代码仓库纳入统一管理，自动识别跨仓库依赖关系：

• 自动识别 npm/pip/maven 等包管理的内部依赖；
• 自动匹配 HTTP 接口定义与调用方，建立微服务之间的调用链路；
• 支持变更传导分析：修改 A 仓库的公共接口，自动算出会影响 B、C、D 仓库的哪些模块。

这是企业级微服务架构场景下的刚需能力，也是前两款工具完全不具备的。

4）增量物化视图更新

针对预计算结果的更新问题，GitNexus 采用「增量差分 + 局部重算」的机制：

• 文件变更后，仅重算该文件相关的符号、调用关系；
• 基于变更的符号，向上追溯影响到的社区、链路，仅重算相关的预计算指标；
• 无需全量重建，中型仓库单次增量更新耗时在 10 秒级，远快于全量重建。

5）Git 元数据融合

自动关联 Git 提交历史、代码负责人、变更频率、故障记录等元数据，让分析结果更贴近工程实际：

• 识别「高频变更且高复杂度」的高风险代码区域；
• 分析代码的负责人与评审人，变更时自动推荐相关人员；
• 基于历史故障记录，评估改动的风险概率。

4、核心工具能力集

1）MCP 核心工具（AI Agent 使用）

GitNexus 的 MCP 工具以「复合分析能力」为主，而非原子查询，Agent 一次调用即可拿到完整分析结论：

2） 人工侧管理与分析能力

• Web 可视化控制台：交互式查看架构图、依赖热力图、影响范围可视化、模块社区划分；
• 多仓库管理面板：统一管理多个代码仓库，查看跨仓依赖拓扑；
• 架构合规检查：自定义架构规则（如分层依赖方向），自动扫描违规依赖；
• 分析报告导出：一键导出架构审计报告、技术债报告、变更风险报告。

3）常用命令

5、典型场景与最佳实践

1）核心适用场景

1. 大型 / 超大型代码库：十万行以上的单体仓库、多微服务架构，单靠人工和简单索引无法驾驭全局；
2. 企业级编码 Agent 开发：作为 Agent 的代码推理底座，提供精确的分析能力，提升 AI 改代码的准确率；
3. 架构重构与模块拆分：自动识别模块边界、依赖关系，生成重构方案与风险评估；
4. 变更风险管控：嵌入 CI/CD 流水线，对每次代码变更自动做影响分析与风险门禁；
5. 技术债务治理：全局扫描高复杂度、高变更频率的风险代码，按优先级推进优化。

2）最佳实践

• 三层工具搭配使用：日常编码查代码用 CodeGraph，业务与架构理解用 Graphify，深度改动与重构用 GitNexus，形成互补；
• 核心仓库定时预计算：对核心仓库配置定时任务，每天凌晨执行全量预计算，保证白天查询时数据最新；
• 配置架构规则：提前定义分层依赖规则、模块边界规则，让 GitNexus 自动扫描架构违规，防止架构腐化；
• 增量更新触发： Git 的 post-merge、post-checkout 钩子添加 gitnexus sync --incremental，切换分支后自动增量同步。

3）能力边界与局限性

1. 动态语言仍有局限：和前两者同源，纯静态解析无法完全覆盖反射、元编程等动态特性，只是通过数据流分析补充了一部分覆盖；
2. 部署与学习成本更高：内置图数据库与大量分析能力，体积更大、概念更多，学习曲线比 CodeGraph 陡峭；
3. 语义理解弱于 Graphify：核心能力是结构化计算，业务语义、文档关联的能力不如 Graphify 全面，建议搭配使用；
4. 预计算有时间成本：全量预计算耗时较长，适合相对稳定的核心仓库，高频迭代的小型项目性价比不高；
5. 无法替代人工决策：影响分析、重构方案都只是辅助建议，最终的架构决策仍需人工确认，不能完全依赖工具结论。

6、实战案例

1）环境准备与安装

1. **全局安装 **：npm install -g gitnexus@latest

2. 验证安装：gitnexus --version

3. 建立代码知识图谱： gitnexus analyze

   • 进阶：如果希望AI精准地理解你项目的特定模块，可以加上 --skills 参数，它会自动为每个功能模块生成专属的上下文文件：npx gitnexus analyze --skills

   `

2）建立代码知识图谱

gitnexus analyze

强制清空重建（索引错乱、切大分支、查不到调用链时用）
gitnexus analyze  --force

1. 扫描全部 java/yaml/xml 文件（你的 228 个文件）
2. 解析类、接口、方法、导入、调用、继承关系
3. 构建本地图数据库存入 .gitnexus/
4. 自动生成 AGENTS.md 给 AI 提供架构上下文

外部：在线免安装 Web（临时看仓库，无需本地索引）

浏览器打开：https://gitnexus.vercel.app

• 粘贴 GitHub 仓库地址 / 上传项目 ZIP
• 浏览器内 WASM 解析生成图谱，适合临时分析外部项目

3）生产内容分析

• 根目录全局规则文档：AGENTS.md、CLAUDE.md，两者是给 AI 助手的强制行为规范手册，AI 打开项目会自动读取，约束 AI 分析 / 改代码的标准流程，杜绝乱改、漏查依赖。
  • CLAUDE.md：专属适配 Claude Code（IDEA/VSCode 插件）
  • AGENTS.md：通用适配 Cursor、各类 AI 编程 MCP 客户端

• Claude MCP 技能脚本目录：.claude/skills/gitnexus/（6 个功能文件夹）

• 底层图谱数据库：隐藏目录 .gitnexus/（截图未展示，存储代码关系库）

<!-- gitnexus:start -->
# GitNexus — 代码智能分析工具
本项目已通过 GitNexus 建立索引，项目标识：**baoxian-merchant-route**（共1887个代码符号、4211条关联关系、131条业务执行流程）。请使用 GitNexus MCP 工具理解代码、评估修改影响、安全梳理代码链路。

> 索引数据过时？在项目根目录执行 `node .gitnexus/run.cjs analyze`，命令会自动选用可用运行器；若项目不存在 `.gitnexus/run.cjs` 文件，执行 `npx gitnexus analyze`。
> npm 11 版本崩溃问题修复方案：执行 `npm i -g gitnexus`（相关问题编号 #1939）。

## 强制执行规范（Always Do）
- **修改任意代码符号前，必须执行影响范围分析**。在修改函数、类、方法前，调用 `impact({target: "符号全称", direction: "upstream"})`，并向使用者输出改动爆炸范围：直接调用方、受影响业务流程、风险等级。
- **提交代码前必须执行 `detect_changes()`**，校验本次修改仅影响预期代码符号与业务流程。如需回归对比主干分支，执行：`detect_changes({scope: "compare", base_ref: "master"})`。
- 若影响分析判定风险等级为「高 / 严重」，**必须提前向使用者发出风险警告**，再执行代码修改操作。
- 阅读陌生业务代码时，优先使用 `query({query: "业务关键词"})` 检索完整执行流程，不建议直接文本全局搜索；该工具会按业务流程分组，按匹配度排序结果。
- 需要获取单个代码符号完整信息（调用者、被调用者、所属业务流程）时，使用 `context({name: "符号全称"})`。

## 绝对禁止操作（Never Do）
- 禁止未执行影响分析就直接修改函数、类、方法。
- 禁止无视「高 / 严重」级风险警告继续修改代码。
- 禁止使用文本全局替换方式修改类/方法名；如需重命名，必须使用图谱感知的 `rename` 工具，自动同步全项目所有调用链路。
- 禁止未执行变更范围校验 `detect_changes()` 就提交代码。

## 内置资源地址
| 资源地址 | 用途说明 |
|----------|---------|
| `gitnexus://repo/xxxx/context` | 项目整体架构概览、校验索引是否最新 |
| `gitnexus://repo/xxxxx/clusters` | 查看项目全部自动划分的业务功能模块 |
| `gitnexus://repo/xxxxx/processes` | 查看项目全部端到端业务执行流程 |
| `gitnexus://repo/xxxxxx/process/{name}` | 单条业务流程分步调用链路追踪 |

## 功能对应技能文档
| 使用场景 | 对应技能文件 |
|------|---------------------|
| 梳理项目架构 / 查询「XX功能如何执行」 | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
| 评估改动爆炸范围 / 查询「修改XX会导致哪些功能异常」 | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
| 故障链路排查 / 定位「XX接口报错根源」 | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
| 代码重构：重命名、抽取方法、类拆分 | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
| 工具说明、资源协议、数据结构参考文档 | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
| 索引构建、状态查看、清理图谱、导出架构文档等终端命令 | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |

<!-- gitnexus:end -->

a、 头部项目元数据

This project is indexed by GitNexus as merchant-sjx (736 symbols, 1438 relationships, 56 execution flows)

• merchant-sjx：你的项目在 GitNexus 内的唯一标识库名
• 736 symbols：解析出 736 个代码单元（类、接口、方法、枚举、常量、配置）
• 1438 relationships：代码关联关系（方法调用、类继承、导入依赖、接口实现）
• 56 execution flows：识别出 56 条完整业务执行链路（如路由规则查询、商户字典加载等接口流程）
• 索引过期修复命令：提供两种重建索引方式，解决代码更新后图谱不准的问题

b、Always Do：AI 必须强制执行的规则（核心价值）

1. **修改任意代码前，强制做上游影响分析 等价终端 ** gitnexus impact，AI 必须先算出修改的爆炸范围：哪些上层 Controller/Service 会被牵连、风险等级，再给你写代码。
2. 代码提交前必须校验变更范围：执行变更对比，防止改动意外污染无关业务模块，支持和 master 基线对比做回归校验。
3. 高风险修改必须主动告警：若影响分析判定改动风险高，AI 不能直接写代码，必须先告知你风险点。
4. 陌生业务优先用图谱检索，不用文本 grep 搜索
5. 查询单个方法完整链路用 context：一键获取该方法全部调用者、被调用者、归属的业务流程

c、 Never Do：AI 绝对禁止的操作

1. 不查影响范围就改代码；
2. 无视高风险提示直接修改；
3. 全局文本替换重命名类 / 方法（会遗漏隐藏调用链路，必须用图谱 rename 工具）；
4. 未校验变更范围就生成提交代码。

d、6个资源 Resources：AI 内置图谱快捷访问地址

e、 七个工具

f、.claude/skills/gitnexus/ 目录下的 6 个技能文件

这些是 Claude MCP 技能定义，让AI 能直接调用 GitNexus 能力，每个文件对应一个可视化 / 分析场景：

4）启动本地 Web 服务

gitnexus serve

1. 全局架构力导向图
   • 节点区分：Resource/Controller、Service、DAO、Enum、Interface、Yaml 配置
   • 连线区分：方法调用、类继承、导入依赖、接口实现
   • 滚轮缩放、拖拽画布、右键聚焦单个类 / 方法
2. 单符号全链路图谱输入你的接口：类.方法
   • 向下展开：内部调用的所有 Service/DAO（callees）
   • 向上展开：所有调用该方法的上游代码（callers）
3. 影响范围分析选中方法 → Impact Graph，自动渲染多层级上游依赖图谱，一眼看清改代码影响哪些模块
4. 循环依赖检测一键筛选项目循环调用，可视化环路节点
5. 路由映射（Spring 项目专属）自动识别 @RequestMapping，可视化 URL 与 Controller 对应关系

5）配置 AI 编辑器集成

这个命令会自动检测你电脑上安装的 AI 编辑器，并写入全局配置。配置完成后，请务必完全重启你的 AI 编辑器。

gitnexus setup 

7、常见问题与排查

1）如何 增量更新

基础结构支持文件级增量更新，影响半径、功能社区等预计算指标采用局部差分重算，无需全量重跑。无原生实时文件监听，以 Git 事件驱动为主。

关键注意

• 暂无原生实时 watch 模式，日常靠 Git 钩子 + 手动 analyze 即可
• 预计算粒度可配置（light/balanced/full），平衡速度与分析深度
• 仅架构级大重构、跨大版本升级时才需要全量重建

a、Git 钩子自动更新

初始化时自动安装钩子，每次代码提交、合并后自动同步基础结构索引。

b、手动增量更新（主流方式）

gitnexus analyze 默认就是增量模式，基于 Git 提交差和文件哈希定位变更，仅处理改动部分。

• 跳过向量生成提速：gitnexus analyze --skip-embeddings
• 强制全量重建：gitnexus analyze --force
• 查看索引状态：gitnexus status

2）增量更新缺点

1. 无原生实时监听，实时性最差：没有常驻文件监听能力，日常未提交的代码变更无法自动同步，必须手动执行命令触发更新，操作成本和使用门槛远高于前两者。
2. 局部预计算存在误差累积：增量模式仅对受影响的区域做局部预计算，影响半径、风险等级、社区划分等指标的精度低于全量计算；多次增量更新后误差会逐步累积，数据质量持续下降，需要定期全量重建校准。
3. 跨仓库增量联动能力弱：多仓库场景下，单个公共仓库变更后，依赖它的业务仓库不会自动触发增量更新与影响传导计算，需手动执行跨仓构建，多仓运维成本高。
4. 配置复杂，调优门槛高：预计算粒度、向量生成、超时时间等参数多，默认配置无法兼顾速度与精度，普通用户难以根据项目场景调优，容易出现「更新慢」或「结果不准」的问题。
5. 大版本升级兼容性差：跨大版本升级时，增量更新常因底层数据格式变更失效，必须执行全量重建，大型仓库升级成本高、耗时长。

3）分支之后的图也需要重建

• 常规切分支：无需全量重建：执行 gitnexus analyze 默认基于 Git diff 做增量更新，自动处理变更文件与局部预计算，分支差异不大时精度和速度都足够。

• 建议全量重建的场景

  • 跨大版本、架构级重构的分支切换，局部预计算误差累积明显；

  • 跨仓库依赖关系发生重大调整；

  • gitnexus status 提示索引损坏、数据不一致。

  • 命令：gitnexus analyze --force

4）增量更新会消耗大量 token 吗

• 核心的结构解析、影响分析、预计算全为本地图算法实现，不依赖 LLM；
• 唯一会消耗 Token 的场景：非建图的附加生成功能，只有主动执行 gitnexus wiki（自动生成项目说明文档）这类生成类命令时，才会调用在线 LLM API 产生 Token 消耗。
  • 这不属于建图流程，是额外的可选功能，需要手动触发、自行配置 API Key；
  • 日常的建图、增量更新、查询分析、影响评估等核心操作，都不会触发这个调用。
• 三个工具里，只有 Graphify 的语义建图 / 语义更新环节会产生 Token 成本，其余所有操作（CodeGraph 全场景、GitNexus 核心功能）都是纯本地计算，日常开发默认配置下完全不用担心增量更新烧 Token 的问题。

5）省 Token 比例：85%～95%，全程无额外 Token 消耗

最高节省幅度原因：原生场景评估改动风险，AI 需要递归读取所有上下游、区分分支路径、统计依赖，多轮文件读取，Token 爆炸；

• GitNexus 预计算完成，一次工具调用返回分级结构化影响报告，几乎不用读取源码；

• 且建图、增量更新、生成分析报告完全不依赖 LLM，零 Token 开销。

• 适合重构、底层函数修改、发布前风险评估，重度复杂场景省 Token 优势断层领先。