Python 代码库分析 RAG 系统

该系统通过解析 Python 文件中的抽象语法树 (AST) 来分析代码，将提取的信息（函数、类、调用、变量等）存储到 Weaviate 向量数据库中，并提供工具以便通过 Model Context Protocol (MCP) 服务器查询和理解代码库。系统借助 Google 的 Gemini 模型生成嵌入式表示和自然语言描述/答案。

功能

• 代码扫描： 解析 Python 文件以识别代码元素（函数、类、导入、调用、赋值）及其关系。提取：

  • 基本信息：名称、类型、文件路径、行号、代码片段、文档字符串。
  • 函数/方法详细信息：参数、返回类型、签名、装饰器。
  • 作用域信息：父作用域（类/函数）UUID、可读 ID（例如 file:type,name）、位置信息（起始和结束行/列）。
  • 元数据：代码文件的哈希值用于版本控制，扫描时间戳记录分析时刻。

• 向量数据库集成： 使用 Weaviate 的多租户功能存储代码文件 (CodeFile) 和代码元素 (CodeElement)。每个代码库由用户定义的 codebase_name 作为租户 ID，并且有一个独立的非多租户集合 CodebaseRegistry 来记录代码库元数据。

• RAG 实现： 使用增强检索（Retrieval-Augmented Generation）回答关于代码库的问题。通过语义搜索找到相关代码元素，再利用大型语言模型 (LLM) 进行答案合成。

• MCP 服务器： 通过 FastMCP 框架设置服务器，管理代码库注册 (CodebaseRegistry)，维护活动代码库上下文 (ACTIVE_CODEBASE_NAME)，整合文件监控逻辑（包括自动启动/停止），管理代码库依赖关系，并公开分析功能作为 MCP 工具。

• 可视化支持： 通过 visualization.py 生成 MermaidJS 调用图，基于存储的关系数据进行代码结构的可视化表示。

环境设置

安装依赖

pip install weaviate-client python-multipart fastapi uvicorn

初始化配置

创建 .env 文件：

WEAVIATE_URL=http://localhost:5000
WEAVIATE_API_KEY=your_api_key
GENERATE_LLM_DESCRIPTIONS=true  # 可选，默认为 false

启动服务器

uvicorn mcp_server:app --reload

架构概述

系统主要模块包括：

• 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 记录代码库元数据（名称、目录、状态、摘要、监视器状态、依赖关系）。MCP 服务器中的全局变量 ACTIVE_CODEBASE_NAME 确定主要代码库租户用于查询。工具 (find_element, ask_question) 可选地在活动代码库及其声明的依赖项中进行搜索。

背景 LLM 处理用于生成代码元素的语义描述和嵌入，此功能通过 .env 文件可选启用/禁用。