内容
<div align="center">
<img src="media/hero.png" alt="Django ORM Lens — 实时侧边栏和ER图，适用于您的Django模型" width="100%"/>
<br/>
<br/>
# Django ORM Lens
### 在编辑器、终端和AI代理中查看整个Django架构
每个应用。每个模型。每个字段。每个关系。分组、导航，并通过一个快捷键即可访问实时ER图。
<br/>
[](https://marketplace.visualstudio.com/items?itemName=frowningdev.django-orm-lens)
[](https://pypi.org/project/django-orm-lens/)
[](https://registry.modelcontextprotocol.io/servers/io.github.FROWNINGdev%2Fdjango-orm-lens)
[](https://github.com/FROWNINGdev/django-orm-lens)
[](https://github.com/sponsors/FROWNINGdev)
<br/>
[](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)
</div>
---
## ⚡ 安装
**VS Code / Cursor / Windsurf / 任何Code分叉：**
```bash
code --install-extension frowningdev.django-orm-lens
```
或在扩展视图中搜索 **`Django ORM Lens`**。
**终端和AI编码代理：**
```bash
pip install django-orm-lens # 仅限CLI
pip install "django-orm-lens[mcp]" # + 用于AI代理的MCP服务器
```
需要Python 3.9+。CLI的运行时依赖为零。
<br/>
## 🎯 问题
你打开一个Django项目。它有20个应用。你需要回答一个简单的问题：
> _“哪个应用拥有 `Order` 模型，它与 `User` 如何连接？”_
今天，这意味着：`Ctrl+P`，“models”，滚动浏览30个匹配结果，打开5个文件，`Ctrl+F`搜索 `class Order`，阅读400行 `ForeignKey('otherapp.Something')` 字符串，尝试记住两文件前学到了什么。
**半天过去了。每次。每个项目。**
<br/>
## ✨ 使用Django ORM Lens
<table>
<tr>
<td width="50%" valign="top">
### 📚 整个架构树
每个应用 → 每个模型 → 每个字段 → 每个 `Meta` 选项。按应用程序分组，字母排序，可展开。
图标区分 `CharField` 和 `ForeignKey` 以及 `ManyToManyField`。
</td>
<td width="50%" valign="top">
### 🕸️ 实时ER图
一个命令打开整个架构的Mermaid实体关系图。边编辑边刷新。导出为SVG。
`ForeignKey`、`OneToOneField` 和 `ManyToManyField` 变成正确的基数箭头。
</td>
</tr>
<tr>
<td width="50%" valign="top">
### 🔎 鼠标悬停查看关系
在任何Python文件中，将鼠标悬停在 `ForeignKey('app.Model')` 上 → 会弹出一个卡片，显示目标模型的字段、关系和“跳转到”链接。无需 `Ctrl+F`，无需文件对话框。
</td>
<td width="50%" valign="top">
### 🧭 跳转到定义
点击树中的任何字段 → 光标落在确切的行上。按应用或模型名称过滤树。支持分割 `models/` 包。
</td>
</tr>
<tr>
<td width="50%" valign="top">
### ⚡ 零配置
无需 `DJANGO_SETTINGS_MODULE`。无需 `runserver`。静态解析 `models.py`。即使在损坏的venv、缺失的依赖或别人的笔记本电脑上也能工作。
</td>
<td width="50%" valign="top">
### 🎨 原生VS Code UI
黑暗主题。浅色主题。您的主题。遵循您的图标主题、字体、快捷键。没有任何俗气的东西，没有品牌。
</td>
</tr>
</table>
<br/>
## 📸 效果展示
<div align="center">
<img src="media/hero.png" alt="Django ORM Lens侧边栏显示应用的模型，包含字段、关系和Meta选项" width="90%"/>
</div>
<br/>
## 🤖 用于终端和AI编码代理
与为VS Code扩展提供支持的相同解析器，作为一个独立的Python包提供 - 可选的 **MCP（模型上下文协议）服务器**，让任何MCP兼容的AI代理都能在不导入Django或启动应用的情况下浏览Django架构。
### CLI
```bash
django-orm-lens scan -f json # 每个应用，每个模型，每个字段
django-orm-lens describe blog.Post # 以Markdown格式显示一个模型
django-orm-lens hover blog.Post # 紧凑的悬停卡片
django-orm-lens list | fzf # 平坦的应用.Model — 可以通过管道传输
django-orm-lens er > schema.mmd # Mermaid ER图
```
每个命令都接受 `--path <dir>` 和 `--exclude <glob>`。
### MCP服务器
注册后，它会向AI代理暴露五个只读工具：
| 工具 | 目的 |
| --- | --- |
| `list_apps` | 工作区中的每个Django应用及其模型数量 |
| `list_models` | 平坦的 `app.Model` 列表，可选应用过滤 |
| `describe_model` | 一个模型的完整字段/关系/Meta详细信息 |
| `find_relations` | 一个模型的入站和出站关系 |
| `er_diagram` | 整个工作区的Mermaid `erDiagram` |
```bash
# 直接启动
django-orm-lens-mcp
# 或通过CLI子命令
django-orm-lens mcp
```
设置 `DJANGO_ORM_LENS_ROOT=/abs/path/to/project` 以指向任何位置。
<br/>
## 🔌 集成
| 客户端 | 如何启用 | 状态 |
|---|---|:-:|
| **VS Code** | `code --install-extension frowningdev.django-orm-lens` | ✅ |
| **Cursor** | 相同的VSIX + `~/.cursor/mcp.json`中的可选MCP条目 | ✅ |
| **Windsurf / VSCodium / 任何Code分叉** | 从 [市场](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服务器 | ✅ (通过MCP) |
| **Zed** | 在Zed设置中注册MCP服务器 | ✅ (通过MCP) |
| **任何MCP兼容客户端** | 将 `command` 指向 `django-orm-lens-mcp`，设置 `DJANGO_ORM_LENS_ROOT` | ✅ |
| **通过 [MCP注册表](https://registry.modelcontextprotocol.io/servers/io.github.FROWNINGdev%2Fdjango-orm-lens) 可发现** | 官方模型上下文协议服务器目录 | ✅ |
| **纯终端 / CI** | `pip install django-orm-lens && django-orm-lens scan` | ✅ |
### 示例：Cursor / 任意MCP客户端
```jsonc
{
"mcpServers": {
"django-orm-lens": {
"command": "django-orm-lens-mcp",
"env": { "DJANGO_ORM_LENS_ROOT": "/abs/path/to/your/project" }
}
}
}
```
<br/>
## 🚀 快速开始（30秒）
**在VS Code中：**
1. `code --install-extension frowningdev.django-orm-lens`
2. 打开包含 `manage.py` 或 `models.py` 的文件夹
3. 点击活动栏中的 **Django ORM Lens** 图标
4. 展开应用 → 模型 → 字段
5. 点击面板顶部的 **type-hierarchy** 图标 → ER图在代码旁边打开
**在终端中：**
```bash
pip install django-orm-lens
cd my-django-project
django-orm-lens scan -f table
```
**作为AI代理工具：**
```bash
pip install "django-orm-lens[mcp]"
```
…然后在代理的MCP配置中注册 `django-orm-lens-mcp`（参见上面的 [集成](#-integrations) 表）。
无需设置屏幕。无需登录。无需遥测。
<br/>
## 🤔 有什么不同？
| | **Django ORM Lens** | `django-extensions graph_models` | `django-schema-graph` | Django Admin |
|---|:-:|:-:|:-:|:-:|
| 不需要可启动的Django项目 | ✅ | ❌ | ❌ | ❌ |
| 零安装（无需graphviz，无需服务器） | ✅ | ❌ | ❌ | ❌ |
| 编辑器内的侧边栏树 | ✅ | ❌ | ❌ | ❌ |
| 实时ER图 | ✅ | ✅ | ✅ | ❌ |
| `ForeignKey` 悬停卡片 | ✅ | ❌ | ❌ | ❌ |
| 支持分割 `models/` 包 | ✅ | ⚠️ | ⚠️ | ✅ |
| 用于终端/CI的CLI | ✅ | ⚠️ | ❌ | ❌ |
| 用于AI代理的MCP服务器 | ✅ | ❌ | ❌ | ❌ |
| 免费&开源 | ✅ | ✅ | ✅ | ✅ |
<br/>
## ⚙️ 配置
默认配置是合理的。如果需要调整：
```jsonc
// .vscode/settings.json
{
"djangoOrmLens.excludeGlobs": [
"**/migrations/**",
"**/node_modules/**",
"**/venv/**",
"**/.venv/**",
"**/env/**"
],
"djangoOrmLens.autoRefresh": true
}
```
| 设置 | 类型 | 默认值 | 功能 |
|---|---|---|---|
| `djangoOrmLens.excludeGlobs` | `string[]` | 见上 | 扫描时跳过的glob模式 |
| `djangoOrmLens.autoRefresh` | `boolean` | `true` | 在 `models.py` 更改时重新扫描 |
<br/>
## 🧭 命令
打开命令面板（`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` | 按应用/模型/字段名称过滤树 |
| `Django ORM Lens: Clear Filter` | 恢复完整树 |
| `Django ORM Lens: Jump to Model` | 程序化 - 由树点击和悬停卡触发 |
<br/>
## 🗺️ 路线图
**已完成**
- [x] 按应用分组的侧边栏树
- [x] 实时Mermaid ER图
- [x] `ForeignKey('app.Model')` 上的悬停卡片
- [x] 按名称过滤树
- [x] 支持分割 `models/` 包
- [x] 以SVG导出ER图
- [x] 用于终端和AI代理的Python CLI + MCP服务器
- [x] 空工作区的欢迎视图
- [x] 路径安全的跳转到定义和消毒的悬停Markdown
**下一个（v0.3.0）**
- [ ] 每个 `class Model` 的CodeLens：`N个关系 · N个字段 · 打开ERD`
- [ ] 图表上的边标签：`CASCADE`、`SET_NULL`、`PROTECT`、`related_name`
- [ ] webview中的缩放 + 迷你地图 + 自动布局
- [ ] 命名颜色主题（默认/海洋/日落/森林/黑暗）
- [ ] 应用/模型切换复选框以减少巨大的架构
**稍后**
- [ ] 迁移依赖图
- [ ] `.filter()`/`.exclude()`/`.annotate()`中的ORM查询自动补全
- [ ] 第三方字段支持（`django-mptt`、`django-taggit`、`django-model-utils`）
- [ ] JetBrains / PyCharm插件（如果有需求）
通过 👍 对应的 [问题](https://github.com/FROWNINGdev/django-orm-lens/issues) 进行投票。
<br/>
## ❓ 常见问题
<details>
<summary><b>你会发送我的任何代码到服务器吗？</b></summary>
<br/>
不会。每个字节都保留在您的机器上。解析器是纯TypeScript（扩展）或纯Python（CLI）。没有LLM调用，没有遥测，没有分析，没有错误报告。Mermaid渲染器在VS Code的webview沙箱中运行。
</details>
<details>
<summary><b>它与Poetry / uv / conda / 没有venv配合使用吗？</b></summary>
<br/>
是的。扩展直接读取Python源代码 - 它不导入Django，不关心您使用的包管理器。CLI需要Python 3.9+，但仅此而已。
</details>
<details>
<summary><b>我的模型分布在 <code>models/</code> 包中的多个文件中。这种情况支持吗？</b></summary>
<br/>
是的，从v0.2.0开始。扩展和CLI都遍历 <code>models/*.py</code> 以及经典的 <code>models.py</code>。
</details>
<details>
<summary><b>我可以使用DRF序列化器、Wagtail、Oscar或第三方基模型吗？</b></summary>
<br/>
任何类似于Django模型的类都被拾取：`models.Model`的子类、以`Abstract`开头的抽象基类、以`Mixin`结尾的常见混入类以及已知的基名称，如`TimeStampedModel`或`PolymorphicModel`。非模型类（`ModelAdmin`、`ModelSerializer`、`Form`、`View`、`Manager`等）被过滤掉。
</details>
<details>
<summary><b>哪些AI代理可以使用MCP服务器？</b></summary>
<br/>
任何MCP兼容的客户端 - Cursor、Aider、Continue.dev、Zed以及其他遵循协议的工具。只需将 `command` 指向已安装的 `django-orm-lens-mcp` 二进制文件。参见 [集成](#-integrations) 部分。
</details>
<details>
<summary><b>有JetBrains / PyCharm版本吗？</b></summary>
<br/>
还未有。PyCharm的Django Structure工具窗口已经很不错，所以价值增幅较小。如果很多人询问，我会做。
</details>
<br/>
## 🆘 支持
- 🐛 **错误报告** — [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)
<br/>
## 📜 许可证
MIT © [FROWNINGdev](https://github.com/FROWNINGdev)
<br/>
<div align="center">
**为关心自己代码库的开发者而打造。**
[市场](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) · [问题](https://github.com/FROWNINGdev/django-orm-lens/issues) · [讨论](https://github.com/FROWNINGdev/django-orm-lens/discussions) · [赞助](https://github.com/sponsors/FROWNINGdev)
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器