内容
<p align="center">
<img src="assets/logo.svg" alt="erdlens" width="96" height="96" />
</p>
<h1 align="center">erdlens</h1>
<p align="center"><b>您的数据库架构变成ER图，直接嵌入到您的文档中。并且它会在图变得过时时通知您。</b></p>
<p align="center">
🇺🇸 English · <a href="README.id.md">🇮🇩 Bahasa Indonesia</a> · <a href="README.zh-CN.md">🇨🇳 简体中文</a>
</p>
<p align="center">
<img alt="license" src="https://img.shields.io/badge/license-MIT-6C8EEF" />
<img alt="runtime deps" src="https://img.shields.io/badge/runtime%20deps-0-6C8EEF" />
<img alt="tests" src="https://img.shields.io/badge/tests-57%20passing-6C8EEF" />
<img alt="mcp" src="https://img.shields.io/badge/MCP-server-6C8EEF" />
<img alt="typescript" src="https://img.shields.io/badge/TypeScript-MVVM-6C8EEF" />
</p>
<p align="center">
<img src="assets/showcase.gif" alt="erdlens turning a schema into an ER diagram, a workflow into a flowchart, and catching drift after a migration" width="720" />
</p>
---
您询问Claude Code来记录您的数据库。它编写文档，您在其他工具中生成ER图，然后将图复制并粘贴回文档中。两个工具，双倍工作，并且在有人运行迁移后，文档中的图就会悄悄地变得不正确。
**erdlens** 是一个MCP服务器，闭合了这个循环。Claude Code读取您的架构，将其转换为Mermaid ER图，并将其写入文档中，一步完成。无需第二个工具，无需复制粘贴。并且它可以稍后检查图是否仍然与架构匹配。
## 为什么它与众不同
现有的图MCP服务器渲染您已经编写的Mermaid。erdlens提前一步：**为您读取架构**，再晚一步：**监视漂移**。
| | 渲染您的Mermaid | 读取架构 | 写入文档 | 漂移检查 |
|--|:--:|:--:|:--:|:--:|
| mermaid-preview MCPs | ✅ | ❌ | 部分 | ❌ |
| mermerd (CLI, 不是MCP) | ❌ | ✅ (仅DB) | ❌ | ❌ |
| **erdlens** | ✅ | ✅ (5个来源) | ✅ | ✅ |
架构来源：**SQL DDL, Prisma, Drizzle, TypeORM, SQLAlchemy** — 文件或文本，自动检测。
## 安装 (Claude Code)
```bash
claude mcp add erdlens -- npx -y github:ryanda9910/erdlens
```
或指向本地克隆：
```bash
git clone https://github.com/ryanda9910/erdlens
claude mcp add erdlens -- node /abs/path/to/erdlens/bin/erdlens.js
```
然后只需询问Claude Code： *"记录数据库并在docs/schema.md中放入ER图"*。它调用`render_erd`，图就会出现在文件中。
## 工具
| 工具 | 它做什么 |
|--|--|
| `schema_to_erd` | 架构（路径或文本）→ Mermaid `erDiagram` + 一个```mermaid 代码块，可粘贴到任何地方 |
| `render_erd` | 将ER图写入磁盘：`.mmd`源文件，可嵌入的`.md`，以及自包含的`.html`预览 — 因此它可以直接进入文档，无需复制粘贴 |
| `drift_check` | 将已经在`.mmd`/`.md`中的ER图与当前架构进行比较，并报告自上次以来添加或删除的每个表、列和关系。在CI中运行它，以便过时的图失败构建 |
| `workflow_to_diagram` | 工作流规范（微型文本DSL或JSON步骤）→ Mermaid `flowchart` + 代码块。记录ER图旁边的过程、管道或状态机 |
| `render_workflow` | 与`render_erd`相同，用于工作流 — 将流程图写入磁盘，可嵌入 |
## 漂移检查
这是保持文档诚实的部分。在迁移后：
```
$ erdlens drift docs/schema.md db/schema.sql
图已过时。它已经偏离了当前的架构：
+ 添加的表：audit_logs
~ posts：+published +slug
+ 添加的关系：posts->users
使用render_erd重新生成以修复。
```
当过时时，退出代码为非零，因此它会进入CI步骤或预提交钩子。
## 工作流
不仅是数据。给它一个工作流，它就会绘制流程图 — 相同的“放入您的文档”路径。
```
# publish.flow
start -> draft
draft -> review
review -> publish : approved
review -> draft : changes
publish -> done
```
```bash
erdlens flow publish.flow
```
```
flowchart TD
start(["start"])
...
review -->|approved| publish
review -->|changes| draft
```
询问Claude Code *"将发布工作流放入docs/flow.md"*，它调用`render_workflow`。
## 也是一个CLI
无需MCP客户端：
```bash
erdlens erd db/schema.sql # 打印Mermaid ER图
erdlens erd prisma/schema.prisma # 自动检测Prisma
erdlens flow pipeline.flow # 打印Mermaid流程图
erdlens drift docs/erd.mmd db/schema.sql # 如果漂移，则退出1
erdlens tune # 运行自我检查循环（如下）
```
## 自我改进循环
`erdlens tune`是一个制造者 → 检查者 → 反射循环：它在固定装置上运行每个解析器，加上漂移场景（制造者），一个独立的评分器标记任何以前通过但现在失败的内容（检查者），并将每个源的传递状态持久化到`~/.erdlens/memory.json`（反射）。这是解析器保持诚实的方式，因为添加了新的架构方言 — 回归出现而不是悄悄溜过。
## 测试
```bash
npm test # 构建，然后57个断言：24个架构引擎 + 14个工作流 + 19个MCP标准输入输出
```
还有一个端到端的脚本，通过真正的Claude Code运行（`bash test/e2e.sh`，需要`claude` CLI登录）。
## 构建方式
TypeScript，布局为MVVM：
- **模型** (`src/model/`) — 纯逻辑：架构解析器，工作流解析器，漂移差异，类型。
- **视图模型** (`src/viewmodel/`) — 协调：工具操作和自我改进循环。
- **视图** (`src/view/`) — 表面：JSON-RPC MCP服务器，CLI和Mermaid/HTML渲染。
零**运行时**依赖。MCP服务器是从头开始的JSON-RPC标准输入输出实现；HTML预览仅在浏览器中打开时从CDN加载Mermaid。
## 许可证
MIT
