zilliz/claude-context-core 实战指南构建向量化代码语义搜索与增量索引引擎【免费下载链接】claude-contextCode search MCP for Claude Code. Make entire codebase the context for any coding agent.项目地址: https://gitcode.com/GitHub_Trending/co/claude-contextzilliz/claude-context-core是 Claude Context 项目Code search MCP for Claude Code让整个代码库成为任意编码 Agent 的上下文的核心索引引擎负责将代码库切分、向量化并存入 Milvus 向量数据库从而支持基于自然语言查询的代码语义搜索。本文以 packages/core/README.md 为骨架结合仓库源码深入讲解其安装配置、核心 API、嵌入模型选择、AST 分割原理与基于 Merkle 树的增量同步机制读完你就能在自己的项目中独立接入这套代码检索能力。一、快速安装与环境准备1.1 安装核心包作为发布在 npm 上的独立包安装方式与普通依赖一致核心引擎实际版本号以 packages/core/package.json 为准npm install zilliz/claude-context-core该包发布内容包含编译产物dist与README.md使用 TypeScript 编写导出类型定义可直接在ts/tsx项目中获得完整的类型提示。1.2 准备环境变量Embedding 与向量数据库运行前需要两组凭据Embedding 模型 API Key与向量数据库地址/Token。OpenAI API Key默认 Embedding 提供方OPENAI_API_KEYyour-openai-api-keyMilvus / Zilliz Cloud 向量数据库Claude Context 依赖向量数据库存储分块与向量。推荐在 Zilliz Cloud 注册并创建免费的 Serverless 集群创建完成后在控制台复制public endpoint公网端点与API keyMILVUS_ADDRESSyour-zilliz-cloud-public-endpoint MILVUS_TOKENyour-zilliz-cloud-api-key提示多场景使用时建议将这些变量写入全局配置文件~/.context/.env一次性生效无需在每个 MCP 客户端重复声明。详细优先级进程环境变量 全局配置文件 默认值与完整变量清单见 docs/getting-started/environment-variables.md。二、Quick Start三分钟跑通索引与搜索核心包的使用围绕三个抽象Context编排入口、Embedding嵌入提供方、VectorDatabase向量数据库。最小可运行示例import { Context, OpenAIEmbedding, MilvusVectorDatabase } from zilliz/claude-context-core; // 初始化嵌入提供方 const embedding new OpenAIEmbedding({ apiKey: process.env.OPENAI_API_KEY || your-openai-api-key, model: text-embedding-3-small }); // 初始化向量数据库 const vectorDatabase new MilvusVectorDatabase({ address: process.env.MILVUS_ADDRESS || localhost:19530, token: process.env.MILVUS_TOKEN || }); // 创建 Context 实例 const context new Context({ embedding, vectorDatabase }); // 索引整个代码库 const stats await context.indexCodebase(./my-project, (progress) { console.log(${progress.phase} - ${progress.percentage}%); }); console.log(Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks); // 语义搜索 const results await context.semanticSearch( ./my-project, function that handles user authentication, 5 ); results.forEach(result { console.log(${result.relativePath}:${result.startLine}-${result.endLine}); console.log(Score: ${result.score}); console.log(result.content); });工作流程分为三步Context构造时合并各类配置并校验vectorDatabase必填缺失会直接抛错indexCodebase递归扫描、切分、向量化并批量写入集合semanticSearch将查询文本编码后到集合中检索相似分块并附带相似度分数。从源码看索引阶段的进度回调按准备集合 → 扫描文件 → 逐文件处理10%~100%推进progress对象包含phase、current、total、percentage四个字段可用于大型仓库的进度展示见 packages/core/src/context.ts 中indexCodebase的实现。三、核心能力总览多语言支持内置 TypeScript、JavaScript、Python、Java、C、C#、Go、Rust、Scala 等主流语言的 AST 解析另支持 Markdown、Jupyter Notebook 等文本/标记文件语义搜索以 AI 嵌入向量为媒介支持自然语言查询代码灵活架构嵌入提供方与向量数据库均抽象为接口可插拔替换智能切分基于 AST 的代码分割保留上下文与结构边界批处理分块缓冲 批量向量化支持大代码库的高效处理与进度回调模式匹配内置针对构建产物、依赖目录的忽略规则增量文件同步基于 Merkle 树的高效变更检测仅重新索引变更文件。四、嵌入提供方Embedding Providers源码解析Context默认使用 OpenAI但四个提供方OpenAI、VoyageAI、Gemini、Ollama可通过环境变量EMBEDDING_PROVIDER切换。注意EMBEDDING_MODEL是通用变量对所有提供方生效直接设置模型名即可。4.1 OpenAI Embeddings在 packages/core/src/embedding/openai-embedding.ts 中内置模型表如下模型向量维度说明text-embedding-3-small1536高性能、高性价比推荐text-embedding-3-large3072最高性能、维度更大text-embedding-ada-0021536旧版模型建议改用 3-small实现细节值得注意对已知模型直接使用内置维度无需调用 API对自定义模型则通过一次真实调用探测维度。OpenAIEmbeddingConfig还支持baseURL可对接兼容 OpenAI 协议的自定义端点Context构造时若设置了OPENAI_BASE_URL会自动透传。4.2 VoyageAI Embeddings专为代码检索优化的提供方默认模型voyage-code-31024 维、上下文长度 32000。其支持模型表见 packages/core/src/embedding/voyageai-embedding.ts非常丰富包括通用检索的voyage-3.5系列、代码专用voyage-code-3以及金融、法律等垂直领域的voyage-finance-2、voyage-law-2。模型维度可通过getSupportedModels()查询多数模型支持 256/512/1024/2048 多档维度配置上下文长度 32000 是该引擎单次处理文本的硬上限。4.3 Gemini 与 OllamaGeminiGoogle 的嵌入模型如gemini-embedding-001通过GEMINI_API_KEY配置Ollama完全本地化的嵌入方案通过OLLAMA_HOST默认http://127.0.0.1:11434连接本地模型适合数据不出内网或离线场景。4.4 运行时切换提供方Context.updateEmbedding(embedding)可在运行期切换嵌入提供方切换后下一次索引/搜索即使用新实例。切换时引擎会调用getProvider()输出当前提供方名称方便排查。五、向量数据库Milvus / Zilliz Cloud目前引擎内置 Milvus 系向量数据库支持MilvusVectorDatabase核心依赖zilliz/milvus2-sdk-node。VectorDatabase接口见 packages/core/src/vectordb/types.ts抽象了完整生命周期能力集合管理createCollection稠密向量、createHybridCollection稠密稀疏双字段混合、dropCollection、hasCollection、listCollections、getCollectionRowCount数据写入insert/insertHybrid检索search纯向量检索、hybridSearch多字段混合检索 重排维护delete、query按过滤表达式查询、checkCollectionLimit。5.1 混合检索Hybrid Search机制引擎默认开启混合检索HYBRID_MODEtrue它同时执行两路检索见 packages/core/src/context.ts 的semanticSearch分支稠密向量检索查询文本 → Embedding → 在vector字段上 ANN 搜索nprobe: 10稀疏/关键词检索查询原文直接在sparse_vector字段上做 BM25 式检索drop_ratio_search: 0.2RRF 融合重排两路结果按 Reciprocal Rank Fusionk: 100合并limit与可选filterExpr在融合阶段生效。混合检索能显著提升代码检索质量语义相近但关键词不重叠的代码片段靠稠密向量召回含精确符号/函数名如authenticateUser的片段靠关键词召回。若希望只做纯向量检索将HYBRID_MODEfalse即可回退到单路search路径支持topK、threshold、filterExpr。5.2 集合命名规则getCollectionName()根据代码库绝对路径生成集合名默认形如code_chunks_pathHash稠密模式或hybrid_code_chunks_pathHash混合模式其中pathHash是绝对路径 MD5 的前 8 位。这保证了同一份代码在不同机器、不同路径下拥有独立集合互不污染。CODE_CHUNKS_COLLECTION_NAME_OVERRIDE环境变量可自定义可读前缀但引擎会强制保留_pathHash后缀以隔离多代码库且对非法字符做清洗非[A-Za-z0-9_]替换为下划线超长截断总长度不超过 Milvus 的 255 字符上限。六、代码分割器Code Splitters切分质量直接决定检索召回率。引擎提供两种策略默认AST 分割器SPLITTER_TYPEast6.1 AST Code Splitter默认基于 tree-sitter支持 JavaScript、TypeScript、Python、Java、C/C、Go、Rust、C#、Scala 共 9 种语言。核心思想是按逻辑代码单元切分而非纯字符截断每种语言定义一组可分割的语法节点类型例如 Python 的function_definition、class_definition、decorated_definition、async_function_definitionTypeScript 额外包含interface_declaration、type_alias_declarationGo 则包含function_declaration、method_declaration、type_declaration、var_declaration、const_declaration遍历语法树命中可分割节点即生成一个分块并记录精确的startLine/endLine/language/filePath元数据若单个语法单元仍超过chunkSize默认 2500 字符会按行二次细分相邻分块间叠加chunkOverlap默认 300 字符的重叠区防止跨块语义被截断丢失若语法树解析失败或语言不受支持自动回退到 LangChain 字符级分割器日志会输出falling back to LangChain保证任何文件都能被索引。6.2 LangChain Code Splitter字符级分割方案基于langchain依赖实现不感知代码结构适合 AST 不支持的边缘语言或纯文本场景可通过SPLITTER_TYPElangchain全局切换也可在构造Context时注入codeSplitter实例。6.3 查询分割策略getSplitterStrategyForLanguage(language)与isLanguageSupported(language)两个方法可在索引前预判某个语言会走 AST 还是 LangChain 路径便于在上层 UI如 MCP 工具中展示预期行为。七、配置详解ContextConfig 与过滤规则7.1 ContextConfig 完整字段interface ContextConfig { embedding?: Embedding; // 嵌入提供方默认 OpenAIEmbedding vectorDatabase?: VectorDatabase; // 向量数据库实例必填 codeSplitter?: Splitter; // 分割策略默认 AstCodeSplitter(2500, 300) supportedExtensions?: string[]; // 需要索引的文件扩展名 ignorePatterns?: string[]; // 忽略模式 customExtensions?: string[]; // MCP 等外部传入的自定义扩展名 customIgnorePatterns?: string[]; // MCP 等外部传入的自定义忽略模式 }从 packages/core/src/context.ts 构造逻辑看各配置项的合并优先级为默认值 构造参数 custom*字段 环境变量CUSTOM_EXTENSIONS、CUSTOM_IGNORE_PATTERNS支持逗号分隔最终去重。因此默认内置规则永远生效自定义规则是增量叠加。7.2 默认支持的文件扩展名[ // 编程语言 .ts, .tsx, .js, .jsx, .py, .java, .cpp, .c, .h, .hpp, .cs, .go, .rs, .php, .rb, .swift, .kt, .scala, .m, .mm, .dart, .sol, // 文本与标记文件 .md, .markdown, .ipynb ]注意.txt、.json、.yaml、.sh等扩展名在源码中以注释形式预留但默认未启用如需要可自行通过supportedExtensions或CUSTOM_EXTENSIONS添加。7.3 默认忽略模式引擎内置了针对常见噪声文件的忽略规则源码 packages/core/src/context.ts 中DEFAULT_IGNORE_PATTERNS是 README 所列规则的超集构建产物与依赖目录node_modules/**、dist/**、build/**、out/**、target/**、coverage/**、.nyc_output/**版本控制.git/**、.svn/**、.hg/**IDE 文件.vscode/**、.idea/**、*.swp、*.swo缓存目录.cache/**、__pycache__/**、.pytest_cache/**日志与临时文件logs/**、tmp/**、temp/**、*.log环境与配置.env、.env.*、*.local压缩与打包文件*.min.js、*.min.css、*.bundle.js、*.map等7.4 忽略模式的加载来源重要增强除了内置规则loadIgnorePatterns()见 packages/core/src/context.ts还会自动加载三类外部规则并合并代码库根目录下所有.xxxignore文件凡是文件名以.开头、以ignore结尾的文件如.gitignore、.dockerignore都会被读取空行与#注释被过滤全局忽略文件~/.context/.contextignore跨项目生效请求级模式indexCodebase/reindexByChange的additionalIgnorePatterns参数。7.5 模式管理 APIcontext.updateIgnorePatterns(patterns); // 重置为「默认 新列表」 context.addCustomIgnorePatterns(patterns); // 在现有基础上增量追加 context.addCustomExtensions(extensions); // 增量追加扩展名自动补点前缀、去重 context.resetIgnorePatternsToDefaults(); // 仅保留内置默认规则addCustomExtensions会自动为未带.的扩展名补点并去重适合上层 MCP 工具在会话中动态追加.vue、.svelte等扩展。八、API ReferenceContext 核心方法Context是引擎的门面类所有能力通过以下方法暴露方法说明indexCodebase(path, progressCallback?, forceReindex?)索引整个代码库forceReindextrue时先删集合重建reindexByChange(path, progressCallback?)仅对变更文件增量重索引semanticSearch(path, query, topK?, threshold?, filterExpr?)语义搜索默认topK5、threshold0.5hasIndex(path)判断代码库是否已索引clearIndex(path, progressCallback?)删除集合与快照文件清除索引updateIgnorePatterns(patterns)更新忽略模式addCustomIgnorePatterns(patterns)追加自定义忽略模式addCustomExtensions(extensions)追加自定义扩展名updateEmbedding(embedding)切换嵌入提供方updateVectorDatabase(vectorDB)切换向量数据库updateSplitter(splitter)切换分割器8.1 索引流程的工程化细节从 packages/core/src/context.ts 的processFileList实现可提取几个关键工程机制批量嵌入分块先进入缓冲区达到EMBEDDING_BATCH_SIZE默认 100可用环境变量调整后统一调用embedBatch批量向量化减少 API 往返分块上限保护单个代码库最多索引450000个分块达到上限会停止并返回状态limit_reached避免资源耗尽容错策略单个文件读取/解析失败仅跳过并告警但嵌入 API 失败如配额耗尽会抛出EmbeddingError中止整个索引流程防止快照已标记完成但 Milvus 中零向量的静默半索引状态validateEmbeddings还会校验返回向量数量与分块数一致、拒绝空向量协作式取消indexCodebase支持AbortSignal信号触发后在下个文件边界抛出IndexAbortError保证不会再写入任何数据供上层如clear_index实现可靠的取消语义分块 ID 稳定分块 ID 由relativePath:startLine:endLine:content的 SHA-256 前 16 位生成内容不变则 ID 不变为增量删除/更新提供了稳定锚点。8.2 搜索结果结构interface SemanticSearchResult { content: string; // 代码内容 relativePath: string; // 相对代码库根目录的文件路径 startLine: number; // 起始行号 endLine: number; // 结束行号 language: string; // 编程语言 score: number; // 相似度分数0-1 }返回结果会经过重叠去重同一文件内行区间重叠超过 50% 的重复结果只保留分数更高者避免同一段代码被重复分块同时命中时污染输出。九、实战示例换用 VoyageAI 与自定义过滤9.1 使用 VoyageAI 嵌入代码检索推荐import { Context, MilvusVectorDatabase, VoyageAIEmbedding } from zilliz/claude-context-core; const embedding new VoyageAIEmbedding({ apiKey: process.env.VOYAGEAI_API_KEY || your-voyageai-api-key, model: voyage-code-3 // 专为代码检索优化 }); const vectorDatabase new MilvusVectorDatabase({ address: process.env.MILVUS_ADDRESS || localhost:19530, token: process.env.MILVUS_TOKEN || }); const context new Context({ embedding, vectorDatabase });若想用同一个嵌入实例同时编码文档与查询VoyageAI 特有的inputType区分可调用setInputType(query)/setInputType(document)提升检索精度。9.2 自定义文件过滤const context new Context({ embedding, vectorDatabase, supportedExtensions: [.ts, .js, .py, .java], ignorePatterns: [ node_modules/**, dist/**, *.spec.ts, *.test.js ] });配合环境变量可实现免改代码的过滤CUSTOM_EXTENSIONS.vue,.svelte,.astro逗号分隔自动补点、CUSTOM_IGNORE_PATTERNStemp/**,*.backup,private/**。十、文件同步架构Merkle 树增量索引对大型代码库而言每次全量重索引成本极高。引擎内置的FileSynchronizer见 packages/core/src/sync/synchronizer.ts采用Merkle 树 SHA-256 文件哈希方案只处理真正变化的文件。10.1 工作原理五步走① 文件哈希代码库中每个文件按内容计算 SHA-256而非修改时间等元数据哈希与相对路径一一对应跨环境一致。② Merkle 树构建全部文件哈希组织成 Merkle DAG——根节点聚合所有文件哈希值root: 拼接哈希串每个文件作为根节点的子节点节点数据为path:hash。任意一个文件内容变化都会引起根节点哈希变化因此根哈希可作为整个代码库状态的指纹。③ 快照管理同步状态持久化到~/.context/merkle/目录每个代码库按绝对路径 MD5 生成唯一快照文件md5.json内含文件哈希数组与序列化的 Merkle 树数据。④ 变更检测快速检查对比当前 Merkle 根哈希与快照详细分析根哈希不一致时做逐文件哈希比对变更分类分为三类——Added新增、Modified内容变化、Removed已删除。⑤ 增量更新仅对变更文件执行删除旧分块、向量化并写入新分块的操作。删除时通过relativePath构造 Milvus 过滤表达式查出旧分块 ID 再批量deleteWindows 路径会转义反斜杠确保向量数据库与磁盘状态最终一致。10.2 与 Context 的联动reindexByChange是增量路径的入口先通过FileSynchronizer.checkForChanges()得到三类变更文件removed文件直接删除分块added与modified文件统一重新切分、向量化。无变更时直接返回{ added: 0, removed: 0, modified: 0 }零 API 消耗。clearIndex在删除集合的同时也会调用FileSynchronizer.deleteSnapshot清理快照避免索引已清但快照残留导致下次误判。10.3 设计要点忽略规则在哈希阶段之前生效shouldIgnore检查先于任何文件系统访问被忽略的目录连哈希都不会计算既省时又避免权限错误目录同样做忽略校验且仅对普通文件哈希符号链接等类型跳过快照加载失败如文件不存在时自动全量重建具备自愈能力。十一、性能与可靠性调优建议结合上文源码机制可归纳出以下实践要点批量大小EMBEDDING_BATCH_SIZE默认 100嵌入 API 支持更大批次时调高可减少网络往返、缩短索引时间但需留意单次请求的 token 预算引擎按 1 token ≈ 4 字符粗略估算增量优先日常迭代用reindexByChange仅重大结构调整如依赖大版本升级或首次接入时用indexCodebase(..., true)强制全量混合模式保留默认HYBRID_MODEtrue以获得关键词语义双通道召回对纯语义场景再关闭以节省稀疏索引开销忽略规则前置把大体积且无关的目录如vendor/**、third_party/**写进.gitignore或~/.context/.contextignore从源头减少待索引文件数集合命名多环境共用同一 Milvus 时善用CODE_CHUNKS_COLLECTION_NAME_OVERRIDE添加可读前缀但仍保持按代码库路径隔离。十二、生态与延伸核心引擎是整个 Claude Context 体系的地基上层构建了两大消费端packages/mcpMCP 服务器将本文的索引/搜索/同步能力封装成 Claude Code 可直接调用的工具环境变量全局配置见 docs/getting-started/environment-variables.mdpackages/vscode-extension基于该引擎的 VSCode 扩展在 IDE 内提供语义搜索面板。文档与示例入口快速上手总览README.md环境变量完整说明docs/getting-started/environment-variables.md文件包含规则docs/dive-deep/file-inclusion-rules.md索引流程时序docs/dive-deep/asynchronous-indexing-workflow.md常见问题docs/troubleshooting/faq.md基础用法示例examples/basic-usage综上zilliz/claude-context-core以抽象接口 默认优配的设计把代码切分、向量化、检索与增量同步四条链路收敛为一个Context对象。无论你是要在自有工具链中嵌入代码语义检索还是想深入理解 AST 分割与 Merkle 树同步的工程实现本文所涉源码路径context.ts、ast-splitter.ts、synchronizer.ts、types.ts都是最佳的继续阅读起点。【免费下载链接】claude-contextCode search MCP for Claude Code. Make entire codebase the context for any coding agent.项目地址: https://gitcode.com/GitHub_Trending/co/claude-context创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考