FROWNINGdev/django-orm-lens
GitHub: FROWNINGdev/django-orm-lens
一款为 Django 提供模型结构可视化、ER 图生成、CLI 查询和 MCP server 支持的零配置开发工具。
Stars: 2 | Forks: 1
# Django ORM Lens ### 在你的编辑器、终端和 AI agent 中查看整个 Django schema。 每一个应用。每一个 model。每一个 field。每一种关系。已分组、可导航，只需一次击键即可查看实时的 ER 图。
[](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) [](https://pypi.org/project/django-orm-lens/) [](https://registry.modelcontextprotocol.io/) [](https://glama.ai/mcp/servers/FROWNINGdev/django-orm-lens) [](https://mcp.so/servers/django-orm-lens) [](https://github.com/FROWNINGdev/django-orm-lens) [](https://github.com/sponsors/FROWNINGdev)
[](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) [](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) [](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens&ssr=false#review-details) [](https://pypi.org/project/django-orm-lens/) [](https://pypi.org/project/django-orm-lens/) [](LICENSE) [](https://github.com/FROWNINGdev/django-orm-lens/actions/workflows/ci.yml)
## 🎯 痛点解析 你打开了一个 Django 项目。它包含 20 个应用。你需要回答一个简单的问题： 如今，这意味着：`Ctrl+P`，"models"，在 30 个结果中滚动，打开五个文件，`Ctrl+F` 查找 `class Order`，阅读 400 行 `ForeignKey('otherapp.Something')` 字符串，努力回忆你两个文件前读到了什么。 **半天时间没了。每次如此。每个项目如此。**
## ✨ 使用 Django ORM Lens
| ### 📚 全览的树状图 每一个应用 -> 每一个 model -> 每一个 field -> 每一个 `Meta` 选项。按应用分组，按字母排序，可自由展开。 图标让你一眼就能区分出 `CharField`、`ForeignKey` 还是 `ManyToManyField`。 | ### 🕸️ 实时 ER 图 只需一个命令，即可打开涵盖你整个 schema 的 Mermaid 实体关系图。看着它随着你的编辑而重绘。可导出为 SVG。 `ForeignKey`、`OneToOneField` 和 `ManyToManyField` 会变成规范的基数箭头。 |
| ### 🔎 悬停查看关系 在任何 Python 文件中将鼠标悬停在 `ForeignKey('app.Model')` 上 -> 弹出一张卡片，显示目标 model 的 fields、关系以及一个“跳转至”链接。无需 `Ctrl+F`，也无需文件对话框。 | ### 🧭 跳转至定义 点击树状图中的任意 field -> 光标直接落在对应行。可按应用或 model 名称过滤树状图。完全支持拆分式的 `models/` 包。 |
| ### ⚡ 零配置 无需 `DJANGO_SETTINGS_MODULE`。无需 `runserver`。静态解析 `models.py`。无论是处于损坏的 venv、缺失依赖，还是在别人的笔记本电脑上，都能正常工作。 | ### 🎨 原生 VS Code UI 深色主题。浅色主题。你的主题。跟随你的图标主题、你的字体、你的快捷键绑定。没有突兀的色调，也没有强加的品牌包装。 |
## 📸 效果展示
## 🤖 面向终端和 AI 编程 agent 支持 VS Code 插件的同一款解析器也作为独立的 Python 包发布 —— 带有可选的 **MCP (Model Context Protocol) server**，以便任何兼容 MCP 的 AI agent 都能在不导入 Django 或启动应用的情况下浏览你的 Django schema。 ### CLI ``` django-orm-lens scan -f json # every app, every model, every field django-orm-lens describe blog.Post # one model in Markdown django-orm-lens hover blog.Post # compact hover card django-orm-lens list | fzf # flat app.Model — pipes anywhere django-orm-lens er > schema.mmd # Mermaid ER diagram ``` 每个命令都接受 `--path
## 🔌 集成 | 客户端 | 如何启用 | 状态 | |---|---|:-:| | **VS Code** | `code --install-extension frowningdev.django-orm-lens` | ✅ | | **Cursor** | 同样的 VSIX + 在 `~/.cursor/mcp.json` 中可选添加 MCP 条目 | ✅ | | **Windsurf / VSCodium / 任何 Code 分支** | 从 [Marketplace](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) 或 [GitHub Releases](https://github.com/FROWNINGdev/django-orm-lens/releases) 安装 VSIX | ✅ | | **Aider** | 在你的 `mcp.json` 中添加 `django-orm-lens-mcp` | ✅ (通过 MCP) | | **Continue.dev** | 在 `~/.continue/config.json` 中注册 MCP server | ✅ (通过 MCP) | | **Zed** | 在 Zed 设置中注册 MCP server | ✅ (通过 MCP) | | **任何兼容 MCP 的客户端** | 将 `command` 指向 `django-orm-lens-mcp`，设置 `DJANGO_ORM_LENS_ROOT` | ✅ | | **可通过 [MCP Registry](https://registry.modelcontextprotocol.io/) 发现** | 官方的 Model Context Protocol server 目录 | ✅ | | **纯终端 / CI** | `pip install django-orm-lens && django-orm-lens scan` | ✅ | ### 示例：Cursor / 任何 MCP 客户端 ``` { "mcpServers": { "django-orm-lens": { "command": "django-orm-lens-mcp", "env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" } } } } ```
## 🚀 开始使用 (30 秒) **在 VS Code 中：** 1. `code --install-extension frowningdev.django-orm-lens` 2. 打开一个包含 `manage.py` 或 `models.py` 的文件夹 3. 点击活动栏中的 **Django ORM Lens** 图标 4. 展开 apps -> models -> fields 5. 点击面板顶部的 **type-hierarchy** (类型层级) 图标 -> ER 图会显示在你的代码旁 **在终端中：** ``` pip install django-orm-lens cd my-django-project django-orm-lens scan -f table ``` **作为 AI agent 工具：** ``` pip install "django-orm-lens[mcp]" ``` …然后在你的 agent 的 MCP 配置中注册 `django-orm-lens-mcp`（参见上方的[集成](#-integrations)表格）。 无需设置界面。无需登录。无遥测。
## 🎯 适用人群 - **Django 开发者** —— 刚接手拥有 10 个以上应用的代码库，迷失在错综复杂的 `models.py` 中。 - **外包 / 自由职业工程师** —— 需要在头一个小时内弄清陌生的 Django 项目，而不是头一个星期。 - **团队入职培训** —— 希望提供一目了然的 schema 视图，而无需搭建文档基础设施。 - **AI agent 高级用户** (Cursor / Aider / Claude Desktop / Zed / Continue) —— 需要 agent 准确回答 schema 问题，而不提供数据库凭据或启动 Django。 - **CI 流水线** —— 在不导入项目的情况下验证 schema 结构（例如“我们是不是意外破坏了某个 `related_name`？”）。 - **独立开发者** —— 在损坏的 venv 或别人的笔记本电脑上工作 —— 不需要 `runserver`，不需要 `manage.py migrate`，依然有效。
## 🗺️ 市场定位 Django ORM Lens 处于**编辑器工具**和 **AI agent 工具**的交汇点 —— 这是一个现有软件包都未覆盖的领域： | 细分领域 | 现有方案 | 需要付出的代价 | |---|---|---| | 启动并绘图 | `django-extensions graph_models` | 需要 Graphviz + Django 设置 + 可用的数据库 URL | | 基于 Web 的查看器 | `django-schema-graph` | 需要运行中的 Django server；又多了一个容易出故障的环节 | | 管理面板 | Django Admin | 需要 runserver + 身份验证 + 数据库 —— 适合看数据，但不适合看架构 | | 编辑器插件 | PyCharm 的 Django Structure | 锁定在 PyCharm 中；无 CLI，不支持 AI agent | | MCP server | (此前没有) | AI agent 只能从源码猜测你的 schema，并不完美 | **Django ORM Lens 是唯一一款从一个解析器衍生出三种使用界面的工具：** VS Code 插件（适用于任何 Code 分支）、零依赖的 CLI（适用于终端 + CI）以及 MCP server（适用于 AI agent）。全部为静态解析。全部免费。全部基于 MIT 协议。
## 🤔 有何不同？ | | **Django ORM Lens** | `django-extensions graph_models` | `django-schema-graph` | Django Admin | PyCharm Django Structure | |---|:-:|:-:|:-:|:-:|:-:| | 无需可启动的 Django 项目即可使用 | ✅ | ❌ | ❌ | ❌ | ⚠️ | | 零安装（无需 graphviz，无需 server） | ✅ | ❌ | ❌ | ❌ | ❌ (需要 PyCharm) | | 可在 VS Code / Cursor / 任何 Code 分支中运行 | ✅ | ❌ | ❌ | ❌ | ❌ | | 编辑器内的侧边栏树状图 | ✅ | ❌ | ❌ | ❌ | ✅ | | 实时 ER 图 | ✅ | ✅ | ✅ | ❌ | ❌ | | `ForeignKey` 悬停卡片 | ✅ | ❌ | ❌ | ❌ | ⚠️ | | model 类上的 Code | ✅ | ❌ | ❌ | ❌ | ❌ | | 支持拆分式的 `models/` 包 | ✅ | ⚠️ | ⚠️ | ✅ | ✅ | | 适用于终端 / CI 的 CLI | ✅ | ⚠️ | ❌ | ❌ | ❌ | | 面向 AI agent 的 MCP server | ✅ | ❌ | ❌ | ❌ | ❌ | | 可在 [MCP Registry](https://registry.modelcontextprotocol.io/) 中发现 | ✅ | ❌ | ❌ | ❌ | ❌ | | 免费且开源 (MIT) | ✅ | ✅ | ✅ | ✅ | ❌ (付费 IDE) |
## ⚙️ 配置 默认配置已经经过了深思熟虑且非常合理。如果你需要微调： ``` // .vscode/settings.json { "djangoOrmLens.excludeGlobs": [ "**/migrations/**", "**/node_modules/**", "**/venv/**", "**/.venv/**", "**/env/**" ], "djangoOrmLens.autoRefresh": true } ``` | 设置 | 类型 | 默认值 | 作用 | |---|---|---|---| | `djangoOrmLens.excludeGlobs` | `string[]` | 见上文 | 扫描时要跳过的 Glob 匹配模式 | | `djangoOrmLens.autoRefresh` | `boolean` | `true` | 在 `models.py` 发生更改时重新扫描 |
## 🧭 命令 打开命令面板 (`Ctrl+Shift+P` / `Cmd+Shift+P`) 并输入 "Django ORM Lens"： | 命令 | 作用 | |---|---| | `Django ORM Lens: Refresh` | 强制重新扫描工作区 | | `Django ORM Lens: Show ER Diagram` | 并排打开 Mermaid ER 图 | | `Django ORM Lens: Filter Models` | 按应用 / model / field 名称过滤树状图 | | `Django ORM Lens: Clear Filter` | 恢复完整的树状图 | | `Django ORM Lens: Jump to Model` | 编程式触发 —— 由点击树状图和悬停卡片触发 |
## 🗺️ 路线图 **已发布** - [x] 按应用分组的侧边栏树状图 - [x] 实时 Mermaid ER 图 - [x] `ForeignKey('app.Model')` 上的悬停卡片 - [x] 按名称过滤树状图 - [x] 支持拆分式的 `models/` 包 - [x] 将 ER 图导出为 SVG - [x] 面向终端和 AI agent 的 Python CLI + MCP server - [x] 针对空工作区的欢迎视图 - [x] 路径安全的跳转定义及经过净化的悬停 Markdown - [x] **v0.3.0** —— 各个 model 类上方的 CodeLens (`N fields · N relations · Open ER diagram`) - [x] **v0.3.0** —— 图表上的边标签 (`CASCADE`, `SET_NULL`, `PROTECT`, `related_name`) - [x] **v0.3.0** —— 命名颜色主题 (`auto` / `default` / `dark` / `forest` / `neutral`) - [x] **v0.3.1** —— M2M 边上的 `through_model` (由 [@kingrubic](https://github.com/kingrubic) 贡献) - [x] **v0.3.1** —— 已被列入[官方 MCP Registry](https://registry.modelcontextprotocol.io/) + [Glama.ai](https://glama.ai/mcp/servers/FROWNINGdev/django-orm-lens) **下一步** - [ ] webview 内部的缩放 + 缩略图 + 自动布局 ([#4](https://github.com/FROWNINGdev/django-orm-lens/issues/4)) - [ ] `.filter()` / `.exclude()` / `.annotate()` 内部的 ORM 查询自动补全 ([#3](https://github.com/FROWNINGdev/django-orm-lens/issues/3)) - [ ] 应用 / model 切换复选框，用于简化庞大的 schema 展示 **未来计划** - [ ] Migration 依赖图 - [ ] 支持第三方 field (`django-mptt`, `django-taggit`, `django-model-utils`) - [ ] JetBrains / PyCharm 插件 (如果有需求的话) 通过对相应的[issue](https://github.com/FROWNINGdev/django-orm-lens/issues)点赞 👍 来进行投票。
## ❓ 常见问题
你们会把我的任何代码发送到服务器吗？
不会。每一个字节都保留在你的机器上。解析器是纯 TypeScript（插件）或纯 Python（CLI）。没有 LLM 调用，没有遥测，没有分析，没有错误报告。Mermaid 渲染器运行在 VS Code 的 webview 沙盒内。
它能与 Poetry / uv / conda / 完全没有 venv 配合使用吗？
可以。插件直接读取 Python 源码 —— 它不会导入 Django，也不关心你使用什么包管理器。CLI 要求 Python 3.9+，但也仅此而已。
我的 models 分散在 models/ 包中的多个文件里。这能支持吗？
是的，从 v0.2.0 开始支持。插件和 CLI 都会在经典的
models.py 之外，遍历 models/*.py。
我能将它用于 DRF serializers、Wagtail、Oscar 或第三方基础 models 吗？
任何看起来像 Django model 的类都会被识别：
models.Model 的子类、以 Abstract 开头的抽象基类、以 Mixin 结尾的通用 mixins，以及像 TimeStampedModel 或 PolymorphicModel 这样已知的基础类名。非 model 的类（ModelAdmin、ModelSerializer、Form、View、Manager、…）都会被过滤掉。
哪些 AI agent 可以使用这个 MCP server？
任何兼容 MCP 的客户端 —— Cursor、Aider、Continue.dev、Zed 以及其他任何支持该协议的工具。只需将
command 指向已安装的 django-orm-lens-mcp 二进制文件即可。请参阅 集成章节。
有 JetBrains / PyCharm 版本吗？
目前还没有。PyCharm 的 Django Structure 工具窗口已经做得很好了，所以带来的额外价值较小。如果有足够多的人提出需求，这就值得去做。
## 🆘 支持 - 🐛 **Bug 报告** —— [GitHub Issues](https://github.com/FROWNINGdev/django-orm-lens/issues)（请附上最小复现的 `models.py` 片段） - 💡 **功能请求 / 创意** —— [GitHub Discussions](https://github.com/FROWNINGdev/django-orm-lens/discussions) - 📝 **应用商店评价** —— [为插件评分](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens&ssr=false#review-details)（这是推动本项目发展的最直接反馈） - 🐍 **PyPI 页面** —— [pypi.org/project/django-orm-lens](https://pypi.org/project/django-orm-lens/) - 💚 **赞助** —— [github.com/sponsors/FROWNINGdev](https://github.com/sponsors/FROWNINGdev)
## 📜 许可证 MIT © [FROWNINGdev](https://github.com/FROWNINGdev)
**献给关心自己代码库的开发者们。**
[Marketplace](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens) · [PyPI](https://pypi.org/project/django-orm-lens/) · [GitHub](https://github.com/FROWNINGdev/django-orm-lens) · [Issues](https://github.com/FROWNINGdev/django-orm-lens/issues) · [Discussions](https://github.com/FROWNINGdev/django-orm-lens/discussions) · [赞助](https://github.com/sponsors/FROWNINGdev)
标签：Django, ER图, MCP, ORM, SOC Prime, VS Code 扩展, 开发工具, 文档结构分析, 逆向工具