D2 图表
编写 D2 源码,将其渲染为 SVG,然后查看渲染结果并修复你所看到的 —— 如此循环,直到图表值得交付。一个你没见过的图表,是一个你还没完成的图表。
参考文件 —— 按需加载
| 文件 | 何时阅读 |
|---|---|
references/d2-language.md | 编写任何非琐碎的 D2 内容时 —— 语法、形状、容器、类、变量,以及那些编译通过但渲染错误的无声陷阱 |
references/layout-engines.md | 选择或调试布局时:TALA vs ELK vs dagre,许可证,随机种子,各引擎行为差异 |
references/diagram-patterns.md | 选择图表类型和结构时 —— 架构图、时序图、ERD、网格、C4;主题、图标、暗黑模式、GitHub 嵌入 |
第 0 步 —— 工具链检查
在首次渲染前,每个会话运行一次(此处的 scripts/ 指的是本技能自己的目录 —— 在 Claude Code 中 ${CLAUDE_SKILL_DIR} 会解析为该目录):
bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh" --check-only
d2: ok→ 继续。d2: MISSING→ 告知用户,然后运行scripts/setup.sh(不带任何标志)以通过 Homebrew(若可用)进行安装,或向用户展示打印出的安装命令。不要盲目渲染 —— 没有 d2,本技能中的其他一切都无法工作。tala: not installed或unlicensed→ 没关系。ELK 是自动回退方案,并能生成良好的布局。仅当图表是软件架构图(此时 TALA 明显更优)并且用户对输出质量要求较高时,才提及 TALA 一次;切勿唠叨。
第 1 步 —— 先规划再编写
首先决定三件事:
- 核心信息。 读者在五秒内应得出什么结论?图表是有所论证的 —— “请求在此扇出”、“此服务是瓶颈”、“这两条路径永不相交”。如果你无法陈述论点,那你即将画出的只是一堆带标签的盒子。
- 类型。 架构/拓扑 → 使用简单的形状和容器。随时间变化的交互 →
sequence_diagram。数据模型 →sql_table。严格对齐(矩阵、仪表盘、多图例)→ 使用网格。每种类型的结构指导请参见references/diagram-patterns.md。 - 规模。 5–15 个节点可读性好;15–25 个需要容器来聚类;超过约 25 个,则拆分为多个图表或使用
layers。宁愿画第二张图,也不要画一幅“壁画”。
对于真实系统的技术图表,请使用真实名称 —— 来自用户代码库或描述的实际服务名、实际表名、实际事件名。如果代码可用,请 grep 搜索。服务 A -> 服务 B 会浪费读者的信任。
第 2 步 —— 编写 D2
在编写任何非琐碎图表之前,请阅读 references/d2-language.md。这些规则可预防 90% 的错误输出:
- 连接键(keys),而非标签。 在
api: API Gateway之后,写api -> db,永远不要写API Gateway -> db—— 后者会静默地创建一个重复的形状。 - 对包含
#或;的标签加引号 —— 未加引号的#会在标签中间开始一条注释,而未加引号的;会将行拆分为两个形状,两者都会编译成功且无错误。对任何带标点的标签加引号是安全的习惯。 - 通过
classes:进行样式设置,而不是逐节点样式 —— 一次定义,通过class:应用。避免在单个节点上使用style.fill;硬编码的填充色会与主题冲突,并破坏暗黑模式的渲染。 - 为大多数架构流程设置
direction: right(从左到右阅读很自然)。所有引擎都尊重根级别的direction;TALA 还额外支持每个容器的direction。 - 将源文件保存为
{name}.d2,放在输出文件旁边(项目中默认为./diagrams/)。
第 3 步 —— 渲染
始终通过捆绑的脚本进行渲染 —— 它会选择布局引擎,防止带水印的输出,并首先进行验证:
bash "${CLAUDE_SKILL_DIR}/scripts/render.sh" --png input.d2 output.svg
--png还会写入output.png—— 在第 4 步中你需要它(Read 工具查看的是栅格图像,而非 SVG)。- 该脚本会打印
engine:(实际使用的引擎)和fallback:(如果未使用 TALA,说明原因)。仅当用户询问引擎或明确要求使用 TALA 时,才向用户转告一行备注。 - 有用的标志:
--theme N,--dark-theme 200(SVG 响应读者的配色方案),--sketch,--pad N,--seed N(TALA 重排),--engine tala|elk|dagre(强制引擎),--allow-watermark(TALA 评估模式)。 - 失败时,脚本会打印带有
文件:行号:列号的 d2 编译错误 —— 在该位置修复源码后重新运行。如果错误不明确,请查看references/d2-language.md中的陷阱部分。
除非用户明确接受,否则切勿渲染带水印的 TALA 输出用于交付;此脚本通过回退到 ELK 来强制执行此规则。
第 4 步 —— 查看,然后修复(不可省略)
.d2 源码并不能说明渲染实际效果如何 —— 布局是引擎的决定,而不是你的。使用 Read 工具打开 PNG 并进行两轮审核:
第一轮 —— 它是否传达了论点?
- 视线是否从故事开始之处进入,并从结束之处离开?
- 流向是否一致(没有意外地折返或自下而上阅读)?
- 容器分组是否与你规划的邏輯分组相匹配?
- 最重要的元素在视觉上是否突出,还是被埋没了?
第二轮 —— 布局缺陷(自动布局引擎会产生所有这些缺陷):
- 边缘标签远离其所属的边缘,或者对描述哪个边缘造成歧义
- 边缘在并行运行时重叠、穿过节点或容器,或者采用荒谬的绕行路线
- 文本被截断或与形状/图标碰撞
- 一个区域拥挤而另一个区域空旷;容器远大于其内容
- 节点过小以致标签占据主导,或节点大小极不一致
- 任何如果你向用户展示时需要道歉解释的东西
使用 D2 的杠杆进行修复,而非手动定位像素(自动布局意味着你改变输入,而非坐标):更改 direction;使用容器进行分组或重新分组;缩短边缘标签(长标签在 ELK 上漂移最严重);将平行边缘合并为一个带标签的边缘;使用 near 将图例/标题移出流程;将过载的图表拆分为 layers;调整 --pad;在 TALA 下,使用 --seed N 重新排列(尝试 2–3 个种子 —— 布局会有显著变化);作为最后手段,为此图表的形状切换引擎(参见 references/layout-engines.md)。
重新渲染,重新查看,重复进行。预计需要两到四个渲染周期 —— 首次渲染就能通过两轮审核的情况很少见。完成意味着:两轮审核均无问题,并且图像中没有任何东西需要道歉或解释。
第 5 步 —— 交付
- 确认最终的
.svg(和.d2源码)路径 —— 始终将两者都提供给用户;.d2是可编辑的制品。 - 如果图表将被放入 GitHub README 或文档站点,请提供一个支持暗黑模式的变体:使用
--dark-theme 200重新渲染(单个 SVG 会跟随读者的配色方案)。PNG/<picture>嵌入的模式在references/diagram-patterns.md中。 - 如果用户将自行迭代图表,请提及
d2 --watch input.d2以在浏览器中提供实时预览。
故障排除
| 症状 | 原因 / 修复 |
|---|---|
d2: command not found | 运行 scripts/setup.sh(引导安装) |
D2_LAYOUT "tala" is not bundled | TALA 不在 PATH 中 —— 脚本自动回退到 ELK;仅当用户需要时才安装 TALA |
输出中出现 UNLICENSED 文本 | TALA 未获得许可 —— 渲染脚本会自动使用 ELK 重新渲染;许可证密钥放入 TSTRUCT_TOKEN 或 ~/.config/tstruct/auth.json |
| PNG 导出失败,SVG 正常 | 首次 PNG 渲染会下载无头浏览器;请重试一次。如果被阻止(脱机/CI),请交付 SVG 并通过任何可用的 SVG 栅格化工具转换来检查 |
在 --layout tala 下出现编译错误,但 ELK 渲染正常 | d2/TALA 版本不匹配 —— 脚本自动回退;建议更新两者 |
| 输出中缺少图标 | 图标 URL 返回 403/404 —— 移除该图标或从 icons.terrastruct.com 选择另一个;尽早测试图标 |