moai-library-mermaid

快速参考

Mermaid Diagram Expert v7.1.0 - 为 Claude Code 提供基于纯技能的 Mermaid 渲染，并集成 MCP Playwright。

此技能提供完整的 Mermaid 11.12.2 语法，涵盖全部 21 种图表类型；集成 MCP Playwright，用于渲染 SVG 和 PNG 输出；提供可直接使用的示例和参考文档，以及遵循最佳实践的企业级图表模式。

如需调用此技能，请使用标准的技能调用模式，并指定技能名称 moai-library-mermaid。

支持的图表类型

此技能支持 21 种图表类型，分为五类：

结构图包括用于流程和决策树的 Flowchart、用于交互序列和消息流的 Sequence、用于面向对象类关系的 Class、用于实体关系数据库的 ER、用于方框图结构的 Block，以及用于状态机和有状态流程的 State。

时间线与跟踪图包括用于按时间顺序展示事件和里程碑的 Timeline、用于项目排期和时间线的 Gantt，以及用于可视化 Git 工作流和分支的 Gitgraph。

架构与设计图包括用于 Context、Container、Component 和 Code 架构图的 C4、用于系统架构图的 Architecture，以及用于需求和可追溯性文档的 Requirement。

数据可视化图包括用于饼图和圆环图的 Pie Chart、用于散点图和折线图的 XY Chart、用于按比例调整宽度的流程图的 Sankey，以及用于多变量比较图表的 Radar。

用户与流程图包括用于层级思维导图的 Mindmap、用于用户体验流程的 User Journey、用于可视化看板状态的 Kanban，以及用于网络数据包结构的 Packet。

MCP Playwright 集成

此技能集成 MCP Playwright 以渲染图表。项目 mcp.json 文件中的 MCP 配置可启用 Playwright 服务，并可配置为使用 npx 和 anthropic-ai playwright-mcp 包。

如需渲染图表，必须在项目 MCP 设置中配置 MCP Playwright 服务，系统必须安装 Node.js，并且必须通过 npx 提供 Playwright。

---

实施指南

图表语法模式

流程图使用 flowchart 关键字，后接方向指示符，例如 TD 表示从上到下，LR 表示从左到右。节点通过括号定义形状：圆括号会创建圆角矩形，方括号会创建标准矩形，花括号会创建菱形决策节点，双层方括号会创建体育场形节点。连接使用带双连字符和尖括号的箭头语法，还可使用以竖线分隔的标签来描述边。子图使用 subgraph 关键字、标题和结束分隔符来对相关节点进行分组。

时序图首先使用 participant 关键字定义参与者，然后使用箭头表示交互。带双尖括号的实线箭头表示同步调用，而虚线箭头表示响应或异步消息。使用 activate 和 deactivate 关键字，或在箭头上使用加号和减号简写，可以通过激活矩形显示参与者的活动时长。可以在参与者的右侧、左侧或上方添加注释。

C4 上下文图使用 C4Context 关键字，并使用 Enterprise_Boundary 或 System_Boundary 函数定义系统边界。使用 Person 函数定义人员，该函数接收一个 ID、姓名和可选的描述。使用 System 定义内部系统，使用 System_Ext 定义外部系统。关系使用 Rel 函数指定源、目标、描述和可选的技术。

类图使用 classDiagram 关键字，并通过类及其属性和方法进行定义。关系包括使用尖括号和竖线符号表示继承、使用星号表示组合、使用圆圈表示聚合，以及使用连字符表示关联。可见性修饰符使用加号表示公开，减号表示私有，井号表示受保护。

状态图使用 stateDiagram-v2 关键字表示较新的语法。状态使用 state 关键字和方括号定义。转换使用箭头表示，并可附带标签。复合状态在状态块内包含嵌套状态。

图表类别

流程与流转图包括 Flowchart、Sequence、State、Timeline、Gitgraph 和 User Journey 图表类型。这些图表表示动态过程和时间序列。

结构与设计图包括 Class、ER、Block、Architecture 和 C4 类型。这些图表表示静态结构和系统组成。

数据与分析图包括 Pie Chart、XY Chart、Sankey 和 Radar 类型。这些图表用于可视化定量数据和比较指标。

规划与组织图包括 Gantt、Mindmap、Kanban 和 Requirement 类型。这些图表用于项目管理和需求跟踪。

网络与技术图目前包括 Packet 类型，其他类型则预留给未来扩展。

最佳实践

清晰度和可读性指南建议为所有节点使用描述性标签，将图表复杂度控制在适中水平，节点数量最多为 20 到 30 个，并在整个图表中使用一致的样式和配色方案。

性能方面的考量包括将复杂图表拆分为多个较小的图表，使用子图组织大型流程图，并限制节点内的文本长度以保持渲染性能。

无障碍要求包括为所有图表提供文本替代内容，使用颜色和形状共同区分而非仅依靠颜色，并添加描述性标题和图例以提供上下文。

组织实践建议将相关图表归入目录，使用一致的图表文件命名规范，并在源文件注释中说明图表用途。

---

高级模式

与 MoAI-ADK 集成

此技能旨在 Claude Code 的各个开发阶段中使用：

在架构阶段，使用 moai:1-plan 命令创建系统设计图，以可视化拟议的解决方案和组件关系。

在文档阶段，使用 moai:3-sync 命令生成可视化文档，包括流程图、时序图和架构概览。

在代码审查阶段，使用图表直观地传达系统设计，并突出需要关注或拟议变更的区域。

在入职培训过程中，创建图表，帮助新团队成员了解架构、数据流和系统边界。

常见架构模式

API 架构模式通常使用 C4 图展示系统上下文，包括 API 网关、后端服务、数据库层和缓存层之间的关系。

微服务流程模式使用时序图，展示客户端请求如何经过 API 网关流向各个服务及其数据存储。

数据管道模式使用流程图展示数据经过提取、转换、加载、验证和报告各阶段的流转过程。

Context7 集成

如需最新的 Mermaid 文档，请使用 Context7 库解析和文档工具。截至 2025 年 12 月，当前稳定版本为 Mermaid 11.12.2。

常规文档请参阅 mermaid.js.org/intro，API 参考请参阅 mermaid.js.org/config/setup/modules/mermaidAPI.html。

发行说明和迁移指南可在 Mermaid GitHub 仓库的 releases 部分查看。

学习资源

Mermaid 官方网站位于 mermaid.js.org。可在 mermaid.live 使用交互式实时编辑器测试图表。完整语法指南位于 mermaid.js.org/syntax/。

如需查看全部 21 种图表类型的实用示例，请参阅此技能目录中的 examples.md 文件。如需扩展参考文档，请参阅 reference.md。如需了解优化技巧，请参阅 optimization.md。如需了解复杂图表模式，请参阅 advanced-patterns.md。

---

协同使用效果良好

此技能可与多个 Agent 和其他技能集成：

与此技能协同效果良好的 Agent 包括 workflow-docs（用于带图表的文档）、workflow-spec（用于 SPEC 图表和需求可视化）以及 design-uiux（用于架构可视化和界面文档）。

与此技能互补的技能包括 moai-docs-generation（用于全面生成文档）、moai-workflow-docs（用于图表验证和文档工作流）以及 moai-library-nextra（用于架构文档站点）。

使用此技能的命令包括 moai:3-sync（用于带嵌入式图表的文档）和 moai:1-plan（用于创建带可视化架构图的 SPEC）。

重点：纯技能式 Mermaid 渲染与 MCP Playwright 集成

常见的自我说服理由

自我说服理由	事实
“ASCII 图用于文档已经足够了。”	ASCII 图在比例字体下会错位，也无法与代码变更一起进行版本管理。Mermaid 在任何地方都能一致地渲染。
“图表一目了然，不需要标签。”	没有标签的边和节点会迫使读者猜测其关系。添加标签的成本远低于产生误解的代价。
“等代码稳定后再添加图表。”	图表有助于设计决策。等到代码稳定后再绘制，记录的就是已经发生的事，而不是原本的设计。
“这个架构太复杂，无法用一张图表示。”	复杂架构需要拆分为多张图（上下文图、容器图、组件图），而不是一张庞大的图。
“Mermaid 语法太有限，无法满足我的需求。”	Mermaid 支持流程图、时序图、类图、状态图、ER 图和甘特图。如果这些都不合适，问题出在图表类型，而不是工具。

风险信号

• 仅用文字记录架构，未提供任何可视化图表
• 图表节点使用单字母标签（A、B、C），而非有意义的名称
• 时序图缺少错误／失败路径
• 架构变更后未更新图表
• 提交前未验证 Mermaid 语法错误

验证

• 图表渲染无语法错误（通过 Mermaid 在线编辑器或 Playwright 验证）
• 所有节点都有描述性标签（不是单字母或缩写）
• 图表与当前架构一致（对照代码结构）
• 时序图包含错误／失败路径
• 图表已嵌入相关文档或从相关文档链接