SarimMalik01/ODESSA

# ODESSA — 静态代码分析平台（测试版 V(1.1)）

ODESSA 是一个静态代码分析平台，旨在**早期发现深层次的结构性工程风险**，避免它们演变为昂贵的生产问题。 它不只关注语法或孤立的 linting，而是**统一分析架构、性能、安全和浏览器兼容性**，覆盖整个代码库，采用**确定性且可解释的解析流水线**。 此外，ODESSA 集成了**检索增强生成（RAG）系统**，允许用户通过自然语言交互式探索代码库，提供**基于上下文、贴合代码库实际的洞察**。 本仓库包含 ODESSA 的**测试版（V1.1）实现**。 ## 🚩 问题背景 在真实系统中，最具破坏性的问题很少是语法错误。 它们通常是**结构性**的： - 架构漂移逐渐侵蚀可维护性 - 热点执行路径中隐藏的性能瓶颈 - 未被察觉的安全风险 - 跨环境静默失败的浏览器 API - 工具链与协作碎片化 大多数工具孤立地解决这些问题。 **ODESSA 将它们整合进一个统一系统。** ## 🔍 设计理念 ODESSA 围绕以下核心信念构建： - 架构决定长期系统健康 - 关键风险往往**跨文件**出现 - 静态分析必须**可解释、确定性、可重现** - 协作与检测同等重要 系统被有意设计为优先关注**信号而非噪声**。 ## 🧠 ODESSA 分析范围 ODESSA 在**四个领域**暴露问题： ### 🧱 架构 - 循环依赖 - 层违反 - 神类模块 - 依赖不稳定 - 领域泄露至 UI 路径 ### ⚡ 性能 - 嵌套循环 - 循环内的函数调用 - 热路径中的昂贵操作 - 跨文件热点函数 - 多调用者热点路径 ### 🔐 安全 - `eval` 使用 - `new Function` 使用 - 硬编码密钥 - 不安全的 DOM 操作 ### 🌐 浏览器兼容性 - Clipboard API 使用 - Fetch API 假设 - ResizeObserver 使用 - IntersectionObserver 使用 - Web Share API 使用 - CSS Grid 与 Flex Gap 支持 - 可选链与空值合并 - `Promise.allSettled` 可用性 测试版 V(1.1) 当前包含 **约 30 条自定义规则**，涵盖： - 单文件分析 - 多文件 / 跨文件分析 ## 🔐 统一扫描模型 ODESSA 提供**一个统一功能**： - **不存在 ZIP 上传或本地扫描模式** - 所有扫描均基于**真实代码库**，使用认证访问执行 ## 🔑 仓库访问（GitHub OAuth） - 用户通过 **GitHub OAuth** 认证 - 授予范围包括： - 公共代码库 - 私有代码库（需明确用户同意） - 不会永久存储 GitHub 凭证 - 代码库克隆至**临时、隔离的工作空间** 这使得分析**生产级代码库**无需手动上传。 ## 🧠 端到端扫描流程（逐步说明） 本节详细描述扫描在内部**具体如何执行**。 ### 1️⃣ 扫描启动 - 用户在 GitHub OAuth 后选择代码库 - 后端创建扫描任务 - 生成唯一 `SCAN_ID` - 任务元数据被存储（仓库 URL、提交引用、用户） ### 2️⃣ 任务排队（使用 BullMQ + Redis） - 扫描任务推入基于 Redis 的 BullMQ 队列 - 后端保持非阻塞 - 扫描进度可通过轮询暴露 重型分析与用户交互完全解耦。 ### 3️⃣ 扫描引擎容器启动 - BullMQ 工作者启动**全新的扫描引擎 Docker 容器** - 容器接收： - 仓库 URL - 提交或分支引用 - 扫描 ID - 在容器内克隆仓库 - 工作空间完全隔离 用户代码**不会在后端容器中运行**。 ### 4️⃣ 文件系统标准化 在扫描引擎内部： - 仓库被规范化为确定性的工作空间 - 识别受支持源码文件 - 构建用于 UI 渲染的分层文件树 确保扫描可重现。 ### 5️⃣ AST 解析与遍历 对每个发现的文件： - 文件被解析为 AST - AST 被逐节点遍历 - 一次遍历中收集多个信号 收集的信号包括： - 函数声明 - 导入与依赖关系 - 循环深度 - 函数调用 - 性能启发式 - 安全敏感结构 - 浏览器 API 使用 ### 6️⃣ 遍历期间执行规则 规则在 AST 遍历过程中**内联执行**： - 规则按 AST 节点类型索引 - 仅对相关节点运行 - 按文件与行号去重 规则领域： - 架构 - 性能 - 安全 - 浏览器兼容性 这避免了冗余遍历，保持扫描高效。 ### 7️⃣ 全局与跨文件分析 所有文件扫描完成后： - 架构规则在**全局依赖图**上运行 - 跨文件性能规则检测： - 跨模块热点函数 - 多调用者性能风险 这些问题**无法仅从单文件检测**。 ### 8️⃣ 问题标准化 所有发现合并为**统一问题模型**： - 架构问题 - 性能问题 - 安全问题 - 浏览器兼容性问题 每个问题包含： - 规则 ID - 严重等级 - 解释说明 - 文件与行上下文 - 附加元数据 ### 9️⃣ 异步 LLM 增强 - 标准化问题可**选择性通过 LLM 增强** - 此步骤： - 免触发、异步 - 非阻塞 - 容错 - 同一 LLM 层级也支持基于 RAG 的交互式仓库探索 核心扫描保持**确定性**，即使增强失败也不受影响。 ## 🐳 容器与部署架构 ODESSA 有意将职责分离到不同容器。 ### 1️⃣ 扫描引擎 Dockerfile **目的：** 在完全隔离的环境中执行静态分析。 **职责：** - 克隆代码库 - 解析文件与 AST - 执行规则 - 生成标准化结果 **构建：** ``` docker build -t odessa-scan-engine ./scan-engine ``` 每次扫描在**全新容器**中运行，完成后即销毁。 ### 2️⃣ 后端与 Redis Dockerfiles ### 后端容器 - API 层 - GitHub OAuth 处理 - 项目与用户管理 - 作业编排 - 结果持久化 ### Redis 容器 - 基于 BullMQ 的作业队列 - 扫描调度 - 工作者协调 每个服务运行在**独立容器**中，实现隔离与可扩展性。 ## 3️⃣ docker-compose.yml `docker-compose.yml` 编排： - 后端服务 - Redis 服务 - 用于作业元数据的共享卷 卷允许 BullMQ 工作者： - 触发扫描引擎容器 - 共享临时扫描上下文 - 不在扫描生命周期外持久化用户代码 ## 🔐 安全与隔离保障 - 每次扫描在**全新容器**中运行 - 工作空间在完成后销毁 - 用户代码**永不持久化** - 禁止跨扫描污染 - OAuth 作用域最小化且可撤销 ## 💬 RAG 驱动的代码理解

ODESSA 集成**检索增强生成（RAG）系统**，实现交互式、上下文感知的代码库探索。 无需手动浏览大型代码库，用户可以**提出自然语言问题**，并获得**基于代码库实际的答案**。 ### 🔍 RAG 带来的能力 - 高层项目理解 -架构与数据流解释 - 深度代码级洞察 - 风险、瓶颈与漏洞识别 - 上下文感知的调试与改进建议 ### ⚙️ 工作原理 - 相关代码块与扫描结果被建立索引 - 查询通过语义检索匹配 - 检索的上下文传递给 LLM - 回答**基于实际仓库数据生成** 这确保答案： - 具备上下文 - 可解释 - 代码库专属（非通用 LLM 猜测） ## 📐 系统架构（高层设计）

该高层设计图展示了 ODESSA 从基于 GitHub OAuth 的仓库访问，到队列驱动的扫描执行，再到隔离的临时扫描容器及其共享、评论与分析端点的端到端流程。 设计强调： - 通过每扫描一容器实现强隔离 - 确定性、可重现的分析 - API、工作者与扫描引擎的清晰分离 - 安全处理 OAuth 令牌 ## 🧪 当前状态 - **阶段：** 测试版（V1.1） - **扫描模式：** 仅支持代码库方式 - **访问：** GitHub OAuth（公共与私有代码库） - **重点：** 信号质量与实际可用性 ## 🎥 演示 **完整演示（早期测试版 — ZIP 上传扫描，现已弃用，替换为基于仓库的扫描）：** https://drive.google.com/file/d/1q3Tor2KKY0fF3mLtv3p_2pMhNDroWp1A/view?usp=sharing **完整演示（基于仓库的扫描 — GitHub OAuth 公共与私有代码库）：** https://drive.google.com/file/d/1wJQMXXzZJYy6AI9lgzVAWHhccGg3KqSt/view?usp=sharing **RAG 功能演示：** https://drive.google.com/file/d/1vMkvpto-7prn9wytdMaKToBgJIj7wV8a/view?usp=sharing ## 🚀 后续计划 该测试版（V1.1）有意作为**过渡版本**。 计划改进包括： - 更深入的架构启发式 - 更优的依赖关系图可视化 - 更智能的规则优先级 - 改进的协作流程 - 性能与可扩展性增强 ## 🔄 版本演进 ODESSA 经历了多次迭代，每次改进代码库的解析与探索方式： - **测试版** → ZIP 上传扫描 - **测试版（v1.0）** → 基于仓库 URL 与 GitHub OAuth（公共 + 私有代码库）的扫描 - **测试版（v1.1）** → 引入**基于 RAG 的自然语言查询**，实现交互式、上下文感知的代码库探索 ## 🚀 本地启动项目 ### 后端与 Redis 在 **backend 目录** 中运行： ``` docker compose up --build ``` 这将启动： - 后端服务 - Redis（用于 BullMQ 队列） - 扫描编排支持 ### 前端 在 **Frontend 目录** 中运行： ``` npm install npm run dev -- --host 127.0.0.1 ``` ### 说明 - 本项目处于积极开发中 - API、规则与结构可能演进 - 欢迎提供反馈

标签：ASN信息, Beta版, RAG, SEO: 安全异味检测, SEO: 性能瓶颈识别, SEO: 架构漂移检测, SEO: 浏览器兼容性风险, SEO: 静态代码分析平台, WebSocket, 云安全监控, 代码库分析, 依赖分析, 信号降噪, 前端分析, 协作平台, 可解释性, 工程风险, 循环依赖, 性能分析, 搜索引擎查询, 架构分析, 检索增强生成, 浏览器兼容性, 确定性分析, 自动化攻击, 请求拦截, 跨文件分析, 逆向工具, 静态分析, 领域驱动设计