N3MO

<!-- mcp-name: io.github.RajX-dev/n3mo --> <div align="center"> <img src="docs/n3mo_intro.gif" alt="N3MO In Action" width="750"> <br>  [](https://n3mo.shop) [](https://pypi.org/project/n3mo/) [](LICENSE) [](https://www.python.org) [](https://www.docker.com) []() [](https://registry.modelcontextprotocol.io/?q=n3mo) [](https://github.com/RajX-dev/N3MO/actions) [](https://pepy.tech/projects/n3mo) [](https://discord.gg/cTgZKHf2G) **结构化代码智能层，源代码转换为可查询的知识图谱，用于搜索，影响分析和AI驱动的开发。** *解析一次，查询永远。准确知道代码变更前会发生什么。* > *"文本差异是所有代码审查焦虑的源头。开发人员修改核心实用程序，审查者不得不花费一小时精神追踪下游服务以猜测是否安全合并。N3MO用硬数学取代人类猜测。* > > **[立即在n3mo.shop部署GitHub Webhook →](https://n3mo.shop)** **📜 遵循PolyForm Noncommercial 1.0.0许可** — 源代码可用于非商业用途。 • [需要商业许可？ **获取商业许可→**](https://n3mo.shop) [什么是N3MO](#-什么是N3MO) • [教程](#-教程) • [基准测试](#-基准测试) • [架构](#-架构) • [安装](#-安装) • [MCP](#-模型上下文协议-mcp) • [用法](#-用法) • [路线图](#-路线图) </div> --- ## 🎯 什么是N3MO？ N3MO是一个以符号为中心的 代码智能层。 它不扫描原始文本，而是解析源代码的AST，映射调用图，并建模依赖关系到一个可查询的关系数据库 - 确定性地，**索引时无需LLM调用**。 对于工程领导者和团队，N3MO是代码库的**结构保险政策**。 ### 💡 为什么选择N3MO？ * **消除回归风险** — 实用程序很少被重构，因为开发人员担心未知的影响。 N3MO映射任意深度的符号的传递影响范围，准确显示修改前会发生什么。 **[在CI/CD中自动化此过程 →](https://n3mo.shop)** * **快速的开发人员入职** — 高级工程师不再花费数小时向新员工解释代码库流程，而是运行一个命令来交互式地可视化复杂的调用链和父子依赖关系。 * **AI代理就绪的基础设施** — 现代LLM代理（Cursor，Claude Desktop）受到上下文窗口和文本搜索的限制。 N3MO的本地MCP服务器允许代理查询实际的代码图，实现快速，无幻觉的重构。 * **⚡ 无嵌入，无漂移** — N3MO是纯静态分析：Tree-sitter AST解析到PostgreSQL。无需与索引同步的矢量索引，无存储库嵌入成本，无语义相似性猜测 - 图中的每个边都是一个确切，可验证的关系。 ### 📊 N3MO比较 | 能力 | Grep / 文本搜索 | IDE "查找引用" | N3MO 代码图 | | :--- | :--- | :--- | :--- | | **分析基础** | 子字符串匹配 | 基于AST，直接引用 | 关系知识图 | | **传递遍历** | ❌ 无 | ❌ 手动，一次一级 | ⚡ **任意深度即时** | | **影响范围映射** | ❌ 无 | ❌ 平面搜索结果列表 | 🎨 **交互式视觉轨道图** | | **CI/CD集成** | ❌ 无 | ❌ 绑定到IDE运行时 | ⚙️ **Dockerized CLI + CTE查询** | | **AI代理集成** | ❌ 注入文件块 | ⚠️ 手动上下文复制 | 🤖 **本地MCP服务器** | | **语言覆盖** | ✅ 任意文本文件 | ⚠️ 语言特定插件 | ✅ **27 Tree-sitter语法** | | **索引方法** | N/A | N/A | ✅ **确定性AST解析 - 无嵌入，无LLM调用** | ### 🛠️ N3MO解决的核心问题 <table> <tr> <td width="50%"> **❌ 没有N3MO** <pre> 开发人员： “'login'出现在哪里？” 工具： grep -r “login” . 结果： 647个匹配项，分布在89个文件上 ...现在怎么办？ </pre> </td> <td width="50%"> **✅ 使用N3MO** <pre> 开发人员： “如果我更改login，会发生什么？” 工具： n3mo impact "login" 结果： 3个直接调用者→5个连锁反应 完整影响范围 < 50ms </pre> </td> </tr> </table> > **N3MO不查找文本 - 它理解结构。** 它跟踪实际的调用图，而不是字符串匹配。 **N3MO立即回答的问题：** | | 问题 | 如何 | |:---:|:---|:---| | 🔎 | 这个仓库中存在哪些函数和类？ | 跨27种语言的完整符号索引 | | 🎯 | 这个符号在哪里使用 - 直接*和传递？ | 递归CTE遍历到任意深度 | | 💥 | 更改此函数的影响范围是什么？ | 交互式轨道图，带有深度滑块 | | 🕸️ | 这些组件如何实际连接？ | 调用图 + 父子层次结构 | | 🤖 | 我的AI代理能否结构性地理解此代码库？ | 用于Cursor / Claude的本地MCP服务器 | --- --- ## ✨ 核心能力 ### 提取和解析 * **多语言支持** — 支持27种Tree-sitter语法（动态加载）；在10种主要语言（包括Python，JS / TS，Go，Java和C / C ++）上积极基准测试 * **并行AST提取** — `ProcessPoolExecutor`在所有可用的核心上分发CPU绑定的解析 * **增量重新索引** — SHA-256文件哈希自动跳过未更改的文件 * **幂等操作** — 重新索引更新现有数据而不会重复 * **智能排除** — 不区分大小写的目录过滤器和驼峰感知文件名检查防止假阳性（例如，允许`contest.py`同时跳过`test_*.py`） ### 分析和查询 * **符号提取** — 具有完整文件路径+行上下文的函数，类，方法 * **分层建模** — 父子关系（模块→类→方法） * **调用图构建** — 调用者，解析摄取时间 * **作用域感知解析** — 类作用域>本地文件>导入>限定点路径>全局 * **影响范围分析** — 递归CTE遍历到任意深度，带有循环保护 ### 性能 * **连接池** — `ThreadedConnectionPool`消除每个符号的DB往返 * **批量插入** — 符号，导入和调用按文件分批，在单个事务中 * **优化查询** — `SPLIT_PART`修复实现了2倍的调用解析速度 ### 可视化和集成 * **交互式图** — vis.js轨道图，带有点击检查节点，侧边栏和深度滑块 * **暗黑模式** — 可切换的画布暗黑模式，实时节点/边缘更新，存储在`localStorage`中 * **高级样式** — 简洁的交互式仪表板登录页面UI和图视觉化，采用`Bricolage Grotesque` ， `Inter`和`JetBrains Mono`字体排版 * **[SKILL.md](SKILL.md)**配置文件 — 系统指令配置Claude作为影响感知编码代理 * **本地MCP服务器** — 与Cursor，Claude Desktop和Windsurf的一流集成 * **Git钩子** — 每次提交自动重新索引 * **CI管道** — GitHub Actions，带有linting（`ruff`），类型检查（`mypy`）和`pytest` --- --- ## 🌐 支持的语言 <div align="center"> | | | | | |:---:|:---:|:---:|:---:| |  |  |  |  | |  |  |  |  | |  |  |  |  | |  |  |  |  | |  |  |  |  | |  |  |  |  | |  |  |  | *…还有更多* | </div> > Tree-sitter解析支持27种语言。目前针对Python，JS / TS和Java优化了深度语义调用图映射。 --- --- ## 🚀 安装 ### erequisites    ### 快速开始 直接从PyPI安装N3MO： ```bash # 安装软件包 pip install n3mo # 启动Docker容器并初始化数据库 n3mo setup ``` 或者，对于以可编辑模式运行的贡献者： ```bash git clone https://github.com/RajX-dev/N3MO.git cd N3MO pip install -e . n3mo setup ``` --- --- ## 💻 用法 ### 索引仓库 ```bash cd /path/to/your/project n3mo index ``` **索引内容：** * ✅ 所有27种支持语言的源文件 * ❌ 虚拟环境（`venv/`，`.venv/`） * ❌ 依赖项（`node_modules/`，`site-packages/`） * ❌ 构建工件（`.git/`，`__pycache__/`，`dist/`） * ❌ 测试/夹具目录（`tests/`，`mocks/`，`specs/`） ### 可视化工具 #### 暗黑模式 — 径向布局  #### 水平树视图  **终端输出示例： ``` ◈ 影响分析 ────────────────────────────────────────────────────────────────── 目标： authenticate_user ────────────────────────────────────────────────────────────────── ◉ 直接调用者 (3 个符号) ▸ login_endpoint api/auth.py:12 ▸ refresh_token api/token.py:23 ▸ validate_session middleware/auth.py:89 ◎ 影响范围 (5 个符号) ╰─▸ POST /login routes.py:67 ╰─▸ admin_login admin/views.py:34 ╰─▸ require_auth decorators.py:12 ╰─▸ dashboard_view views/dashboard.py:8 ╰─▸ settings_view views/settings.py:22 ────────────────────────────────────────────────────────────────── 总影响：8个引用 │ 深度≤3 ``` ### 依赖图可视化 ```mermaid graph LR A[main.py] --> B[auth.py::login] A --> C[db.py::connect] B --> D[utils.py::hash_password] B --> E[models.py::User] C --> F[config.py::DB_URI] style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color=#fff style B fill:#4ecdc4,stroke:#0ca89e,stroke-width:2px,color=#000 style C fill:#45b7d1,stroke:#1098ad,stroke-width:2px,color=#000 style D fill:#96ceb4,stroke:#63b598,stroke-width:2px,color=#000 style E fill:#ffd93d,stroke:#f5c200,stroke-width:2px,color=#000 style F fill:#e0e0e0,stroke:#a0a0a0,stroke-width:2px,color=#000 ``` --- --- ## 🎥 教程 [在GitHub上观看教程视频](https://github.com/RajX-dev/N3MO/blob/main/docs/tutorial.mp4?raw=true) --- ## 🤖 模型上下文协议（MCP） N3MO包含一个本地MCP服务器，针对LLM代理（如Claude，Cursor或Windsurf）暴露存储库分析和图遍历工具。 ### 自动Claude Desktop设置 ```bash # 导航到您要分析的工作区，然后运行： n3mo mcp install ``` 此注册N3MO并自动设置路径。重启Claude Desktop，您就可以开始了！ ### 🧠 Claude技能（系统指令） 要配置Claude在编辑器中更改代码之前主动查询影响，请导入或复制粘贴来自 **[SKILL.md](SKILL.md)** 配置文件的自定义指令。 ### Cursor设置 1. 进入 **设置 → 模型 → MCP**。 2. 点击 **+ 添加新的MCP服务器**。 3. 设置配置详细信息： * **名称**：`n3mo` * **类型**：`command` * **命令**：`n3mo mcp start`（或`uvx n3mo mcp start`直接运行） * **环境变量**：`TARGET_CODE_DIR=/绝对路径/到/您的/活动/工作区` 4. 点击保存，Cursor将立即能够索引和查询您的工作区影响范围。 ### 🏢 扩展至团队呼叫 * 将AI代理引入您的团队工作区？* 停止强制每个开发人员在其本地笔记本电脑上运行繁重的索引管道和PostgreSQL实例。 直接通过 **[n3mo.shop](https://n3mo.shop)** 连接Cursor到全球云图谱，绕过本地机器数据库开销。您的代理立即查询云图谱。 ### 🧰 可用的MCP工具 | 工具 | 描述 | |:---|:---| | `n3mo_index` | 提取并索引代码库 | | `n3mo_search_symbol` | 在工作区中找到符号的定义（文件路径，行号） | | `n3mo_get_dependencies` | 查找给定符号调用的所有外部符号（前向依赖图） | | `n3mo_get_file_symbols` | 列出特定文件中定义的类和函数 | | `n3mo_get_blast_radius` | 跟踪符号的传递影响/调用图 | --- --- ## ☁️ 企业CI/CD自动化（SaaS支点） 在本地循环中运行确定性AST解析很棒，但是手动构建多步骤YAML操作，维护CI数据库基础设施和编排PR时间线事件是工程团队的巨大摩擦点。 **[n3mo.shop](https://n3mo.shop)** 是我们的权威，零维护的基础设施层，抽象了所有这些。 * **零配置Webhooks：** 2次点击GitHub应用同步。无需维护YAML样板。 * **自动内联PR评论：** N3MO钩入您的仓库，并在GitHub审查时间线中直接发布确切的影响范围： ```markdown ◈ N3MO拉取请求影响分析 ⚠️ 检测到影响范围：修改`core_auth.py`会间接影响3个下游服务。 - `api/billing.py:process_payment()` - `web/handlers.py:login_route()` - `cron/sync_users.py:execute()` ``` * **严格的“零信任”隐私：** 我们只解析结构AST元数据。**您的原始源代码从未存储在我们的服务器上。** 临时解析容器在PR注释发布后立即被销毁。 **[今天就使用n3mo.shop进行基础设施外包 →](https://n3mo.shop)** ## 📊 基准测试 所有基准测试均在 **Intel i5-13450HX，24 GB RAM，NVMe SSD** 上进行测量。 <!-- ... --> ``` ### Django — 优化历史 Django 是主要的基准测试目标：**3,021 个文件**，**约 43K 符号**，**约 181K 调用**。 ``` Django 索引时间（分钟） ═══════════════════════════════════════════════════════════════ v0.3 基线 ██████████████████████████████████████████████ 23 分钟 1× SPLIT_PART 修复 ██████████████████████ 11 分钟 2× 批量插入 █████████ 5 分钟 4.6× + 多进程 ████ 2.5 分钟 9× 🚀 ═══════════════════════════════════════════════════════════════ ``` | 优化 | 索引时间 | 速度提升 | 更改内容 | |:---|:---|:---|:---| | v0.3 基线 | 23 分钟 | 1× | 每个符号的数据库插入，朴素的调用解析 | | + SPLIT_PART 查询修复 | 11 分钟 | 2× | 调用解析中消除冗余的字符串分割 | | + 批量插入 | 5 分钟 | 4.6× | 文件的符号、导入和调用批量处理（1 个事务） | | + 多进程 | 约 2.5 分钟 | **约 9×** | `ProcessPoolExecutor` 在多个核心上分发 AST 解析 | > ✅ 所有结果都是在 [Django](https://github.com/django/django) 仓库上的实际测量。多进程增益随着核心数量的增加而扩展。 ### TensorFlow — 企业级大型单体仓库 **在 [TensorFlow](https://github.com/tensorflow/tensorflow) 上测试** — 一个包含 36,000 个文件、多语言（C++/Python）的单体仓库。 | 指标 | 结果 | |:---|:---| | **仓库大小（总文件数）** | 约 36,000 | | **处理和索引的文件** | **14,611** *(过滤测试、配置和非源文件后)* | | **提取的符号总数** | **79,523** | | **提取的调用边总数** | **480,851** | | **完整索引时间（冷启动）** | **14.06 分钟** | | **峰值内存（Docker 容器）** | **185 MB RAM** | | **CPU 利用率** | **约 5%** | > N3MO 从 3K 文件的纯 Python 仓库（Django）扩展到 36K 文件的多语言企业级单体仓库（TensorFlow）— 大约 **5× 更大的索引作业，接近线性吞吐量**，而无需显著的资源开销。TensorFlow 的符号/边每个文件和增量（热）重新索引的数字正在完整的基准测试报告中最终确定。 ### ScanCode 工具包 — 大型代码库 **在 [ScanCode 工具包](https://github.com/nexB/scancode-toolkit) 上测试** — 约 600K 行 Python 代码。 | 指标 | 结果 | |:---|:---| | **代码行数** | 约 600,000 | | **完整索引时间** | 约 3 分钟 | | **处理模式** | 单线程（v0.3） | ### 增量重新索引 N3MO 使用 SHA-256 文件哈希来跳过后续运行中未更改的文件。 | 场景 | 时间 | 备注 | |:---|:---|:---| | **完整索引**（第一次运行） | 基线 | 所有文件解析和插入 | | **无更改**（重新运行） | **< 1 秒** | 仅哈希比较，无数据库写入 | | **1 个文件修改** | **< 2 秒** | 仅更改的文件被重新解析和更新 | > 这些结果来自内置的基准测试脚本，在一个包含 20 个文件的综合仓库上运行。实际的增量性能与更改的文件数量成比例，而不是整个仓库大小。 ### 查询性能 影响分析使用 PostgreSQL 递归 CTE 和循环保护。查询时间独立于仓库大小 — 它们仅取决于结果子图的 size。 | 查询类型 | 典型延迟 | |:---|:---| | 符号的直接调用者 | **< 10 毫秒** | | 完整的爆炸半径（深度 ≤ 5） | **< 50 毫秒** | | 完整的图遍历 | **< 200 毫秒** | ### 运行基准测试 ```bash python benchmarks/benchmark_indexing.py ``` --- --- ## 📈 项目状态 N3MO 的核心架构和分发阶段（基础、性能、正确性和扩展性以及分发）已成功完成。 该项目目前稳定，积极维护，准备好投入生产使用。 --- --- ## 📝 设计原则 **1. 结构先于语义** 在添加 AI 分析之前，映射代码骨架（AST）。正确的图胜过一个聪明但错误的图。 **2. 数据库作为真实来源** 所有状态都存储在 PostgreSQL 中，消除了内存复杂性，并启用了图形查询，而应用程序级遍历无法匹配。 **3. 正确性高于速度** 解析器必须优雅地处理语法错误，而不会破坏图形。一个快速的索引器默默地丢弃符号比一个慢的索引器但能正确处理所有符号要差。 **4. 幂等操作** 重新运行摄取会产生相同的结果，从而实现安全的增量更新和 CI/CD 集成。 --- --- ## 🤝 贡献 欢迎贡献！请阅读 **[CONTRIBUTING.md](CONTRIBUTING.md)** 指南，开始设置项目、编码标准和本地运行检查。 ### 开发设置 ```bash # 安装开发依赖 pip install -e ".[dev]" # 校验 ruff check n3mo/ # 类型检查 mypy n3mo/ # 测试 pytest tests/ ``` --- --- ## 📜 许可证和定价 ### 定价和许可 N3MO 在 **PolyForm Noncommercial 1.0.0 许可证** 下免费用于本地使用和单个开发者的 MCP 集成。 * **100% 免费和本地** — CLI 查询、本地 MCP 集成和可视化工具，无限制。 * **商业 SaaS 和 Webhooks** — 在团队环境、CI/CD 管道和私有 GitHub Webhooks 中使用 N3MO，请在 [n3mo.shop](https://n3mo.shop) 购买商业许可证。 * **企业许可** — 用于大规模组织部署、自定义 SLA 或零信任隔离环境，请联系以获取企业选项。 --- 在 **PolyForm Noncommercial 1.0.0** 许可证下授权。 * ✅ 免费用于个人项目、学术研究和爱好工具 * ✅ 源代码可用 — 查看、修改和分发用于非商业目的 * ⚠️ 非商业 — 您不得将其用于商业目的 * ⚠️ 限制适用于作为服务提供 有关商业部署或专有修改，请联系以获取许可选项。 请参阅 [LICENSE](LICENSE) 以获取完整的法律详情。 --- --- ## 👨💻 作者 **Raj Shekhar** — 德里理工大学 [](https://github.com/RajX-dev) [](https://linkedin.com/in/raj-shekhar349) --- --- ## 🙏 致谢 * **[Tree-sitter](https://tree-sitter.github.io/)** — 用于健壮、增量、错误容忍的解析 * **[PostgreSQL](https://www.postgresql.org/)** — 使递归图查询成为可能，无需图数据库 * **[Docker](https://www.docker.com/)** — 用于可复制、单命令环境 * **[vis.js](https://visjs.org/)** — 用于交互式图可视化 * **[FastAPI](https://fastapi.tiangolo.com/)** — 用于高性能 REST 层 --- <div align="center"> **⭐ 如果您觉得这个项目有用，请给它点个星 — 感谢您的访问！** *构建用于理解大规模代码的工具。*   <br><br> <pre> ███╗ ██╗ ██████╗ ███╗ ███╗ ██████╗ ████╗ ██║ ╚════██╗ ████╗ ████║ ██╔═══██╗ ██╔██╗ ██║ █████╔╝ ██╔████╔██║ ██║ ██║ ██║╚██╗██║ ╚═══██╗ ██║╚██╔╝██║ ██║ ██║ ██║ ╚████║ ██████╔╝ ██║ ╚═╝ ██║ ╚██████╔╝ ╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ C O D E I N T E L L I G E N C E L A Y E R </pre> </div>