# 全局安装
npm install -g @hsingjui/contextweaver

# 或使用 pnpm
pnpm add -g @hsingjui/contextweaver

# 交互式配置向导（创建 ~/.contextweaver/.env）
contextweaver init
# 或简写
cw init

# 非交互环境（管道 / CI）或直接写入默认模板
contextweaver init --defaults

# 默认：ContextWeaver 内置本地 Embedding
EMBEDDINGS_PROVIDER=local
EMBEDDINGS_MODEL=embeddinggemma-300m
EMBEDDINGS_MAX_CONCURRENCY=1

# 远程回退：改用 OpenAI 兼容 Embedding API 时替换上面的配置
# EMBEDDINGS_PROVIDER=remote
# EMBEDDINGS_API_KEY=your-api-key-here
# EMBEDDINGS_BASE_URL=https://api.siliconflow.cn/v1/embeddings
# EMBEDDINGS_MODEL=BAAI/bge-m3
# EMBEDDINGS_MAX_CONCURRENCY=10
# EMBEDDINGS_DIMENSIONS=1024

# 单文件大小上限（可选，单位字节，默认 100 KB）
# MAX_FILE_SIZE_BYTES=102400

# Reranker 配置（必需）
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

# 忽略模式（可选，逗号分隔，gitignore 语法，可用 ! 取反默认项）
# IGNORE_PATTERNS=.venv,node_modules

# 不带 action 时等同于 model list
contextweaver model
contextweaver model list

# 安装、切换和删除
contextweaver model install embeddinggemma-300m
contextweaver model install qwen3-embedding-0.6b
contextweaver model use qwen3-embedding-0.6b
contextweaver model remove jina-embeddings-v2-base-code
# 自动化环境可用 --yes 跳过删除确认
contextweaver model remove qwen3-embedding-0.6b --yes

# 无法直连 Hugging Face 时，可指定可信的兼容镜像
HF_ENDPOINT=https://your-hugging-face-mirror.example contextweaver model install embeddinggemma-300m

# 校验环境变量、目录权限、API 连通性与向量维度一致性
contextweaver doctor

# 跳过网络连通性测试
contextweaver doctor --offline

# 在代码库根目录执行
contextweaver index

# 指定路径
contextweaver index /path/to/your/project

# 强制重新索引
contextweaver index --force

# 语义搜索
cw search --information-request "用户认证流程是如何实现的？"

# 带精确术语
cw search --information-request "数据库连接逻辑" --technical-terms "DatabasePool,Connection"

# 启动 MCP 服务端（供 Claude 等 AI 助手使用）
contextweaver mcp

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

flowchart TB
    subgraph Interface["CLI / MCP Interface"]
        CLI[contextweaver CLI]
        MCP[MCP Server]
    end

    subgraph Search["SearchService"]
        VR[Vector Retrieval]
        LR[Lexical Retrieval]
        RRF[RRF Fusion + Rerank]
        VR --> RRF
        LR --> RRF
    end

    subgraph Expand["Context Expansion"]
        GE[GraphExpander]
        CP[ContextPacker]
        GE --> CP
    end

    subgraph Storage["Storage Layer"]
        VS[(VectorStore<br/>LanceDB)]
        DB[(SQLite<br/>FTS5)]
    end

    subgraph Index["Indexing Pipeline"]
        CR[Crawler<br/>fdir] --> SS[SemanticSplitter<br/>Tree-sitter] --> IX[Indexer<br/>Batch Embedding]
    end

    Interface --> Search
    RRF --> GE
    Search <--> Storage
    Expand <--> Storage
    Index --> Storage

contextweaver/
├── src/
│   ├── index.ts              # CLI 入口
│   ├── config.ts             # 配置管理（环境变量）
│   ├── cli/                  # CLI 体验层
│   │   ├── init.ts           # init 交互式配置向导
│   │   ├── doctor.ts         # 配置体检命令
│   │   ├── prompts.ts        # 交互提示原语（select/input/password/confirm）
│   │   ├── progress.ts       # 进度条与 Spinner
│   │   ├── probe.ts          # API 连通性探测
│   │   └── theme.ts          # 颜色 / 符号 / TTY 降级
│   ├── api/                  # 外部 API 封装
│   │   ├── embed.ts          # Embedding API
│   │   └── rerank.ts         # Reranker API
│   ├── chunking/             # 语义分片
│   │   ├── SemanticSplitter.ts   # AST 语义分片器
│   │   ├── SourceAdapter.ts      # 源码适配器
│   │   ├── LanguageSpec.ts       # 语言规范定义
│   │   └── ParserPool.ts         # Tree-sitter 解析器池
│   ├── scanner/              # 文件扫描
│   │   ├── crawler.ts        # 文件系统遍历
│   │   ├── processor.ts      # 文件处理
│   │   └── filter.ts         # 过滤规则
│   ├── indexer/              # 索引器
│   │   └── index.ts          # 批量索引逻辑
│   ├── vectorStore/          # 向量存储
│   │   └── index.ts          # LanceDB 适配层
│   ├── db/                   # 数据库
│   │   └── index.ts          # SQLite + FTS5
│   ├── search/               # 搜索服务
│   │   ├── SearchService.ts  # 核心搜索服务
│   │   ├── GraphExpander.ts  # 上下文扩展器
│   │   ├── ContextPacker.ts  # 上下文打包器
│   │   ├── fts.ts            # 全文搜索
│   │   ├── config.ts         # 搜索配置
│   │   ├── types.ts          # 类型定义
│   │   └── resolvers/        # 多语言 Import 解析器
│   │       ├── JsTsResolver.ts
│   │       ├── PythonResolver.ts
│   │       ├── GoResolver.ts
│   │       ├── JavaResolver.ts
│   │       └── RustResolver.ts
│   ├── mcp/                  # MCP 服务端
│   │   ├── server.ts         # MCP 服务器实现
│   │   ├── main.ts           # MCP 入口
│   │   └── tools/
│   │       └── codebaseRetrieval.ts  # 代码检索工具
│   └── utils/                # 工具函数
│       └── logger.ts         # 日志系统
├── package.json
└── tsconfig.json

interface SearchConfig {
  // === 召回阶段 ===
  vectorTopK: number;        // 向量召回数量（默认 30）
  vectorTopM: number;        // 送入融合的向量结果数（默认 30）
  ftsTopKFiles: number;      // FTS 召回文件数（默认 15）
  lexChunksPerFile: number;  // 每文件词法 chunks 数（默认 3）
  lexTotalChunks: number;    // 词法总 chunks 数（默认 30）

  // === 融合阶段 ===
  rrfK0: number;             // RRF 平滑常数（默认 60）
  wVec: number;              // 向量权重（默认 1.0）
  wLex: number;              // 词法权重（默认 0.5）
  fusedTopM: number;         // 融合后送 rerank 数量（默认 40）

  // === Rerank ===
  rerankTopN: number;        // Rerank 后保留数量（默认 10）
  maxRerankChars: number;    // Rerank 文本最大字符数（默认 1200）

  // === 扩展策略 ===
  neighborHops: number;      // E1 邻居跳数（默认 2）
  breadcrumbExpandLimit: number;  // E2 面包屑补全数（默认 3）
  importFilesPerSeed: number;     // E3 每 seed 导入文件数（默认 0）
  chunksPerImportFile: number;    // E3 每导入文件 chunks（默认 0）

  // === Smart TopK ===
  enableSmartTopK: boolean;  // 启用智能截断（默认 true）
  smartTopScoreRatio: number;     // 动态阈值比例（默认 0.5）
  smartMinScore: number;          // 绝对下限（默认 0.25）
  smartMinK: number;              // Safe Harbor 数量（默认 2）
  smartMaxK: number;              // 硬上限（默认 15）
}

1. Crawler     → 遍历文件系统，过滤忽略项
2. Processor   → 读取文件内容，计算 hash
3. Splitter    → AST 解析，语义分片
4. Indexer     → 批量 Embedding，写入向量库
5. FTS Index   → 更新全文搜索索引

1. Query Parse     → 解析查询，分离语义和术语
2. Hybrid Recall   → 向量 + 词法双路召回
3. RRF Fusion      → Reciprocal Rank Fusion 融合
4. Rerank          → 交叉编码器精排
5. Smart Cutoff    → 智能分数截断
6. Graph Expand    → 邻居/面包屑/导入扩展
7. Context Pack    → 段落合并，Token 预算
8. Format Output   → 格式化返回给 LLM

# 开启 debug 日志
LOG_LEVEL=debug contextweaver search --information-request "..."