graphviz

graphviz 技能概览

graphviz 的用途

graphviz 是一种基于 DOT 的制图技能，用于把结构化关系自动排版成图。它最适合需要让图表随着规模增长仍保持可读的场景：依赖树、调用图、包层级、所有权关系图，以及其他使用 graphviz 进行 Diagramming 的场景，在这些场景里，手动摆放节点很快就会成为瓶颈。

适合谁使用

如果你脑子里已经有关系结构，或者手里有文字描述，希望模型快速生成合法 DOT，那么就该用 graphviz 技能。它非常适合开发者、技术写作者、架构师，以及需要一份 graphviz 指南来把粗略结构转换成可渲染语法的 agent。

它的不同之处

它的核心价值是语法可靠性，而不只是“画图”。这个技能强调 Graphviz 特有的约束，比如 digraph 和 graph 的区别、-> 和 -- 的区别、cluster 命名规则，以及包含空格的 ID 需要加引号。之所以重要，是因为大多数失败不是设计失败，而是渲染失败。

什么时候 graphviz 不合适

不要把 graphviz 用在仪表盘风格图表、基于图标的网络拓扑，或者需要强视觉品牌表达的演示型图形上。如果你需要的是表格图表或数据图，换别的工具会更合适。如果你需要的是带自动布局和明确边关系的层级结构，graphviz 通常是更好的选择。

如何使用 graphviz 技能

安装并检查正确的文件

先把 graphviz 技能安装到你的 skills 目录，然后在开始起草图之前，先阅读技能主体和语法参考。这个 repo 里最有用的文件路径是 SKILL.md 和 references/syntax.md；它们是最快弄清 graphviz 实际安装预期，以及哪些语法在实践中最容易出错的方式。

把模糊目标转成可直接写 DOT 的输入

像“帮我画一张架构图”这样的弱请求还不够。更强的请求应该包含图类型、节点、边的方向，以及任何布局约束。例如：“创建一个 digraph，展示 frontend、API gateway、services 和 database。使用自上而下的流向，把 services 分组成 cluster，给 gateway 到 service 的边加标签，并且只有在需要时才给节点名加引号。”

从最小图开始

先构建最小可用图：选择 digraph 或 graph，定义核心节点，用正确的边操作符连接它们，然后等结构能正确渲染之后再加属性。这样可以避开最常见的 graphviz 使用问题：一边给坏掉的图做样式。

在增加复杂度前先读语法规则

在加入 cluster、record 节点或边标签之前，先查看语法参考，确认 node ID、cluster 名称、edge 属性和布局控制项的规则。Graphviz 的错误往往只由一个非法 token 引发，所以快速过一遍语法规则，通常比反复试错更省时间。

graphviz 技能 FAQ

graphviz 比通用提示词更好吗？

如果输出必须是合法 DOT，而且还要稳定渲染，那么答案是肯定的。通用提示词可能能把图意描述清楚，却仍然会漏掉 graphviz 的语法细节。对于更在意安装后可用性和正确性，而不只是大致说明的用户来说，graphviz 技能更合适。

哪类图最适合？

它最适合层级型或关系密集型图：依赖树、调用流程、包关系图、决策树和所有权结构图。如果你需要自动布局，并且边关系必须清楚表达方向，graphviz 是很强的选择。

初学者需要先懂 DOT 吗？

不需要，但必须有明确目标。初学者通常只要说明实体、实体之间的关系，以及图应该是有向还是无向，就能做成。这个技能可以处理语法，但它无法从模糊请求中推断你的领域模型。

什么时候不该用 graphviz？

如果图形依赖像素级精确摆放、视觉图标，或者更接近图表式展示，就不要用它。若你的需求本质上是数据可视化而不是关系映射，也应该避免使用。即使 graphviz 技术上能生成一张图片，这些情况下它也不是合适的工具。

如何改进 graphviz 技能

先把图的结构给对

提升 graphviz 结果的最好方式，是先提供一份清晰的节点和边清单。明确核心对象、哪些对象应归为一组，以及关系是单向还是双向。这样可以减少歧义，并提升第一次渲染的成功率。

指定真正重要的布局约束

如果你的图必须自上而下、从左到右，或者按子系统分组，请明确说出来。说明 cluster 边界、跨 cluster 的边是否应尽量减少，以及是否有节点需要保持在视觉中心。对大多数 graphviz 使用场景来说，这些细节比样式偏好更重要。

避开常见语法坑

最常见的失败包括：图类型和边语法不匹配、带空格的 node ID 没有加引号，以及 cluster 名称没有以 cluster_ 开头。如果第一次输出有问题，先检查这些，再考虑让它重设计。很多 graphviz 安装问题，本质上其实是语法问题。

一次只要求改一处

如果第一次输出在结构上正确，但视觉效果一般，就一次只迭代一个维度：标签、cluster 边界、边标签，或 rank 方向。这样比笼统地说“让它更好看”更容易得到干净结果，也能帮助模型保留它已经生成的合法 DOT。