AI热点项目阅读1：claude-context

上课摸鱼的喵酱
73 阅读7分钟

前言

作为一个毕业两年的菜鸟FE、感觉再不学点什么就要被AI蒸馏了；所以开这个系列是为了每周阅读一个最近比较火的AI相关的项目，然后再给一到三个问题，方便去和AI提问。也是为了响应月哥的每周阅读源码计划；

分析项目和编写文章的过程中、使用了AI辅助阅读；

本周项目

github上11k+star的项目，claude-context：github.com/zilliztech/…

github上的项目介绍：

在日常使用 Cursor、Claude Code、Windsurf 等 AI 编程助手时，我们常常面临一个痛点：当项目代码量达到十万甚至百万级别时，直接将整个工程塞给大模型不仅容易触发“上下文超长”的报错，还会产生极其高昂的 Token API 费用。并且，过长的上下文也会导致大模型出现“幻觉”或“注意力丢失”。

问题

  1. 该项目使用了哪些 AI Agent 开发相关的技术与服务？
  2. 单纯的基于代码文本的 RAG 有什么缺点，该项目是如何避免该缺点的？
  3. 如何实现增量式索引？
  4. 该项目使用的 code search 技术与 codex/cursor/claude code 等有何不同？

代码结构

项目使用 Monorepo 架构，使用 pnpm 作为包管理工具。

分成了好几个部分：

claude-context/
├── packages/
│   ├── core/               # 核心引擎层：分块、向量化、增量同步、检索
│   ├── mcp/                # MCP 服务层：将核心引擎包装为大模型可调用的 Tools
│   ├── vscode-extension/   # VS Code 插件：提供 IDE 内的可视化语义搜索
│   └── chrome-extension/   # Chrome 插件：网页端代码语义检索（开发中）
├── evaluation/             # 评估脚本：用于验证检索质量与 Token 节省率
├── examples/               # 示例代码
└── docs/                   # 项目文档

用sonnet 4.6拆出来的具体文件结构

模块解析

1. packages/core：项目的主要内容

负责处理代码被检索前的所有繁重工作。入口是 src/context.ts，它作为总调度器协调下面四个子模块：

  • 代码切分 (src/splitter/)

    这一块是实现代码切分的功能，用于后续的存储/向量化；这也是面试中容易问到的，怎么对chunk进行切分，切多切少会怎么样代码；

    这个项目选择了 AST Splitter（基于抽象语法树的分割器）（ast-splitter.ts）。项目里面用这个分割器、解析代码的语法树后然后选择完整的函数、类定义作为独立的单元进行切割。这里只写了一些常用的语言，所以还保留了 langchain-splitter.ts 作为后备方案。

截屏2026-05-17 15.47.38.png

  • Merkle Tree 增量同步 (src/sync/)

    如果是每一次有文件变化，都粗暴地把所有文件都重新同步一遍，就会浪费资源；开发团队在面对增量文件的同步问题时引入了 Merkle DAG 来管理文件状态。

截屏2026-05-17 15.59.52.png 原理就是在本地 ~/.context/merkle 缓存一份按绝对路径 MD5 命名的哈希快照 JSON 文件。每次同步时，首先生成全目录的 SHA-256 文件哈希，然后与 Merkle Tree 根哈希做比对——相同则跳过，不同则逐对文件 Diff，按 Added/Modified/Removed 三类仅对变更文件重新向量化。

这里的增量同步只是文件级别的，如果一个文件只加了一行代码，那么还是会对整个文件进行重新向量化；这里其实是一个可以优化的地方；

  • 多模型向量化配置 (src/embedding/)

    这一个部分其实就是支持多种embedding模型；在 base-embedding.ts 里定义了统一的 Embedding 抽象接口，目前支持 OpenAI（openai-embedding.ts）、Gemini（gemini-embedding.ts）、VoyageAI（voyageai-embedding.ts），并且支持 Ollama（ollama-embedding.ts）允许接入本地模型；

  • 混合向量检索 (src/vectordb/)

    和市面上其他的节省token的工具库的区别在于（虽然好像有几个项目也有类似的设计）：能够使用混合检索，也就是除了Dense Vector（深度语义匹配） 外，还使用了Milvus SDK内置的 BM25（精准词频匹配）。

两个匹配分别得到一个分数、然后用RRF倒数排名融合两个策略的排名找到最相似的结果；

截屏2026-05-17 16.12.13.png

2. packages/mcp：MCP服务

这套 MCP Server 向外暴露了 4 个标准的 Tools：

  1. index_codebase：触发项目的索引构建动作，支持 force 强制重建、splitter 选择切分器、customExtensions / ignorePatterns 定制文件范围。
  2. search_code：核心工具。AI 接收到用户的自然语言指令后，调用此工具查询 Milvus 集合，直接获取最相关的代码路径、行号和片段（支持 limit 和 extensionFilter）。
  3. get_indexing_status：查询异步索引进度（阶段式百分比，非精确文件数）。
  4. clear_index：清理特定代码库的向量集合和快照数据。

此外，snapshot.ts 管理索引进度的本地持久化（~/.context/mcp-codebase-snapshot.json），sync.ts 负责后台定期自动同步的调度逻辑。大模型在遇到不熟悉的代码问题时，会自主调用 Tool 去"查阅资料"，再将查到的精准代码片段放入上下文回答用户。

3. packages/vscode-extension & chrome-extension：其他生态

  • VS Code 插件（src/extension.ts 作为入口）：直接内嵌在编辑器中。commands/ 目录注册了三个核心命令（Index、Search、Sync），webview/ 目录实现了语义搜索面板的 UI 和数据通信。插件不依赖大模型的对话窗口，开发者可以手动在侧边栏输入自然语言去全库搜代码。
  • Chrome 插件（开发中）：background.ts 运行 Service Worker，content.ts 注入页面。chromeMilvusAdapter.ts 在浏览器沙箱环境中适配 Milvus 链接，indexedRepoManager.ts 管理 IndexedDB 中的仓库索引映射表。预期让开发者在 Github / GitLab 网页上浏览大型开源项目时，也能享受到语义级搜索。

4. evaluation/：开发团队留下的一个测试入口

开发团队用 Python 编写了一套测试RAG质量的脚本：

  • generate_subset_json.py 从 SWE-bench_Verified 数据集筛选 30 个典型实例
  • run_evaluation.py 是实验主入口，分别以 grep-only 和 grep + Claude Context MCP（增强） 两种策略运行同一任务，各跑 3 次取均值
  • retrieval/custom.py 使用 LangGraph 的 ReAct Agent 框架，将 Claude Context MCP 注册为 Agent 可用 Tool
  • analyze_and_plot_mcp_efficiency.py 生成效率对比图表

提供的评测结果显示，在保证同样的检索质量（F1-Score 均为 0.40）下，Claude Context 能为开发者节省约 40% 的 Context Tokens（从 73,373 降至 44,449），Tool Call 次数也减少了 36%。

问题回答

  1. 该项目使用了哪些 AI Agent 开发相关的技术与服务？

    MCP、embedding、Milvus向量数据库、测评脚本和代码切分里的langchain、tree-sitter AST解析；

  2. 单纯的基于代码文本的 RAG 有什么缺点，该项目是如何避免该缺点的？

    如果只用稠密向量，搜 MerkleDAG 这个类名时，语义向量相似度搜索可能返回"哈希树相关逻辑"而非那个精确的类。体现在业务上就是名词A和名词B，只有在业务逻辑上的某一步有细微差别；但是纯语义向量对精确符号名匹配出来的结果就是会混在一起；

    Claude Context 的解法其实就是Embedding + milvus内置的BM25；

    milvus-vectordb.ts:476-591：建表时同时存 Dense 向量和 BM25 稀疏向量，查询时两路并发，用 RRF（k=100）融合排序：

  3. 如何实现增量式索引？

    sync/synchronizer.ts + sync/merkle.ts + context.ts:reindexByChange()，三步：

    1. 初始化：生成文件哈希快照 递归扫描目录，对每个文件算 SHA-256 内容哈希（不用时间戳，跨平台可靠），快照 JSON 存在 ~/.context/merkle/<md5(绝对路径)>.json。

    2. 变更检测：两层对比；先比较 Merkle 树根哈希（O(1)），相同则完全跳过。根哈希不同才做逐文件 Map 对比，分类为 added / modified / removed

    3. 差量更新：

for (const file of removed)  deleteFileChunks(collectionName, file)   // 删 Milvus 向量
for (const file of modified) deleteFileChunks(collectionName, file)   // 删旧向量
processFileList([...added, ...modified], ...)                         // 重新 Embed 写入

  1. 该项目使用的 code search 技术与 codex/cursor/claude code 等有何不同？

    Cursor / Claude Code 的原生方式： 大模型通过多轮 Tool Call（Read File、Grep、List Dir）主动"探索"代码库，本质是模型驱动的人工搜索过程，每一步都消耗 Token 和时间。

    Claude Context ： 预先把整个代码库向量化存入数据库，查询时直接返回 Top-K 结果，大模型跳过探索过程，直接取用。

    使用Claude Context是一个补充工具：Claude Context 作为 MCP 插件叠加在 Cursor/Claude Code 之上，给它们增加一个"预索引的代码库记忆"工具。

avatar
文章
阅读
粉丝