Claude Context：让 AI 编程助手真正"看见"整个代码库

问题在哪

用 Claude Code、Cursor 这类 AI 编程工具写代码时，最常遇到的瓶颈不是模型能力不够，而是模型看不到足够多的代码。

一个中大型项目动辄几十万行代码，分布在上千个文件里。AI 助手每次只能看到你当前打开的文件，或者通过 grep、文件搜索一轮一轮地找相关代码。这个过程有两个代价：一是 token 消耗大，每次多轮搜索都在烧钱；二是慢，Agent 需要好几轮工具调用才能定位到真正相关的代码片段。

Claude Context 要解决的就是这个问题：把整个代码库变成一个可语义搜索的索引，让 AI 助手一次调用就能找到所有相关代码。

Claude Context 是什么

Claude Context 是 Zilliz 开源的一个 MCP 插件，给 AI 编程助手加上语义代码搜索能力。它不是一个独立的 IDE 或编辑器，而是通过 MCP（Model Context Protocol）协议接入现有工具链。

支持的客户端包括：Claude Code、Cursor、VS Code、Windsurf、Gemini CLI、OpenAI Codex CLI、Qwen Code、Cherry Studio、Cline 等。基本上只要支持 MCP 协议的 AI 编程工具都能用。

项目在 GitHub 上开源（MIT 协议），截至目前已有超过 10000 star。

核心架构

整个系统分三层：Core 引擎负责索引和搜索逻辑，MCP Server 负责对外暴露工具接口，客户端通过 MCP 协议调用。

代码分块：AST Splitter

代码不能整个文件丢进向量数据库，需要先切成合理大小的块。Claude Context 默认用 AST（抽象语法树）做代码分块，每块大约 2500 字符，块之间有 300 字符的重叠区域保证上下文连续性。

AST 分块的好处是能按函数、类、方法这些语义边界来切，不会把一个函数从中间劈开。如果某个文件的语言不支持 AST 解析，会自动回退到基于字符长度的分块策略。

Embedding 向量化

代码块切好之后，需要转成向量才能做语义搜索。Claude Context 支持四种 Embedding 提供商：

OpenAI（默认，text-embedding-3-small）
VoyageAI（专门为代码优化的 voyage-code-3）
Gemini（gemini-embedding-001）
Ollama（本地部署，数据不出本机）

可以通过环境变量 EMBEDDING_PROVIDER 和 EMBEDDING_MODEL 切换。如果对数据隐私有要求，Ollama 方案可以完全本地运行。

向量数据库：Milvus / Zilliz Cloud

向量存储用的是 Milvus，Zilliz 自家的开源向量数据库。可以用 Zilliz Cloud 的免费额度（注册就有），也可以自己部署 Milvus 实例。

搜索模式默认开启混合搜索（HYBRID_MODE=true），同时用 BM25 关键词匹配和稠密向量语义匹配，两路结果融合排序。纯语义搜索可能漏掉精确的函数名匹配，纯关键词搜索又抓不住语义相近但措辞不同的代码，混合模式兼顾两边。

Merkle Tree 增量同步

大型代码库全量重新索引很慢。Claude Context 用 Merkle DAG（有向无环图）做文件变更检测：每个文件算一个 SHA-256 哈希，目录树构成 Merkle 结构，只要某个文件内容变了，从它到根节点的路径上所有哈希都会变。

下次索引时，系统对比本地快照（存在 ~/.context/merkle/ 目录下）和当前文件状态，只重新处理变化的文件。对于日常开发场景，增量索引通常只需要处理几个文件，几秒钟就能完成。

工作流程

异步索引

索引是后台异步执行的。调用 index_codebase 工具后立即返回，不会阻塞 Agent 的其他操作。索引过程中可以随时搜索（会返回已索引部分的结果），也可以通过 get_indexing_status 查看进度。

进度报告是粗粒度的：0% 表示准备阶段，5% 左右是扫描文件列表，10% 到 100% 是实际处理文件、生成向量、写入数据库。大型代码库可能会在 10% 停留较长时间，这是正常的。

MCP 暴露的四个工具：

index_codebase：启动后台索引
search_code：语义搜索代码
get_indexing_status：查看索引进度
clear_index：清除索引数据

语义搜索

搜索时，用户的自然语言查询会被转成向量，在向量数据库中找到最相似的代码块。返回结果包含：代码内容、相对文件路径、起止行号、编程语言、相似度分数。

比如搜索"处理用户认证的函数"，即使代码里写的是 handleAuth 或 verifyToken，语义搜索也能匹配到。这是 grep 做不到的。

文件过滤

不是所有文件都需要索引。Claude Context 的过滤规则是多源合并的：

包含规则 （取并集）：默认支持的编程语言扩展名（.ts、.py、.java、.go 等 22 种）+ MCP 调用时动态传入的自定义扩展名 + 环境变量 CUSTOM_EXTENSIONS 指定的扩展名。

排除规则 （取并集）：内置忽略模式（node_modules、dist、.git 等）+ MCP 动态传入的忽略模式 + 环境变量 CUSTOM_IGNORE_PATTERNS + .gitignore + 任何 .xxxignore 文件 + 全局 ~/.context/.contextignore。

这意味着你可以直接告诉 Agent "索引这个代码库，包含 .vue 文件，排除 temp 目录"，Agent 会把这些参数传给 MCP 工具。

实测效果

Zilliz 团队在 SWE-bench Verified 数据集上做了对照实验。从中选了 30 个中等难度的问题（需要修改 2 个文件的那种），用 GPT-4o-mini 作为 Agent 模型，分别测试"只用 grep"和"grep + Claude Context"两种配置，每种跑 3 次取平均。

结果：

指标	只用 grep	grep + Claude Context	变化
F1 分数	0.40	0.40	持平
平均 token 消耗	73,373	44,449	-39.4%
平均工具调用次数	8.3	5.3	-36.3%

检索质量没有下降，但 token 消耗减少了近 40%，工具调用次数减少了 36%。换算成实际场景：每个任务省下约 29000 个 token，响应速度更快，成本更低。

在固定 token 预算下，这意味着同样的钱能处理更多任务，或者在 context window 有限的情况下能留出更多空间给推理。

快速上手

前置条件

Node.js >= 20
一个 Embedding API key（OpenAI、VoyageAI、Gemini 任选，或本地 Ollama）
一个向量数据库（Zilliz Cloud 免费注册即可）

Claude Code 配置

bash 复制代码

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-key \
  -e MILVUS_ADDRESS=your-zilliz-endpoint \
  -e MILVUS_TOKEN=your-zilliz-api-key \
  -- npx @zilliz/claude-context-mcp@latest

Cursor 配置

编辑 ~/.cursor/mcp.json：

json 复制代码

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key",
        "MILVUS_ADDRESS": "your-zilliz-endpoint",
        "MILVUS_TOKEN": "your-zilliz-api-key"
      }
    }
  }
}

Gemini CLI 配置

编辑 ~/.gemini/settings.json，结构和 Cursor 一样。

全局配置（推荐）

如果你在多个工具里都要用，可以把环境变量写到全局配置文件，避免每个客户端重复配置：

bash 复制代码

mkdir -p ~/.context
cat > ~/.context/.env << 'EOF'
EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-your-key
EMBEDDING_MODEL=text-embedding-3-small
MILVUS_ADDRESS=your-zilliz-endpoint
MILVUS_TOKEN=your-zilliz-api-key
EOF

配好之后，各客户端的 MCP 配置里就不需要再写环境变量了。

进阶配置

切换 Embedding 模型

如果想用更高质量的 Embedding（代价是更贵或更慢）：

bash 复制代码

# OpenAI 大模型
EMBEDDING_MODEL=text-embedding-3-large

# VoyageAI 代码专用
EMBEDDING_PROVIDER=VoyageAI
VOYAGEAI_API_KEY=pa-your-key
EMBEDDING_MODEL=voyage-code-3

# 本地 Ollama（数据不出本机）
EMBEDDING_PROVIDER=Ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_HOST=http://127.0.0.1:11434

调整批处理大小

默认每批处理 100 个代码块。如果你的 Embedding API 吞吐量高，可以加大批次减少索引时间：

bash 复制代码

EMBEDDING_BATCH_SIZE=512

自定义文件类型和忽略规则

bash 复制代码

# 额外索引 Vue、Svelte 文件
CUSTOM_EXTENSIONS=.vue,.svelte,.astro

# 额外排除某些目录
CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**

自定义集合名

默认集合名是路径哈希，不太可读。可以加一个前缀：

bash 复制代码

CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project
# 最终集合名：code_chunks_my_project_<pathHash>

混合搜索开关

如果只想用纯向量搜索（省一些存储空间）：

bash 复制代码

HYBRID_MODE=false

适用场景

适合用的情况：

代码库超过几万行，grep 搜索需要多轮才能定位到相关代码
团队项目，你不熟悉所有模块的实现细节
需要频繁做跨文件的代码理解和修改
想降低 AI 编程助手的 token 消耗

不太需要的情况：

小项目（几千行代码），Agent 直接读文件就够了
你对代码库了如指掌，能直接告诉 Agent 去哪个文件找
对数据隐私有极高要求，又不想部署本地 Ollama + 本地 Milvus

一个实际的判断标准： 如果你发现 Agent 经常需要 5 次以上工具调用才能找到相关代码，Claude Context 大概率能帮上忙。

技术细节补充

代码库识别方式

Claude Context 用解析后的绝对路径来标识一个代码库。同一个仓库如果通过不同路径访问（比如符号链接、不同的 clone 位置），会被当作不同的代码库分别索引。建议对同一个项目始终用同一个路径调用。

本地状态文件

~/.context/merkle/<hash>.json：Merkle 树快照，用于增量同步
~/.context/mcp-codebase-snapshot.json：索引状态元数据

项目结构

项目是 monorepo 结构，主要包含：

packages/core：核心引擎，npm 包 @zilliz/claude-context-core
packages/mcp：MCP Server，npm 包 @zilliz/claude-context-mcp
packages/vscode-extension：VS Code 扩展
packages/chrome-extension：Chrome 浏览器扩展
evaluation：基于 SWE-bench 的评估框架

Core 包也可以独立使用，不依赖 MCP 协议：

typescript 复制代码

import { Context, OpenAIEmbedding, MilvusVectorDatabase } from '@zilliz/claude-context-core';

const context = new Context({
  embedding: new OpenAIEmbedding({ apiKey: 'sk-...' }),
  vectorDatabase: new MilvusVectorDatabase({ address: '...', token: '...' })
});

// 索引
await context.indexCodebase('./my-project', (progress) => {
  console.log(`${progress.phase} - ${progress.percentage}%`);
});

// 搜索
const results = await context.semanticSearch(
  './my-project',
  'user authentication handler',
  5
);

和其他方案的对比

vs grep / ripgrep： grep 只能做精确字符串匹配，搜"认证逻辑"找不到 verifyToken。Claude Context 能理解语义。但 grep 不需要预先索引，对小范围搜索更快。两者配合使用效果最好，评估数据也是在 grep 基础上加 Claude Context。

vs 全文件加载： 把整个目录丢给 Agent 读，token 消耗极高，大项目根本装不下。Claude Context 只返回最相关的代码片段，token 效率高得多。

vs 其他代码 RAG 方案： Claude Context 的优势在于：通过 MCP 协议接入，不绑定特定 IDE；支持多种 Embedding 提供商；混合搜索（BM25 + 向量）；Merkle Tree 增量索引避免重复计算。劣势是需要外部向量数据库（虽然 Zilliz Cloud 有免费额度）。

总结

Claude Context 解决的是一个很具体的问题：让 AI 编程助手在大型代码库中快速找到相关代码，减少多轮搜索的 token 浪费。架构设计上，AST 分块保证代码语义完整，混合搜索兼顾精确匹配和语义理解，Merkle Tree 让增量更新高效。

配置门槛不高，一行命令加三个环境变量就能跑起来。如果你日常用 AI 编程助手处理中大型项目，值得试一下。

项目地址：github.com/zilliztech/... 协议：MIT