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 配置。颜色、字体、布局引擎全部由这套主题统一下发因此规范反复强调不要在单个图里自造颜色或布局否则会破坏站点的统一性。选择节点形状职责即形状形状是节点语义的第一载体。规范要求按顺序逐条检查命中第一条即停节点是流程的开始或结束→ 圆形写作(( start ))节点在等待一个人如审批、人工输入→id{ shape: manual-input, label: ... }节点读写持久化数据如存储快照→id{ shape: cyl, label: ... }节点按条件分叉→ 菱形写作{approved?}其余情况视为一个工作单元→ 跑道形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含义accent运行成功完成the run completed successfullypending被阻塞等待外部事物blocked, waiting on something externaldanger停止、被拒绝或失败stopped, rejected, or failed节点通过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 还覆盖了该不该画图的前置决策与本文规范互为补充。附主题渲染管线速览把上述所有规则串起来的渲染链路是MDX 中的mermaid代码围栏被 Docusaurus 识别docs/src/theme/Mermaid/index.tsx 读取当前明暗模式useColorMode调用mastraMermaidConfig(colorMode)mastra-mermaid-theme.ts 依据 light/dark 两套Palette生成MermaidConfigtheme: base、layout: elk、字体Inter / Geist Mono、以及注入themeCSS的accent/pending/danger三类节点与连线样式渲染结果由ErrorBoundary包裹任何解析失败都会显示错误回退而不是破坏整页。这也解释了 DIAGRAM.md 每一条规则的底层动机规范的本质是让作者只表达语义形状、连线、状态类、可访问性描述而把表现颜色、字体、布局、明暗适配完全交给主题层。遵循这套规范写出的图在明暗两套主题下、在灰度打印中、在屏幕阅读器中都能保持一致的信息传达——这正是大型开源文档站让数百张图看起来像一个网站的关键。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考