代码图谱（GitNexus）#

为当前项目一键完成 GitNexus 安装、MCP 配置和知识图谱构建。 每一步都有跳过检测，已完成的步骤不会重复执行。

语言支持#

TypeScript、JavaScript、Python、Java、C、C++、C#、Go、Rust、PHP、Swift、Dart、Kotlin、Ruby 等 14 种语言。

---

执行流程#

按顺序执行以下步骤。每步先检测当前状态，已完成则跳过。

第 1 步：定位项目根目录#

gitnexus analyze 需在项目根目录下执行。首先检查当前工作目录是否即为项目根目录：

bash

git rev-parse --show-toplevel 2>&1 && echo "已定位到项目根目录"

如果 Git 未初始化，则通过常见项目标志文件判断：

bash

ls package.json 2>&1 || ls pom.xml 2>&1 || ls go.mod 2>&1 || ls Cargo.toml 2>&1 || ls requirements.txt 2>&1 || echo "未找到项目根目录标志文件"

• 当前目录即为根目录 → 继续下一步
• 检测到其他目录为根目录 → cd 到该目录
• 找不到任何项目标志 → 询问用户项目根目录在哪，或使用 git init 初始化

第 2 步：检查 Node.js 环境#

bash

node --version

要求 Node.js >= 22。 如果版本过低或未安装：

• 引导用户到 nodejs.org 下载 LTS 版本
• Windows 用户也可用 winget install OpenJS.NodeJS.LTS 安装
• 升级完成后重新执行本技能

第 3 步：安装 GitNexus#

注意，gitNexus安装时指定1.6.5版本

先检测，再决定是否安装：

bash

gitnexus --version 2>&1

判断逻辑：

• 输出类似 1.x.x 的版本号 → 已安装，跳过本步骤，直接进入第 4 步
• 输出 command not found 或 not recognized → 未安装，执行以下安装

安装命令（Windows，推荐全局安装）：

bash

set GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 && npm install -g gitnexus@1.6.5

安装命令（macOS / Linux）：

bash

GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus@1.6.5

GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 跳过 Dart/Proto 原生语法解析器的编译，安装只需几秒，无需 C++ 工具链。

权限不足时的回退方案 — 如果全局安装失败（EACCES / Permission denied），后续命令统一改用 npx 前缀：

bash

npx gitnexus analyze    # 代替 gitnexus analyze
npx gitnexus setup      # 代替 gitnexus setup
npx gitnexus status     # 代替 gitnexus status

第 4 步：配置 MCP 服务#

gitnexus setup 自动检测已安装的编辑器并写入 MCP 配置，全局只需执行一次。

先检测是否已配置：

bash

gitnexus setup 2>&1

判断逻辑：

• 输出包含 already configured、 up to date、 MCP configuration exists 等字样 → 已配置，跳过
• 输出包含 wrote、 created、 configured、 Updated 等字样 → 配置成功
• 若 gitnexus 命令不可用（未全局安装），使用 npx gitnexus setup

setup 是幂等的，重复执行不会产生重复配置，可安全地直接运行。

第 5 步：构建知识图谱#

先检测当前项目是否已索引：

bash

gitnexus status 2>&1

判断逻辑：

• 输出包含 Indexed、 symbols、 up to date、 fresh 等字样 → 已索引且是最新的，跳过本步骤
• 输出包含 Not indexed、 No index found、 unknown 等字样 → 未索引，执行以下命令
• 如果 gitnexus 不可用，改用 npx gitnexus status

执行索引：

bash

gitnexus analyze

此命令解析整个代码库、解析导入关系、追踪调用链、检测代码社区，在项目根目录生成 .gitnexus/ 索引（自动加入 .gitignore）。优先使用gitnexus analyze进行索引，若出现错误则尝试增加选项。

如果需要强制重建（已索引但过期）：

bash

gitnexus analyze --force

常用选项：

选项用途--embeddings启用语义/向量搜索，速度较慢但搜索更强--force强制重建索引（索引过期时使用）--skip-embeddings跳过嵌入生成，大幅加速（默认行为）--skip-git允许对非 git 目录构建索引--skip-agents-md保留自定义的 CLAUDE.md / AGENTS.md--verbose输出详细日志，包括被跳过的文件--worker-timeout 60大型仓库增加 Worker 超时时间

预期输出：

text

Scanning files... ✓ (1,247 files)
Parsing code... ✓ (TypeScript, Python, etc.)
Resolving imports... ✓ (3,892 relationships)
Tracing calls... ✓ (104 processes)
Creating indexes... ✓
Done! Indexed 30,816 symbols in 12s

第 6 步：验证#

bash

gitnexus status
gitnexus list

status 确认当前项目的索引状态， list 展示全局所有已索引的仓库。

---

索引后可用的 MCP 工具#

工具用途list_repos查看所有已索引的仓库query混合搜索（关键词 + 语义），按执行流程分组context360° 符号视图（调用者、被调用、所属流程）impact爆炸半径分析 — 修改某个符号会影响哪些地方detect_changesGit diff 影响映射cypher原始图谱查询语言rename多文件协调重命名

MCP 资源：

资源用途gitnexus://repo/{name}/context代码库概览 + 索引新鲜度检查gitnexus://repo/{name}/clusters所有功能聚类gitnexus://repo/{name}/processes所有执行流程gitnexus://repo/{name}/schema图谱 Schema（Cypher 查询用）

---

常见问题排查#

"Not inside a git repository"（不在 git 仓库中）#

bash

git init && git add . && git commit -m "initial"
gitnexus analyze

或使用 --skip-git 跳过 git 检查：

bash

gitnexus analyze --skip-git

"Permission denied"（npm install -g 权限不足）#

改用 npx 免安装运行：

bash

npx gitnexus analyze

"Already indexed"（已索引）#

索引已存在且是最新的，无需操作。如需强制重建：

bash

gitnexus analyze --force

"Node version too old"（Node 版本过旧）#

需要 Node.js >= 22，升级后重试：

• Windows: winget install OpenJS.NodeJS.LTS
• macOS: brew install node
• Linux: 使用 nvm

MCP 工具未出现在 Claude Code / Cursor 中#

1. 重新执行 gitnexus setup
2. 重启编辑器
3. 确认 gitnexus 在 PATH 中：Windows 用 where gitnexus，Unix 用 which gitnexus

索引过期（代码变更后）#

bash

gitnexus analyze    # 增量更新，保留已有嵌入
gitnexus analyze --force  # 完全重建

---

对话示例#

用户："安装GitNexus"

执行：

1. 定位项目根目录
2. node --version → 确认 >= 22
3. gitnexus --version → 未安装 → npm install -g gitnexus
4. gitnexus setup → MCP 已配置则跳过
5. gitnexus status → 未索引 → gitnexus analyze
6. gitnexus status → 验证成功
7. 回复用户："已索引 N 个符号，生成知识图谱。可通过 context / impact / query 等 MCP 工具查询代码库。"