informatique-cdc/retro-doc

Automated retro-documentation for existing codebases

## 关于 Retro-Doc 分析现有代码库以自动生成文档和结构洞察。上传源代码的 zip 压缩包，Retro-Doc 会提取抽象语法树 (AST)、控制流图 (CFG) 和数据流图 (DFG)，然后通过交互式 UI、基于 RAG 的聊天机器人和自主深度分析 agent 让结果变得可探索。 由 [Caisse des Dépôts Informatique (ICDC)](https://www.icdc.caissedesdepots.fr/) 构建。 ## 目录 - [功能](#features) - [架构](#architecture) - [技术栈](#tech-stack) - [仓库结构](#repository-structure) - [快速开始](#getting-started) - [贡献](#contributing) - [维护者与贡献者](#maintainers--contributors) - [许可证](#license) ## 功能 - **代码分析流水线** — 上传源代码的 zip 压缩包，选择目标语言，并运行多步分析，提取每个文件的 AST、CFG 和 DFG 图 - **图浏览器** — 通过基于 [Cytoscape](https://cytoscape.org/) 的可视化交互式浏览生成的图 - **RAG 聊天机器人** — 在对话界面中针对分析的代码库提问，由 [LangChain](https://www.langchain.com/langchain/) 驱动，并以 [Azure AI Search](https://azure.microsoft.com/en-us/products/ai-services/ai-search/) 作为向量存储 - **深度分析** — 使用 [DeepAgents](https://www.langchain.com/deep-agents/) 提交自由格式查询以进行自主的多步代码分析，并支持 PDF 导出 - **流水线跟踪** — 实时监控分析进度（待处理、运行中、已完成、失败） - **多用户支持** — [Microsoft Entra ID](https://www.microsoft.com/en-gb/security/business/identity-access/microsoft-entra-id/) 身份验证、按用户区分的仓库列表以及共享仓库访问权限 ## 架构 ``` graph LR User([User]) --> Frontend subgraph Azure Frontend["Frontend
Angular"] Backend["Backend API
FastAPI"] Worker["Worker
Durable Functions"] Blob[(Blob Storage)] DB[(Cosmos DB
for MongoDB)] Search[(Azure AI Search)] end Frontend -->|REST API| Backend Backend -->|triggers| Worker Backend -->|RAG| Search Backend --> DB Backend --> Blob Worker --> Blob Worker --> DB Worker --> Search ``` | 组件 | 角色 | |---|---| | **Backend** | FastAPI 服务器，处理身份验证、CRUD 操作、聊天机器人对话（SSE 流式传输）和深度分析编排 | | **Frontend** | Angular 单页应用 (SPA)，提供用于仓库管理、图浏览、聊天机器人和深度分析的 UI | | **Worker** | Azure Durable Functions 应用，运行分析流水线：zip 解压、按文件生成 AST/CFG/DFG 以及创建摘要 | ## 技术栈 ### 后端 (`backend/`) [FastAPI](https://fastapi.tiangolo.com/) • [Beanie](https://beanie-odm.dev/) • [LangChain](https://www.langchain.com/langchain/) • [LangGraph](https://langchain-ai.github.io/langgraph/) • [DeepAgents](https://www.langchain.com/deep-agents/) • [Mistral AI](https://mistral.ai/) • [Azure AI Search](https://learn.microsoft.com/azure/search/) • [Loguru](https://loguru.readthedocs.io/) ### 前端 (`frontend/`) [Angular 21](https://angular.dev/) • [Cytoscape.js](https://js.cytoscape.org/) • [Mermaid](https://mermaid.js.org/) • [highlight.js](https://highlightjs.org/) ### Worker (`worker/`) [Azure Durable Functions](https://learn.microsoft.com/en-us/azure/durable-task/durable-functions/durable-functions-overview/) • [javalang](https://github.com/c2nes/javalang) • [NetworkX](https://networkx.org/) • [Beanie](https://beanie-odm.dev/) • [LangChain](https://www.langchain.com/langchain/) • [Mistral AI](https://mistral.ai/) • [Loguru](https://loguru.readthedocs.io/) ## 仓库结构 ``` retro-doc/ ├── backend/ # FastAPI REST API server ├── frontend/ # Angular SPA ├── worker/ # Azure Durable Functions analysis pipeline └── LICENSE ``` 每个组件都有各自的依赖管理，可以独立开发。请查看每个文件夹中的 `README.md` 文件以获取详细文档。 ## 快速开始 ### 前置条件 - [Python 3.12](https://www.python.org/) - [uv 0.10.9](https://docs.astral.sh/uv/) - [Node.js 22](https://nodejs.org/)（用于 frontend 和 Azure Functions Core Tools） - [Azure Functions Core Tools v4](https://learn.microsoft.com/azure/azure-functions/functions-run-local)（用于 worker） - [Docker](https://www.docker.com/)（推荐，用于在本地运行 MongoDB） ### 基础设施服务 backend 和 worker 都需要一个 **MongoDB** 实例和一个 **Azure Blob Storage** 账户。对于本地开发，您可以模拟这两者： | 服务 | 本地替代方案 | 生产环境 | |---|---|---| | MongoDB | Docker | Azure Cosmos DB for MongoDB | | Blob Storage | [Azurite](https://github.com/Azure/Azurite)（通过 npx 包含） | Azure Blob Storage | | AI Search | 无本地模拟器 -- 需要 [Azure AI Search](https://learn.microsoft.com/azure/search/) 实例 | Azure AI Search | | LLM / Embeddings | 任何 [LangChain 支持的聊天模型](https://python.langchain.com/docs/integrations/chat/) 提供商 | Mistral AI / Azure OpenAI | ### 后端 ``` cd backend cp .env.example .env # fill in your credentials uv sync uv run uvicorn app.main:app --host localhost --port 8000 ``` 当 `APP_DEBUG=True` 时，API 文档可在 `http://localhost:8000/docs` 获取。 ### 前端 ``` cd frontend npm install npm start ``` 应用在 `http://localhost:4200/` 提供服务。 ### Worker ``` cd worker cp .env.example .env # fill in your credentials uv sync ``` 在两个终端中分别启动本地存储模拟器和 Functions 运行时： ``` # Terminal 1 npx azurite --skipApiVersionCheck --location .azurite-data # Terminal 2 func start ``` ## 许可证 本项目基于 [Apache License 2.0](LICENSE) 授权。

标签：AI智能体, Angular, Grype, Python, RAG, SOC Prime, 代码分析, 凭证管理, 开发工具, 无后门, 特权检测, 自动文档生成, 逆向工具