diagram-generator

diagram-generator 技能概览

diagram-generator 的作用

diagram-generator 技能可以帮你从结构化输入出发，在 drawio、Mermaid 和 Excalidraw 中创建和编辑图，而不是靠手工一个节点一个节点地搭建。它特别适合那些希望 diagram-generator 技能把粗略的架构、流程或拓扑想法，转成可直接使用的图文件，同时尽量减少反复试错的人。

最适合的场景与真实任务

如果你的目标是产出适合文档使用的系统图、流程图或网络图，并且同时在意生成速度和后续可编辑性，就该用 diagram-generator。它最适合技术用户：既要干净的输出、能纳入版本控制，又希望后续可以在 GUI 里继续调整，或者在需求更新后重新生成。

你需要知道的核心差异

diagram-generator 的主要价值在于它支持多种格式，并且能够读取现有的 .drawio、.mmd 和 Excalidraw 文件。如果你要更新的是遗留图，而不是从头开始画，这一点非常关键。它还依赖 MCP server，这会减少大量 token 消耗的手工排版工作，也让输出比通用 prompt 更稳定、更一致。

什么时候它不是合适工具

如果你只需要快速草图，而且并不打算以后保存或继续编辑文件，那么普通 prompt 可能就够了。只有当格式正确性、可重复性以及后续编辑的价值，明显高于一张“差不多看得懂”的草图时，diagram-generator 才更有用。

如何使用 diagram-generator 技能

安装并验证 MCP 依赖

在执行 diagram-generator install 时，先把技能加进去，并确认配套 server 可用后再请求输出。这个技能依赖 mcp-diagram-generator；如果 server 缺失，生成要么会失败，要么结果不完整。请先检查该 server 暴露的工具，只有在环境准备好之后再使用这个技能。

从正确的输入形状开始

最好的 diagram-generator usage 是一段简洁的 brief，明确说明图的类型、目标格式、受众，以及必须包含的实体。例如：“为登录流程创建一个 Mermaid sequence diagram：browser、auth service、database，包含成功和失败路径。”这比“做一个登录图”要好得多，因为前者给了技能足够的结构信息去决定布局、标签和范围。

先阅读这些文件

如果你想要一份实用的 diagram-generator guide，先读 SKILL.md，再查看 references/json-schema-guide.md 了解输入结构，以及 references/format-selection-guide.md 来决定在 draw.io、Mermaid 和 Excalidraw 之间怎么选。如果你要做网络图，references/network-topology-examples.md 是最快了解预期嵌套方式和命名模式的方法。

能产出更好结果的工作流

建议按这个顺序来：先选格式，写一份简短规范，先生成一次，然后只修正有问题的部分。保持节点命名稳定，明确说明层级关系，并指出图应更偏向可读性、紧凑性还是手动可编辑性。比如，不要让布局决策隐含不说，而应直接要求：“为分层基础设施图输出 draw.io，层级为 environment > datacenter > zone > device，优化为后续在 GUI 中编辑。”

diagram-generator 技能 FAQ

diagram-generator 比普通 prompt 更好吗？

当你需要结构化文件、可重复的格式化结果，或者要修改现有图时，答案是肯定的。普通 prompt 也能描述图，但当你想要的是支持格式中的真实输出工件，而不是一张近似图片时，diagram-generator 更强。

我该选哪种格式？

如果你要的是快速、适合 markdown、方便版本控制的图，选 Mermaid。若是复杂的架构或拓扑工作，而且后续需要人工精修，选 draw.io。若你想要更松弛的视觉风格，或者只是轻量草图，选 Excalidraw。只有当格式选择与任务匹配时，diagram-generator 技能的价值才最大，而不是事后再靠猜。

新手能用 diagram-generator 吗？

可以，但新手如果能提供一点点结构，效果会更好：图的用途、实体、关系，以及偏好的格式。这个技能并不难用，只是如果输入太模糊，产出的图通常还需要第二轮修改。

什么时候应该避免使用它？

如果你的图偏艺术化、需要品牌插画工作，或者依赖超出技术制图范围的高度定制视觉设计，就不适合用 diagram-generator。如果你的环境里无法安装或访问所需的 MCP server，也应该避免使用。

如何改进 diagram-generator 技能

给它它无法自行推断的决策

提升质量最明显的方法，是明确指定格式、受众和细节深度。你要说清楚重点应该放在什么上：依赖关系、流程方向、职责边界、环境层级，还是失败路径。对于 diagram-generator 来说，这些选择往往比原始组件列表更重要。

减少实体和关系中的歧义

常见失败模式包括命名模糊、箭头缺失，以及把不同抽象层级混在一起。不要只说“展示系统”，而是给出明确边界的清单，比如“API gateway、auth service、billing service、Postgres、Redis”，并说明它们如何连接。如果你要的是网络图，请把层级关系直接定义出来，这样技能就不会自己猜 container 的层次。

一次只迭代一个修正点

拿到第一版输出后，只提出一个聚焦的修改：重命名节点、简化布局、切换格式，或者补上一条缺失关系。这样既能避免 diagram-generator 技能跑偏，又能继续改善最终文件。如果结构错了，先修结构；如果标签错了，下一步再修标签。

利用仓库参考来打磨后续提示词

如果第一次结果已经接近目标，但还不理想，就把问题对应回 references/json-schema-guide.md 或 references/format-selection-guide.md，然后调整输入，让它更符合预期模型。提升 diagram-generator usage 最快的方法，是搞清楚哪些约束应该写进 prompt，哪些应该放在图的 schema 里。