VectorCode

VectorCode 是一个代码仓库索引工具。它通过索引并提供您正在处理的代码仓库的相关信息，帮助您为编码大模型构建更优质的提示词。该仓库还包含相应的 Neovim 插件，提供一组 API 供您构建或增强 AI 插件使用，并与一些流行的插件集成。

[!注意] 本项目目前处于测试阶段，正处于快速迭代中。我知道还有许多改进空间，欢迎任何帮助。

• 为什么选择 VectorCode？
• 文档
  • 关于版本控制
• 待办事项
• 致谢
  • 特别感谢
• 星标历史

为什么选择 VectorCode？

大语言模型通常对闭源项目、不知名项目以及尚未发布到正式版本中的前沿开发了解非常有限。它们在这些项目上的能力相当受限。借助 VectorCode，您可以轻松地（甚至以编程方式）将与任务相关的项目上下文注入到提示词中。这显著提升了模型输出的质量，并减少了幻觉现象。

文档

[!注意] main 分支上的文档反映了最新提交的代码状态。如需查看您所使用的版本对应的文档，可以 切换到相应标签。

• 关于命令行工具的设置和使用，请参阅 CLI 文档；
• 对于 Neovim 用户，在阅读完 CLI 文档后，请参考 Neovim 插件文档（可选：Lua API 参考）以获取进一步说明。
• 其他资源：
  • wiki，提供额外技巧和建议，帮助您充分利用 VectorCode；
  • 讨论区，您可以在其中提出一般性问题，并分享您对 VectorCode 的精彩用法。
  • 如果您想尝试一些新功能，不妨查看 拉取请求，了解正在进行中的特性开发。

如果您希望为本项目做出贡献，请查阅 贡献指南，其中包含一些基本准则及可能对您有帮助的提示。

关于版本控制

本项目采用调整后的语义化版本控制：

• 在 1.0.0 版本发布之前，主版本号保持为 0，表示该项目仍处于早期阶段，功能和接口可能会不时发生变化；
• 次要版本号用于标记__破坏性变更__。当我决定移除某个功能或配置选项时，实际移除操作会在次要版本号递增时进行。因此，如果您希望避免现有配置被破坏，可以选择类似 "vectorcode<0.7.0" 的版本约束；
• 补丁版本号用于标记__非破坏性变更__。这包括新增功能和错误修复。当决定弃用某些功能时，我会发布一个补丁版本递增的新版本。在次要版本号递增之前，被弃用的功能仍将正常工作，但会显示警告信息。建议您更新配置以适应新功能。

待办事项

• 按文件路径排除路径查询；
• 支持分块；
  • 为文件添加元数据；
  • 配置分块大小；
  • 更智能的分块方式（基于语义/语法），使用 py-tree-sitter 和 tree-sitter-language-pack 实现；
  • 可配置从查询结果中选择文档；
• 带有缓存的 NeoVim Lua API，用于在项目未被索引时跳过检索 现改为返回空数组；
• 异步缓存的工作池；
• 持久化客户端；
• 正式支持 远程 Chromadb（包括身份验证等）；
• 尊重 .gitignore 文件；
• 实现某种项目根锚点（例如 .git 或自定义的 .vectorcode.json），以增强自动检测项目根目录的功能。 已实现项目级别的 .vectorcode/ 和 .git 作为根锚点
• 能够查看和删除集合中的文件；
• 联合搜索（某种程度上，使用 codecompanion.nvim/MCP）；
• Nix 支持（非官方包 这里）；
• 查询重写 (#124)。

致谢

• @milanglacier（以及 minuet-ai.nvim）在本项目早期阶段提供的支持；
• @olimorris 在本项目首次尝试工具调用时提供的帮助（无论是个人层面还是通过 codecompanion.nvim）；
• @ravitemer 帮助将 VectorCode 与 MCP 进行对接；
• Nix 社区（尤其是 @sarahec 和 @GaetanLepage）维护 Nix 包的支持。

特别感谢

星标历史

VectorCode 快速上手指南

VectorCode 是一款代码仓库索引工具，旨在通过索引项目代码并为提示词（Prompt）提供上下文信息，帮助开发者为大语言模型（LLM）构建更精准的编程辅助提示，从而减少幻觉并提升输出质量。它提供命令行工具及 Neovim 插件集成。

注意：本项目目前处于 Beta 阶段，功能迭代迅速，接口可能发生变化。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL 推荐)。
• Python：版本需为 3.9 或更高。
• 包管理器：推荐使用 pip 或 pipx 进行安装。
• 可选依赖：
  • 若使用 Neovim 集成，需安装 Neovim 0.8+ 及 Lua 环境。
  • 若需智能代码分块（基于语法），工具会自动安装 py-tree-sitter 相关依赖。

安装步骤

方式一：使用 pip 安装（推荐）

直接使用 pip 安装最新稳定版：

pip install vectorcode

如果您希望将工具隔离在全局环境中而不污染项目依赖，推荐使用 pipx：

pipx install vectorcode

国内加速建议： 如果下载速度较慢，可使用国内镜像源安装：

pip install vectorcode -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：Nix 用户

如果您使用 Nix 包管理器，可以使用非官方源安装：

nix-env -iA nixpkgs.vectorcode

基本使用

VectorCode 的核心工作流分为两步：索引项目 和 查询上下文。

1. 初始化与索引项目

进入您的代码项目根目录（需包含 .git 文件夹或 .vectorcode.json 配置文件），运行以下命令建立索引：

vectorcode index

• 该命令会自动识别项目根目录。
• 默认会尊重 .gitignore 规则，忽略不需要索引的文件。
• 索引完成后，代码将被分块并存入本地向量数据库（默认使用 ChromaDB）。

2. 查询相关代码上下文

索引完成后，您可以针对特定问题查询相关的代码片段。例如，查询关于“用户认证逻辑”的代码：

vectorcode query "How is user authentication implemented?"

工具将返回与问题最相关的代码片段及其文件路径，您可以将这些内容直接复制到大模型的提示词中。

3. 在 Neovim 中使用（可选）

如果您是使用 Neovim 的开发者，安装 Python 包后，还需配置 Neovim 插件以调用 API。请参考 Neovim 插件文档 进行具体配置，配置成功后即可在编辑器内直接获取上下文信息。

---

下一步建议：

• 查看 CLI 详细文档 了解分块大小配置、排除路径等高级选项。
• 访问 Wiki 获取更多使用技巧。