# GitNexus **Repository Path**: yeylcode/GitNexus ## Basic Information - **Project Name**: GitNexus - **Description**: GitNexus：无需服务器的代码智能引擎。 GitNexus 是一款完全运行于浏览器端的客户端知识图谱构建工具。只需拖入 GitHub 仓库或 ZIP 文件，即可生成具备内置图 RAG 智能体的交互式知识图谱，是代码探索的绝佳利器。 - **Primary Language**: TypeScript - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-03-09 - **Last Updated**: 2026-03-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GitNexus abhigyanpatwari%2FGitNexus | Trendshift **为 Agent 上下文构建的 Git。** 将任意代码库索引为知识图谱 —— 涵盖每个依赖关系、调用链、集群和执行流程 —— 然后通过智能工具暴露这些信息，让 AI Agent 永不错过代码。 [![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus) [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/) https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72 > *像 DeepWiki，但更深入。* DeepWiki 帮助你*理解*代码。GitNexus 让你*分析*代码 —— 因为知识图谱追踪每个关系，而不仅仅是描述。 **一句话总结：** **Web UI** 是与任意仓库快速对话的方式。**CLI + MCP** 是让你的 AI Agent 真正可靠的方法 —— 它为 Cursor、Claude Code 和其他工具提供代码库的深层架构视图，让它们不再遗漏依赖、破坏调用链或盲目修改代码。即使是较小的模型也能获得完整的架构清晰度，使其能够与大模型竞争。 --- ## Star 历史 [![Star History Chart](https://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left) ## GitNexus 的两种使用方式 | | **CLI + MCP** | **Web UI** | | ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ | | **是什么** | 本地索引仓库，通过 MCP 连接 AI Agent | 浏览器中的可视化图谱探索器 + AI 聊天 | | **适用场景** | 使用 Cursor、Claude Code、Windsurf、OpenCode 进行日常开发 | 快速探索、演示、一次性分析 | | **规模** | 完整仓库，任意大小 | 受浏览器内存限制（约 5k 文件），或通过后端模式无限制 | | **安装** | `npm install -g gitnexus` | 无需安装 —[gitnexus.vercel.app](https://gitnexus.vercel.app) | | **存储** | KuzuDB 原生版（快速、持久化） | KuzuDB WASM（内存中、会话级） | | **解析** | Tree-sitter 原生绑定 | Tree-sitter WASM | | **隐私** | 全部本地运行，无网络 | 全部在浏览器中运行，无服务器 | > **桥接模式：** `gitnexus serve` 连接两者 —— Web UI 自动检测本地服务器，可以浏览所有 CLI 索引的仓库，无需重新上传或重新索引。 --- ## CLI + MCP（推荐） CLI 索引你的代码仓库并运行 MCP 服务器，为 AI Agent 提供深度代码库感知能力。 ### 快速开始 ```bash # 索引你的仓库（在仓库根目录运行） npx gitnexus analyze ``` 就这样。这会索引代码库、安装 Agent 技能、注册 Claude Code 钩子，并创建 `AGENTS.md` / `CLAUDE.md` 上下文文件 —— 全部通过一个命令完成。 要为你的编辑器配置 MCP，运行一次 `npx gitnexus setup` —— 或按照下面的说明手动配置。 ### MCP 设置 `gitnexus setup` 自动检测你的编辑器并写入正确的全局 MCP 配置。你只需要运行一次。 ### 编辑器支持 | 编辑器 | MCP | 技能 | 钩子（自动增强） | 支持程度 | | --------------------- | --- | ------ | -------------------- | -------------- | | **Claude Code** | 是 | 是 | 是 (PreToolUse) | **完整** | | **Cursor** | 是 | 是 | — | MCP + 技能 | | **Windsurf** | 是 | — | — | MCP | | **OpenCode** | 是 | 是 | — | MCP + 技能 | > **Claude Code** 获得最深度集成：MCP 工具 + Agent 技能 + PreToolUse 钩子，可自动用知识图谱上下文增强 grep/glob/bash 调用。 ### 社区集成 | Agent | 安装 | 来源 | |-------|---------|--------| | [pi](https://pi.dev) | `pi install npm:pi-gitnexus` | [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) | 如果你更喜欢手动配置： **Claude Code**（完整支持 — MCP + 技能 + 钩子）： ```bash claude mcp add gitnexus -- npx -y gitnexus@latest mcp ``` **Cursor**（`~/.cursor/mcp.json` — 全局，适用于所有项目）： ```json { "mcpServers": { "gitnexus": { "command": "npx", "args": ["-y", "gitnexus@latest", "mcp"] } } } ``` **OpenCode**（`~/.config/opencode/config.json`）： ```json { "mcp": { "gitnexus": { "command": "npx", "args": ["-y", "gitnexus@latest", "mcp"] } } } ``` ### CLI 命令 ```bash gitnexus setup # 为你的编辑器配置 MCP（一次性） gitnexus analyze [path] # 索引仓库（或更新过期的索引） gitnexus analyze --force # 强制完全重新索引 gitnexus analyze --skip-embeddings # 跳过嵌入生成（更快） gitnexus mcp # 启动 MCP 服务器（stdio）—— 服务所有已索引仓库 gitnexus serve # 启动本地 HTTP 服务器（多仓库）用于 Web UI 连接 gitnexus list # 列出所有已索引仓库 gitnexus status # 显示当前仓库的索引状态 gitnexus clean # 删除当前仓库的索引 gitnexus clean --all --force # 删除所有索引 gitnexus wiki [path] # 从知识图谱生成仓库 wiki gitnexus wiki --model # 使用自定义 LLM 模型生成 Wiki（默认：gpt-4o-mini） gitnexus wiki --base-url # 使用自定义 LLM API 基础 URL 生成 Wiki ``` ### 你的 AI Agent 获得什么 **通过 MCP 暴露的 7 个工具**： | 工具 | 功能 | `repo` 参数 | | ------------------ | ----------------------------------------------------------------- | -------------- | | `list_repos` | 发现所有已索引仓库 | — | | `query` | 流程分组的混合搜索（BM25 + 语义 + RRF） | 可选 | | `context` | 360 度符号视图 —— 分类引用、参与的流程 | 可选 | | `impact` | 影响半径分析，带深度分组和置信度 | 可选 | | `detect_changes` | Git 差异影响 —— 将修改的行映射到受影响的流程 | 可选 | | `rename` | 多文件协调重命名，结合图谱 + 文本搜索 | 可选 | | `cypher` | 原生 Cypher 图谱查询 | 可选 | > 当只有一个仓库被索引时，`repo` 参数是可选的。如果有多个仓库，需要指定哪一个：`query({query: "auth", repo: "my-app"})`。 **用于即时上下文的资源**： | 资源 | 用途 | | ----------------------------------------- | ---------------------------------------------------- | | `gitnexus://repos` | 列出所有已索引仓库（先读取这个） | | `gitnexus://repo/{name}/context` | 代码库统计、过期检查和可用工具 | | `gitnexus://repo/{name}/clusters` | 所有功能集群及其内聚分数 | | `gitnexus://repo/{name}/cluster/{name}` | 集群成员和详情 | | `gitnexus://repo/{name}/processes` | 所有执行流程 | | `gitnexus://repo/{name}/process/{name}` | 带步骤的完整流程追踪 | | `gitnexus://repo/{name}/schema` | Cypher 查询的图谱架构 | **用于引导工作流的 2 个 MCP 提示词**： | 提示词 | 功能 | | ----------------- | ------------------------------------------------------------------------- | | `detect_impact` | 预提交变更分析 —— 范围、受影响流程、风险等级 | | `generate_map` | 从知识图谱生成架构文档，包含 mermaid 图表 | **自动安装到 `.claude/skills/` 的 4 个 Agent 技能**： - **探索（Exploring）** — 使用知识图谱导航不熟悉的代码 - **调试（Debugging）** — 通过调用链追踪 bug - **影响分析（Impact Analysis）** — 在修改前分析影响半径 - **重构（Refactoring）** — 使用依赖映射规划安全的重构 --- ## 多仓库 MCP 架构 GitNexus 使用**全局注册表**，这样一个 MCP 服务器就可以服务多个已索引仓库。无需为每个项目配置 MCP —— 设置一次即可随处使用。 ```mermaid flowchart TD subgraph CLI [CLI Commands] Setup["gitnexus setup"] Analyze["gitnexus analyze"] Clean["gitnexus clean"] List["gitnexus list"] end subgraph Registry ["~/.gitnexus/"] RegFile["registry.json"] end subgraph Repos [Project Repos] RepoA[".gitnexus/ in repo A"] RepoB[".gitnexus/ in repo B"] end subgraph MCP [MCP Server] Server["server.ts"] Backend["LocalBackend"] Pool["Connection Pool"] ConnA["KuzuDB conn A"] ConnB["KuzuDB conn B"] end Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"] Analyze -->|"registers repo"| RegFile Analyze -->|"stores index"| RepoA Clean -->|"unregisters repo"| RegFile List -->|"reads"| RegFile Server -->|"reads registry"| RegFile Server --> Backend Backend --> Pool Pool -->|"lazy open"| ConnA Pool -->|"lazy open"| ConnB ConnA -->|"queries"| RepoA ConnB -->|"queries"| RepoB ``` **工作原理：** 每次 `gitnexus analyze` 将索引存储在仓库内的 `.gitnexus/` 中（可移植、gitignored），并在 `~/.gitnexus/registry.json` 中注册一个指针。当 AI Agent 启动时，MCP 服务器读取注册表并可以服务任何已索引的仓库。KuzuDB 连接在首次查询时延迟打开，并在 5 分钟不活动后被逐出（最多 5 个并发）。如果只有一个仓库被索引，所有工具的 `repo` 参数都是可选的 —— Agent 无需改变任何东西。 --- ## Web UI（基于浏览器） 完全客户端的图谱探索器和 AI 聊天。无服务器、无需安装 —— 你的代码永远不会离开浏览器。 **立即体验：** [gitnexus.vercel.app](https://gitnexus.vercel.app) — 拖放 ZIP 文件即可开始探索。 gitnexus_img 或本地运行： ```bash git clone https://gitee.com/yeylcode/GitNexus.git cd gitnexus/gitnexus-web # 1. 下载 CPU 版本的 ONNX Runtime wget https://github.com/microsoft/onnxruntime/releases/download/v1.21.0/onnxruntime-linux-x64-1.21.0.tgz # 2. 将文件放入 npm 缓存目录 mkdir -p ~/.npm/_cacache/content-v2/sha512/6c/4a mv onnxruntime-linux-x64-1.21.0.tgz ~/.npm/_cacache/content-v2/sha512/6c/4a/ # 3. 清理缓存（避免旧依赖干扰） npm cache clean --force # 4. 通过环境变量跳过 GPU 版本，强制安装 CPU 版本的 ONNX Runtime export ONNXRUNTIME_DISABLE_GPU=1 # 5. 重新加载配置文件 source ~/.bashrc # 6. 安装依赖 npm install # 7. 仅修复非破坏性漏洞 npm audit fix # 8. 应显示已安装的版本 npm list onnxruntime-node # 9. 编译 npm run build # 10. 启动，浏览器访问 http://${IP地址}:5173/ npm run dev -- --host 0.0.0.0 ``` Web UI 使用与 CLI 相同的索引管道，但完全在 WebAssembly 中运行（Tree-sitter WASM、KuzuDB WASM、浏览器内嵌入）。它适合快速探索，但对于较大的仓库受浏览器内存限制。 **本地后端模式：** 运行 `gitnexus serve` 并在本地打开 Web UI —— 它自动检测服务器并显示所有已索引仓库，支持完整的 AI 聊天功能。无需重新上传或重新索引。Agent 的工具（Cypher 查询、搜索、代码导航）自动通过后端 HTTP API 路由。 --- ## GitNexus 解决的问题 **Cursor**、**Claude Code**、**Cline**、**Roo Code** 和 **Windsurf** 等工具很强大 —— 但它们并不真正了解你的代码库结构。 **发生的情况：** 1. AI 修改 `UserService.validate()` 2. 不知道有 47 个函数依赖其返回类型 3. **破坏性变更被发布** ### 传统图谱 RAG vs GitNexus 传统方法给 LLM 原始图谱边，希望它探索得足够。GitNexus **在索引时预计算结构** —— 聚类、追踪、评分 —— 这样工具在一次调用中返回完整上下文： ```mermaid flowchart TB subgraph Traditional["Traditional Graph RAG"] direction TB U1["User: What depends on UserService?"] U1 --> LLM1["LLM receives raw graph"] LLM1 --> Q1["Query 1: Find callers"] Q1 --> Q2["Query 2: What files?"] Q2 --> Q3["Query 3: Filter tests?"] Q3 --> Q4["Query 4: High-risk?"] Q4 --> OUT1["Answer after 4+ queries"] end subgraph GN["GitNexus Smart Tools"] direction TB U2["User: What depends on UserService?"] U2 --> TOOL["impact UserService upstream"] TOOL --> PRECOMP["Pre-structured response: 8 callers, 3 clusters, all 90%+ confidence"] PRECOMP --> OUT2["Complete answer, 1 query"] end ``` **核心创新：预计算的关系智能** - **可靠性** — LLM 不会错过上下文，它已经在工具响应中 - **Token 效率** — 无需 10 次查询链来理解一个函数 - **模型民主化** — 较小的 LLM 也能工作，因为工具承担了繁重工作 --- ## 工作原理 GitNexus 通过多阶段索引管道构建代码库的完整知识图谱： 1. **结构** — 遍历文件树并映射文件夹/文件关系 2. **解析** — 使用 Tree-sitter AST 提取函数、类、方法和接口 3. **解析** — 使用语言感知逻辑跨文件解析导入和函数调用 4. **聚类** — 将相关符号分组为功能社区 5. **流程** — 从入口点通过调用链追踪执行流程 6. **搜索** — 构建混合搜索索引以实现快速检索 ### 支持的语言 TypeScript、JavaScript、Python、Java、C、C++、C#、Go、Rust --- ## 工具示例 ### 影响分析 ``` impact({target: "UserService", direction: "upstream", minConfidence: 0.8}) TARGET: Class UserService (src/services/user.ts) UPSTREAM (what depends on this): Depth 1 (WILL BREAK): handleLogin [CALLS 90%] -> src/api/auth.ts:45 handleRegister [CALLS 90%] -> src/api/auth.ts:78 UserController [CALLS 85%] -> src/controllers/user.ts:12 Depth 2 (LIKELY AFFECTED): authRouter [IMPORTS] -> src/routes/auth.ts ``` 选项：`maxDepth`、`minConfidence`、`relationTypes`（`CALLS`、`IMPORTS`、`EXTENDS`、`IMPLEMENTS`）、`includeTests` ### 流程分组搜索 ``` query({query: "authentication middleware"}) processes: - summary: "LoginFlow" priority: 0.042 symbol_count: 4 process_type: cross_community step_count: 7 process_symbols: - name: validateUser type: Function filePath: src/auth/validate.ts process_id: proc_login step_index: 2 definitions: - name: AuthConfig type: Interface filePath: src/types/auth.ts ``` ### 上下文（360 度符号视图） ``` context({name: "validateUser"}) symbol: uid: "Function:validateUser" kind: Function filePath: src/auth/validate.ts startLine: 15 incoming: calls: [handleLogin, handleRegister, UserController] imports: [authRouter] outgoing: calls: [checkPassword, createSession] processes: - name: LoginFlow (step 2/7) - name: RegistrationFlow (step 3/5) ``` ### 检测变更（预提交） ``` detect_changes({scope: "all"}) summary: changed_count: 12 affected_count: 3 changed_files: 4 risk_level: medium changed_symbols: [validateUser, AuthService, ...] affected_processes: [LoginFlow, RegistrationFlow, ...] ``` ### 重命名（多文件） ``` rename({symbol_name: "validateUser", new_name: "verifyUser", dry_run: true}) status: success files_affected: 5 total_edits: 8 graph_edits: 6 (high confidence) text_search_edits: 2 (review carefully) changes: [...] ``` ### Cypher 查询 ```cypher -- Find what calls auth functions with high confidence MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn) MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn) WHERE r.confidence > 0.8 RETURN caller.name, fn.name, r.confidence ORDER BY r.confidence DESC ``` --- ## Wiki 生成 从知识图谱生成 LLM 驱动的文档： ```bash # 需要 LLM API 密钥（OPENAI_API_KEY 等） gitnexus wiki # 使用自定义模型或提供商 gitnexus wiki --model gpt-4o gitnexus wiki --base-url https://api.anthropic.com/v1 # 强制完全重新生成 gitnexus wiki --force ``` Wiki 生成器读取索引的图谱结构，通过 LLM 将文件分组为模块，生成每个模块的文档页面，并创建概述页面 —— 全部带有到知识图谱的交叉引用。 --- ## 技术栈 | 层次 | CLI | Web | | ------------------------- | ------------------------------------- | --------------------------------------- | | **运行时** | Node.js（原生） | 浏览器（WASM） | | **解析** | Tree-sitter 原生绑定 | Tree-sitter WASM | | **数据库** | KuzuDB 原生版 | KuzuDB WASM | | **嵌入** | HuggingFace transformers.js（GPU/CPU） | transformers.js（WebGPU/WASM） | | **搜索** | BM25 + 语义 + RRF | BM25 + 语义 + RRF | | **Agent 接口** | MCP（stdio） | LangChain ReAct agent | | **可视化** | — | Sigma.js + Graphology（WebGL） | | **前端** | — | React 18、TypeScript、Vite、Tailwind v4 | | **聚类** | Graphology | Graphology | | **并发** | Worker threads + async | Web Workers + Comlink | --- ## 路线图 ### 正在积极开发 - [ ] **LLM 集群增强** — 通过 LLM API 生成语义集群名称 - [ ] **AST 装饰器检测** — 解析 @Controller、@Get 等 - [ ] **增量索引** — 仅重新索引修改的文件 ### 最近完成 - [X] Wiki 生成、多文件重命名、Git 差异影响分析 - [X] 流程分组搜索、360 度上下文、Claude Code 钩子 - [X] 多仓库 MCP、零配置设置、9 种语言支持 - [X] 社区检测、流程检测、置信度评分 - [X] 混合搜索、向量索引 --- ## 安全与隐私 - **CLI**：所有内容都在你的机器上本地运行。无网络调用。索引存储在 `.gitnexus/`（gitignored）中。全局注册表在 `~/.gitnexus/` 只存储路径和元数据。 - **Web**：所有内容都在你的浏览器中运行。没有代码上传到任何服务器。API 密钥仅存储在 localStorage 中。 - 开源 —— 你可以自己审计代码。 --- ## 致谢 - [Tree-sitter](https://tree-sitter.github.io/) — AST 解析 - [KuzuDB](https://kuzudb.com/) — 带向量支持的嵌入式图数据库 - [Sigma.js](https://www.sigmajs.org/) — WebGL 图谱渲染 - [transformers.js](https://huggingface.co/docs/transformers.js) — 浏览器 ML - [Graphology](https://graphology.github.io/) — 图数据结构 - [MCP](https://modelcontextprotocol.io/) — 模型上下文协议