Python 代码库分析 RAG 系统

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

功能

• 代码扫描： 解析 Python 文件以识别代码元素（函数、类、导入、调用、赋值）及其关系。提取：
  • 基本信息：名称、类型、文件路径、行号、代码片段、文档字符串。
  • 函数/方法详细信息：参数、返回类型、签名、装饰器。
  • 作用域信息：父作用域（类/函数）UUID、可读 ID（例如 file:type:name:line）、基类名称。
  • 使用信息：作用域内的属性访问、调用关系（部分跟踪）。
• 向量存储： 使用 Weaviate 存储代码元素及其向量嵌入（当启用 LLM 生成时）。
• LLM 丰富（可选且后台运行）： 使用 Gemini 为函数和类生成语义描述和嵌入。现在作为后台任务运行，在扫描后或手动触发。可以通过 .env 文件启用/禁用。
• 自动优化（可选且后台运行）： 当启用 LLM 生成时，自动根据上下文（调用者、被调用者、同级、相关变量）对新/更新的函数进行描述优化，作为后台处理的一部分。
• RAG Q&A： 使用检索增强生成 (Retrieval-Augmented Generation) 回答关于代码库的自然语言问题（需要启用 LLM 功能并完成后台处理）。
• 用户澄清： 允许用户为特定代码元素添加手动注释。
• 可视化： 根据存储的关系生成 MermaidJS 调用图。
• MCP 服务器： 通过 MCP 工具公开分析和查询功能，管理代码库和活动代码库上下文。
• 文件监视器（集成）： 在扫描代码库时自动启动 (scan_codebase)，并在选择另一个代码库 (select_codebase) 或删除代码库 (delete_codebase) 时停止。当活动代码库的文件发生变化时，触发重新分析和数据库更新。也可以通过 start_watcher 和 stop_watcher 工具手动控制。
• 代码库依赖关系： 允许定义扫描代码库之间的依赖关系 (add_codebase_dependency, remove_codebase_dependency)。
• 跨代码库查询： 允许在活动代码库及其声明的依赖项中搜索 (find_element) 和提问 (ask_question)。

设置

1. 环境： 确保已安装 Python 3.10+ 和 Docker。

2. Weaviate： 使用 Docker Compose 启动 Weaviate 实例：

   docker-compose up -d
   

3. 依赖项： 安装 Python 包：

   pip install -r requirements.txt
   

4. API 密钥和配置： 在项目根目录下创建一个 .env 文件，并添加你的 Gemini API 密钥。你也可以配置其他设置：

   # --- 必填 ---
   GEMINI_API_KEY=YOUR_API_KEY_HERE
   
   # --- 可选 ---
   # 设置为 true 以启用后台 LLM 描述生成和细化
   GENERATE_LLM_DESCRIPTIONS=true
   # 最大并发后台 LLM 任务数（嵌入/描述/细化）
   LLM_CONCURRENCY=5
   # ANALYZE_ON_STARTUP 不再使用。扫描通过 scan_codebase 工具完成。
   
   # 如果不使用默认值，请指定 Weaviate 连接详情
   # WEAVIATE_HOST=localhost
   # WEAVIATE_PORT=8080
   # WEAVIATE_GRPC_PORT=50051
   
   # 如有需要，指定替代的 Gemini 模型
   # GENERATION_MODEL_NAME="models/gemini-pro"
   # EMBEDDING_MODEL_NAME="models/embedding-001"
   
   # 调整 Weaviate 批处理大小
   # WEAVIATE_BATCH_SIZE=100
   
   # SEMANTIC_SEARCH_LIMIT=5
   # SEMANTIC_SEARCH_DISTANCE=0.7
   # 监视器轮询间隔（秒）
   # WATCHER_POLLING_INTERVAL=5
   

5. 运行 MCP 服务器： 在单独的终端中启动服务器：

   python src/code_analysis_mcp/mcp_server.py
   

   (确保此终端保持运行，以便工具可用)

架构概述

该系统分析 Python 代码，将提取的信息存储在 Weaviate 向量数据库中，并通过 Model Context Protocol (MCP) 服务器提供查询和理解代码库的工具。它利用 Google 的 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 服务器获取。

系统使用 Weaviate 的多租户特性来管理 `CodeFile` 和 `CodeElement` 集合，其中租户 ID 是用户定义的 `codebase_name`。一个单独的、非多租户的 `CodebaseRegistry` 集合用于跟踪代码库元数据（名称、目录、状态、摘要、观察者状态、依赖项）。服务器中的 `ACTIVE_CODEBASE_NAME` 全局变量决定了查询的主要代码库租户。查询工具（`find_element`、`ask_question`）可以选择性地在活动代码库及其在注册表中声明的依赖项之间进行搜索。可以使用 `list_codebases` 工具来查看所有代码库的状态和依赖项。

后台 LLM 处理用于生成代码元素的语义描述和嵌入。这是一个可选功能，可以通过 `.env` 文件启用或禁用。

有关可用工具及其参数的详细信息，可以在服务器运行后直接通过标准 MCP 自省方法从 MCP 服务器获取。