efcore-d2-db-diagram

EF Core D2 数据库关系图生成器

何时使用

当用户希望从 Entity Framework Core 代码库生成数据库 / ERD 关系图时，使用此技能。

典型请求：

• 从 EF Core 实体生成 D2 数据库关系图。
• 可视化表、列、主键、外键和关系。
• 分析 DbContext、DbSet<T>、IEntityTypeConfiguration<T>、Fluent API 和迁移。
• 生成可用 d2 命令行渲染为 SVG/PNG 的 .d2 文件。
• 记录 ASP.NET Core / .NET 项目的数据库模型。

目标

创建一个可读的 D2 实体关系图，反映实际的 EF Core 持久化模型，而不仅仅是原始 C# 类结构。

关系图必须优先考虑：

1. 数据库表和关系。
2. 主键、外键、必填/可选列。
3. 拥有的类型和值对象。
4. 多对多关系和联接表。
5. 索引、唯一约束和表名。
6. 仅在缺少显式映射时使用 EF Core 约定。

输出为 .d2 源代码。可通过 d2 命令行渲染为 SVG 或 PNG。

工具

• d2 命令行：将 .d2 文件渲染为 SVG/PNG。
  • d2 input.d2 output.svg
  • d2 --layout=elk input.d2 output.svg
• d2 fmt：格式化 D2 文件。
  • d2 fmt input.d2
• 不需要 MCP 服务。此技能以文本形式生成 D2 源代码。

推荐工作流

1. 阅读 EF Core 项目结构。
2. 定位所有 DbContext 类。
3. 定位所有 DbSet<T> 声明。
4. 定位实体类、拥有的类型、枚举类型和值对象。
5. 阅读 OnModelCreating 和所有 IEntityTypeConfiguration<T> 类。
6. 在可用时阅读迁移，以确认表名、联接表、索引和删除行为。
7. 在编写 D2 之前构建规范化的数据库模型。
8. 在生成之前询问必答的关系图问卷。
9. 使用数据库模型生成 .d2 文件，而不是原始类嵌套。
10. 在交付前用 d2 fmt 验证 D2 语法。
11. 在可能时用 d2 --layout=elk schema.d2 schema.svg 渲染。
12. 如果要重新生成，先重新阅读 EF Core 映射和迁移。

生成关系图之前的必答问题

对每个新关系图和每次重新生成都询问这些问题，除非用户已在同一请求中回答过。

1. 应该为哪个 DbContext 绘制关系图？(auto-detect/all/specific name)
2. 显示列？(all/key-only/none)
3. 显示列类型？(Yes/No)
4. 显示可空/必填标记？(Yes/No)
5. 显示索引和唯一约束？(Yes/No)
6. 显示枚举值？(Yes/No)
7. 显示拥有的类型？(inline/separate/hide)
8. 显示多对多联接表？(explicit/compact/hide)
9. 显示审计/技术表？(Yes/No)
10. 显示仅存在于迁移中而不作为实体存在的表？(Yes/No)
11. 使用哪种分组模式？(bounded-context/schema/namespace/flat)
12. 使用哪种布局引擎？(elk/dagre/tala)
13. 使用哪种输出格式？(d2/svg/png)

当用户要求快速生成时的默认值：

• DbContext：auto-detect
• 列：key-only
• 列类型：Yes
• 可空标记：Yes
• 索引：Yes
• 枚举：No
• 拥有的类型：inline
• 联接表：explicit
• 审计/技术表：No
• 仅迁移表：Yes
• 分组：bounded-context
• 布局：elk
• 输出：d2

参考文档

在需要时按需加载这些文档：

参考	何时加载
references/efcore-model-extraction.md	读取 DbContext、DbSet、Fluent API、配置和迁移的规则
references/d2-erd-style.md	ERD 关系图的 D2 语法和视觉约定
references/relationship-rules.md	如何推断一对一、一对多、多对多和拥有的关系
references/grouping-modes.md	bounded-context、schema、namespace 和 flat 分组的规则
references/quality-gate.md	交付生成的关系图之前的最终检查清单

EF Core 提取规则

来源优先级

当来源不一致时，使用以下优先级顺序：

1. 最新应用的迁移 / 迁移快照。
2. OnModelCreating 或 IEntityTypeConfiguration<T> 中的 Fluent API 配置。
3. 数据注解。
4. EF Core 约定。
5. 原始 C# 类形态。

需要检测的 EF Core 核心概念

检测并表示：

• DbContext 和 DbSet<T>。
• 来自 ToTable 的实体类名和实际表名。
• 来自 ToTable("Table", "schema") 的架构名称。
• 来自 HasKey、[Key]、约定和迁移的主键。
• 复合键。
• 来自 HasForeignKey、导航属性和迁移操作的外键。
• 显式指定时的删除行为：Cascade、Restrict、NoAction、SetNull、ClientSetNull。
• 必需/可选关系标记。
• 来自 OwnsOne、OwnsMany 和 [Owned] 的拥有类型。
• 来自 UsingEntity 和隐式 EF Core 联接表的多对多关系。
• 来自 HasIndex、IsUnique 和迁移的索引。
• 来自 HasAlternateKey 的备用键。
• 在 Fluent API 中配置的影子属性。
• 影响持久化类型或可读性时的值转换。
• 枚举属性。
• 忽略的属性与忽略的实体。

图表渲染规则

表

在可能的情况下，将每个持久化表表示为一个带有 shape: sql_table 的 D2 节点。

使用以下内容约定：

Clients: {
  shape: sql_table
  constraint: primary_key
  Id: uuid {constraint: primary_key}
  Name: text
  Status: enum
}

如果 sql_table 不可用或导致验证问题，则回退为带有结构化文本的矩形。

关系

使用从依赖表指向主体表的有向边。

标签必须包含关系基数，并在已知时包含外键名称：

Offers.ClientId -> Clients.Id: "N:1 FK_Offers_Clients_ClientId"

使用以下基数标签：

• 1:1
• 1:N
• N:1
• N:N
• owned

拥有类型

拥有类型默认以内联方式渲染。

内联示例：

Clients: {
  shape: sql_table
  Id: uuid {constraint: primary_key}
  Address.Street: text
  Address.ZipCode: text
  Address.City: text
}

如果用户选择 separate，则将拥有类型表示为视觉上从属的表，并使用 owned 关系。

多对多

默认使用显式联接表，因为 EF Core 会创建真实表。

对于隐式多对多关系，创建一个生成的联接表节点，并将其标记为 implicit join。

技术表

除非有要求，否则默认隐藏技术表。

示例：

• __EFMigrationsHistory
• Hangfire 表
• ASP.NET Identity 表
• 审计日志
• Outbox 表

如果技术表被隐藏，请在图表后的摘要中提及它们。

分组模式

• bounded-context：按检测到的领域区域或文件夹/模块分组。
• schema：按数据库架构分组，例如 public、auth、billing。
• namespace：按 C# 命名空间分组。
• flat：不使用容器，所有表处于同一层级。

样式规则

使用一致的样式：

• 主实体表：实线边框。
• 联接表：虚线边框。
• 拥有类型：较浅的描边或嵌套内联字段。
• 技术表：弱化样式。
• 外部表或仅迁移表：点线边框。
• 必需关系：实线。
• 可选关系：虚线。
• 级联删除：标签后缀 cascade。

交付前的质量门禁

在交付图表之前，请验证：

• 所选 DbContext 清晰明确。
• 所有 DbSet<T> 实体均已考虑。
• Fluent API 配置已读取。
• 存在迁移时已检查迁移。
• 表名和架构名称与 EF Core 映射一致。
• 主键已存在。
• 外键和基数均已表示。
• 拥有类型已根据用户选择处理。
• 多对多联接表为显式，除非用户另有要求。
• 隐藏的技术表已在最终摘要中列出。
• D2 语法通过 d2 fmt 验证有效。
• 在容器内时，边端点使用完整点表示法。
• 图表保持可读，并避免交叉密集的布局。

输出格式

当用户要求安装 skill 时，提供以下文件夹结构：

.github/
  skills/
    efcore-d2-db-diagram/
      SKILL.md
      references/
        efcore-model-extraction.md
        d2-erd-style.md
        relationship-rules.md
        grouping-modes.md
        quality-gate.md

当用户要求生成图表时，提供：

1. .d2 源文件内容。
2. 使用所选布局引擎的渲染命令。
3. 对假设和隐藏表格的简要总结。