figma-generate-diagram

generate-diagram

每次调用 generate_diagram 工具前，必须先加载此技能。 跳过此步骤会导致本可避免的渲染失败和低质量输出。

generate_diagram 接受 Mermaid.js 语法，并生成可编辑的 FigJam 图表。此技能会引导你查阅正确的图表类型指南，并设定通用约束。

第 1 步：generate_diagram 是合适的工具吗？

支持的图表类型

flowchart、sequenceDiagram、stateDiagram / stateDiagram-v2、gantt、erDiagram。

不支持 — 请勿调用此工具

如果用户需要以下任何一种图表，请直接告知他们 generate_diagram 不支持，而不要调用工具后再失败：

• 饼图、思维导图、维恩图、类图、用户旅程图、时间线、象限图、C4 图、Git 图、需求图

何时建议用户在 Figma 中编辑

此工具无法：

• 更改现有图表中的字体
• 移动单个形状
• 在生成后逐个编辑图表节点

如果用户要求对现有图表进行上述任一操作，建议他们在 Figma 中打开图表并在那里编辑。对于内容层面的更改，重新生成通常更快。

第 2 步：选择图表类型

快速路由 — 使用第一个匹配项。

用户需要…	类型	下一步
服务 + 数据存储 + 队列 + 集成	架构流程图	阅读 references/architecture.md
决策树、流程、流水线、依赖关系图、用户旅程	流程图	阅读 references/flowchart.md
各方随时间发生的交互（API 调用、身份验证、消息传递）	时序图	阅读 references/sequence.md
数据模型、表、键、基数	ER 图	阅读 references/erd.md
带有相互转换关系的命名状态	状态图	阅读 references/state.md
带有日期和里程碑的项目计划	甘特图	阅读 references/gantt.md

如果用户请求流程图，而其描述的是软件基础设施（服务、数据存储、队列、外部集成），请转到 architecture.md，而不是 flowchart.md。如有疑问，请询问用户。

第 3 步：通用约束（适用于所有图表类型）

1. Mermaid 源码的任何部分都不得包含表情符号。 工具会拒绝它们。
2. 标签中不得使用 \n。仅在绝对必要时使用换行，并且只能通过实际换行实现（不能使用转义序列）。
3. 标签中不得使用 HTML 标签。
4. 保留字 — 不要将 end、subgraph、graph 用作节点 ID。
5. 节点 ID：使用驼峰命名法（userService），不得包含空格。下划线可能会导致某些处理器中的边路由出错。
6. 标签中的特殊字符必须用引号括起来：A["Process (main)"]、-->|"O(1) lookup"|。
7. 时序图 — Mermaid 的 Note over X / Note left of X / Note right of X 会被渲染器静默移除；不要将它们放入源码。如果用户想为时序图添加注释，先生成基础图表，再通过混合工作流添加便签／文本（references/workflow.md）。
8. 甘特图 — classDef、class 及其他样式设置都会在预处理中被移除；渲染后的图表不会带有颜色。如果用户想为阶段、里程碑或任务添加颜色标记，先生成基础图表，再通过混合工作流添加颜色／注释（references/workflow.md）——或者，对于本质上需要样式的图表，直接使用 use_figma 构建时间线（参见 references/gantt.md §11）。
9. 在任何 use_figma 扩展中仅使用 FigJam API。 generate_diagram 的输出会放入 FigJam 文件（figma.com/board/...），因此混合扩展必须使用 FigJam 支持的 API。不要调用 figma.createPage()——它仅适用于 Design（figma.com/design/...），在 FigJam 中会抛出 TypeError: figma.createPage no such property 'createPage' on the figma global object。请改用 FigJam 分区来整理内容（参见 figma-use-figjam）。

第 4 步：垃圾进，垃圾出

生成图表的质量受你编写的 Mermaid 质量所限，而 Mermaid 的质量又受你掌握的上下文所限。编写 Mermaid 之前，请确保你有足够的真实信息来准确描述主题，并利用当前环境提供的任何资源收集信息。

根据可用资源，有用的上下文来源包括：

• 源代码 — grep／读取相关文件，让图表反映真实的服务名称、边标签、数据存储和入口点。查看实际路由／处理程序／消费者，胜过凭记忆重建。
• 用户提供的文档 — PRD、规格说明、会议记录、文字稿、研究综述、入职文档、流程说明。如果主题不是代码，请让用户粘贴或附上相关文档。
• 现有 Figma 或 FigJam 文件 — 如果新图表应与用户已有图表保持一致，请使用 get_figjam 或 get_design_context 读取文件（参见 figma-use 和 figma-use-figjam 技能）。
• 其他可用的 MCP 服务或工具 — 问题跟踪器、文档站点、CRM、分析工具、内部维基、设计系统、数据库架构等。如果某个已连接的工具包含与你要绘制的内容相关的准确信息，请从中获取，而不是猜测。
• 用户本人 — 当描述过于简略或含糊时（流程方向不明确、范围不清楚、不确定哪些实体重要），生成图表前先提出一两个有针对性的问题。例如：“主要步骤有哪些？请列出 3–5 个。”“每个步骤由谁负责？”“什么会触发下一步？”问一个好问题，胜过浪费时间生成一张无用的图表。

不要为了让图表“更完整”而编造边、标签或实体。信息缺失总比凭空捏造好——留出缺口，并告知用户。

步骤 5：图表是否需要表达 Mermaid 无法表达的内容？

Mermaid 无法做到面面俱到。与特定节点关联的便签注释、ERD 中逐节点的领域着色、附带数据的标注——这些都需要将 generate_diagram 与 use_figma 结合使用（通过 figma-use-figjam 技能）。这就是混合工作流。

这需要酌情判断，而非默认采用。仅当用户的需求明显能从中受益时才使用；如果基础图表显然已经足够，就跳过。表明适合采用的信号：用户明确要求添加笔记、颜色、标注或“为每个节点附加 X”；用户提供了可映射到特定节点的数据；图表是可分享的成品，而非用于梳理思路的草图。表明不适合采用的信号：请求简短或不言自明、图表规模较小、用户只是在探索或测试。

如果适合采用混合工作流，请在调用 generate_diagram 前阅读 references/workflow.md——其中介绍了工作模式、两种核心方案（注释 + 色彩编码）、沟通方式和故障处理。如果不适合，请直接进入步骤 6。

步骤 6：调用工具

必填项：

• name：描述性标题（会显示给用户）
• mermaidSyntax：Mermaid 源码

可选项：

• userIntent：用一句简短的话描述用户想要完成的目标——有助于遥测和下游调优
• useArchitectureLayoutCode：仅用于架构图；取值见 references/architecture.md
• fileKey：如果用户希望将图表添加到现有 FigJam 文件，而不是新建文件

不要在调用 generate_diagram 前调用 create_new_file——该工具会自行创建文件。

步骤 7：生成后

• 工具会返回一个链接（或小组件），用户可点击以在 FigJam 中打开图表。如果客户端不会内联渲染小组件，请将其显示为 Markdown 链接。
• 如果适合扩展（见步骤 5），现在使用 use_figma 组合操作——模式和方案见 references/workflow.md。
• 如果用户对同一张图表尝试 2 次后仍不满意，请停止重新生成。询问具体哪里不对，或建议用户在 Figma 中打开并手动编辑，而不是继续消耗工具调用。

迭代或添加相关图表时复用同一文件

每次调用不带 fileKey 的 generate_diagram，都会在用户的草稿中创建一个新的 FigJam 文件。重新生成 4 次 = 需要清理 4 个草稿文件。以下情况优先复用现有文件：

• 用户正在迭代同一张图表（“再试试……”，“修改标签……”）。
• 用户希望添加与第一张图表并列的后续图表（例如，在同一系统的流程图旁添加一张时序图）。

复用方法：

1. 后续调用 generate_diagram 时传入 fileKey。从 figma.com/board/{fileKey}/... URL 中提取。图表会添加到现有文件中，而不是创建新文件。
2. 如果想替换之前的图表，而非在旁边添加新图表，请使用 use_figma 工具（见 figma-use-figjam 技能）先删除旧图表的节点，然后使用相同的 fileKey 调用 generate_diagram。或者保留旧图表，将新图表放在旁边——读者通常也能从尝试过程的记录中受益。

第一次迭代时，询问用户更喜欢哪种方式——“覆盖旧图表，还是并排保留两张？”——并在本次会话后续迭代中记住他们的选择。