Mermaid Architecture 架构图实战指南用 architecture-beta 绘制云基础设施拓扑【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文是 scientific-agent-skills 仓库中 markdown-mermaid-writing 技能体系下的 Architecture 图类型完整指南围绕 architecture.md 展开。该技能确立了以 Markdown 内嵌 Mermaid 图表作为默认文档标准的规范而architecture-beta正是其中用于表达云基础设施、服务拓扑、部署架构、网络布局的专属语法。读完本文你将掌握group/service/in三层核心语法、方向注释连线规则、内置图标类型的使用边界并能直接复制生产级示例与模板绘制出符合可访问性要求、可在 GitHub 明暗双主题下稳定渲染的架构图。一、为什么需要专门的架构图语法在 mermaid_style_guide.md 的Choosing the Right Diagram选择表中Mermaid 共覆盖 24 种图类型其中与系统结构相关的就有 Flowchart、C4、Block、Architecture 四种。选对类型而不是默认用流程图是该技能反复强调的第一原则Flowchartflowchart.md表达顺序流程、工作流、决策逻辑、排障树C4c4.md表达系统架构的不同缩放层级Context / Container / Component面向逻辑系统边界Blockblock.md表达组件布局、分层架构侧重空间排布Architecturearchitecture-beta表达云基础设施、服务拓扑、部署架构、网络布局带云语义图标。三者的边界在 architecture.md 中定义得十分明确图类型语法关键字最适合不适合Architecturearchitecture-beta云基础设施、服务拓扑、部署架构、网络布局逻辑系统边界改用 C4无云语义的组件布局改用 BlockC4C4Context/C4Container/C4Component系统架构缩放层级基础设施拓扑、运行时序列Blockblock-beta系统块组合、分层架构、空间排布过程流程、带云图标的基建⚠️无障碍前置要求与 Flowchart、Sequence、C4 等类型不同Architecture 图不支持accTitle/accDescr。因此必须在代码块正上方放置一段描述性的斜体Markdown 段落供屏幕阅读器与文本检索使用。这一规则同样适用于 Mindmap、Timeline、Quadrant、Sankey、XY Chart、Block、Kanban、Packet、Radar、Treemap见 mermaid_style_guide.md 的 Accessibility Requirements 一节。二、语法基础group、service 与 inarchitecture-beta的核心语法只有三组概念理解它们即可覆盖 90% 的绘图需求1.group— 逻辑边界用group表达逻辑容器VPC、区域Region、集群、可用区Availability Zone。语法结构为group 节点id(图标类型)[标签]其中(cloud)指定图标类型。group图标类型同样从内置图标集中选取参见下文。2.service— 单个组件用service表达独立部署的组件负载均衡器、API 服务器、数据库、缓存等。语法结构为service 节点id(图标类型)[标签] in 父组id。in关键字将节点放入已声明的组中。3. 连线与方向注释节点之间的连线是架构图最有特色的部分——每条边都必须声明连接锚点方向方向注释语法为源节点:方向 -- 方向:目标节点支持四个方位:L— 左侧left:R— 右侧right:T— 顶部top:B— 底部bottom语法元素说明示例group逻辑边界VPC、区域、集群、可用区group vpc(cloud)[VPC] in cloudservice单个组件service api(server)[API Server] in vpcin嵌套归属in cloud、in vpc--有向箭头api:R -- L:db--无向边api:R -- L:cache:L / :R / :T / :B连接锚点方向注释lb:R -- L:api关于方向注释有两个必须记住的要点方向注释是防重叠的关键手段。api:B -- T:cache表达从 api 底部连到 cache 顶部lb:R -- L:api表达从 lb 右侧连到 api 左侧。若省略方向注释Mermaid 会把边全部堆叠在一起导致图面混乱见 architecture.md 复杂示例的 Why this works 说明。--的箭头语法对空格严格敏感必须严格按lb:R -- L:api这种格式书写该陷阱被明确记录在 mermaid_style_guide.md 的 Known Parser Gotchas 表格中。4. 内置图标类型Architecture 图提供一组内置图标类型直接写在( )中图标类型含义典型用法cloud云 / 平台云平台分组、区域分组server服务器 / 计算API 服务器、应用服务器database数据库PostgreSQL、主从数据库internet网络 / 公网负载均衡、CDN 边缘disk磁盘 / 存储Redis 缓存等存储类组件三、示例图云托管 Web 应用下面这段来自 architecture.md 的示例展示了一个部署在 VPC 内的云托管 Web 应用负载均衡器、API 服务器、数据库与缓存四类组件。注意代码块上方必须放置描述性斜体段落以满足可访问性要求Architecture diagram showing a cloud-hosted web application with a load balancer, API server, database, and cache deployed within a VPC:阅读这段代码时可以拆解为三个层次分组层cloud组代表整个云平台vpc组通过in cloud嵌套其中形成云 → VPC的两级逻辑边界组件层四个service通过in vpc全部归属 VPC分别使用internet、server、database、disk四种图标区分角色连线层三条边全部带方向注释——lb:R -- L:api表示负载均衡右侧连 API 左侧api:R -- L:db表示 API 到数据库api:B -- T:cache表示 API 底部连缓存顶部。四、核心操作要点Tips 全览architecture.md 给出了 8 条经过验证的操作要点逐条解读如下用group表达逻辑边界——VPC、区域、集群、可用区都是典型的 group 场景用service表达单个组件——每个部署单元一个 service连线必须带方向注释——:L左、:R右、:T顶、:B底用于控制边的连接锚点内置图标类型共五种——cloud、server、database、internet、disk用in parent_group嵌套组——支持多级嵌套如 region in cloud标签必须是纯文本——[]标签内禁用 emoji、禁用连字符。这是最重要的坑之一解析器会把-当作边的操作符edge operator因此[US-East Region]会导致解析失败必须写成[US East Region]用--表示有向箭头--表示无向边每个图控制在 6–8 个 service——超出会显著降低可读性始终搭配上方文字描述——供屏幕阅读器使用对应可访问性规则。⚠️标签纯文本规则的深层原因Emoji 与连字符这两个限制都被 mermaid_style_guide.md 的 Known Parser Gotchas 表单独列出——Architecture 图中[]标签内出现 emoji 会导致解析错误连字符会被解析为边操作符。因此 Architecture 图的视觉区分完全依赖组嵌套与图标类型internet、server、database这也是它与其他图类型如允许 emoji 的 Flowchart、Block在风格上的关键差异。五、开箱即用的模板以下模板可直接复制使用。_Description of the infrastructure topology and key components:_为必填的斜体说明段请替换为你的实际描述Description of the infrastructure topology and key components:模板结构解读一个group表达云区域三个service表达前端、后端、数据存储三层两条:R -- L:横向连线表达请求从左向右流动。这是最简单的三层架构表达任何云平台AWS、GCP、Azure的入门部署图都可由此扩展。六、复杂示例多区域云部署当需要表达多区域、跨区复制、CDN 分发、集中监控这类真实基础设施拓扑时groupin的嵌套能力便派上用场。architecture.md 提供了一个 3 层嵌套组、9 个 service 的生产级复杂示例Multi-region cloud deployment with 3 nested groups (2 regional clusters shared services) showing 9 services, cross-region database replication, CDN distribution, and centralized monitoring. Demonstrates how nestedgroupinsyntax creates clear infrastructure boundaries:这个复杂示例为什么有效原文档从四个角度解释了该设计的合理性这也是任何大规模架构图的通用准则嵌套组镜像真实基础设施——cloud region services正是团队思考多区域部署的方式嵌套天然划清了爆炸半径blast radius边界仅用纯文本标签——Architecture 图在[]标签中使用 emoji 会解析失败所有视觉区分都来自组嵌套与图标类型internet、server、database方向注释防止重叠——cdn:B -- T:lb_east底到顶、db_primary:R -- L:db_replica右到左精确控制边连接锚点如果省略这些注释Mermaid 会把边堆叠在一起跨区域复制被显式表达——db_primary:R -- L:db_replica这条边是全图最重要的基础设施细节它以一条清晰的横向连接在区域之间阅读起来一目了然。连线方向小结cdn:B -- T:表示 CDN 底部向下分发流量lb_east:R -- L:与db_primary:R -- L:表示东西向流量与数据复制app_east:B -- T:db_primary表示南北向的数据访问——方向注释组合起来正好还原了真实流量路径。七、何时不要用 Architecture 图原文档在开头就明确划定了 Architecture 图的边界这里结合仓库中对应的替代图类型c4.md 与 block.md展开说明场景应使用原因逻辑系统边界系统间职责划分、人员与系统的交互C4C4Context/C4Container/C4ComponentC4 提供 Context → Container → Component 三级缩放视角Person()、System()、System_Ext()等语义元素更适合表达逻辑边界C4 不支持基础设施拓扑无云语义的组件布局、分层架构Blockblock-betaBlock 用columns N控制布局网格、space:N控制间距且允许在标签中使用 emoji如[ Browser]适合空间排布优先的场景过程流程、决策逻辑Flowchartflowchart流程图表达顺序、分支与循环与拓扑图语义完全不同判断口诀有云图标语义 → Architecture有逻辑系统边界 → C4有空间布局需求 → Block有流程与决策 → Flowchart。八、可访问性与风格合规自查Architecture 图在 mermaid_style_guide.md 中属于不支持accTitle/accDescr的 11 种类型之一因此在每次使用 Architecture 图之前请对照以下清单逐项检查代码块正上方是否有描述性的斜体Markdown 段落替代accTitle/accDescr[]标签是否为纯文本——无 emoji、无连字符每条连线是否都带方向注释:L/:R/:T/:B且--两侧空格正确是否控制 service 数量在 6–8 个以内本仓库复杂示例虽有 9 个 service但以三个嵌套组消化了复杂度是否使用了语义化的snake_case节点 ID如db_primary、lb_east而非a、b是否有%%{init}主题指令或内联style—— 两者都会被 GitHub 深色模式破坏必须改用classDefclass该规则适用于所有图类型见 mermaid_style_guide.md 的 Theme Configuration 一节是否在 GitHub 明、暗两种主题下分别验证过渲染效果九、快速参考卡片最后将本指南压缩为一张可直接查阅的速查表项目值语法关键字architecture-beta逻辑边界group 名称(cloud)[标签] in 父组组件service 名称(图标)[标签] in 组图标类型cloud、server、database、internet、disk方向注释:L/:R/:T/:B有向 / 无向--/--标签约束纯文本禁止 emoji 与连字符service 数量上限6–8 个可访问性不支持accTitle/accDescr需斜体段落文件位置skills/markdown-mermaid-writing/references/diagrams/architecture.md本指南属于 markdown-mermaid-writing 技能下 24 种图类型指南之一。完整的图类型选择表、GitHub 兼容色板classDef调色板、emoji 语义集以及全部解析器陷阱请查阅 mermaid_style_guide.md文档排版、引用与标题规范见 markdown_style_guide.md。当单个 Architecture 图无法覆盖全部视角时可参考 complex_examples.md 中的 Overview Detail 与 Before/After Architecture 组合模式例如迁移项目场景建议用 Gantt 排期 Architecture 表达迁移前后拓扑 Flowchart 表达迁移流程将多张图组合成一套完整的系统文档。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mermaid Architecture 架构图实战指南：用 architecture-beta 绘制云基础设施拓扑
Mermaid Architecture 架构图实战指南用 architecture-beta 绘制云基础设施拓扑【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文是 scientific-agent-skills 仓库中 markdown-mermaid-writing 技能体系下的 Architecture 图类型完整指南围绕 architecture.md 展开。该技能确立了以 Markdown 内嵌 Mermaid 图表作为默认文档标准的规范而architecture-beta正是其中用于表达云基础设施、服务拓扑、部署架构、网络布局的专属语法。读完本文你将掌握group/service/in三层核心语法、方向注释连线规则、内置图标类型的使用边界并能直接复制生产级示例与模板绘制出符合可访问性要求、可在 GitHub 明暗双主题下稳定渲染的架构图。一、为什么需要专门的架构图语法在 mermaid_style_guide.md 的Choosing the Right Diagram选择表中Mermaid 共覆盖 24 种图类型其中与系统结构相关的就有 Flowchart、C4、Block、Architecture 四种。选对类型而不是默认用流程图是该技能反复强调的第一原则Flowchartflowchart.md表达顺序流程、工作流、决策逻辑、排障树C4c4.md表达系统架构的不同缩放层级Context / Container / Component面向逻辑系统边界Blockblock.md表达组件布局、分层架构侧重空间排布Architecturearchitecture-beta表达云基础设施、服务拓扑、部署架构、网络布局带云语义图标。三者的边界在 architecture.md 中定义得十分明确图类型语法关键字最适合不适合Architecturearchitecture-beta云基础设施、服务拓扑、部署架构、网络布局逻辑系统边界改用 C4无云语义的组件布局改用 BlockC4C4Context/C4Container/C4Component系统架构缩放层级基础设施拓扑、运行时序列Blockblock-beta系统块组合、分层架构、空间排布过程流程、带云图标的基建⚠️无障碍前置要求与 Flowchart、Sequence、C4 等类型不同Architecture 图不支持accTitle/accDescr。因此必须在代码块正上方放置一段描述性的斜体Markdown 段落供屏幕阅读器与文本检索使用。这一规则同样适用于 Mindmap、Timeline、Quadrant、Sankey、XY Chart、Block、Kanban、Packet、Radar、Treemap见 mermaid_style_guide.md 的 Accessibility Requirements 一节。二、语法基础group、service 与 inarchitecture-beta的核心语法只有三组概念理解它们即可覆盖 90% 的绘图需求1.group— 逻辑边界用group表达逻辑容器VPC、区域Region、集群、可用区Availability Zone。语法结构为group 节点id(图标类型)[标签]其中(cloud)指定图标类型。group图标类型同样从内置图标集中选取参见下文。2.service— 单个组件用service表达独立部署的组件负载均衡器、API 服务器、数据库、缓存等。语法结构为service 节点id(图标类型)[标签] in 父组id。in关键字将节点放入已声明的组中。3. 连线与方向注释节点之间的连线是架构图最有特色的部分——每条边都必须声明连接锚点方向方向注释语法为源节点:方向 -- 方向:目标节点支持四个方位:L— 左侧left:R— 右侧right:T— 顶部top:B— 底部bottom语法元素说明示例group逻辑边界VPC、区域、集群、可用区group vpc(cloud)[VPC] in cloudservice单个组件service api(server)[API Server] in vpcin嵌套归属in cloud、in vpc--有向箭头api:R -- L:db--无向边api:R -- L:cache:L / :R / :T / :B连接锚点方向注释lb:R -- L:api关于方向注释有两个必须记住的要点方向注释是防重叠的关键手段。api:B -- T:cache表达从 api 底部连到 cache 顶部lb:R -- L:api表达从 lb 右侧连到 api 左侧。若省略方向注释Mermaid 会把边全部堆叠在一起导致图面混乱见 architecture.md 复杂示例的 Why this works 说明。--的箭头语法对空格严格敏感必须严格按lb:R -- L:api这种格式书写该陷阱被明确记录在 mermaid_style_guide.md 的 Known Parser Gotchas 表格中。4. 内置图标类型Architecture 图提供一组内置图标类型直接写在( )中图标类型含义典型用法cloud云 / 平台云平台分组、区域分组server服务器 / 计算API 服务器、应用服务器database数据库PostgreSQL、主从数据库internet网络 / 公网负载均衡、CDN 边缘disk磁盘 / 存储Redis 缓存等存储类组件三、示例图云托管 Web 应用下面这段来自 architecture.md 的示例展示了一个部署在 VPC 内的云托管 Web 应用负载均衡器、API 服务器、数据库与缓存四类组件。注意代码块上方必须放置描述性斜体段落以满足可访问性要求Architecture diagram showing a cloud-hosted web application with a load balancer, API server, database, and cache deployed within a VPC:阅读这段代码时可以拆解为三个层次分组层cloud组代表整个云平台vpc组通过in cloud嵌套其中形成云 → VPC的两级逻辑边界组件层四个service通过in vpc全部归属 VPC分别使用internet、server、database、disk四种图标区分角色连线层三条边全部带方向注释——lb:R -- L:api表示负载均衡右侧连 API 左侧api:R -- L:db表示 API 到数据库api:B -- T:cache表示 API 底部连缓存顶部。四、核心操作要点Tips 全览architecture.md 给出了 8 条经过验证的操作要点逐条解读如下用group表达逻辑边界——VPC、区域、集群、可用区都是典型的 group 场景用service表达单个组件——每个部署单元一个 service连线必须带方向注释——:L左、:R右、:T顶、:B底用于控制边的连接锚点内置图标类型共五种——cloud、server、database、internet、disk用in parent_group嵌套组——支持多级嵌套如 region in cloud标签必须是纯文本——[]标签内禁用 emoji、禁用连字符。这是最重要的坑之一解析器会把-当作边的操作符edge operator因此[US-East Region]会导致解析失败必须写成[US East Region]用--表示有向箭头--表示无向边每个图控制在 6–8 个 service——超出会显著降低可读性始终搭配上方文字描述——供屏幕阅读器使用对应可访问性规则。⚠️标签纯文本规则的深层原因Emoji 与连字符这两个限制都被 mermaid_style_guide.md 的 Known Parser Gotchas 表单独列出——Architecture 图中[]标签内出现 emoji 会导致解析错误连字符会被解析为边操作符。因此 Architecture 图的视觉区分完全依赖组嵌套与图标类型internet、server、database这也是它与其他图类型如允许 emoji 的 Flowchart、Block在风格上的关键差异。五、开箱即用的模板以下模板可直接复制使用。_Description of the infrastructure topology and key components:_为必填的斜体说明段请替换为你的实际描述Description of the infrastructure topology and key components:模板结构解读一个group表达云区域三个service表达前端、后端、数据存储三层两条:R -- L:横向连线表达请求从左向右流动。这是最简单的三层架构表达任何云平台AWS、GCP、Azure的入门部署图都可由此扩展。六、复杂示例多区域云部署当需要表达多区域、跨区复制、CDN 分发、集中监控这类真实基础设施拓扑时groupin的嵌套能力便派上用场。architecture.md 提供了一个 3 层嵌套组、9 个 service 的生产级复杂示例Multi-region cloud deployment with 3 nested groups (2 regional clusters shared services) showing 9 services, cross-region database replication, CDN distribution, and centralized monitoring. Demonstrates how nestedgroupinsyntax creates clear infrastructure boundaries:这个复杂示例为什么有效原文档从四个角度解释了该设计的合理性这也是任何大规模架构图的通用准则嵌套组镜像真实基础设施——cloud region services正是团队思考多区域部署的方式嵌套天然划清了爆炸半径blast radius边界仅用纯文本标签——Architecture 图在[]标签中使用 emoji 会解析失败所有视觉区分都来自组嵌套与图标类型internet、server、database方向注释防止重叠——cdn:B -- T:lb_east底到顶、db_primary:R -- L:db_replica右到左精确控制边连接锚点如果省略这些注释Mermaid 会把边堆叠在一起跨区域复制被显式表达——db_primary:R -- L:db_replica这条边是全图最重要的基础设施细节它以一条清晰的横向连接在区域之间阅读起来一目了然。连线方向小结cdn:B -- T:表示 CDN 底部向下分发流量lb_east:R -- L:与db_primary:R -- L:表示东西向流量与数据复制app_east:B -- T:db_primary表示南北向的数据访问——方向注释组合起来正好还原了真实流量路径。七、何时不要用 Architecture 图原文档在开头就明确划定了 Architecture 图的边界这里结合仓库中对应的替代图类型c4.md 与 block.md展开说明场景应使用原因逻辑系统边界系统间职责划分、人员与系统的交互C4C4Context/C4Container/C4ComponentC4 提供 Context → Container → Component 三级缩放视角Person()、System()、System_Ext()等语义元素更适合表达逻辑边界C4 不支持基础设施拓扑无云语义的组件布局、分层架构Blockblock-betaBlock 用columns N控制布局网格、space:N控制间距且允许在标签中使用 emoji如[ Browser]适合空间排布优先的场景过程流程、决策逻辑Flowchartflowchart流程图表达顺序、分支与循环与拓扑图语义完全不同判断口诀有云图标语义 → Architecture有逻辑系统边界 → C4有空间布局需求 → Block有流程与决策 → Flowchart。八、可访问性与风格合规自查Architecture 图在 mermaid_style_guide.md 中属于不支持accTitle/accDescr的 11 种类型之一因此在每次使用 Architecture 图之前请对照以下清单逐项检查代码块正上方是否有描述性的斜体Markdown 段落替代accTitle/accDescr[]标签是否为纯文本——无 emoji、无连字符每条连线是否都带方向注释:L/:R/:T/:B且--两侧空格正确是否控制 service 数量在 6–8 个以内本仓库复杂示例虽有 9 个 service但以三个嵌套组消化了复杂度是否使用了语义化的snake_case节点 ID如db_primary、lb_east而非a、b是否有%%{init}主题指令或内联style—— 两者都会被 GitHub 深色模式破坏必须改用classDefclass该规则适用于所有图类型见 mermaid_style_guide.md 的 Theme Configuration 一节是否在 GitHub 明、暗两种主题下分别验证过渲染效果九、快速参考卡片最后将本指南压缩为一张可直接查阅的速查表项目值语法关键字architecture-beta逻辑边界group 名称(cloud)[标签] in 父组组件service 名称(图标)[标签] in 组图标类型cloud、server、database、internet、disk方向注释:L/:R/:T/:B有向 / 无向--/--标签约束纯文本禁止 emoji 与连字符service 数量上限6–8 个可访问性不支持accTitle/accDescr需斜体段落文件位置skills/markdown-mermaid-writing/references/diagrams/architecture.md本指南属于 markdown-mermaid-writing 技能下 24 种图类型指南之一。完整的图类型选择表、GitHub 兼容色板classDef调色板、emoji 语义集以及全部解析器陷阱请查阅 mermaid_style_guide.md文档排版、引用与标题规范见 markdown_style_guide.md。当单个 Architecture 图无法覆盖全部视角时可参考 complex_examples.md 中的 Overview Detail 与 Before/After Architecture 组合模式例如迁移项目场景建议用 Gantt 排期 Architecture 表达迁移前后拓扑 Flowchart 表达迁移流程将多张图组合成一套完整的系统文档。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考