内容
# ⚡ 代码库分析器
一款智能、由AI驱动的代码库分析引擎，基于**检索增强生成（RAG）**技术。它通过**混合搜索**、**语言感知AST分块**、**精确行级引用**和**MCP（模型上下文协议）**工具，对代码仓库进行精确分析，实现与IDE和AI代理的无缝集成。
---
## ✨ 功能特点
- **🔍 混合检索管道（密集 + 稀疏）**：结合**FAISS**密集向量搜索与**BM25**稀疏关键词检索，通过**互惠排名融合（RRF）**，在精确代码标识符上实现高精度。
- **🌳 语言感知AST分块**：使用`langchain-text-splitters`沿语法边界（函数、方法、类）分割代码，而不是任意的机械行切割。
- **📌 精确行级源引用**：直接链接和行范围（`path/file.py:L10-L45`），实现完全可追溯性和幻觉预防。
- **⚡ 持久索引和分块缓存**：将生成的FAISS索引和元数据（`chunks.jsonl`）缓存到磁盘，实现后续查询的即时加载。
- **🔌 模型上下文协议（MCP）工具**：为代码仓库摄入、语义搜索和上下文检索提供模块化工具，供外部AI客户端（Claude Desktop、Cursor、VS Code）使用。
- **🎨 现代Web UI和CLI**：暗黑模式Web界面，动态Markdown渲染，搭配快速、生产就绪的CLI。
---
## 🛠️ 架构概览
```text
[Git仓库URL / 目录]
│
▼
[AST / 语言分割器] ──► 保留语法代码结构
│
├──► [FAISS索引]（密集语义向量） ──┐
│ ├──► [RRF融合] ──► [LLM上下文和引用]
└──► [BM25索引]（精确标识符令牌） ──┘
```
---
## 📋 需求
- Python 3.11+
- `git`
---
## 🚀 快速启动和安装
### 1. 克隆和设置环境
```bash
python -m venv .venv
# 在Windows PowerShell上：
.venv\Scripts\Activate.ps1
# 在Linux/macOS上：
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. 配置Gemini API密钥
从[Google AI Studio](https://aistudio.google.com/apikey)获取API密钥。
**Windows PowerShell**
```powershell
$env:AICA_LLM_PROVIDER="gemini"
$env:AICA_GEMINI_API_KEY="您的Gemini API密钥"
$env:AICA_GEMINI_MODEL="gemini-2.5-pro"
```
**Linux/macOS**
```bash
export AICA_LLM_PROVIDER="gemini"
export AICA_GEMINI_API_KEY="您的Gemini API密钥"
export AICA_GEMINI_MODEL="gemini-2.5-pro"
```
### 推荐模型
| 模型 | 推荐使用场景 |
|--------|----------------------|
| `gemini-2.5-pro` | 适用于复杂代码和架构问题的最佳推理 |
| `gemini-2.0-flash-lite` | 超快速且高效，适用于快速问答 |
| `gemini-1.5-flash` | 稳定的备用选项 |
---
## 🖥️ Web UI和CLI使用
### Web UI（推荐）
启动FastAPI应用程序：
```bash
python -m aica.web_app
# 或使用PowerShell脚本
.\run_web.ps1
```
打开 **http://127.0.0.1:8080** 查看仪表盘，配置模型参数，摄入代码仓库，并查询实时Markdown渲染的引用。
### CLI使用
#### 摄入代码仓库
```bash
python -m aica ingest https://github.com/pallets/flask
```
创建：
- `data/repos/<repo_hash>/` – 克隆的代码仓库文件
- `data/index/<repo_hash>/` – FAISS索引和分块元数据
#### 提问
```bash
python -m aica ask https://github.com/pallets/flask "请求上下文在哪里创建？" --top-k 4 --show-citations
```
---
## 🔌 MCP服务器（适用于外部AI代理和IDE）
在本地运行MCP服务器：
```bash
python -m aica.mcp_server
```
### 暴露的工具
- `ingest_repo_tool(repo_url)`
- `search_code(repo_url, query, top_k)`
- `ask_repo(repo_url, question, top_k)`
### 与Claude Desktop / Cursor集成
将服务器添加到您的`claude_desktop_config.json`：
```json
{
"mcpServers": {
"codebase-analyser": {
"command": "python",
"args": ["-m", "aica.mcp_server"],
"env": {
"PYTHONPATH": "."
}
}
}
}
```
---
## 📄 许可证
在MIT许可证下分发。
