C4容器图生成器

C4容器图生成器 是做什么的？

遵循C4模型规范生成容器图，导出为可编辑的.drawio XML文件，可直接在draw.io（桌面或网页版）中打开。

何时使用

显式触发：

• 用户要求生成C4图、容器图或架构图
• 用户说“绘制架构”、“系统图”、“展示组件”
• 用户需要为文档或演示可视化系统架构
• 用户提到draw.io、drawio，或想要可编辑的图表

主动触发：

• 解释包含3个以上交互组件的系统
• 讨论微服务、API、数据库及其关系
• 审查或设计系统架构

跳过时机：

• 用户想要简单的流程图（改用Mermaid）
• 用户想要UI线框图或原型
• 系统组件少于3个

流程

第1步：收集需求

从对话中识别或询问用户：

• 我们要绘制什么系统？
• 用户/角色（人员）是谁？
• 存在哪些容器（应用、服务、数据库、队列、文件存储）？
• 它与哪些外部系统交互？
• 关键的数据流和协议是什么？

如果用户提供了规格说明、代码库描述或架构概览，自动提取元素并在生成前确认。

第2步：分类元素

将每个元素映射到C4类别：

类别	颜色	形状	描述
人员	#08427B（深蓝）	shape=actor + 文本标签	用户、角色
容器	#438DD5（蓝色）	圆角矩形	应用、服务、API
数据库	#438DD5（蓝色）	圆柱体	任何数据存储（SQL、NoSQL、文件）
队列/代理	#438DD5（蓝色）	圆角矩形 + 标签	消息队列、事件总线
外部系统	#999999（灰色）	圆角矩形	第三方服务、API
系统边界	无（透明）	虚线矩形	内部容器组

参考：references/element-templates.md 获取精确的draw.io XML模板。

第3步：规划布局

应用严格分层布局（从上到下）：

第1层（y ~= 20）：    人员元素（角色）
第2层（y ~= 250）：   包含内部容器的系统边界
第3层（y ~= 700+）：  外部系统

布局规则：

• 每个元素都有显式的x、y坐标（无自动布局）
• 同一层元素之间最小200px水平间距
• 层之间最小200px垂直间距
• 系统边界 = 虚线矩形，包裹所有内部容器，四周40px内边距
• 元素从左到右排列，遵循主要数据流方向
• 如果系统包含不同子系统，在子边界内分组相关容器
• 保持图表宽度在1600px以内以保证可读性
• 元素在其层内水平居中

最小化连线交叉：

• 将频繁通信的元素相邻放置
• 连接尽可能垂直路由
• 避免对角线穿过其他元素
• 禁止箭头穿过无关容器：如果A连接到C，箭头不得穿过B。解决方法：(a) 将A和C相邻放置，(b) 使用显式的进出口点，(c) 重新组织布局
• 箭头标签不得与容器文本重叠：在所有边上使用labelBackgroundColor=#ffffff，并使用垂直偏移（mxGeometry中的y）将标签推离容器

第4步：定义连接

对于每个连接，指定：

• 源和目标元素
• 标签：动作 + 协议（例如“读取/写入 [SQL/TCP]”、“发送事件 [AMQP]”）
• 样式：实线 = 同步调用，虚线 = 异步调用（事件、队列、Webhook）
• 方向：总是从源到目标（遵循数据流）

连接规则：

• 每个箭头必须有标签（没有无标签的连接）——如果标签重叠，请修复布局或偏移，切勿移除标签
• 在连接样式中始终包含labelBackgroundColor=#ffffff
• 使用[协议]后缀：[REST/JSON]、[gRPC]、[SQL]、[AMQP]、[WebSocket]
• 双向流：使用两个独立的箭头，带有不同的标签
• 自引用：避免（改为重新组织图表）

第5步：生成.drawio XML

以references/drawio-template.md中的XML结构为基础。

按照以下规则构建XML：

1. 以<mxfile>包装器和带有合适尺寸的<mxGraphModel>开始
2. 添加根单元格（id="0"和id="1"）
3. 首先添加系统边界矩形（它们是包含元素的父级）
4. 添加所有元素，带有显式的几何信息（x、y、宽度、高度）
5. 添加所有连接，带有源/目标引用
6. 在右下角添加图例

元素尺寸：

• 人员：40 x 60px 角色 + 下方 220 x 60px 文本标签
• 容器：240 x 120px
• 数据库（圆柱体）：240 x 120px
• 外部系统：240 x 120px
• 系统边界：计算得出，包裹子元素 + 每侧40px内边距

第6步：添加图例

**每张图必须包含图例。**放在右下角。

图例必须显示：

• 人员 = 深蓝色火柴人（#08427B）
• 容器 = 蓝色圆角矩形（#438DD5）
• 数据库 = 蓝色圆柱体（#438DD5）
• 外部系统 = 灰色圆角矩形（#999999）
• 实线箭头 = 同步流
• 虚线箭头 = 异步流

参考：references/legend-template.md 获取精确的XML。

第7步：保存并验证

保存到用户请求的路径，默认为./c4_[系统名称].drawio。

验证清单：

• 所有元素都有显式的x、y坐标
• 图层从上到下顺序：人员 -> 系统边界 -> 外部系统
• 系统边界包裹所有内部容器
• 图例在右下角
• 无重叠元素（检查坐标和尺寸）
• 连线交叉最少
• 每个连接都有带协议的标签
• 实线 = 同步，虚线 = 异步
• 彩色背景上的字体颜色为白色（#ffffff）
• 文件能在draw.io中正常打开（XML结构有效）

C4模型规则

遵循C4容器图约束：

• 容器图展示高层次技术选择以及容器之间的通信方式
• 每个容器是一个可单独部署/运行的单元（不是类或模块）
• 不要混合C4层级：本技能仅生成容器层级
• 对于容器内部的组件级细节，请创建单独的图表
• 人员元素代表角色，而非具体个人
• 外部系统是团队不拥有的、在系统边界之外的任何东西

反模式

• 禁止自动布局——始终使用显式的x、y坐标以获得可预测的结果
• 禁止无标签箭头——每个连接都需要动作和协议
• 禁止缺少图例——每张图必须包含图例
• 禁止拥挤布局——元素之间保持最小间距
• 禁止混合C4层级——仅容器层级（无类、无基础设施）
• 禁止不可见文本——确保字体颜色与背景对比清晰
• 禁止硬编码尺寸——根据子元素计算系统边界大小
• 禁止使用mxgraph.c4.*形状——它们需要C4形状库，而draw.io默认不加载。请使用内置形状：人员用shape=actor，数据库用shape=cylinder3
• 禁止箭头穿过无关容器——重新排列布局，使每个箭头在源和目标之间都有清晰的路径
• 禁止不使用labelBackgroundColor=#ffffff的标签——裸露的标签在穿过其他元素时变得不可读
• 禁止移除标签以解决重叠——如果标签与容器重叠，修复布局或偏移，切勿移除信息