用途：用 Mermaid 语法编写可维护的技术图表，可在 GitHub、GitLab 及多数文档工具中渲染。图表作为代码资产与代码同库管理，必须保持同步，否则会误导读者。
主要能力：按意图选择图类型——结构用 flowchart/C4/class/ERD，随时间变化的行为用时序图，生命周期用状态图。架构建议用 C4 分层缩放（Context→Container→Component），而非一张庞杂大图。
使用方式与要点：方向用 flowchart TB/LR；节点形状 [Rect]、(Rounded)、{Diamond}、[(DB)]、((Circle))；边 --> 实线、-.-> 虚线、==> 强调、->> 同步消息、-->> 异步/返回。时序图关键字有 participant、autonumber、alt/else/end、loop/end、par/and/end、Note over。ERD 基数 || 恰一、o| 零或一、}| 一或多、}o 零或多。
常见解析陷阱：flowchart 中 end 为保留字，小写节点 id end 会破坏解析，改用 End、END 或 id["end"]；含 ()、{}、[]、#、:、; 或引号的标签需用引号包裹，如 A["fetch(url)"]，字面特殊字符用 HTML 实体（"、&、#）；换行用 <br/> 而非 \n；边标签含特殊字符需加引号；边首的 o/x 会变成箭头，需加空格或改名；子图方向在子图内设 direction LR，跨边界边可能覆盖该方向；注释用 %% 独占一行。C4 图布局控制有限且可能滞后，提交前需在目标工具验证，普通 flowchart 加子图是稳妥回退。
限制：节点超过约 15-20 个即难以阅读和评审，应按关注点或缩放层级拆分，一图一概念。图表应在同一 PR 中随代码更新并纳入 diff 评审。完成前需确认在目标工具中可渲染、标签已正确包裹、图类型与意图匹配、节点数受控且与当前代码一致。