Skip to content
BranchesTags
 
 

Repository files navigation

ContextWeaver

🧵 为 AI Agent 精心编织的代码库上下文引擎

Hybrid Search • Graph Expansion • Token-Aware Packing • Prompt Context Preparation

English | 中文

ContextWeaver 是一个由 CLI + Skill + MCP 组成的代码库上下文引擎：CLI 提供稳定的本地索引、检索与证据准备命令，Skill 指导 agent 何时及如何消费证据，MCP 则通过 stdio 向兼容客户端暴露同一套检索能力。

Overview

核心特性

  • 混合检索引擎：向量召回 + 词法召回 + RRF 融合 + 精排
  • 三阶段上下文扩展：邻居扩展、Breadcrumb 补全、Import 追踪
  • 明确的索引范围：首次索引必须先预览范围并显式确认
  • Skill：内置可分发的 using-contextweaver 与 enhancing-prompts 技能资产
  • MCP stdio 适配器：向兼容客户端提供代码检索与 Prompt Context 工具，并在首次索引前通过 Elicitation 请求授权
  • Prompt Context 准备 (Prompt Enhancement)：把模糊请求转换为基于仓库事实的证据包，供 agent 自行增强任务说明

安装

npm install -g @monkeyray/contextweaver

Windows 安装通常会使用可用的预编译原生依赖；如需本地构建工具或无构建安装路径，见 Windows 安装说明。

初始化

contextweaver init

# Or `cw` for short
cw init

编辑 ~/.contextweaver/.env，填入 Embedding 与 Reranker 配置：

EMBEDDINGS_API_KEY=your-api-key-here
EMBEDDINGS_BASE_URL=https://api.siliconflow.cn/v1/embeddings
EMBEDDINGS_MODEL=BAAI/bge-m3
EMBEDDINGS_BATCH_SIZE=10
EMBEDDINGS_MAX_CONCURRENCY=10
EMBEDDINGS_NETWORK_RETRIES=5
EMBEDDINGS_RETRY_BASE_DELAY_MS=1000
EMBEDDINGS_RETRY_INTERVAL_INCREMENT_MS=1000
EMBEDDINGS_REQUEST_TIMEOUT_MS=60000
EMBEDDINGS_WINDOW_SIZE=50
EMBEDDINGS_DIMENSIONS=1024
EMBEDDINGS_MAX_INPUT_TOKENS=8192
CW_CHUNK_MAX_SIZE=1000
CW_CHUNK_MIN_SIZE=50
CW_CHUNK_OVERLAP=20

RERANK_API_KEY=your-api-key-here
RERANK_BASE_URL=https://api.siliconflow.cn/v1/rerank
RERANK_MODEL=BAAI/bge-reranker-v2-m3
RERANK_TOP_N=20
环境变量 默认值 说明
EMBEDDINGS_BATCH_SIZE 10 单次 Embedding API 请求的文本条数，非法值会回退到默认值
EMBEDDINGS_NETWORK_RETRIES 5 网络/超时类错误重试次数，0 表示不重试
EMBEDDINGS_RETRY_BASE_DELAY_MS 1000 重试基础等待时间（毫秒）
EMBEDDINGS_RETRY_INTERVAL_INCREMENT_MS 1000 每次重试额外增加的等待时间（毫秒），设为 0 可关闭递增等待
EMBEDDINGS_REQUEST_TIMEOUT_MS 60000 单次 Embedding 请求超时（毫秒），0 表示不启用显式超时
EMBEDDINGS_WINDOW_SIZE 50 索引时每个窗口最多处理的 Embedding item 数
CW_CHUNK_MAX_SIZE 1000 语义分片最大大小
CW_CHUNK_MIN_SIZE 50 语义分片最小大小
CW_CHUNK_OVERLAP 20 语义分片重叠大小

项目索引配置

仓库根目录通过 cwconfig.json 控制索引范围：

contextweaver init-project

示例：

{
  "indexing": {
    "includePatterns": ["src/**"],
    "ignorePatterns": ["**/generated/**", "**/__snapshots__/**"]
  }
}

索引器将先匹配includePatterns, 然后从匹配项中排除ignorePatterns. 索引范围决定了后续语义搜索的精度, 请为每个项目仔细配置索引范围.

常用命令

# 建立或更新索引
contextweaver index

# 语义检索（默认文本输出）
contextweaver search [--format json] --information-request "提示词增强相关逻辑是怎么实现的？"

# 为模糊请求准备 repo-aware 证据（默认文本输出）
contextweaver prompt-context [--format json] "把 prompt enhance 对齐到 Skills"

# 启动 stdio MCP 服务器
contextweaver mcp

# 安装内置 Skill 到指定目录（--dir 必填）
contextweaver install-skills --dir ./agent-skills

# 清理失效索引
contextweaver clean

CLI 默认输出优先给人看：search 与 prompt-context 默认都是 text；在 Skill 脚本中显式用 --format json. search 与 prompt-context 都要求当前仓库已经成功完成过一次索引 contextweaver index。

MCP 集成

MCP 是当前 retrieval 与 promptContext 应用层的 stdio 适配器，不维护另一套索引或搜索逻辑。可在支持 MCP 的客户端中注册：

{
  "mcpServers": {
    "contextweaver": {
      "command": "contextweaver",
      "args": ["mcp"]
    }
  }
}

也可以把 command 改为 cw。不同客户端的配置位置和首次启用授权方式不同，请遵循对应客户端文档。服务器当前只暴露两个工具：

工具 作用
codebase-retrieval 按自然语言问题和可选技术术语检索仓库代码上下文
prepare-prompt-context 为模糊请求准备证据包；仅在传入 repo_path 时检索仓库

两条工具的仓库型调用共享同一首次索引授权流程：

工具调用 → 校验仓库路径与 MCP Roots → 检查确认式索引
  ├─ 已确认：执行检索 / Prompt Context 准备
  └─ 未确认：先检查客户端 Elicitation 能力
       ├─ 支持 Form Elicitation：在本地生成并展示范围预览后请求授权
       │    ├─ accept 且 approve=true：索引完成后继续原工具调用
       │    └─ decline / cancel：不索引、不调用外部模型
       └─ 客户端不支持 Elicitation：返回 authorization_required
            并提供 cliExecutable + cliArgs；cliCommand 仅为 POSIX 展示命令

授权与运行边界：

  • 授权来自当前 MCP 会话中的 Elicitation 响应；cwconfig.json 只定义索引范围，不能替用户授权。该响应是对合规客户端行为的信任，不是“物理用户已点击”的密码学证明。
  • 首次授权成功后，confirmedAt 作为该仓库路径的持久授权跨 MCP 会话生效，后续调用不会逐次 Elicitation。它尚未绑定 cwconfig.json 内容或模型服务配置；后续范围或供应商变化不会自动再次触发授权，变更后应人工复核并重新索引。
  • 客户端声明 Roots 时，仓库必须位于可用的 file:// Root 内；Roots 查询失败、为空或没有可用文件 Root 时会闭锁拒绝。客户端未声明 Roots 时，只接受真实存在的绝对目录，并拒绝文件系统根目录和用户 HOME；这是兼容性降级，不等同于会话级文件系统沙箱，需要严格会话边界的客户端应声明 Roots。
  • 首次预览阶段不调用外部模型；用户授权并开始索引后，匹配的代码片段会发送到配置的 Embedding 服务。检索还会把查询及候选片段发送到配置的 Embedding/Reranker 服务。请在授权前核对 cwconfig.json、服务地址、数据策略与费用边界。
  • 如果调用携带 MCP progress token，长时间索引会发送尽力而为、严格递增的进度通知；通知失败不会中断索引。当前不提供 MCP Tasks，进度通知也不保证重置客户端或宿主的请求超时。
  • stdio MCP 由客户端作为子进程启动，可能避免每次通过 agent shell 执行命令时遇到的 bwrap 网络命名空间问题；但 MCP 协议不能保证客户端不会再次沙箱化服务器，也不能保证外部 API 网络可达。

如果客户端不支持 Elicitation，请在可信终端中检查 CLI 展示的预览并完成：

程序化回退应直接以 authorization.cliExecutable 和 authorization.cliArgs 启动进程；authorization.cliCommand 只是 POSIX shell 展示字符串。

cw index '/absolute/path/to/repository'

随后重试原 MCP 工具调用。不要让 agent 把 --yes 当作对未知索引范围或外部传输的隐式授权。

Skill 资产

仓库提供可分发的 Skill 目录：skills/

  • skills/using-contextweaver/
    • 面向语义检索与代码定位
    • 配套脚本 scripts/search-context.mjs
  • skills/enhancing-prompts/
    • 面向“模糊代码库请求 -> repo-aware 推荐任务解释 -> 必要时一次 Question -> 最终任务 prompt”
    • 配套脚本 scripts/prepare-enhancement-context.mjs
    • Prompt 模板位于 templates/

通过 npm 全局安装后，内置 Skill 会随包一起分发；contextweaver install-skills 必须显式传入 --dir 指定安装目录，不提供默认目标。若目标完整路径不存在，CLI 会先展示解析后的路径并询问是否创建，确认后才继续安装。

架构

     索引: Crawler → Processor → SemanticSplitter → Indexer → VectorStore / SQLite
     搜索: Query → Vector + FTS Recall → RRF Fusion → Rerank → GraphExpander → ContextPacker
适配边界: CLI / Skill / MCP → retrieval + promptContext → 共享搜索与索引基础设施

关键模块：

模块 位置 作用
SearchService src/search/SearchService.ts 混合搜索核心
GraphExpander src/search/GraphExpander.ts 三阶段上下文扩展
ContextPacker src/search/ContextPacker.ts 段落合并与预算控制
retrieval src/retrieval/index.ts 结构化检索输出与 CLI 渲染
promptContext src/promptContext/index.ts Prompt 证据准备与技术词提取
mcp src/mcp/ stdio 协议、Roots 校验与首次索引授权

超长 Chunk 自动拆分

Embedding 模型对单次输入有 token 上限（由 EMBEDDINGS_MAX_INPUT_TOKENS 控制，默认 8192）。当某个 chunk 超过上限时，ContextWeaver 会按行将其拆分为多个符合限制的子片段，分别请求 Embedding，再将所得向量逐维平均聚合为单个最终向量。整个过程无需人工干预，超限时会输出 warn 日志供排查。

多语言支持

ContextWeaver 通过 Tree-sitter 原生支持以下编程语言的 AST 解析；当部分原生语法包在当前 Node/平台不可加载时，会对已列出的兜底语言使用行分片保证可检索。

语言 AST 解析 Import 解析 文件扩展名
TypeScript ✅ ✅ .ts, .tsx
JavaScript ✅ ✅ .js, .jsx, .mjs
Python ✅ ✅ .py
Go ✅ ✅ .go
Java ✅ ✅ .java
Rust ✅ ✅ .rs
Kotlin 条件支持* ✅ .kt, .kts
PHP ✅ ✅ .php
Ruby ✅ ✅ .rb
Swift 条件支持* ✅ .swift
Dart 条件支持* ✅ .dart
C ✅ ✅ .c, .h
C++ ✅ ✅ .cpp, .hpp, .cc, .cxx
C# ✅ ✅ .cs, .csx
Shell 行分片 — .sh, .bash, .zsh
YAML/Ansible 行分片 — .yaml, .yml
  • Kotlin/Swift/Dart 的 AST 解析取决于 tree-sitter-kotlin / tree-sitter-swift / tree-sitter-dart 原生绑定是否存在且能在当前 Node ABI 与安装环境中加载；这些条件语法包不进入默认安装图，缺失或加载失败时扫描器会自动退回到行分片，Import 解析仍可用。

致谢

License

MIT

About

ContextWeaver 是一个利用 Tree-sitter 和向量搜索为大语言模型提供本地代码库智能上下文编织与检索的工具

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages