我们尝试了向量、抽象语法树（AST）以及粗暴地堆砌上下文以进行代码检索。带有大语言模型（LLM）生成语义的图结构效果最佳。以下是我们的经验总结。

过去的一年里，我们构建了一个代码索引系统，并尝试了几乎每一种检索方法。在此分享实际有效和无效的方法，因为目前关于“直接用嵌入向量”或“直接用 Tree-sitter”的讨论忽略了一些细微差别。**核心问题**在于，AI 编码工具在每个会话中都会重新读取你的整个代码库。上下文窗口虽然变大了，但这只是意味着你花费更多的 token 重复说同样的话。我们需要的是针对代码库的持久化结构化记忆。 **我们尝试过的方法及其失败原因：** * **代码块的向量嵌入**：听起来显而易见，但在实践中效果不佳。支付服务中的 `process()` 函数和图像流水线中的 `process()` 函数会因为 token 相似而被映射到相似的向量。但事实上，它们之间没有任何关联。向量扁平化了调用图、继承关系和导入关系——这些让代码具有意义的结构性关系。检索精度之差以至于我们完全放弃了这种方法。 * **Tree-sitter AST 解析**：精确且快速。但它只提供了结构，没有提供含义。它能告诉你某个函数存在以及它调用了什么，但它无法告诉你“这个函数处理 Stripe 支付失败后的 webhook 重试”。对于用业务语言表述的开发者问题，纯 AST 方法力不从心。 **实际有效的方法：** 对每个文件进行 LLM 分析，为每个文件生成目的、摘要和业务上下文，并将这些信息作为节点存储在 Neo4j 图中，边缘连接到类、函数、关键词和导入。然后，在这些语义字段上执行全文搜索，而不是依赖向量相似度。这符合近期论文的研究发现。RepoGraph (ICLR 2025) 显示，基于图的方法在 SWE-bench 上提升了 32.8%。Code-Craft 显示，来自代码图的自底向上 LLM 摘要使 top-1 检索精度提高了 82%。 这种方法的权衡是索引成本。你需要对每个文件进行一次 LLM 调用。我们使用 SHA-256 差异对比，因此重新索引只针对更改过的文件，这使得成本可控，但前期成本确实是存在的。 我们开源了该系统，如果任何人想查看实现或找出其中的漏洞，欢迎参与：[github.com/ByteBell/bytebell-oss](http://github.com/ByteBell/bytebell-oss) 我真心好奇其他人看到了什么。有没有人在大型代码库上运行 GitNexus、Sourcegraph 或 Augment？与暴力填充上下文相比，检索质量感觉如何？有没有人发现在代码上使用嵌入向量能取得好效果而我却遗漏了？ **与显而易见的竞争者有何不同** 我知道“代码知识图谱”现在是一个拥挤的领域，所以以下是我们 `comparison.md` 中诚实的并列比较： | | Bytebell | PageIndex | GitNexus | GraphRAG | Sourcegraph/Cody | Augment | |:-|:-|:-|:-|:-|:-|:-| | **领域** | 代码 | 长 PDF/文档 | 代码 | 通用文本 | 代码 | 代码 | | **部署** | 本地 Bun 守护进程，自带基础设施 | Python 库 + 云端 | 浏览器/WASM 或 CLI | Python 库 | 自托管或 SaaS | SaaS | | **索引** | 每文件 LLM → 目的 + 摘要 + 业务上下文 + 实体 | 目录推理树 | Tree-sitter AST + 社区检测 | 每块 LLM 实体 + 社区聚类 | LSIF/SCIP 搜索索引 | 专有语义索引 | | **存储** | Neo4j + MongoDB | 目录树，无向量数据库 | LadybugDB (前 Kuzu) | Parquet/GraphML | 专有 | 专有云 | | **每节点语义** | `purpose` / `summary` / `businessContext` | 无（结构性） | 可选每符号 | 社区文本摘要 | 无（基于搜索） | 嵌入向量 | | **差异感知重新索引** | 每文件 SHA-256，LLM 成本 ∝ 变化率 | 完全重新解析 | Git-diff 钩子 | 完全重新提取 | 增量 | 连续（托管） | | **出站调用** | 仅 OpenRouter，绑定 [127.0.0.1](http://127.0.0.1) | 云端代理选项 | 无 | 仅 LLM 提供商 | 代码片段 → 云端 LLM | 源代码 → SaaS | | **向量？** | **否** — 仅图 + 全文 | 否 | 可选 | 是（社区） | 否 | 是 | 简而言之，差异化在于： * **与 PageIndex 相比** — PageIndex 非常适合 PDF 和财报文件，但不适合代码。没有代码图，没有 MCP 服务器，没有类/函数/导入边缘。 * **与 GitNexus 相比** — 最接近的邻居。两者都是原生的 MCP 代码图。GitNexus 使用 Tree-sitter AST（精确但受限于语言且仅包含结构）；Bytebell 使用 LLM 生成的每文件叙述语义（`purpose` / `summary` / `businessContext`），因此检索匹配开发者*的意思*，而不仅仅是代码拼写的表面。我们索引的是词汇差距；他们索引的是语法。 * **与 Microsoft GraphRAG 相比** — GraphRAG 用于叙述性文本。每块实体提取 + 社区聚类不能很好地映射到代码上，因为代码中的“社区”是一个服务或模块。我们借用了图的想法，并为代码重建了模式。 * **与 Sourcegraph 相比** — Sourcegraph 是带有 LSIF/SCIP 的搜索索引。功能强大，但没有每节点语义增强，没有原生 MCP 检索界面，且云端版本会将片段发送出去。Bytebell 是单租户、本地的，每个节点都有结构化语义。 * **与 Augment 相比** — Augment 是一个很好的 SaaS 上下文引擎，但你的源代码会发送到他们的服务器。Bytebell 绑定到 [127.0.0.1](http://127.0.0.1)，唯一的出站调用是用于每文件分析的 OpenRouter（如果你愿意，可以路由到本地模型）。 # 检索形态 只有三个 MCP 工具——就是这样： 1. `smart_search(query)` — 融合六通道搜索，跨越文件目的/摘要、业务上下文、路径、关键词名称、类/函数签名、模块导入。返回排名靠前的 top-K 结果，并带有文件夹聚类。 2. `keyword_lookup(term)` — 反向：术语 → 所有匹配的命名实体（关键词、类、函数、模块）→ 文件。 3. `retrieve_file` — `metadata`（目的 + 类/函数行范围）、`content`（特定行范围或带有周围上下文的文件内搜索）、`bulk_search`（并行扫描最多 50 个文件）。 大多数形式良好的代码问题可在 2-4 次工具调用中解决。无需重新克隆，无需完整文件转储，无需嵌入向量往返。 # 快速开始 ```bash # 前提条件: Bun ≥1.1, Docker, OpenRouter 密钥 bytebell set openrouter-api-key sk-or-... bytebell set openrouter-model anthropic/claude-sonnet-4.6 bytebell boot # 在本地启动 Mongo+Neo4j+Redis bytebell index https://github.com/anthropics/claude-code # 索引 Claude Code claude mcp add --transport http bytebell http://127.0.0.1:8080/mcp ``` # 研究基础（供好奇者参考） 这种形态——摄入时的图 + 每节点 LLM 派生的语义 + MCP 检索——遵循近期的研究工作，表明纯结构性（AST/调用图）和纯语义（嵌入向量）检索都留下了大量未解决的问题： * RepoGraph (ICLR 2025) — SWE-bench 提升 32.8% * CodexGraph (NAACL 2025) — 图数据库查询胜过仅相似性检索 * Code-Craft (2504.08975) — 来自代码图的自底向上 LLM 摘要，top-1 检索精度提升 82% * Hierarchical Repo-Level Code Summarization (ICSE LLM4Code 2025) — 与我们 `purpose`/`summary`/`businessContext` 模式最接近的动机匹配 完整的阅读列表和链接在 README 中。 # 这**不是**什么 * 不是托管产品。不是聊天 UI。不是多租户。只有一个租户（`orgId="local"`），服务器绑定到 127.0.0.1。 * 目前还不是企业级 Sourcegraph 的替代品——尚未有跨文件调用边缘（这是为了语言无关摄入而做出的有意权衡；未来策略将添加它们）。 * 商业使用不免费。AGPL-3.0 + 非商业条款。如果你想将此项用于营利产品，那是另一回事（`[email protected]`）。 **仓库:** [https://github.com/ByteBell/bytebell-oss](https://github.com/ByteBell/bytebell-oss) 欢迎诚实的反馈、问题和“你在 X 上是错的”——特别是来自那些在实际项目中使用 GitNexus、Sourcegraph 或 Augment 的人。我们在比较表中力求公平，但也乐于接受纠正。