## 📖 简介 **DevMind** 是一款旗舰级的基于上下文的 AI 代码智能引擎，旨在自动化仓库扫描、结构分析和交互式代码探索。通过提取结构化语法元数据并将整个代码库编译到语义向量存储中，DevMind 消除了代码解释引擎中常见的“上下文漂移”和“幻觉”问题。 开发者可以上传仓库 ZIP 压缩包或粘贴公共 GitHub 仓库链接。DevMind 会立即索引工作区，创建优化的向量 embedding 块，通过弹性模型故障转移 pipeline 运行专用智能体（Planner、Reviewer、Security、Critic），并提供实时的 Grounded Chat 工作区。 ### 解决的问题 传统 LLM 在处理代码库时会失败，原因如下： 1. **上下文限制：** 将整个代码库插入单个上下文窗口成本高昂，并会导致推理质量下降（中间内容丢失）。 2. **上下文漂移：** 标准检索系统返回过多噪音，检索到的是文件 lockfile、软件包列表或测试固定装置，而不是核心业务逻辑。 3. **截断的 JSON 响应：** LLM API 经常流式传输不完整或格式错误的 JSON payload，破坏前端解析器并导致聊天会话崩溃。 ### 对开发者的价值 DevMind 通过构建高度本地化的 **Retrieval-Augmented Generation (RAG)** pipeline 解决了这些问题。它会从向量 pipeline 中过滤掉 lockfile，使用基于路径的重排对搜索查询进行评分，通过回溯字符串匹配修复截断的 JSON payload，并提取与仓库中特定行直接链接的代码引用。它充当了一个*真正*了解你代码库的自主代码审计员和对话伙伴。 ## 🚀 功能 * 📁 **智能仓库摄取：** 直接支持远程 Git 仓库克隆（深度 1）和本地 ZIP 上传处理。 * 🔍 **静态结构分析器：** 自动识别语言、框架、包结构、依赖列表和文件统计信息。 * 🤖 **多提供商故障转移链：** 弹性的 AI 推理查询多个云提供商，如果 LLM 离线，可优雅地回退到本地启发式模型。 * 🧠 **语义搜索与 RAG：** 通过 Google AI / HuggingFace 模型生成向量 embedding，将其索引到本地 FAISS 向量存储中，并带有代码路径分数加权。 * 💬 **流式 Grounded Chat：** 多轮对话界面，显示实时的 Markdown 回答、交互式代码预览、行引用和可点击的后续建议。 * 📤 **多格式导出：** 即时将聊天记录导出为 Markdown (.md) 文档，或直接从 UI 渲染适合打印的 PDF 手册。 * 🛡️ **嘈杂依赖过滤：** 在分块过程中自动绕过 `package-lock.json`、`yarn.lock`、`node_modules` 和压缩资产，严格专注于业务逻辑。 ## 🏛️ 架构概述 该系统由微服务风格的 FastAPI 后端组成，用于协调仓库下载和向量存储，并配有一个响应式的、暗色主题的 React SPA 前端。 ``` graph TD %% Client & Routing User([Developer / Recruiter]) -->|Upload ZIP / GitHub URL| ReactApp[React + TS SPA] ReactApp -->|HTTP requests / SSE Stream| FastAPI[FastAPI Backend Router] %% Ingestion & Scanner FastAPI -->|Job Dispatch| PipelineService[Pipeline Service] PipelineService -->|Clone/Extract| RepoService[Repository Service] RepoService -->|Local Workspace Files| ScannerService[Static Scanner Service] ScannerService -->|Framework/Language Metadata| DB[(PostgreSQL Database)] %% Chunking & Vector DB PipelineService -->|Raw Code files| ChunkService[Chunk Service] ChunkService -->|Code Chunks| RAGService[RAG Service] RAGService -->|Generate Embeddings| EmbeddingService[Embedding Service] EmbeddingService -->|FAISS vectors| VectorStore[FAISS Vector Store Disk] %% Chat & LLM Grounding ReactApp -->|Grounded Questions| ChatRouter[Chat API Router] ChatRouter -->|Retrieval Query| RetrievalService[Retrieval Service] RetrievalService -->|FAISS Search + Path Boost Rerank| VectorStore RetrievalService -->|High-quality Source Chunks| PromptBuilder[Chat Prompt Builder] PromptBuilder -->|Context-grounded Messages| AIOrchestrator[Conversation Service] AIOrchestrator -->|Model Failover Pipeline| LLMChain{Cloud Providers / Ollama} LLMChain -->|JSON Response| ResponseParser[Response Parser + JSON Repair] ResponseParser -->|Clean Markdown Answer + Citations| ReactApp ``` ## 📊 DevMind 的工作原理 以下流程图展示了 DevMind 如何处理代码库、对其进行语义索引，并通过健壮的 JSON 修复返回基于上下文的聊天响应。 ``` sequenceDiagram autonumber actor User as Developer participant UI as React UI Workspace participant API as FastAPI Router participant RAG as Retrieval & Chunking participant DB as Postgres & FAISS participant LLM as LLM Cloud Providers User->>UI: Submit Git URL / ZIP Archive UI->>API: POST /api/analyze/git API->>RAG: Clone & static scan workspace RAG->>RAG: Filter lockfiles (package-lock.json, etc.) RAG->>DB: Save repository metadata RAG->>DB: Generate embeddings & build FAISS Vector Store API->>UI: Return analysis completed (Auto-bind) User->>UI: Ask grounded question UI->>API: GET /chat/stream?message=... API->>DB: Query FAISS store for query similarity DB->>API: Return top vector chunks API->>API: Apply path-based reranking (READMEs, app/*) API->>LLM: Send prompt containing query + context chunks LLM-->>API: Stream JSON chunks (answer + citations) API->>API: Parse tokens via StreamingAnswerExtractor API-->>UI: Stream clean Markdown tokens (Server-Sent Events) Note over API,LLM: In case LLM returns truncated or broken JSON API->>API: Apply parenthesis closure & backtracking repair API-->>UI: Yield repaired markdown answer stream ``` ## ⚙️ 技术栈 | 层级 | 组件 | 技术 | 用途 | | :--- | :--- | :--- | :--- | | **Backend** | 核心框架 | `Python 3.10`, `FastAPI` | 高性能异步 API 路由 | | **Backend** | 数据库与 ORM | `PostgreSQL`, `SQLAlchemy`, `Alembic` | 用于仓库、任务和聊天记录的关系存储 | | **Backend** | 向量索引 | `FAISS` (Facebook AI Similarity Search) | 用于代码块向量的本地相似性搜索 | | **Backend** | 模型与解析器 | `Pydantic v2`, `HuggingFace`, `Google Gemini` | schema 校验、语义 embedding 和 LLM 文本生成 | | **Frontend** | 构建系统 | `Node.js`, `Vite`, `TypeScript` | 现代化生产环境资产打包 | | **Frontend** | 库核心 | `React 18`, `React Router v6`, `React Context` | 组件逻辑和全局应用状态 | | **Frontend** | 样式与主题 | `Vanilla CSS`, `TailwindCSS` | 毛玻璃暗色风格和布局响应式 | | **Frontend** | 图标与高亮 | `Lucide React`, `highlight.js` | 交互式 UI 元素和代码格式化 | ## 📂 项目结构

📂 点击查看目录树

### Backend 工作区结构 ``` backend/ ├── alembic/ # Database migration version files ├── app/ │ ├── ai/ # AI Provider clients and prompt registry │ ├── api/ # API routers, endpoint schemas, dependencies │ ├── chat/ # Grounded chat service, schemas, prompts, parser │ ├── core/ # Configs, logger, security handlers │ ├── db/ # DB engine, session builder, registry base │ ├── models/ # SQLAlchemy ORM models (Repository, Chat, Embeddings) │ ├── services/ # Pipeline, scanning, chunking, RAG services │ ├── utils/ # JSON repair helpers, git helpers, file utilities │ └── main.py # Main ASGI Application entry point ├── tests/ # 38 pytest unit & integration test suites ├── alembic.ini # Alembic configuration └── poetry.lock / pyproject # Python package dependencies ``` ### Frontend 工作区结构 ``` src/ ├── assets/ # Static global styling and SVG banners ├── chat/ │ ├── components/ # ChatWindow, ChatSidebar, ChatMessage, CitationCard, ExportMenu │ ├── ChatContext.tsx # State management for grounded chat │ ├── api.ts # SSE Fetch API and conversation services │ ├── chat.css # Custom layout CSS with print queries │ └── types.ts # TypeScript interfaces ├── components/ # Dashboard cards, output panel, intelligence components ├── context/ # AnalysisContext state ├── hooks/ # useAnalysis hook ├── layouts/ # Layout shell (Navbar, MainLayout, Footer) ├── pages/ # Dashboard and ChatPage ├── types/ # Report, Agent, Toast types ├── App.tsx # Main Routing core └── main.tsx # Vite render mount ```

## ⚙️ 安装说明 ### 环境变量 在 `backend/` 目录下创建一个 `.env` 文件： ``` # Core Server 配置 DATABASE_URL=postgresql://postgres:postgres@localhost:5432/devmind WORKSPACE_ROOT=./temp_workspace SECRET_KEY=devmind_secure_key_here # Cloud LLM Provider 凭证 GOOGLE_API_KEY=AIzaSy... GOOGLE_MODEL_NAME=gemini-2.5-flash GROQ_API_KEY=gsk_... GROQ_MODEL_NAME=llama3-70b-8192 ``` ### Backend 设置 确保你已安装 Python 3.10 和 PostgreSQL。 ``` # 导航到 backend 目录 cd backend # 创建虚拟环境并安装依赖项 python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -r requirements.txt # 运行 migrations 以更新数据库表 alembic upgrade head # 启动 FastAPI 开发服务器 uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload ``` ### Frontend 设置 确保你已安装 Node.js (v18+)。 ``` # 安装包依赖项 npm install # 启动 Vite 本地开发服务器 npm run dev # 编译 production bundle npm run build ``` ## 🔌 API 概览 | 方法 | Endpoint | 描述 | Payload / Query | | :--- | :--- | :--- | :--- | | **POST** | `/api/analyze/upload` | 上传 ZIP 仓库并排队分析 | Multipart form file, `task_type` | | **POST** | `/api/analyze/git` | 克隆 Git URL 并排队分析 | JSON: `{repo_url, task_type}` | | **GET** | `/api/analyze/status/{job_id}` | 轮询分析任务的状态 | path parameter | | **GET** | `/repositories` | 列出唯一的已索引仓库 | Query params: none | | **POST** | `/chat/conversations` | 开启新的聊天会话 | JSON: `{repository_id, title}` | | **GET** | `/chat/conversations` | 列出仓库的对话 | Query: `repository_id`, `search` | | **DELETE** | `/chat/conversations/{id}` | 删除一个对话会话 | path parameter | | **GET** | `/chat/conversations/{id}/messages` | 会话的分页消息 | Query: `limit`, `offset` | | **GET** | `/chat/stream` | 多轮 Grounded Chat SSE 流 | Query: `conversation_id`, `message` | ## 📸 截图与预览 ### Grounded Chat 预览 多轮聊天工作区提供移动端侧边栏切换、可展开的源代码引用详情和快速建议。 ``` +-----------------------------------------------------------------------------------+ | [Sessions Sidebar] | Grounded: owner/repo / General Grounded Chat | | +-------------------------+ +---------------------------------------------------+ | | | (+) NEW CHAT | | User: How do the models work in this codebase? | | | | ----------------------- | | | | | | General Grounded Chat | | DevMind AI: django models are in `models.py`. | | | | Auth Logic Check | | They extend `models.Model` to create tables. | | | | | | | | | | ----------------------- | | [+] Sources Cited: | | | | [Export Chat (MD/PDF)] | | - models.py (L10-L20) [Copy Code] | | | +-------------------------+ +---------------------------------------------------+ | | | | [ Ask a question... ] [ Send ] | +-----------------------------------------------------------------------------------+ ``` ### AI 报告预览 基于多智能体执行构建的全面代码库结构诊断、文件层级和结构报告。 ``` +-----------------------------------------------------------------------------------+ | | | 01. Target Repository 02. Agent Pipeline Status | | +---------------------------------------+ +--------------------------------+ | | | GitHub URL: [ github.com/owner/repo ] | | STAGE: Reviewer stage | | | +---------------------------------------+ | PROGRESS: [=======> ] 60% | | | +--------------------------------+ | | | | 03. Repository Intelligence 04. Analysis Report Output | | +---------------------------------------+ +--------------------------------+ | | | Language: Python | Files: 231 | | # Code Review & Architecture | | | | Framework: Django | Dirs: 34 | | - Models are clean... | | | +---------------------------------------+ +--------------------------------+ | +-----------------------------------------------------------------------------------+ ``` ### 仓库智能预览 动态工作区映射，指示语言组成、依赖项、测试存在情况和框架信息。 ``` +-----------------------------------------------------------------------------------+ | Active Repo: devmind-engine/core | Language: TS (64%), Python (30%), Shell (6%) | | ------------------------------------------------------------------------------- | | [ Frameworks ] FastAPI, Vite React | [ Tests ] pytest (Py), jest (JS) | | [ Package Mgr ] poetry, npm | [ Readme ] README.md present (MIT) | | [ Largest Fs ] app/main.py (14KB), src/chat/ChatContext.tsx (11KB) | +-----------------------------------------------------------------------------------+ ``` ## 📤 导出功能 * **Markdown 导出：** 将整个消息历史记录转换为可读的 Markdown 文件，包含引用块、语法高亮、代码段和引用，通过浏览器直接下载。 * **打印为 PDF 手册：** 在 [chat.css](file:///c:/Users/aishw/Desktop/Projects/DevMind/src/chat/chat.css) 中使用定制的 `@media print` CSS 覆盖，以剥离侧边栏模板、输入框、导航块和边距。渲染出精美的打印文档，招聘人员可以直接阅读。 ## ⚡ 性能亮点 1. **DB 连接释放：** 在调用下游 LLM 流式传输 endpoint 之前，数据库会话句柄会立即提交并关闭。这确保了 PostgreSQL 连接池在长时间的流式操作中永远不会被锁定或耗尽。 2. **快速重排切片：** Embedding 数据库查询经过优化，可获取更广泛的候选列表 (`k=20`)，使用 O(N) regex 过滤器在内存中对路径进行重新排序，并将结果截断为标准大小。这实现了亚毫秒级的检索周期。 3. **排除嘈杂资产：** 在典型的 Node/Python 工作区中，跳过 lockfile 可将向量数据库大小减少 **超过 70%**，从而最小化 FAISS 搜索空间并显著缩短查询响应时间。 ## 🛡️ 安全特性 1. **本地工作区擦除：** 克隆的仓库和上传的文件在被分析和索引后，一旦数据库加载和向量存储完成，就会立即从磁盘清除。 2. **安全的密钥隔离：** API key 绝不会持久化存储在数据库中；它们严格从操作系统环境变量中读取。 3. **Regex PII 清理：** 日志会自动净化敏感字符串，如仓库认证 token。 ## 💡 为什么选择 DevMind DevMind 专为希望安全高效地与代码进行对话的团队而构建，无需依赖会无限期索引你文件的第三方云包装器。凭借自定义的 JSON 恢复、本地 FAISS 结构以及对故障转移模型（包括本地 Ollama）的支持，它在仓库探索中提供了无与伦比的弹性、隐私和速度。 ## 🔮 未来愿景 * **本地 RAG Airgap：** 支持完全气隙部署，在消费级硬件上运行本地 sentence-transformers embedding 和本地 Ollama 模型。 * **智能体协作工作区：** 支持并发的多智能体执行，其中 Planner、Critic、Security 和 Architect 智能体在输出报告前对代码库设计进行辩论。 * **GitHub Actions 集成：** 自动化 PR 审查机器人，在合并前对 commit diff 触发语义 RAG 检查。 ## 🗺️ 项目开发路线图 ### 开发状态 | 状态 | 阶段 | 描述 | 关键交付物 | | :---: | :--- | :--- | :--- | | **✅** | **阶段 1** | 项目基础 | Cloner, FastAPI API, React Frontend, PostgreSQL | | **✅** | **阶段 2** | 仓库智能 | 静态扫描器、框架/语言统计、本地缓存 | | **✅** | **阶段 3** | AI 分析引擎 | Prompt 系统、故障转移链、解析器重试机制 | | **✅** | **阶段 4** | 代码智能仪表板 | 动态 UI 时间线、缓存指标、Markdown 与 PDF 导出 | | **✅** | **阶段 5** | Grounded AI Chat | FAISS 向量索引、RAG、引用、流式过滤器 | | **✅** | **阶段 6** | 多智能体智能 | Planner、Reviewer、Security 智能体并行执行 | | **✅** | **阶段 7** | GitHub 开发者工作流 | Pull request 审查自动化、内联 diff 审查评论 | | **🔄** | **阶段 8** | 文档智能 | UML 生成、依赖图、自动 README 生成器 | | **🔄** | **阶段 9** | 安全与 DevOps 审计 | 漏洞分析、Dockerfile 审查、CI/CD 审计日志 | | **🔄** | **阶段 10**| 协作平台 | 多用户工作区、身份验证、组织指标 | | **🔄** | **阶段 11**| IDE 集成 | VS Code 扩展、JetBrains 插件、终端 CLI | | **🔄** | **阶段 12**| 企业平台 | MCP 集成、本地 LLM Ollama 配置 | ## 📄 许可证 本项目基于 **DEVMIND COMMUNITY LICENSE v1.0** 授权 — 详情请参阅 [LICENCE](https://github.com/pushkarsingh26/DevMind/blob/main/LICENSE) 文件。 ## 💖 鸣谢 * **FastAPI** 提供的 ASGI 路由功能。 * **FAISS** 提供的快速相似性索引。 * **Google DeepMind** 开创性的 Gemini 模型功能。 * **Pushkar Chhokar** 架构和指导了第 5 阶段的 DevMind 引擎。

标签：AI代码审计, SOC Prime, 代码智能, 大语言模型(LLM), 开发工具, 检索增强生成(RAG), 测试用例, 语义搜索, 逆向工具