Mastra 文档 Mermaid 图示规范：为 Agent 工作流绘制可灰度、可读屏、可检索的技术示意图

Mastra 文档 Mermaid 图示规范：为 Agent 工作流绘制可灰度、可读屏、可检索的技术示意图

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

本篇指南完整解析 Mastra 文档仓库（docs/styleguides/DIAGRAM.md）中的 Mermaid 图示写作规范：从节点形状选择、连线语义、三色状态分类，到 ELK 布局下的主干路径声明、无障碍标题（accTitle/accDescr）与“绝不”清单。读完你将掌握一套可直接套用到 Agent 工作流、暂停恢复（suspend/resume）、人工审批（human-in-the-loop）等场景的 Mermaid 绘图方法，并理解其在 docs/src/theme/Mermaid/ 渲染管线中的落地原理。

为什么 Mastra 文档需要一套图示规范

Mastra 的文档主体由 MDX 文件构成，其中大量工作流说明（如 control-flow.mdx、suspend-and-resume.mdx、human-in-the-loop.mdx）依赖图示来展示步骤之间的执行关系。图示不是装饰，而是文档信息架构的一部分：读者需要把图与代码互相对照，屏幕阅读器用户需要能"听"到图的内容，灰度打印和色觉障碍读者需要仅凭形状就能区分节点职责。

Mastra 文档中的全部图示使用 Mermaid 编写，置于mermaid代码围栏中。它们经由 docs/src/theme/Mermaid/index.tsx 渲染——该组件监听站点的明暗主题（useColorMode），把当前配色模式交给 mastra-mermaid-theme.ts 生成对应的 Mermaid 配置。颜色、字体、布局引擎全部由这套主题统一下发，因此规范反复强调：不要在单个图里自造颜色或布局，否则会破坏站点的统一性。

选择节点形状：职责即形状

形状是节点语义的第一载体。规范要求按顺序逐条检查，命中第一条即停：

1. 节点是流程的开始或结束→ 圆形，写作(( start ))
2. 节点在等待一个人（如审批、人工输入）→id@{ shape: manual-input, label: "..." }
3. 节点读写持久化数据（如存储快照）→id@{ shape: cyl, label: "..." }
4. 节点按条件分叉→ 菱形，写作{approved?}
5. 其余情况视为一个工作单元→ 跑道形（stadium），写作([step1])

这套决策树的用意在于：形状承载的含义在灰度打印和色觉障碍场景下依然成立。两份职责不同的节点绝不能共用同一形状，否则图在失去颜色后便不可读。

在真实文档中可以找到每一类形状的实例。例如 human-in-the-loop.mdx 中的暂停图使用manual-input表示"等待人工输入"，而 suspend-and-resume.mdx 中的快照图使用cyl表示"已保存的快照"：

选择连线：实线与虚线的语义分工

连线同样有严格的语义约定：

• 实线-->：工作流自行推进。步骤完成后流程自然进入下一步。
• 虚线-.->：工作流之外的事件必须先发生，例如一个人回复、一个事件到达、或一个定时器触发。

规范还要求用引发状态迁移的 API 名称标注连线（如suspend、resume、out），而不是对迁移的描述。这样读者把图与底层代码对照时，能在图中和代码里找到同一个词——图就变成了代码的可视化索引。观察 suspend-and-resume.mdx 中的两幅图：暂停用-. suspend .->，恢复用-. resume .->，与run.resume()、suspend()等 API 一一对应。

三色语义类：只表达结果，不装饰路径

主题预置了三个语义类，绘图时只能引用类名，绝不直接写颜色：

节点通过class <node> <name>引用类；连线则需要以类名作为 id 前缀（如accent1、pending2、danger1）才能上色：

为什么连线必须走 id 前缀这条"隐晦"的路径？源码给出了答案。在 mastra-mermaid-theme.ts 中可以看到，Mermaid 不会把 CSS 类附加到渲染出的连线路径上，但会保留作者提供的边 id，因此主题通过semanticEdgeCSS生成选择器.edgePaths path[id*="-accent"], path.flowchart-link[id*="-accent"]来命中这些边：

// Mermaid does not put edge classes on the rendered path, but it does keep the // author-supplied edge id. Name an edge `accent1`, `pending2`, `danger1` and it // picks up the matching color in both light and dark mode. function semanticEdgeCSS(name: string, color: string) { return [ `.edgePaths path[id*="-${name}"], path.flowchart-link[id*="-${name}"] {`, ` stroke: ${color} !important;`, `}`, ].join('\n') }

同一文件中，semanticClassCSS则为accent、pending、danger三个类分别生成明暗两套填充与描边（如 light 模式下的accentBg: '#e7f4ea'与 dark 模式下的accentBg: '#0e2417'）。这正是"只用类名、不用颜色"的原因：颜色是主题在明暗两套模式下动态解析的，手写十六进制色值必然在某一种模式下失效。

规范同时强调：只给结果上色。步骤与步骤之间的普通路径保持中性，这样当图变大时，彩色部分依然有意义——accent标出成功出口，pending标出阻塞等待，danger标出失败分支，而不是让整张图五彩斑斓。

保持主干平直：先声明主路径，再挂分支

这是"为什么图经常画歪"的最常见原因。ELK 布局引擎会把源文件中读到的第一条链当作主干（spine），其余连线从主干上挂出去。如果过早声明一个分支，主干就会绕着它弯曲。

因此规范要求：

• 先按源码顺序声明主路径，再声明任何分支。
• 默认使用flowchart LR。只有当一张八节点的图在手机上溢出页面时，才切换到TB。
• 超过八个节点：拆分图表，或改用散文叙述。

这个上限同样来自工程约束——Mermaid 会把节点缩放到标签大小，一个超长标签就会产生一个压垮整张图的巨型节点。

从 control-flow.mdx 的并行分支图可以看到主路径先行的实际写法：start → step1 → step3 → end这条链被先写出，并行节点step2随后挂入：

此外，规范明确禁止在单个图中设置layout:或look:。原因同样可在主题源码中确认——mastra-mermaid-theme.ts 全局配置了layout: 'elk'与 ELK 参数（nodePlacementStrategy: 'BRANDES_KOEPF'、mergeEdges: false等）。一张图自行指定布局，就会让文档站失去一致性。

编写标签：小写、短标签、八节点上限

标签三原则：

• 全小写，除非对应 API 本身大写。
• 超过 16 个字符的标签用<br/>断行。因为节点尺寸随标签伸缩，一个超长标签会造出一个压垮整图的巨型节点。
• 八节点是上限，超出则拆分或改为文字。

注意标签里的 API 名保持原样（如.then(step1)、.branch([A, B])、.commit()），这延续了"图与代码互文"的原则。在 control-flow.mdx 的条件分支图中可以看到用<br/>断行与 API 标注的完整组合：

描述图表：accTitle 与 accDescr 是硬性要求

每张图都必须同时携带accTitle与accDescr，否则屏幕阅读器用户将什么都得不到。这两行放在图的开头，充当图片本该有的 alt 文本：

从仓库中所有 mermaid 图（包括 agent-lifecycle.mdx、authentication-identity.mdx、semantic-recall.mdx 等）可以看到，accTitle是句子的短语，accDescr用完整的陈述句描述图的流转路径。这也让图示内容可被搜索引擎与 LLM 直接检索，而非只存在于 SVG 像素中。

绝不（Never）清单

以下内容在任何图中都被禁止，并给出了明确的技术理由：

• 十六进制颜色、style、classDef、linkStyle：它们无法跟随明暗主题，会破坏两种模式之一。
• 图中出现var(--token)：Mermaid 的解析器会拒绝(-序列，导致整页渲染失败。
• 重复上文已经说过的内容：图示应当增加信息，而不是复读。

第三点在"主路径先行 + 结果上色"的规则配合下尤其重要——图是代码的索引、是视觉的摘要，而不是散文的插图版。

何时不使用 Mermaid：保留图片的场景

Mermaid 自动放置节点，因此如果元素的位置本身携带含义（自动布局会摧毁这种含义），或者主题是截图，就保留图片。例如涉及界面外观、真实运行结果或需要精确空间关系的场景，应继续使用静态图。

这一判断在 Mastra 文档体系中有一个更完整的判定流程，位于.claude/skills/docs-diagrams（在 docs/AGENTS.md 中被引用），DIAGRAM.md 是其中关于"画法"的浓缩版本。从源码结构看，该 skill 还覆盖了"该不该画图"的前置决策，与本文规范互为补充。

附：主题渲染管线速览

把上述所有规则串起来的渲染链路是：

1. MDX 中的mermaid代码围栏被 Docusaurus 识别；
2. docs/src/theme/Mermaid/index.tsx 读取当前明暗模式（useColorMode），调用mastraMermaidConfig(colorMode)；
3. mastra-mermaid-theme.ts 依据 light/dark 两套Palette生成MermaidConfig：theme: 'base'、layout: 'elk'、字体（Inter / Geist Mono）、以及注入themeCSS的accent/pending/danger三类节点与连线样式；
4. 渲染结果由ErrorBoundary包裹，任何解析失败都会显示错误回退而不是破坏整页。

这也解释了 DIAGRAM.md 每一条规则的底层动机：规范的本质，是让作者只表达语义（形状、连线、状态类、可访问性描述），而把表现（颜色、字体、布局、明暗适配）完全交给主题层。遵循这套规范写出的图，在明暗两套主题下、在灰度打印中、在屏幕阅读器中都能保持一致的信息传达——这正是大型开源文档站让数百张图"看起来像一个网站"的关键。

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra