Python代码库分析RAG系统
该系统使用抽象语法树（AST）分析Python代码，将提取的信息（函数、类、调用、变量等）存储在Weaviate向量数据库中，并通过模型上下文协议（MCP）服务器提供查询和理解代码库的工具。它利用谷歌的Gemini模型生成嵌入和自然语言描述/答案。
特性
- 代码扫描： 解析Python文件以识别代码元素（函数、类、导入、调用、赋值）及其关系。提取物：
- 基本信息：名称、类型、文件路径、行号、代码段、文档字符串。 - 函数/方法详细信息：参数、返回类型、签名、装饰器。 - 作用域信息：父作用域（类/函数）UUID、可读ID（例如。， file:type:name:line)，基类名称。 - 用法信息：作用域内的属性访问、调用关系（部分跟踪）。
- 矢量存储： 使用Weaviate存储代码元素及其向量嵌入（启用LLM生成时）。
- LLM强化（可选和背景）： 使用Gemini为函数和类生成语义描述和嵌入。这现在作为扫描后触发的后台任务或手动运行。可以通过启用/禁用
.env文件。 - 自动细化（可选和背景）： 启用LLM生成后，作为后台处理的一部分，使用上下文（调用者、被调用者、兄弟姐妹、相关变量）自动细化新/更新函数的描述。
- 抹布问答： 使用检索增强生成回答有关代码库的自然语言问题（需要启用LLM功能并完成后台处理）。
- 用户说明： 允许用户向特定代码元素添加手动注释。
- 可视化： 基于存储的关系生成MermaidJS调用图。
- MCP服务器： 通过MCP工具公开分析和查询功能，管理代码库和活动代码库上下文。
- 文件监视器（集成）： 扫描代码库时自动启动(
scan_codebase)并在选择另一个代码库时停止(select_codebase)或者代码库被删除(delete_codebase).触发重新分析和数据库更新 *活跃的* 当文件发生变化时，代码库。也可以通过以下方式手动控制start_watcher和stop_watcher工具。 - 代码库依赖关系 ： 允许定义扫描代码库之间的依赖关系(
add_codebase_dependency,remove_codebase_dependency). - 跨代码库查询： 启用搜索(
find_element)并提出问题(ask_question)跨活动代码库及其声明的依赖关系。
设置
- 环境： 确保安装了Python 3.10+和Docker。
- 编织： 使用Docker Compose启动Weaviate实例：
docker-compose up -d- 依赖关系： 安装Python包：
pip install -r requirements.txt- API密钥和配置： 创建一个
.env文件在项目根目录中，并添加您的Gemini API密钥。您还可以配置其他设置：
# --- Required ---
GEMINI_API_KEY=YOUR_API_KEY_HERE
# --- Optional ---
# Set to true to enable background LLM description generation and refinement
GENERATE_LLM_DESCRIPTIONS=true
# Max concurrent background LLM tasks (embeddings/descriptions/refinements)
LLM_CONCURRENCY=5
# ANALYZE_ON_STARTUP is no longer used. Scanning is done via the scan_codebase tool.
# Specify Weaviate connection details if not using defaults
# WEAVIATE_HOST=localhost
# WEAVIATE_PORT=8080
# WEAVIATE_GRPC_PORT=50051
# Specify alternative Gemini models if desired
# GENERATION_MODEL_NAME="models/gemini-pro"
# EMBEDDING_MODEL_NAME="models/embedding-001"
# Adjust Weaviate batch size
# WEAVIATE_BATCH_SIZE=100
# SEMANTIC_SEARCH_LIMIT=5
# SEMANTIC_SEARCH_DISTANCE=0.7
# Watcher polling interval (seconds)
# WATCHER_POLLING_INTERVAL=5- 运行MCP服务器： 在单独的终端中启动服务器：
python src/code_analysis_mcp/mcp_server.py*（确保此终端保持运行，以便工具可用）*
架构概述
该系统分析Python代码，将提取的信息存储在Weaviate向量数据库中，并通过模型上下文协议（MCP）服务器提供查询和理解代码库的工具。它利用谷歌的Gemini模型生成嵌入和自然语言描述/答案。
主要模块包括：
code_scanner.py：查找Python文件，使用AST解析它们，提取结构元素（函数、类、导入、调用等），并为Weaviate准备数据。weaviate_client.py：管理与Weaviate的连接，定义数据模式(CodeFile,CodeElement,CodebaseRegistry)，并提供批量上传、查询、更新和删除数据的功能。rag.py：实现检索增强生成（RAG），用于回答有关代码库的问题。它使用语义搜索来查找相关的代码元素，并使用LLM来合成答案。mcp_server.py：设置FastMCP服务器，管理其中的代码库CodebaseRegistry集合，处理活动代码库上下文(ACTIVE_CODEBASE_NAME)，集成文件监视逻辑（包括自动启动/停止），管理代码库依赖关系，并将分析功能作为具有详细参数描述的MCP工具公开。visualization.py：基于存储的关系生成MermaidJS调用图。
该系统使用Weaviate的多租户功能 CodeFile 和 CodeElement 集合，其中租户ID是用户定义的 codebase_name.独立的、非多租户 CodebaseRegistry 集合跟踪代码库元数据（名称、目录、状态、摘要、观察者状态、依赖关系）。这 ACTIVE_CODEBASE_NAME 服务器中的全局变量决定了查询的主要代码库租户。查询工具(find_element, ask_question)可以选择在注册表中存储的活动代码库及其声明的依赖关系中进行搜索。这 list_codebases 该工具可用于查看所有代码库的状态和依赖关系。
后台LLM处理用于生成代码元素的语义描述和嵌入。这是一个可选功能，可以通过启用/禁用 .env 文件。
一旦服务器运行，可以使用标准的MCP自检方法直接从MCP服务器检索有关可用工具及其参数的详细信息。