ARTICLE · 1377814
现在写文档都用MD了,因为AI好识别~

昨天团队里一个小伙子在写设计文档,为了画个协议交互的时序图,在 draw.io 里拖了一下午的框框。看着实在难受,于是过去跟他聊了聊,安利了 Mermaid——几行文本就能出图,画完往 markdown 里一贴,直接渲染,省时省力。
而且现在AI对于图片的识别于解析还比较弱,不过让AI干文本的事情是再合适不过了,比如你想写设计文档时,直接"帮我画一个 OTA 升级的时序图,包括设备端、云端、APP 端三个角色,采用Mermaid ",几秒钟 Mermaid 代码就出来了,你只需要核对一下逻辑对不对,微调两行就完事,传统画图工具目前还比较麻烦。
1
Mermaid是个啥?
Mermaid 是一个基于 JavaScript 的图表生成工具,你用类似 markdown 的纯文本语法描述图表结构,它帮你渲染成图形。跟传统画图工具最大的区别——你关心的是"内容是什么",而不是"框框放哪里、线条怎么弯"。
传统画图 vs Mermaid 的工作流对比,一张图就看明白:

同样的上面的图表是如下代码生成:
flowchart LR subgraph T[传统方式 — 5步折腾] direction TB A1[打开画图软件] --> A2[拖拽图形元素] A2 --> A3[手动调整布局] A3 --> A4[导出为PNG] A4 --> A5[贴入文档] end subgraph M[Mermaid — 2步搞定] direction TB B1[编写文本语法] --> B2[引擎渲染 + 嵌入文档] end T -.->|"VS"| M几个特点直接说清楚:
纯文本:图表就是一段代码,可以进 git 版本管理,diff 起来明明白白 Markdown 原生集成:GitHub、GitLab、Notion、语雀全都原生支持,写文档时顺手就画了 语法简单:画个流程图可能就十几行,比拖拽快得多 对 AI 极度友好:这一点很多人没意识到——Mermaid 是纯文本,AI 工具(Copilot、Claude、GPT)可以直接读写、理解、生成。你甚至可以用自然语言对 AI 说"画个 I2C 通信时序图",它直接输出 Mermaid 代码,渲染出来就是一张专业图表。而那些二进制格式,AI 根本看不懂 免费开源:不掏一分钱,不限制导出
对于嵌入式开发的小伙伴,写设计文档、画状态机、梳理协议交互流程,这玩意简直是效率神器。
2
流程图
流程图是 Mermaid 的入门款,语法也最直观。直接看例子:
flowchart TD A[系统上电] --> B{初始化是否成功} B -->|成功| C[进入主循环] B -->|失败| D[记录错误码] D --> E[尝试复位] E --> B C --> F[任务调度]
上面这段渲染出来就是一个标准流程图,菱形是判断节点,矩形是操作节点,箭头带标签。
几个常用方向记一下就行:
TD(Top-Down):从上到下LR(Left-Right):从左到右BT:从下到上RL:从右到左
节点形状直接用括号控制:[矩形]、(圆角)、{菱形}、((圆形))、[[子程序]]。不用记全,写的时候翻一下文档就行。
还有一个 特别实用的——subgraph 子图分组。比如你要把初始化流程和业务逻辑分开:

flowchart LR subgraph 初始化阶段 A[时钟配置] --> B[外设初始化] B --> C[RTOS启动] end subgraph 业务运行 D[传感器采集] --> E[数据处理] E --> F[上报云端] end C --> D用 subgraph 把复杂流程分成几个逻辑块,看图的人一眼就知道你在分哪几个阶段,比自己用框框圈来圈去清爽多了。
3
时序图
干嵌入式的天天跟协议打交道——I2C、SPI、UART、MQTT、CAN...协议交互最头疼的就是时序:谁先发?谁应答?超时了怎么办?
时序图就是干这个的。Mermaid 的 sequenceDiagram 语法直接帮你把交互线画得明明白白:
sequenceDiagram participant MCU as 主控MCU participant Sensor as 传感器 participant Cloud as 云平台 MCU->>Sensor: I2C读取数据 Sensor-->>MCU: 返回原始数据 MCU->>MCU: 数据校验与滤波 MCU->>Cloud: MQTT上报 Cloud-->>MCU: ACK确认
语法还是非常简单的,如果你是初次用习惯一段时间就好:A->>B: 消息 就是同步请求,A-->>B: 消息 是异步返回,虚线实线自动帮你区分。
还有更实用的——alt/else 分支和loop 循环。比如带重试机制的通信流程:
sequenceDiagram participant MCU as 主控 participant Dev as 从设备 MCU->>Dev: 发送查询命令 alt 正常应答 Dev-->>MCU: 返回数据 else 超时(3次重试) loop 重试 MCU->>Dev: 重新发送 end Dev-->>MCU: 超时异常 end
以前画这种带分支的时序图,在图形工具里要拉一堆生命线、拖条件框、调对齐,一画就是半小时。用 Mermaid 几分钟写完,初稿还可以用AI生成,准确度也高的~
多说一句:写设计文档时把时序图往 spec 里一贴,review 的时候大家对着图看协议有没有漏洞,比纯文字描述直观太多。bug菌现在团队里写接口文档已经强制要求配时序图了。
4
状态图
嵌入式软件里状态机可多了,可为面向状态机编程——按键消抖、通信协议栈、电源管理、设备工作模式...每个状态机都要解释清楚"在什么条件下跳转到什么状态"。
用状态图就方便了:

stateDiagram-v2 [*] --> 空闲 空闲 --> 采集 : 定时触发 采集 --> 处理 : 数据就绪 处理 --> 发送 : 处理完成 发送 --> 空闲 : 发送完毕 空闲 --> 低功耗 : 无任务5分钟 低功耗 --> 空闲 : 外部中断唤醒 state 处理 { [*] --> 滤波 滤波 --> 计算 计算 --> 打包 打包 --> [*] }注意里面那个 state 处理 { ... }——这是复合状态,把"处理"这个大状态拆成几个子状态。真实项目中一个设备的工作状态往往就三四层嵌套,用复合状态表达是最贴切的。
5
类图
类图很多人觉得是 Java/C++ 那帮面向对象的专属,其实现在的大型嵌入式 C 代码也是要用的,毕竟面向对象只是一种思想。
如果用 C 写了套模块化框架——比如一个通用的传感器驱动抽象层——用类图来表达模块之间的关系非常清晰:

classDiagram class SensorDriver { +init() int +read(float* data) int +setRange(int range) void -m_calibData[16] uint8_t } class I2CInterface { +write(addr, buf, len) int +read(addr, buf, len) int } class DataFilter { +kalman(float input) float +movingAvg(float* buf) float } SensorDriver --> I2CInterface : 依赖 SensorDriver --> DataFilter : 使用这里 + 表示外部可访问的接口,- 表示模块内部用的私有数据。虽然不是严格的 UML,但表达设计意图完全够用。
在架构设计文档里用类图画一下模块关系,团队里的人理解成本会低很多。毕竟一个项目十几个模块,光靠文字描述依赖关系,光靠嘴那多费力。
6
其他的实用的几个
上面四个是最常用的,剩下的也算有一定使用频率:
甘特图 — 排项目计划用的。几个人、几个模块、时间怎么排,一目了然:
gantt title MCU固件开发排期 dateFormat YYYY-MM-DD section 底层驱动 I2C驱动开发 :a1, 2026-07-01, 3d SPI驱动开发 :a2, 2026-07-03, 2d section 业务逻辑 传感器采集模块 :b1, 2026-07-05, 4d 数据处理算法 :b2, 2026-07-08, 4d
饼图 — 汇报时用,比如展示各模块的 ROM 占用占比:
pie title Flash占用分布 "启动代码+向量表" : 8 "FreeRTOS内核" : 24 "驱动层" : 30 "业务逻辑" : 38
ER图 — 如果你做的是带数据库的嵌入式 Linux 应用(比如边缘网关),ER 图用来梳理表结构:

erDiagram DEVICE ||--o{ SENSOR_DATA : 产生 DEVICE { int device_id PK string device_name int protocol_type } SENSOR_DATA { int data_id PK int device_id FK float value timestamp time }这些虽然不像前面四个那么高频,但真到用的时候,知道 Mermaid 能画、不用再开一个别的工具,这感觉还是挺 nice 的~
这玩意不难,语法也记不住多少,用的时候翻一下官方文档就行。bug菌觉得真正的价值不在于"Mermaid 有多好用",而在于降低了你画图的阻力——以前画张时序图要开 Visio 或者 draw.io、拖半天,现在打开编辑器敲几行就完事。还有一个容易被忽略的点:Mermaid 的纯文本本质,意味着它天然适配 AI 时代——AI 能读懂你的图、也能帮你画图,这是任何二进制画图工具永远做不到的。
起飞吧~
星标公众号,第一时间看嵌入式技术文章! 
推荐好文点击蓝色字体即可跳转
☞专辑|Linux应用程序编程大全
☞ 专辑|学点网络知识
☞ 专辑|手撕C语言
☞ 专辑|手撕C++语言
☞ 专辑|经验分享
☞ 专辑|从单片机到Linux
☞ 专辑|电能控制技术
☞ 专辑|嵌入式必备数学知识
☞ MCU进阶专辑
☞ 经验分享

推荐好文点击蓝色字体即可跳转








☞ MCU进阶专辑















































































