#问题：大型代码库 + Claude Code 的上下文困境
让 Claude Code 理解一个大型代码库，最直接的方式是把整个 /src 目录加入 context。这在小项目上可行，但在真实工程场景下面临两个问题：
- 成本 ：把几千个文件全塞进 context 窗口，每次请求消耗大量 token
- 质量 ：无关代码越多，Claude 越难专注在真正相关的部分，输出质量下降
claude-context 的方案是：先建索引，用时再搜索——只把语义相关的代码片段拉进 context。
#混合检索：BM25 + 向量双路并行
claude-context 使用混合检索策略，同时运行两条搜索路径：
- BM25（关键词精确匹配） ：适合已知函数名、变量名、API 名称的精确查找
- 稠密向量相似度（Dense Vector Search） ：适合语义相关代码的模糊查询，比如「找所有处理认证的地方」
两路结果通过 Reciprocal Rank Fusion（RRF）合并排序，返回综合相关性最高的代码片段。
#增量索引：Merkle Tree 加速重建
全量索引大型代码库一次不贵，贵在每次代码变更后的重建。claude-context 用 Merkle tree 做文件变更追踪：
- 每个文件计算内容 hash，形成树状校验结构
- 代码更新时只对内容变更的文件重新索引
- 其余文件跳过，显著缩短增量更新时间
对于活跃开发中的仓库，这让索引保持最新的成本降到可接受范围。
#AST 感知切块：不在函数中间截断
传统 RAG 切块通常按固定字符数截断，可能把一个函数从中间切开，导致每个 chunk 的语义不完整。claude-context 使用 AST（抽象语法树）感知切块：
- 解析代码结构，识别函数、类、模块边界
- 在语义边界处切块，不截断表达式或函数体
- 每个 chunk 包含完整的语义单元
这保证 Claude 拿到的每段代码都是能独立理解的逻辑单元，而不是碎片。
#Embedding 与后端配置
支持多种 embedding 方案，可按成本和精度选择：
| Embedding 方案 | 说明 |
|---|---|
| OpenAI | 精度高，有调用成本 |
| VoyageAI | 代码专用 embedding，适合技术代码库 |
| Ollama | 本地运行，零 API 成本 |
| Gemini | Google 生态集成 |
向量数据库后端支持两种部署方式：
- Zilliz Cloud ：托管服务，零运维
- 本地 Milvus ：自部署，数据不出本地
#MCP 接入与兼容性
claude-context 通过标准 MCP 协议暴露代码搜索能力，兼容：
- Claude Code
- Cursor
- Cline
- 其他支持 MCP 的 AI 编程工具
安装后，agent 可以通过 MCP 工具调用发起语义代码搜索，不需要修改 agent 逻辑本身。