Mastra 文档 Mermaid 图表规范从形状语义、状态着色到 ELK 主题渲染的完整指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 开源仓库的官方文档将所有架构与流程示意图统一为 Mermaid 编写并通过 docs/src/theme/Mermaid 定制主题完成渲染。本篇指南以仓库中的 DIAGRAM.md 规范文档 为骨架结合主题源码与文档内真实图表案例系统讲解形状决策树、实线/虚线边语义、accent/pending/danger三类状态着色、ELK 布局约束与无障碍描述accTitle/accDescr等全部规则。读完你既能按规范手写符合文档风格的 Mermaid 流程图也能理解这些规则在主题源码层是如何落地生效的。一、为什么文档图表统一使用 MermaidMastra 文档中的图表全部是 Mermaid统一写在mermaid代码围栏中例如这些图表的颜色、字体和布局引擎并非来自图表自身的声明而是由文档站点侧的src/theme/Mermaid/组件统一供应。在仓库中对应的实现是 docs/src/theme/Mermaid/index.tsx 与 docs/src/theme/Mermaid/mastra-mermaid-theme.ts。规范的第一条要求因此非常明确永远不要在图表里重复这些主题信息。也就是说不要在图表内写十六进制颜色、自定义style或classDef——站点全局主题已经替你处理了视觉外观图表作者只需要表达结构与语义。二、形状即语义五步决策树规范给出了一个按顺序执行的形状决策树逐个检查节点命中第一条即停止顺序判定条件采用形状Mermaid 语法1节点是整次运行的开始或结束圆形(( start ))、(( end ))2节点在等待一个真实的人手动输入形id{ shape: manual-input, label: ... }3节点在读写存储的数据圆柱体id{ shape: cyl, label: ... }4节点按条件分支菱形{approved?}5其余情况一律是一段工作圆角矩形体育场形([step1])这套决策树的用意在规范中被明确点出形状承载着即使经过灰度打印、即使读者是色盲也能存活下来的含义。两个职责不同的节点永远不允许共用同一个形状——例如等待人工输入与读写数据库如果都画成矩形黑白打印后便无法区分。从源码证据看这几种形状在 human-in-the-loop 文档 与 suspend-and-resume 文档 中得到了原样落地开始/结束用(( start ))/(( end ))等待人工输入用{ shape: manual-input, label: awaitingbr/human input }保存快照用{ shape: cyl, label: saved snapshot }。三、边的语义实线驱动虚线等待两条边的规则构成图表的动词体系实线--工作流自己会往前走。步骤之间只要没有外部依赖就用实线连接。虚线-.-工作流外部必须先生成某个条件例如一个人回复、一个事件到达、或者一个定时器触发后续步骤才可能继续。边的标签使用引发状态迁移的那个 API 名称如suspend、resume、out而不是对它的描述性文字。这条规则的动机非常工程化读者把图表和下方的代码对照时应该在两处看到同一个词。例如 suspend-and-resume 文档中的代码yield* suspend()与图中虚线边的suspend标签一一对应。四、语义化着色三种状态类与主题源码落地图表只使用三个语义类且永远用类名不写颜色类名含义accent本次运行成功完成pending被阻塞正在等待外部事物danger已停止、被拒绝或失败节点通过class node name获得着色边则通过以类名作为前缀的边 id获得着色为什么边要用accent1--、pending1-.这种写法查看主题源码 docs/src/theme/Mermaid/mastra-mermaid-theme.ts 可以找到答案——注释明确写道Mermaid 不会把边类写到渲染后的路径上但它会保留作者提供的边 id因此约定以accent、pending、danger前缀命名边 id主题侧通过 CSS 属性选择器path[id*-${name}]匹配并着色。这三类状态在明暗两套调色板中各有独立取值mastra-mermaid-theme.ts例如accent在浅色模式下是绿色系#0d8020描边、#e7f4ea填充在深色模式下切换为荧光绿系#18fb6f描边、#0e2417填充。主题通过semanticClassCSS(...)为节点注册类样式、通过semanticEdgeCSS(...)为边注册类样式mastra-mermaid-theme.ts。一个必须遵守的纪律是只给结局上色。步骤之间平凡的前进路径保持中性色这样当图变大时被着色的部分依然意味着什么而不是满屏花花绿绿。五、完整示例把所有规则合在一起把形状、边、颜色、无障碍描述组合起来就是文档中一张符合规范的完整图表取自 human-in-the-loop 文档 的写法逐条对照规范start/stop是圆形运行起止step1是圆角矩形工作单元paused是手动输入形等待人实线表达自主流转虚线suspend表达外部等待只有成功结束accent和阻塞等待pending被着色accTitle与accDescr提供了无障碍描述。这张图在仓库中的实际落版还展示了同款结构的另一形态快照场景用{ shape: cyl, label: saved snapshot }表示持久化存储见 suspend-and-resume 文档。六、保持主路径笔直为 ELK 布局写作Mastra 文档站点全局启用 ELK 布局引擎见主题配置layout: elkmastra-mermaid-theme.ts。ELK 会把读到的第一条链当作主干spine再把后续边挂在主干上。由此导出两条写作规则按源码顺序先声明主路径再声明任何分支。如果过早声明分支主干就会绕弯——规范直言这是这类图表最常见的翻车方式。默认使用flowchart LR。只有当一张八节点的图在手机上跑出页面时才切换到TB。超过八个节点拆分图表或者干脆改用散文描述。此外永远不要在图表里设置layout:或look:。站点全局统一使用 ELK某页单独退出全局设置就会让一个文档站看起来不像同一个站。这是站点一致性优先于单页表现的设计取舍。七、标签书写规则小写除非 API 本身是大写比如start、step1、suspend。任何超过 16 个字符的标签都要用br/换行。Mermaid 按标签尺寸撑大节点一个超长标签会造出一个压扁整张图的巨型节点——这也是awaitingbr/human input而非awaiting human input的原因。八节点是上限。超限后要么拆分图表要么转成文字叙述不要硬塞。八、无障碍每张图都必须携带 accTitle 与 accDescr每一张图都必须同时携带accTitle与accDescr两个声明否则屏幕阅读器用户将什么都得不到accTitle用一句话点明图的主题accDescr用一句完整的话描述图讲述的故事。规范明确说明这两行声明取代了图片原本应有的 alt 文本。在文档站点上这两行会被 Mermaid 渲染进 SVG 的可访问性属性中。九、禁区清单Never规范列出三项绝对禁止并给出了技术原因禁止十六进制颜色、style、classDef、linkStyle它们无法跟随浅色/深色主题必然会在两种模式中的一种里显示错误。这也是主题实现中刻意用类名 CSS 变量而不是图内样式的原因。禁止在图中出现var(--token)Mermaid 的解析器会拒绝(-这个序列整页会渲染失败。换言之一个 CSS 变量写法足以让整篇文档页面挂掉。禁止让图表重复上面那句话已经说过的东西图表必须提供句子之外的新信息否则就是冗余装饰。十、什么时候不要用 MermaidMermaid 会自动排布节点因此如果位置本身承载含义自动布局会毁掉它或者主题是截图则保留图片。配套的 docs-diagrams 技能 给出了三条按序决策的判断标准是 UI 截图吗→保留图片。Mermaid 画的是图不是产品界面。含义存在于事物放在哪里而非谁连着谁吗→保留图片。例如 agent 总览图中tool、LLM、memory 刻意放在 agent 下方——布局引擎一碰这个用意就没了。是方框 箭头并且换一个人只看节点与边标签就能重画出来吗→转换为 Mermaid。该技能还强调如果一张图只能靠对抗布局引擎才能画出来例如加隐形占位节点、在标签里塞空格、手调elk块那它就应该继续用图片。因为下一个维护者不会知道那些技巧为什么存在。十一、渲染管线源码级拆解规范提到的src/theme/Mermaid/在仓库中由三个文件构成彼此分工明确docs/src/theme/Mermaid/index.tsxReact 渲染入口。它通过 Docusaurus 的useColorMode()感知当前明暗模式把colorMode传给mastraMermaidConfig(colorMode)生成配置index.tsx并用ErrorBoundary包裹整个渲染器任何渲染异常都会走兜底错误页而不是白屏index.tsx。docs/src/theme/Mermaid/mastra-mermaid-theme.ts主题与配置中心。定义 light/dark 两套调色板、themeVariables到 Mermaid 配置项的完整映射、semanticClassCSS/semanticEdgeCSS三个状态类的样式生成以及 ELK 布局参数nodePlacementStrategy: BRANDES_KOEPF、mergeEdges: false等。值得注意的细节是边的标签被强制设为等宽字体、12pxmastra-mermaid-theme.ts这让边标签与代码 API 名的对照关系在视觉上更明显。docs/src/theme/Mermaid/styles.module.css容器样式。图表居中、带1.25rem内边距与细边框、水平方向overflow-x: auto保证宽图在移动端可滚动而不撑破页面。从这套实现可以推断文档作者在图表中唯一需要写的视觉信息就是语义类名其余全部由主题在渲染期统一注入。十二、真实案例对照以下两张图来自文档正文是规范在真实工作流文档中的落地样本。挂起与快照suspend-and-resume.mdx等待人工输入human-in-the-loop.mdx注意两张图都遵循了先主路径、后分支的声明顺序且都只对结局着色。类似的模式还出现在 control-flow.mdx、agents-and-tools.mdx 等页面可作为编写新图表时的风格参照。十三、本地验证与构建检查规范的落地离不开验证手段。在仓库中图表相关检查分两层开发预览在docs/目录运行pnpm dev --port 3005在浏览器中逐一核对——主路径是否笔直弯了说明分支声明太早、是否有节点宽度超过邻居两倍有则用br/断行、边标签是否贴在边上而非悬空、明暗模式切换后文字是否都可读且没有残留另一模式的填充色。文档技能特别强调截图不算验证必须实际渲染。静态检查与构建运行pnpm lint:remark做 Markdown 风格检查运行pnpm build——因为 Mermaid 解析错误会让构建失败而不是降级展示所以构建通过本身就是对全部图表语法有效性的证明。同时Mastra 文档写作生态中还有配套规范可交叉查阅整体写作规则见 STYLEGUIDE.md 与 DOC.md组件用法见 COMPONENTS.md将既有图片迁移为 Mermaid 的完整流程见 docs-diagrams 技能。小结Mastra 文档的图表体系可以浓缩为一句话作者只表达语义形状、边、状态类、无障碍描述主题负责呈现颜色、字体、ELK 布局。按形状决策树选型、用实线/虚线区分自主与等待、只对结局着三类语义色、先主路径后分支地书写、每图必带accTitle/accDescr产出的图表便天然具备灰度可读、色盲友好、可访问、可对照代码、在明暗双主题下都正确的品质。当这些规则与 docs/src/theme/Mermaid 的主题实现配合使用时一篇 Mastra 文档就能在任何模式、任何设备上保持一致的视觉语言。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考