pma-d2

D2 图表编写者

生成符合 D2 惯例的 .d2 源文件——以声明式文本编码的图表，由官方 d2 CLI 渲染为 SVG / PNG / PDF / GIF。输出内容易于阅读、方便比较差异，可嵌入任何支持嵌入 D2 的位置（GitHub、Notion、VS Code、文档网站、Oxide 的 play.d2lang.com）。

保持此入口文件简短。只加载与当前图表匹配的参考资料包。

始终遵循的规则

1. 只输出 .d2 文本，不输出其他内容。 此技能绝不调用渲染器；用户会运行 d2 input.d2 out.svg 或打开 play.d2lang.com。质量必须能通过阅读源文件来评估。
2. 优先使用符合惯例的 D2，而非耍巧。 优先使用声明式节点名称（api -> db），而不是 ID + 标签，只要名称读起来自然即可。仅当自然名称显得别扭或重复时才使用 label:。
3. 形状类型应匹配概念。 数据库使用 shape: cylinder，队列使用 shape: queue，参与者使用 shape: person。绝不要默认所有内容都用 rectangle。完整目录见 references/shapes.md。
4. 预先声明方向。 在根级（必要时也在每个容器级）设置 direction: down | right | up | left。布局方向是表达选择，不是无关紧要的默认值。
5. 边的样式应表达语义，而非装饰。 异步 / 弱依赖使用 stroke-dash；数据流使用 animated: true；关键路径 / 故障路径用 stroke 颜色编码。目录见 references/connections.md。
6. 按容器分组，而非按距离分组。 如果节点属于同一领域（子系统、云、限界上下文），就在容器映射中嵌套它们。容器是 D2 原生的分组方式——使用容器，而不是手动放置。
7. 每张图表只表达一个概念。 如果一张图表要回答两个问题，就拆分为两个 layers: 或两个文件。不要硬塞在一起。
8. 重复样式使用类。 ≥ 2 个节点共享样式时，在 classes: {} 中定义一个类，并通过 .class: name 或 glob 应用。
9. 不要自创形状。 所有 shape: 值都必须来自 references/shapes.md。D2 遇到拼写错误时会静默回退为矩形，这是最糟糕的失败模式：看起来正确，实际上却不对。
10. 源文件应可直接提交。 文件以换行符结尾，使用 2 空格缩进，不留行尾空白；注释说明意图，而非机制。D2 适合使用 git 管理——保持这一特点。

核心工作流

第 1 步：选择图表类型

类型	D2 基元	适用场景
架构 / 流程	default（节点 + 连接）	系统、流水线、依赖关系图
时序	shape: sequence_diagram	协议交互、API 调用流程、时序
ERD / 架构	每张表使用 shape: sql_table	数据模型、外键
UML 类图	每个类使用 shape: class	面向对象设计、类型关系
网格 / 矩阵	grid-rows / grid-columns	表格布局、比较矩阵、k8s 集群视图
多画板	layers: / scenarios: / steps:	前后对比、逐层深入、动画

各类型的详情见 references/special-diagrams.md 和 references/composition.md。

第 2 步：选择布局引擎

• dagre（默认，免费，已捆绑）：面向有向无环图，适用于大多数架构图。
• elk（免费，自 v0.7 起已捆绑）：适合嵌套层级和正交路由，布局更整洁。多容器图表值得尝试。
• tala（付费，独立二进制文件）：处理复杂、密集图表的顶级选择。如果需要，请在文件头部注明，让用户知道需要安装什么。

每个文件通过 vars.d2-config.layout-engine 选择一次。不要用手动位置与布局引擎较劲——D2 没有 x,y。

第 3 步：起草结构

1. 先勾勒顶层容器：有哪些系统 / 领域。
2. 在每个容器内添加节点，并使用正确的 shape:。
3. 添加连接——先确定方向，拓扑正确后再加标签。
4. 使用 classes: 合并重复样式。
5. 在顶部添加 vars.d2-config 块（主题、布局引擎）。

第 4 步：样式检查

• 检查每条连接——其样式（实线／虚线／动画／颜色）在语义上是否与相邻连接有所区别？
• 检查每个节点——其 shape: 和类是否承载信息？
• 移除不表达含义的装饰（装饰性颜色、多余的阴影）。

第 5 步：验证并交付

运行 references/validation.md 中的预检查。告知用户：

• 输出路径（默认为 docs/architecture/<name>.d2）。
• 渲染命令：d2 <name>.d2 <name>.svg（或他们需要的其他目标格式）。
• 选用的布局引擎，以及是否需要单独安装。
• 所有通过 URL 引用的图标（以便他们在需要时镜像到内部）。

大型图表的分节编写

1. 编写 vars + direction 头部和一个容器。
2. 每次编辑追加一个容器；如果子 ID 可能冲突，就为其添加容器前缀。
3. 跨容器边使用点分路径（aws.api -> gcp.auth）；输出边之前先确认路径存在。
4. 当图表增长到约 60 个节点以上时，拆分到 layers: 或单独的 .d2 文件，并通过 @file 导入组合（references/composition.md）。

输出

• 文件：默认为 docs/architecture/<name>.d2，也可以使用用户指定的路径。
• 渲染（由用户运行）：
  • d2 name.d2 → name.svg（默认）
  • d2 name.d2 name.png / name.pdf / name.gif
  • d2 --watch name.d2 → 在 localhost 上实时预览
  • d2 --theme <id> --dark-theme <id> name.d2 → 主题配对
• 网页预览：粘贴到 https://play.d2lang.com/，无需安装 D2 即可即时渲染。
• 嵌入：请参阅 references/integration.md，了解 MDX、GitHub README（提交 SVG）、文档站点（构建时实时渲染）和 CI 流水线的相关信息。

参考资料包

• references/syntax.md 核心语法：标识符、标签、映射、注释、转义，以及 D2 中大量使用的简写规则。
• references/shapes.md 所有内置形状，包含外观描述、数据语义和“适用场景”指南。
• references/connections.md 边运算符（->、<-、<->、--）、链式连接、箭头、标签和语义样式模式。
• references/containers.md 嵌套、_ 父级引用、点分路径、容器与形状的区别，以及何时扁平化而非嵌套。
• references/classes.md classes: 块、通过 .class: 应用类、多类数组和基于 glob 的批量应用。
• references/styles.md 完整的样式键目录（fill、stroke、stroke-dash、shadow、3d、multiple、animated、fill-pattern、border-radius、font-size、bold/italic/underline、opacity）。
• references/layouts.md 方向、网格布局、dagre 与 elk、tala 的权衡，以及用于标题和图例定位的 near:。
• references/special-diagrams.md 时序图（参与者、跨度、注释、分组）、sql_table ERD、class UML、Markdown／代码／LaTeX 块。
• references/composition.md layers:（隔离画布）、scenarios:（继承 + 覆盖）、steps:（动画）、@file 导入、...@file 展开。
• references/vars.md vars: 块、${var} 替换、d2-config（theme-id、dark-theme-id、sketch、pad、center、layout-engine），用于设计令牌的嵌套变量。
• references/templates.md 可复制粘贴的起始文件：三层 Web、微服务、数据流水线、CI/CD、时序图（OAuth）、ERD、k8s 集群（网格）。
• references/design.md 概念→模式映射、同构测试、D2 优于 ReactFlow / Mermaid / Excalidraw 的场景，以及不如它们的场景。
• references/validation.md 预检查算法和清单；常见的 D2 错误（形状静默回退、缺少容器路径、标签与注释冲突）。
• references/render.md CLI 标志、监视模式、Playground、图标目录（terrastruct icons、svgrepo）、主题图库。
• references/integration.md MDX / Docusaurus / Nextra 嵌入、通过已提交的 SVG 在 GitHub README 中展示、文档站点构建流水线、提交前渲染。

快速路由

• 初次接触 D2 语法：加载 syntax.md + shapes.md + connections.md。
• 架构图 / 系统图：shapes.md + containers.md + layouts.md + templates.md。
• 序列图 / SQL / UML：special-diagrams.md + templates.md。
• 样式调整：classes.md + styles.md。
• 多画板故事（前后对比、逐层深入、动画）：composition.md。
• 主题 / 配置：vars.md + render.md。
• 交付前：validation.md。
• 告知用户如何渲染或嵌入：render.md + integration.md。

如果项目还使用 /pma 控制工作流，请先加载 /pma，仅在需要图表时再加载 /pma-d2。如果项目需要带有自定义 React 节点组件、可在浏览器中交互的图表，请改用 /pma-draw——D2 会渲染为静态图像。