Markdown Mermaid 写作技能

技能概述

Markdown Mermaid 写作技能是创建科学文档、技术报告和可视化内容的文本优先解决方案，将 Mermaid 图表嵌入 Markdown 文档作为规范格式，实现 Git 友好的版本控制和原生渲染。

适用场景

1. 科研论文和科学报告 编写实验工作流程、数据流程图、系统架构图和时间线，所有图表以文本形式嵌入 .md 文件，支持 Git 差异对比，可在 GitHub、GitLab 和 Notion 等平台直接渲染。

2. 技术文档和软件架构设计 创建 API 序列图、ER 图、状态机、C4 架构图和类图，使用 9 种文档模板（决策记录、项目文档、状态报告等）和 24 种 Mermaid 图表类型，确保团队文档标准和一致性。

3. 项目管理和可视化需求 生成甘特图、看板图、用户旅程图、需求追溯矩阵和项目时间线，文本优先的方式使图表易于修改和版本控制，无需重新生成图像即可更新内容。

核心功能

1. 24 种 Mermaid 图表类型支持 涵盖流程图、序列图、ER 图、状态图、甘特图、饼图、思维导图、时间线、类图、雷达图、象限图、需求图、桑基图、XY 图、块图、看板、架构图、用户旅程、树图、数据包图、Git 图、ZenUML 和复杂组合示例，每种图表提供完整样式指南、最佳实践和复制粘贴模板。

2. 三阶段文档工作流程 第一阶段（必需）：Mermaid 嵌入 Markdown 作为源文本；第二阶段（可选）：Python 生成数据图表（matplotlib、seaborn）；第三阶段（可选）：AI 生成润色图像。文本版本始终是真实来源，确保可编辑性和版本控制友好性。

3. 完整文档写作规范和模板 提供 Markdown 样式指南（733 行）、Mermaid 样式指南（458 行）和 9 种文档模板（Pull Request、Issue、看板、决策记录、演示、研究论文、项目文档、教程、状态报告），包含 H1/H2 规则、表情符号使用、引用规范、表格优化和可访问性标注（accTitle/accDescr）。

常见问题

Markdown 中如何使用 Mermaid 图表？

在 .md 文件中使用三个反引号和 mermaid 标记创建代码块，编写 Mermaid 语法即可。GitHub、GitLab、VS Code 和大多数 Markdown 查看器原生支持渲染，无需构建步骤。建议为每个图表添加 accTitle 和 accDescr 以提升可访问性。

Mermaid 支持哪些图表类型？

支持 24 种图表类型，包括流程图、序列图、ER 图、状态图、甘特图、饼图、思维导图、时间线、类图、雷达图、象限图、需求图、桑基图、XY 图、块图、看板、架构图、用户旅程、树图、C4 图、数据包图、Git 图、ZenUML 和复杂组合示例。每种图表都有专门的参考文件和模板。

为什么文本优先的文档更适合版本控制？

文本图表在 Git 中生成可读的差异，易于查看修改历史和协作编辑。图像文件（PNG、JPG）是二进制 blob，无法显示具体更改内容。Mermaid 图表作为文本，可以使用 AI 工具解析，消耗的 Token 比长篇文字描述更少，并且可以随时转换为高质量图像。