Communitygithub.com

khollingworth/d2-diagram-skill

Claude Code 插件,用于渲染专业的 D2 架构图(TALA/ELK),并配备自检渲染循环。

d2-diagram-skill 是什么?

此技能将 Claude Code 变为一个能够自主绘制、检查并优化 D2 架构图的 AI 代理。它遵循一种独特的“渲染——审查——修复”循环:AI 首先根据系统描述撰写 D2 代码,然后将其渲染为 SVG/PNG,接着通过读取图片进行自检,识别布局问题(如重叠、裁剪或错误流向),最后调整 D2 源代码并重新渲染,直至图表达到可交付质量。此技能支持三种布局引擎(TALA、ELK、dagre),并能自动处理许可证检查与回退。该过程通过参考文件(D2 语法、布局引擎选择、图表模式)提供引导,并包含用于工具链验证和渲染的脚本,非常适合在 Cursor、Codex 或 Claude Code 中创建系统架构、序列图或数据模型。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add khollingworth/d2-diagram-skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 步 —— 先规划再编写

首先决定三件事:

  1. 核心信息。 读者在五秒内应得出什么结论?图表是有所论证的 —— “请求在此扇出”、“此服务是瓶颈”、“这两条路径永不相交”。如果你无法陈述论点,那你即将画出的只是一堆带标签的盒子。
  2. 类型。 架构/拓扑 → 使用简单的形状和容器。随时间变化的交互 → sequence_diagram。数据模型 → sql_table。严格对齐(矩阵、仪表盘、多图例)→ 使用网格。每种类型的结构指导请参见 references/diagram-patterns.md。
  3. 规模。 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 bundledTALA 不在 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 选择另一个;尽早测试图标

相关技能