在使用 Claude Code、Cursor 等 AI 编程助手时，我们经常会遇到一个核心问题：如何让 AI 准确理解我们的代码库？
传统的代码搜索工具主要依赖关键词匹配，难以理解代码的语义关系。而简单的向量检索虽然能捕捉语义，但在处理函数名、类名等精确术语时又显得力不从心。更重要的是，检索到的代码片段往往缺乏上下文，导致 AI 无法完整理解代码逻辑。
为了解决这些问题，我开发了 ContextWeaver —— 一个专为 AI 编程助手设计的语义代码检索引擎。
ContextWeaver 结合了三种检索策略：
这种混合策略既能捕捉语义相似性，又能保证技术术语的精确匹配，大幅提升检索准确率。
基于 Tree-sitter 的抽象语法树解析，ContextWeaver 能够：
MyClass > myMethod），增强召回能力检索到代码片段后，ContextWeaver 会自动进行智能扩展：
这种分阶段扩展策略确保 AI 获得足够的上下文，同时避免信息过载。
不是所有检索结果都值得返回。ContextWeaver 实现了智能截断机制：
v1.5.0+ 版本引入了性能优化特性：
contextweaver watch 监控文件变化，自动增量索引作为 Model Context Protocol 的原生实现，ContextWeaver 提供了 5 个精心设计的 MCP 工具：
| 工具 | 用途 | Embedding 成本 |
|---|---|---|
codebase-retrieval | 主力工具：混合语义 + 精确匹配检索 | 有 |
list-files | 列出索引文件结构 | 无 |
find-references | 查找符号引用 | 无 |
get-symbol-definition | 查找符号定义 | 无 |
stats | 索引/搜索/健康统计 | 无 |
这种分层设计遵循"语义检索优先，结构浏览其次"的原则，在保证检索质量的同时降低 API 成本。
ContextWeaver 采用了精心设计的存储架构：
~/.contextweaver/<projectId>/
├── index.db # SQLite
│ ├── files # 文件元数据 + 完整内容（唯一真实来源）
│ ├── files_fts # 外部内容表，倒排索引
│ ├── chunks_fts # 块级倒排索引
│ ├── metadata # schema_version / 迁移状态 / 锁
│ ├── stats # 累计索引/搜索计数器
│ └── pending_marks # Outbox：失败时重放
└── vectors.lance/ # LanceDB chunks 表（仅向量 + 定位元数据）关键设计决策：
files.content，LanceDB 仅存储向量和元数据，索引体积减少 30-50%pending/done/aborted 持久化，崩溃恢复时自动重建1. 查询解析 → 分离语义意图与技术术语
2. 缓存查找 → 命中直接返回（v1.5.0+）
3. 混合召回 → 双通道向量 + 词法召回
4. RRF 融合 → Reciprocal Rank Fusion
5. 重排序 → Cross-encoder 精排
6. 智能截断 → 动态分数截断
7. 图扩展 → 邻居/面包屑/导入扩展
8. 上下文打包 → 段落合并，token 预算控制
9. 缓存存储 → 写入缓存
10. 格式化输出 → 返回给 LLM# 全局安装
npm install -g @chiway/contextweaver
# 或使用 pnpm
pnpm add -g @chiway/contextweaver# 创建配置文件 ~/.contextweaver/.env
contextweaver init
# 或使用短命令
cw init编辑 ~/.contextweaver/.env，填入你的 API 密钥：
# Embedding API 配置（必填）
EMBEDDINGS_API_KEY=your-api-key-here
EMBEDDINGS_BASE_URL=https://api.siliconflow.cn/v1/embeddings
EMBEDDINGS_MODEL=BAAI/bge-m3
EMBEDDINGS_DIMENSIONS=1024
# Reranker 配置（必填）
RERANK_API_KEY=your-api-key-here
RERANK_BASE_URL=https://api.siliconflow.cn/v1/rerank
RERANK_MODEL=BAAI/bge-reranker-v2-m3# 在代码库根目录运行
contextweaver index
# 或指定路径
contextweaver index /path/to/your/project
# 强制完整重建
contextweaver index --force# 监控文件变化，自动增量索引
contextweaver watch
# 指定路径和防抖窗口
contextweaver watch /path/to/project --debounce 800# 语义搜索
cw search --information-request "用户认证流程是如何实现的？"
# 带精确术语
cw search --information-request "数据库连接逻辑" --technical-terms "DatabasePool,Connection"# 列出索引文件
contextweaver list-files --glob "src/**/*.ts" --language typescript
# 查找符号定义
contextweaver definition SearchService --hint-path src/search
# 查找符号引用
contextweaver references handleStats --exclude-definition在 Claude Desktop 配置文件中添加：
{
"mcpServers": {
"contextweaver": {
"command": "contextweaver",
"args": ["mcp"]
}
}
}重启 Claude Desktop 后，Claude 就能通过 MCP 工具访问你的代码库了。
list-files/find-references/get-symbol-definition 不调用 Embedding APIcontextweaver stats 输出三大指标组：
当检测到异常迁移状态、pending_marks 积压或缺失向量行时，报告会附加诊断警告和对应的修复命令。
查询：
cw search --information-request "How is JWT token validation implemented?" \
--technical-terms "JwtValidator,validateToken"ContextWeaver 会：
JwtValidator 和 validateToken当查询涉及到跨文件的依赖关系时，E3 导入解析会自动追踪：
cw search --information-request "Database migration system architecture"ContextWeaver 会：
# 快速找到 SearchService 的定义
cw definition SearchService
# 查找所有调用 handleStats 的地方
cw references handleStats --exclude-definition这些零成本工具让你能快速浏览代码结构，无需消耗 Embedding API 配额。
v1.4.0 引入了完整的事务补偿机制：
files.content 是唯一的内容来源，避免不一致处理多字节字符（如中文、emoji）时，传统的字节偏移会导致切片错误。ContextWeaver 通过 SourceAdapter.toCharOffset 在写入元数据前统一到 UTF-16 字符域，完美解决这个问题。
智能 TopK 不是简单的"取前 N 个"：
缓存键设计为 normalized_query + projectId + index_version + config_fingerprint，这意味着：
ContextWeaver 特别适合以下场景：
✅ 大型代码库探索：快速理解陌生代码库的架构和实现
✅ 重构和迁移：找到所有相关代码，避免遗漏
✅ 代码审查：让 AI 理解完整上下文，提供更准确的建议
✅ 文档生成：基于实际代码生成准确的技术文档
✅ Bug 定位：快速找到可能引入问题的相关代码
项目仍在积极开发中，计划中的特性包括：
ContextWeaver 不是简单的代码搜索工具，而是一个为 AI 编程助手精心设计的上下文编织引擎。通过混合检索、智能扩展和崩溃安全的数据架构，它能为 LLM 提供精准、完整、可靠的代码上下文。
如果你在使用 Claude Code、Cursor 等 AI 编程助手，或者正在开发自己的 AI 工具，ContextWeaver 值得一试。它已经通过 156 个测试用例的验证，并在实际项目中证明了其可靠性。
欢迎访问 GitHub 仓库 了解更多细节，或直接通过 npm 安装体验。期待你的反馈和贡献！