Semble、CodeGraph、GitNexus 对比调研

调研日期：2026-05-21

说明：本文中的 CodeGraph 指 colbymchenry/codegraph。同名项目较多，如果要比较的是 CodeGraphContext、code-graph-rag-mcp 或 codegraph.ru，结论需要单独重做。

一句话结论

这三个项目都在解决“AI 编程助手如何更可靠地理解代码库”的问题，但层级不同：

工具	最短定位	适合优先解决的问题
Semble	语义版 grep，为 agent 返回少量相关代码片段	快速找代码、减少 grep + read 带来的 token 浪费
CodeGraph	本地预索引代码知识图谱，面向 Claude Code / Codex / Cursor 等 agent	让 agent 用符号、调用关系、上下文图谱探索中大型仓库
GitNexus	更重的代码知识图谱与 Graph RAG 平台，含 Web UI、CLI、MCP、多仓能力	架构理解、依赖影响分析、跨模块/跨仓上下文、可视化探索

粗略选型：

• 只想让 agent 更快找到相关代码：选 Semble。
• 想在本地项目里给 agent 一个轻量图谱索引：选 CodeGraph。
• 想做更完整的代码知识图谱、Web 可视化、Graph RAG、多仓分析：看 GitNexus。

项目概览

维度	Semble	CodeGraph	GitNexus
GitHub	MinishLab/semble	colbymchenry/codegraph	abhigyanpatwari/GitNexus
包管理	PyPI: semble	npm: @colbymchenry/codegraph	npm: gitnexus
最新包版本	0.1.10	0.8.0	以 npm/GitHub 为准
GitHub 热度	约 3.4k stars	约 11k stars	约 39k stars
License	MIT	MIT	README 标注 PolyForm Noncommercial
本地运行	是	是	是，另有浏览器 Web UI
MCP	支持	支持	支持
核心数据结构	代码 chunk + hybrid search	SQLite 符号图谱 + FTS5	知识图谱、执行流、依赖/调用关系
主要目标	检索相关代码片段	agent 上下文与关系查询	深度代码分析和 Graph RAG

能力层级差异

可以把它们放在三层：

Semble
  代码搜索层：自然语言/符号查询 -> 相关代码片段

CodeGraph
  本地图谱层：文件、符号、调用、导入、路由、影响范围 -> agent 查询

GitNexus
  深度分析层：知识图谱、执行流、依赖链、聚类、多仓、Web 可视化、Graph RAG

Semble 更像“更聪明的搜索入口”；CodeGraph 是“给 agent 用的本地代码地图”；GitNexus 则接近“代码知识图谱平台”。

Semble

核心定位

Semble 是面向 AI agent 的代码搜索库。它用 tree-sitter 做代码切块，用 Model2Vec 静态 embedding、BM25、RRF 融合排序和代码感知 rerank，把自然语言问题或代码符号映射到少量相关片段。

官方强调它相比 grep + read 可减少约 98% token，并且 CPU 本地运行，无需 API key、GPU 或外部服务。

适合场景

• Agent 需要快速定位“某个功能在哪里实现”。
• 想降低 rg 搜到关键词后读取整文件造成的上下文浪费。
• 对调用图、影响分析要求不高，只需要高相关代码片段。
• 希望通过 MCP、CLI 或 AGENTS.md 给 Codex、Claude Code、Cursor、OpenCode 等工具接入搜索能力。
• 私有代码不能上传第三方服务，但可以接受本地索引和本地模型。

不适合场景

• 需要完整调用链、继承关系、跨模块影响分析。
• 需要精确 rename、find all references、类型跳转，这类仍应交给 LSP/IDE。
• 需要安全审计、依赖漏洞扫描、合规报告。
• 需要“必须找全”的查询。语义检索适合找高相关，不保证穷举。

工程判断

Semble 的引入成本最低，最适合作为 agent 的第一层搜索工具。它不会替代 rg，更像在 rg 前面加一个“先找最可能相关区域”的智能入口。

CodeGraph

核心定位

CodeGraph 是一个本地预索引代码知识图谱工具，主打 Claude Code、Codex、Cursor、OpenCode 等 agent。它用 tree-sitter 提取函数、类、方法、调用、导入、继承等关系，存入本地 .codegraph/codegraph.db SQLite 数据库，并通过 MCP/CLI 暴露查询能力。

官方 README 提到的核心能力包括：

• codegraph_search：按符号/名称查找。
• codegraph_context：为任务构建相关代码上下文。
• codegraph_callers / codegraph_callees：查调用方和被调用方。
• codegraph_impact：分析修改某符号的影响范围。
• codegraph_files / codegraph_status：查看索引文件结构和健康状态。

适合场景

• 中大型仓库，普通 grep 已经让 agent 频繁读错文件或读太多文件。
• 需要查询调用关系、影响范围、入口点和相关符号。
• 希望 100% 本地、无 API key、无外部服务。
• 主要使用 Claude Code、Codex、Cursor 或 OpenCode 做代码探索和改造。
• Web 框架项目，需要识别路由到 handler 的关系。CodeGraph README 提到支持 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等路由形态。

不适合场景

• 小仓库或一次性脚本。README 也提到小项目里原生搜索成本已经很低，收益会变窄。
• 只需要语义代码片段检索。此时 Semble 更轻。
• 需要跨仓统一知识图谱、Web 可视化分析或更完整的 Graph RAG 体验。
• 团队不愿维护本地索引目录，或不希望 agent 工作流依赖额外 MCP 配置。

工程判断

CodeGraph 是三者里“轻重比较均衡”的选择。它比 Semble 更理解结构关系，比 GitNexus 更贴近本地 agent 工作流和轻量安装。适合把它作为日常 coding agent 的默认代码地图。

GitNexus

核心定位

GitNexus 是更完整的代码知识图谱和 Graph RAG 工具。README 对它的定位是：把任意代码库索引为知识图谱，覆盖依赖、调用链、聚类和执行流，并通过智能工具让 AI agent 不遗漏代码关系。

它有两种主要使用方式：

• CLI + MCP：本地索引仓库，把深层代码结构暴露给 Cursor、Claude Code、Codex 等 agent。
• Web UI：浏览器内图谱探索和 AI chat，可上传 GitHub repo 或 ZIP；README 也提到浏览器模式受内存限制，约 5k 文件左右，后端/bridge 模式可扩展。

适合场景

• 需要架构级理解，而不只是找几个代码片段。
• 需要分析依赖链、调用链、执行流、功能聚类。
• 多仓库或大型仓库，需要统一视图。
• 需要可视化图谱，给团队做代码走读、架构审查、onboarding。
• 希望 agent 在修改前能看到更完整的系统关系，减少漏改依赖和破坏调用链。

不适合场景

• 只是想快速搜索代码。GitNexus 的能力更重，可能过度。
• 小项目、短期 demo、单体脚本。
• 商业项目未确认授权前直接引入。GitHub API 未识别标准 SPDX，README 徽章显示 PolyForm Noncommercial，需要认真审 license。
• 对工具链稳定性和配置成本极敏感的团队。GitNexus 功能面更大，索引、MCP、Web、bridge 等概念更多。

工程判断

GitNexus 更适合作为“代码理解平台”而不是单纯 agent 搜索工具。它的价值在复杂系统、多人团队、多仓和架构分析中放大；如果只是给单个 agent 减少 token，Semble 或 CodeGraph 会更轻。

横向对比

1. 搜索能力

工具	搜索体验	评价
Semble	自然语言/代码查询 -> 高相关 chunk	最专注、最快上手
CodeGraph	符号搜索 + 上下文构建 + FTS5	搜索和结构结合更好
GitNexus	Graph RAG + 图谱查询	最强，但也最重

2. 结构理解

工具	结构理解深度
Semble	主要靠代码切块和语义相关性，结构关系较弱
CodeGraph	文件、符号、调用、导入、继承、路由等关系
GitNexus	依赖、调用链、执行流、聚类、多仓知识图谱

3. Agent 适配

工具	Agent 接入方式	典型用途
Semble	MCP、CLI、AGENTS.md	搜索相关代码片段
CodeGraph	MCP、CLI、自动写 agent 配置	让 agent 查询图谱、调用关系、影响范围
GitNexus	MCP、CLI、Web UI、bridge	让 agent 获得架构级上下文

4. 维护成本

工具	维护成本	主要成本来源
Semble	低	安装、首次模型/依赖、索引缓存
CodeGraph	中	.codegraph 索引、MCP 配置、文件监听
GitNexus	中高	索引、图谱、Web/CLI/MCP/bridge、多仓配置

5. 风险点

工具	主要风险
Semble	项目较新；语义检索不能保证找全；不做深层影响分析
CodeGraph	需要 agent 正确调用工具才有收益；索引准确性依赖语言解析和图谱解析
GitNexus	License 需要确认；工具链更重；Web UI 模式可能受浏览器内存限制

选型建议

个人开发者 / 单仓项目

优先顺序：

1. Semble：先解决找代码和 token 浪费。
2. CodeGraph：当你开始需要调用关系和影响范围时引入。
3. GitNexus：除非你明确需要图谱可视化或深度架构分析。

中大型业务仓库

优先顺序：

1. CodeGraph：作为 agent 的本地代码地图。
2. Semble：作为快速语义搜索补充。
3. GitNexus：用于架构分析、复杂重构、团队 onboarding。

多仓库 / 平台团队 / 架构治理

优先顺序：

1. GitNexus：重点看多仓知识图谱和可视化分析。
2. CodeGraph：给每个具体仓库的 agent 工作流补充本地图谱。
3. Semble：作为轻量搜索能力嵌入日常工具链。

对 license 敏感的商业团队

优先顺序：

1. Semble：MIT。
2. CodeGraph：MIT。
3. GitNexus：先审查 PolyForm Noncommercial 和商业使用条款，再决定。

推荐组合

最轻组合

只接入 Semble。

适合：个人项目、小团队、希望快速提升 agent 找代码能力。

日常 agent 开发组合

CodeGraph + 原生 rg / IDE。

适合：希望 agent 能理解调用关系、影响范围，同时保留精确搜索和人工确认。

深度分析组合

GitNexus + CodeGraph + rg / LSP。

适合：复杂系统重构、架构审查、多仓影响分析。

搜索增强组合

Semble + CodeGraph。

适合：Semble 负责自然语言找片段，CodeGraph 负责结构关系和影响范围。

最终判断

如果只能选一个：

• 低成本试用：Semble。
• 日常 AI coding agent 增强：CodeGraph。
• 复杂系统理解和架构级分析：GitNexus。

更稳妥的路线是分阶段引入：

1. 先用 Semble 解决“找不到相关代码”和“读太多文件”。
2. 再用 CodeGraph 解决“调用关系、影响范围、任务上下文”。
3. 最后在复杂仓库或团队场景中评估 GitNexus，重点验证 license、索引稳定性、Web/CLI/MCP 是否符合团队流程。

参考来源

• MinishLab/semble
• Semble PyPI
• colbymchenry/codegraph
• @colbymchenry/codegraph npm
• abhigyanpatwari/GitNexus