古法编程

要为 AI 编程助手添加语义代码搜索能力，最简单的方法是安装 Claude Context 的 VSCode 扩展。本文将引导您完成从安装、配置嵌入模型与向量数据库，到首次索引代码库并执行语义搜索的全过程。您将学会如何利用这个扩展，让 Claude Code 或 Cursor 等助手精准理解您的代码库上下文。

Claude Context VSCode 扩展使用教程：安装、配置与语义搜索实操

Claude Context 项目通过一个 VSCode 扩展，将强大的语义代码搜索能力直接集成到您的编辑器中。这个扩展基于其核心引擎 @zilliz/claude-context-core，能将您的代码库转化为向量形式，并存储在 Zilliz Cloud 等向量数据库中，从而实现超越关键词的智能搜索。本文将手把手带您完成安装、配置到首次搜索的完整流程。

第一步：安装扩展

安装 Claude Context 的 VSCode 扩展非常简单，有两种主要方式。

  1. 通过 VSCode Marketplace 安装 您可以直接访问 VS Code Marketplace 的扩展页面 并点击安装。

  2. 在 VSCode 内手动搜索安装

    • 在 VSCode 中打开扩展视图（快捷键 Ctrl+Shift+X 或 Cmd+Shift+X）。
    • 在搜索框中输入 Semantic Code Search。
    • 在搜索结果中找到由 “zilliz” 发布的扩展，点击 Install 按钮即可。

安装完成后，VSCode 侧边栏会出现一个名为 “Semantic Search” 的新面板，这是后续进行搜索操作的主要界面。

第二步：核心配置

首次使用前，您需要配置三个关键部分：用于生成代码向量的嵌入（Embedding）提供商、用于分割代码的分割器（Splitter），以及用于存储向量的数据库。您可以通过点击侧边栏 “Semantic Search” 面板顶部的齿轮图标（⚙️）进入设置界面。

2.1 配置嵌入提供商

嵌入提供商负责将您的代码文本转换为机器可以理解的数值向量。扩展支持多种主流提供商。

  • OpenAI：在设置界面的 “Embedding Provider” 下拉菜单中选择 OpenAI。您需要填写：

    • Model name: 选择具体的嵌入模型，例如 text-embedding-3-small 或 text-embedding-3-large。
    • OpenAI API key: 您的 OpenAI API 密钥。
    • Custom API endpoint URL: 可选，用于自定义 API 端点，默认为 https://api.openai.com/v1。

  • 其他提供商：扩展还支持 Gemini、VoyageAI 以及用于本地模型的 Ollama。选择对应提供商后，填写相应的 API 密钥即可。

配置完成后，可以点击 Test Embedding 按钮测试连接是否正常。

2.2 配置代码分割器

代码分割器决定了如何将您的源文件切分成适合处理的片段。设置界面提供了以下选项：

  • Splitter Type：选择分割策略。
    • LangChain Splitter：基于字符的递归分割，更通用。
    • AST Splitter：基于语法抽象树（AST）的分割，推荐使用。它能更好地理解代码结构，生成语义更完整的代码块。
  • Chunk Size：每个代码块的最大字符数，默认为 1000。
  • Chunk Overlap：相邻代码块之间重叠的字符数，默认为 200。

2.3 配置 Zilliz Cloud 向量数据库

Claude Context 需要一个向量数据库来存储索引。您可以免费使用 Zilliz Cloud 提供的 Serverless 集群。

  1. 访问 Zilliz Cloud 注册并创建一个免费集群。
  2. 创建后，在 Zilliz Cloud 控制台中找到您的集群的**公开端点（Public Endpoint）**和 API Key。
  3. 回到扩展设置界面，在 “Vector Database Configuration” 部分填写：
    • Milvus Address：粘贴您的 Zilliz Cloud 公开端点。
    • Milvus Token：粘贴您的 API Key。
  4. 最后，点击 Save Configuration 保存所有设置。扩展将自动重新加载配置。

第三步：实操——索引代码库并执行搜索

配置完成后，您就可以开始使用扩展的核心功能了。整个过程分为两步：索引代码库和执行搜索。

3.1 索引当前代码库

索引是将您的代码转换为向量并存入数据库的过程，是执行搜索的前提。

  1. 打开 VSCode 的命令面板（快捷键 Ctrl+Shift+P 或 Cmd+Shift+P）。
  2. 输入并选择命令 Semantic Code Search: Index Codebase。
  3. 扩展会在后台开始处理。您可以在状态栏看到提示。索引完成后，会弹出通知。

您也可以直接在侧边栏的 “Semantic Search” 面板中，点击 Index Current Codebase 按钮来触发索引。

3.2 执行语义搜索

索引完成后，您可以立即进行搜索。

  1. 在侧边栏的 “Semantic Search” 面板的搜索框中，输入自然语言查询，例如 “用户登录认证的实现逻辑” 或 “数据序列化的主要函数”。
  2. （可选）在下方的 “Extension filter” 框中，输入文件后缀名（如 .py,.ts）可以限定搜索范围。
  3. 点击 Search 按钮。

搜索结果会显示在面板下方，每个结果都包含文件路径、匹配的代码片段以及一个相似度分数。您可以直接点击结果跳转到源文件的相应位置。

另一个便捷方式是在编辑器中，选中一段代码，然后通过命令面板执行 Semantic Code Search: Semantic Search 命令，这将以选中的代码作为查询进行语义搜索。

小结：扩展在激活时，通过 activate() 函数注册了 semanticCodeSearch.semanticSearch、semanticCodeSearch.indexCodebase、semanticCodeSearch.clearIndex 等命令，将这些操作映射到了具体的用户交互上。更多关于搜索命令实现的细节，可以参考 Claude Context VSCode 扩展搜索命令实现详解。

FAQ

Q: 索引时提示连接错误或失败怎么办？ A: 首先检查您在 Zilliz Cloud 配置中输入的地址和 Token 是否正确。其次，确保您的网络可以访问 Zilliz Cloud 的服务。您可以在 Zilliz Cloud 控制台检查集群状态是否正常。

Q: 搜索结果不理想或没有结果是什么原因？ A: 可能原因有几个：1) 代码库还未成功完成索引，请先执行 Index Codebase 命令。2) 嵌入模型配置有误，尝试使用 “Test Embedding” 功能测试连接。3) 查询语句过于模糊，尝试使用更具体、贴近代码功能的描述。您也可以尝试调整代码分割器的参数，例如使用 AST Splitter 并适当增大 Chunk Size。