n3mo

一个结构化代码智能层，将源代码转化为可查询的知识图谱，用于搜索、影响分析和 AI 驱动的开发。

一次解析，永久查询。在问题发生之前，准确知道什么会出问题。

“文本差异是所有代码审查焦虑的根源。开发者修改了一个核心工具函数，审查者却不得不花一个小时在脑中追踪下游服务，才能猜测是否可以安全合并。N3MO 用硬核数学取代了人类的猜测。”

在 n3mo.shop 即时部署 GitHub Webhook →

📜 基于 PolyForm Noncommercial 1.0.0 许可 — 源代码可用于非商业用途。 • 需要商业用途？获取商业许可 →

什么是 N3MO • 核心能力 • 安装 • 使用 • MCP • CI/CD SaaS • 基准测试 • 教程 • 赞助

🎯 什么是 N3MO？

N3MO 是一个以符号为中心的代码智能层。它不扫描原始文本，而是解析源代码的 AST、映射调用图，并在可查询的关系数据库中建模依赖关系 —— 确定性地完成，且在索引时 零 LLM 调用。

对于工程负责人和团队而言，N3MO 是代码库的 结构性保险单。

💡 为什么选择 N3MO？

• 🛡️ 消除回归风险 — 工具函数很少被重构，因为开发者担心未知的副作用。N3MO 可将任意符号的传递性影响范围映射到任意深度，让你在编辑前就准确知道哪些地方会出问题。在你的 CI/CD 中自动化这一过程 →
• 🏎️ 快速上手开发 — 不再需要资深工程师花费数小时向新员工讲解代码库流程，开发者只需运行一条命令，即可交互式地可视化复杂的调用链和父子依赖关系。
• 🤖 为 AI Agent 就绪的基础设施 — 现代大模型 Agent（Cursor、Claude Desktop）受限于上下文窗口和文本搜索。N3MO 原生 MCP 服务让 Agent 能够查询真实的代码图，从而实现快速、无幻觉的重构。
• ⚡ 无需嵌入，无漂移 — N3MO 是纯静态分析：使用 Tree-sitter AST 解析并存入 PostgreSQL。没有需要保持同步的向量索引，没有按仓库计算的嵌入成本，也没有语义相似度的猜测——图中的每条边都是精确、可验证的关系。

📊 N3MO 对比

🛠️ N3MO 解决的核心问题

开发者：“'login' 出现在哪里？”
工具：     grep -r "login" .
结果：     在 89 个文件中有 647 处匹配
           ……然后呢？

开发者：“如果我修改 login 会有什么影响？”
工具：     n3mo impact "login"
结果：     3 个直接调用者 → 5 个连锁影响
           完整影响范围在 < 50ms 内得出

N3MO 不是查找文本——而是理解结构。 它追踪真实的调用图，而不是字符串匹配。

N3MO 能即时回答的问题：

👥 适用对象

✨ 核心能力

数据摄取与解析

• 多语言支持 — 支持 27 种 Tree-sitter 语法（动态加载）；在 Python、JS/TS、Go、Java 和 C/C++ 等 10 种主要语言上进行持续基准测试
• 并行 AST 摄取 — ProcessPoolExecutor 在所有可用核心上分发 CPU 密集型解析任务
• 增量重新索引 — SHA-256 文件哈希自动跳过未更改的文件
• 幂等操作 — 重新索引会更新现有数据而不会产生重复
• 智能排除 — 大小写不敏感的目录过滤器和 camelCase 感知的文件名检查可防止误报（例如允许 contest.py 而跳过 test_*.py）

分析与查询

• 符号提取 — 函数、类、方法，附带完整文件路径 + 行上下文
• 层次建模 — 父子关系（模块 → 类 → 方法）
• 调用图构建 — 谁调用了谁，在摄取时解析
• 作用域感知解析 — 类作用域 > 本地文件 > 导入 > 限定点路径 > 全局
• 爆炸半径分析 — 递归 CTE 遍历至任意深度，带循环防护

性能

• 连接池 — ThreadedConnectionPool 消除了每个符号的数据库往返
• 批量插入 — 符号、导入和调用按文件在单个事务中批量处理
• 优化查询 — SPLIT_PART 修复使调用解析速度提升 2 倍

可视化与集成

• 交互式图谱 — vis.js 轨道图，支持点击查看节点、侧边栏和深度滑块
• 深色模式 — 可切换的画布深色模式，实时更新节点/边，持久化存储在 localStorage 中
• 高级样式 — 时尚的交互式仪表盘落地页 UI 和图谱可视化工具，使用 Bricolage Grotesque、Inter 和 JetBrains Mono 字体排版
• SKILL.md 配置文件 — 系统指令，将 Claude 配置为影响感知的编码 Agent
• 原生 MCP 服务 — 与 Cursor、Claude Desktop 和 Windsurf 的一流集成
• Git 钩子 — 每次提交时自动重新索引
• CI 流水线 — GitHub Actions，包含代码检查（ruff）、类型检查（mypy）和 pytest

🌐 支持的语言

			……以及更多

支持 27 种语言的 Tree-sitter 解析。深度语义调用图映射目前针对 Python、JS/TS 和 Java 进行了优化。

🚀 安装

前提条件

快速开始

直接从 PyPI 安装 N3MO：

# Install the package
pip install n3mo

# Start Docker containers & initialize the database
n3mo setup

或者，对于以可编辑模式运行的贡献者：

git clone https://github.com/RajX-dev/N3MO.git
cd N3MO
pip install -e .
n3mo setup

💻 用法

索引代码仓库

cd /path/to/your/project
n3mo index

会被索引的内容：

• ✅ 所有 27 种受支持语言的源文件
• ❌ 虚拟环境（venv/、.venv/）
• ❌ 依赖项（node_modules/、site-packages/）
• ❌ 构建产物（.git/、__pycache__/、dist/）
• ❌ 测试 / 固定装置目录（tests/、mocks/、specs/）

可视化工具

深色模式 — 径向布局

水平树视图

终端输出示例：

  ◈ IMPACT ANALYSIS
  ──────────────────────────────────────────────────────────────────
  Target:  authenticate_user
  ──────────────────────────────────────────────────────────────────

  ◉ Direct Callers  (3 symbols)

  ▸ login_endpoint             api/auth.py:12
  ▸ refresh_token              api/token.py:23
  ▸ validate_session           middleware/auth.py:89

  ◎ Ripple Effects  (5 symbols)

    ╰─▸ 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

  ──────────────────────────────────────────────────────────────────
  Total impacted: 8 references  │  depth ≤ 3

依赖关系图可视化

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

🎥 教程

教程涵盖的内容：

💡 更喜欢动手实践？ 按照 快速开始 在 60 秒内在本地运行 N3MO。

🤖 Model Context Protocol (MCP)

N3MO 包含一个原生 MCP 服务，向大模型 Agent（如 Claude、Cursor 或 Windsurf）暴露仓库分析和图遍历工具。

自动设置 Claude Desktop

# Navigate to the workspace you want Claude to analyze, then run:
n3mo mcp install

这会注册 N3MO 并自动设置路径。重启 Claude Desktop 即可使用！

🧠 Claude Skill（系统指令）

要配置 Claude 在编辑器中修改代码之前主动运行 N3MO 影响查询，请从 SKILL.md 配置文件导入或复制粘贴自定义指令。

Cursor 设置

1. 前往 Settings → Models → MCP。
2. 点击 + Add New MCP Server。
3. 设置配置详情：
   • Name：n3mo
   • Type：command
   • Command：n3mo mcp start（或 uvx n3mo mcp start 直接运行）
   • Environment Variables：TARGET_CODE_DIR=/absolute/path/to/your/active/workspace
4. 点击 Save，Cursor 将立即能够索引和查询你的工作区影响范围。

🏢 扩展到团队

想把 AI Agent 引入你的团队工作区？ 不要再强迫每个开发人员在自己的笔记本电脑上运行繁重的索引流水线和 PostgreSQL 实例。

将 Cursor 直接连接到 n3mo.shop 的全局云图，完全绕过本地机器的数据库开销。你的 Agent 可以即时查询云图。

🧰 可用的 MCP 工具

☁️ 企业级 CI/CD 自动化（SaaS 转型）

在本地循环中运行确定性的 AST 解析很棒，但手动构建多步骤 YAML 操作、维护 CI 数据库基础设施，以及编排 PR 时间线事件，对工程团队来说是巨大的摩擦点。

n3mo.shop 是我们确定性的、零维护的基础设施层，抽象了所有这些复杂性。

• 零配置 Webhook： 2 次点击完成 GitHub App 同步。无需维护 YAML 样板文件。

• 自动内联 PR 评论： N3MO 接入你的仓库，并将确切的影响范围直接发布到你的 GitHub 审查时间线：

  ◈ N3MO Pull Request Impact Analysis
  ⚠️ Blast Radius Detected: Modifying `core_auth.py` transitively impacts 3 downstream services.
  - `api/billing.py:process_payment()`
  - `web/handlers.py:login_route()`
  - `cron/sync_users.py:execute()`
  

• 严格的「零信任」隐私： 我们只解析结构性 AST 元数据（符号关系）。你的原始源代码永远不会存储在我们的服务器上。 临时解析容器在 PR 评论发布后的毫秒内立即销毁。

立即在 n3mo.shop 卸载你的流水线基础设施 →

📊 基准测试

所有基准测试均在 Intel i5-13450HX、24 GB RAM、NVMe SSD 上测量。

Django — 优化历程

Django 是主要的基准测试目标：3,021 个文件、约 43K 个符号、约 181K 次调用。

Django Index Time (minutes)
═══════════════════════════════════════════════════════════════

v0.3 Baseline       ██████████████████████████████████████████████  23 min   1×
SPLIT_PART Fix      ██████████████████████                          11 min   2×
Batch Inserts       █████████                                        5 min   4.6×
+ Multiprocessing   ████                                           2.5 min   9× 🚀

═══════════════════════════════════════════════════════════════

✅ 所有结果均为在 Django 仓库上的真实测量值。多进程的收益随核心数量而扩展。

TensorFlow — 企业级单体仓库

在 TensorFlow 上测试 — 一个包含 36,000 个文件、多语言（C++/Python）的单体仓库。

N3MO 可从 3K 文件的纯 Python 仓库（Django）扩展到 36K 文件的多语言企业级单体仓库（TensorFlow）—— 索引任务规模约扩大 5×，吞吐量接近线性，且没有显著的资源开销。TensorFlow 的每文件符号/边数量以及增量（热）重新索引数据正在完整的基准测试报告中最终确定。

ScanCode Toolkit — 大型代码库

在 ScanCode Toolkit 上测试 — 约 600K 行 Python 代码。

增量重新索引

N3MO 使用 SHA-256 文件哈希在后续运行中跳过未更改的文件。

这些结果来自在包含 20 个文件的合成仓库上运行的内置基准测试脚本。真实世界的增量性能与更改的文件数量成正比，而非仓库总大小。

查询性能

影响分析使用带有循环防护的 PostgreSQL 递归 CTE。查询时间与仓库大小无关 —— 它们仅取决于结果子图的大小。

运行基准测试

python benchmarks/benchmark_indexing.py

📈 项目状态

N3MO 的核心架构和分发阶段（基础、性能、正确性与扩展、分发）已成功完成。 项目目前稳定，正在积极维护，并已准备好投入生产使用。

📝 设计原则

1. 先结构，后语义 在加入 AI 分析之前，先映射代码骨架（AST）。一张正确的图胜过一张聪明但错误的图。

2. 数据库作为唯一事实来源 所有状态都存放在 PostgreSQL 中，消除了内存中的复杂性，并支持应用层遍历无法比拟的图查询。

3. 正确性优先于速度 解析器必须优雅地处理语法错误，而不破坏图。一个会静默丢弃符号的快速索引器，比一个能把一切做对的慢速索引器更糟糕。

4. 幂等操作 重复运行数据摄取会产生相同的结果，从而实现安全的增量更新和 CI/CD 集成。

🤝 贡献

欢迎贡献！请阅读 CONTRIBUTING.md 指南，了解如何搭建项目、编码规范以及在本地运行检查。

开发环境搭建

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check n3mo/

# Type check
mypy n3mo/

# Tests
pytest tests/

📜 许可证与定价

定价与许可

N3MO 在 PolyForm Noncommercial 1.0.0 License 下可免费用于本地使用和单开发者 MCP 集成。

• 100% 免费且本地 — 命令行查询、本地 MCP 集成以及可视化工具均无任何限制。
• 商业 SaaS 与 Webhook — 若要在团队环境、CI/CD 流水线和私有 GitHub webhook 中使用 N3MO，请在 n3mo.shop 购买商业许可证。
• 企业许可 — 对于大规模组织部署、定制 SLA 或零信任气隙环境，请联系我们获取企业版方案。

在 PolyForm Noncommercial 1.0.0 License 下授权。

• ✅ 可免费用于个人项目、学术研究和业余工具
• ✅ 源码可用 — 可查看、修改并分发用于非商业目的
• ⚠️ 非商业性 — 你不得将其用于商业目的
• ⚠️ 将其作为服务提供受到限制

如需商业部署或专有修改，请联系我们获取许可方案。

完整法律细节请参见 LICENSE。

❤️ 赞助

如果 N3MO 在代码审查中为你节省了时间，或帮助你的 AI Agent 理解你的代码库，请考虑赞助该项目以支持持续开发。

你的赞助将帮助资助：

• 🔧 持续的维护和新语言支持
• 🚀 性能改进与扩展
• 📖 更好的文档和教程
• 🌍 让命令行和 MCP 服务对个人开发者保持免费

👨‍💻 作者

Raj Shekhar — Delhi Technological University

🙏 致谢

• Tree-sitter — 提供健壮、增量、容错的解析
• PostgreSQL — 让无需图数据库即可进行递归图查询成为可能
• Docker — 提供可复现、单命令的环境
• vis.js — 提供交互式图可视化
• FastAPI — 提供高性能的 REST 层

███╗   ██╗    ██████╗   ███╗   ███╗    ██████╗ 
████╗  ██║   ╚════██╗   ████╗ ████║   ██╔═══██╗
██╔██╗ ██║    █████╔╝   ██╔████╔██║   ██║   ██║
██║╚██╗██║    ╚═══██╗   ██║╚██╔╝██║   ██║   ██║
██║ ╚████║   ██████╔╝   ██║ ╚═╝ ██║   ╚██████╔╝
╚═╝  ╚═══╝    ╚═════╝   ╚═╝     ╚═╝    ╚═════╝ 
C O D E   I N T E L L I G E N C E   L A Y E R