next-ai-draw-io 图形形状库速查：全面解析 mxgraph 图标库目录体系与 AI 绘图调用机制

本文面向希望深入掌握 next-ai-draw-io（AI 结合 draw.io 的图表生成应用）图标能力的开发者与 AI 提示工程实践者。核心对象是仓库内 docs/shape-libraries/README.md 目录化图表文档，它定义了 33 类、4 281 个可被 AI 直接引用的 mxgraph 图形形状。读完本文，你将掌握其文档结构与 style 语法、逐库分类清单、单个形状库页面的使用模板，以及 get_shape_library 工具如何在 app/api/chat/route.ts 中被实现并喂给大模型的完整调用链路，从而能够为自己的图表生成场景正确选库、精确调用、避免"猜图标语法"的典型错误。

一、这批文档是什么：AI 图表生成的"形状目录"

draw.io 的图形本质上是由 style 属性驱动的，只要写出正确的形状标识，就能渲染出带图标的产品级图形。next-ai-draw-io 将海量 draw.io 官方/第三方形状以 Markdown 索引页的形式沉淀在 docs/shape-libraries 目录下，形成一张供大模型检索的"形状目录"。

整套体系的锚点是目录首页 docs/shape-libraries/README.md。它以一行核心约定开头，指明了所有图元引用的统一语法：

style="shape=mxgraph.<library>.<shape_name>"

也就是说，任意一个图标，最终都会被序列化到 draw.io XML 的 mxCell 元素的 style 字段中。接下来，README 按用途将库划分为 8 大类，并用"库名 / 形状数 / 前缀 / 描述 / 明细文档"五列给出索引，明细文档再逐个罗列可用的 shape 名称。

1.1 单个形状库文档的统一结构

以 docs/shape-libraries/flowchart.md 为例，每个明细页结构高度统一，包含四部分：

1. 元信息：Type（一律为 mxgraph shapes）与 Prefix（如 mxgraph.flowchart）；
2. Usage 用法模板：一段可直接粘贴的 <mxCell> XML 示例；
3. Shapes 完整清单：当前库支持的全部 shape 名称（小写 + 下划线风格）；
4. 分类归属：通过所在目录与 README 表格体现。

这种"索引页 + 明细页"的二级结构非常适合 RAG / 工具调用场景：模型先查 README 确定要用的库，再拉取单个文档获取精确到 shape 名的语法，始终不用"猜"。

1.2 两种前缀体系

汇总表揭示了 draw.io 形状的两大实现路线，这一点对理解 style 语法至关重要：

• 向量形状（绝大多数）：使用 mxgraph.xxx 作为形状引擎标识，例如 shape=mxgraph.aws4.ec2、shape=mxgraph.kubernetes.deploy；
• 位图/引用形状：少数组件并非纯向量，例如 azure2 的 Prefix 写为 img/lib/azure2/，意味着其图形资源以图片路径形式挂载，这与其余 32 个库的调用约定不同，使用前务必对照 azure2.md 确认。

二、33 个形状库完整目录（继承自 README）

下文按 README 原始分类顺序完整保留全部 33 个库的索引信息，并将相对链接统一转换为以仓库根为起点的路径，方便直接跳转细读。

2.1 云厂商（Cloud Providers）

库名	形状数	前缀	描述	明细文档
aws4	1031	mxgraph.aws4	Amazon Web Services（2025 版）——EC2、S3、Lambda、RDS 等	aws4.md
azure2	608	img/lib/azure2/	Microsoft Azure（2024 版）——VM、Storage、AI、Networking 等	azure2.md
gcp2	297	mxgraph.gcp2	Google Cloud Platform——Compute Engine、BigQuery、GKE 等	gcp2.md
alibaba_cloud	273	mxgraph.alibaba_cloud	阿里云——ECS、OSS、RDS、SLB、VPC 等	alibaba_cloud.md
openstack	18	mxgraph.openstack	OpenStack 云平台图标	openstack.md
digitalocean	74	mxgraph.digitalocean	DigitalOcean——Droplets、Spaces、Kubernetes 等	（当前仓库快照中暂无独立文档页）
salesforce	96	mxgraph.salesforce	Salesforce 平台图标	salesforce.md

2.2 网络与基础设施（Networking & Infrastructure）

库名	形状数	前缀	描述	明细文档
cisco19	232	mxgraph.cisco19	Cisco 网络设备——路由器、交换机、防火墙	cisco19.md
network	58	mxgraph.networks	通用网络图符号	network.md
arista	45	mxgraph.arista	Arista 网络交换机与设备	（当前仓库快照中暂无独立文档页）
kubernetes	40	mxgraph.kubernetes	Kubernetes——pod、service、deployment、node	kubernetes.md
vvd	93	mxgraph.vvd	VMware Validated Design 图标	vvd.md
rack	11	mxgraph.rack	服务器机架与数据中心设备	rack.md

2.3 业务流程（Business Process）

库名	形状数	前缀	描述	明细文档
bpmn	39	mxgraph.bpmn	BPMN 业务流程建模——事件、网关、任务	bpmn.md
eip	36	mxgraph.eip	企业集成模式——消息、路由	（当前仓库快照中暂无独立文档页）
lean_mapping	13	mxgraph.lean_mapping	精益 / 价值流图（VSM）符号	lean_mapping.md

2.4 通用图表（General Diagrams）

库名	形状数	前缀	描述	明细文档
flowchart	34	mxgraph.flowchart	标准流程图符号——处理、判定、数据	flowchart.md
basic	30	mxgraph.basic	基础形状——星形、横幅、标注框、爱心	basic.md
arrows2	34	mxgraph.arrows2	箭头形状与连接符	arrows2.md
infographic	29	mxgraph.infographic	信息图元素——图表、图标、徽章	infographic.md
sitemap	50	mxgraph.sitemap	网站站点地图图标——页面、表单、导航	sitemap.md

2.5 UI 原型（UI/Mockups）

库名	形状数	前缀	描述	明细文档
android	17	mxgraph.android	Android UI 原型组件	android.md

补充说明：在 lib/system-prompts.ts 的工具描述中还出现了 material_design（Material Design 图标），仓库内也确实提供了 material_design.md 明细页，只是它未被计入 README 首页表格。

2.6 企业软件（Enterprise Software）

库名	形状数	前缀	描述	明细文档
citrix	97	mxgraph.citrix	Citrix 虚拟化——XenApp、XenDesktop、NetScaler	citrix.md
sap	98	mxgraph.sap	SAP 企业软件图标	sap.md
mscae	73	mxgraph.mscae	Microsoft Cloud and Enterprise 符号	mscae.md
atlassian	26	mxgraph.atlassian	Atlassian——Jira、Confluence 问题类型	atlassian.md

2.7 工程制图（Engineering）

库名	形状数	前缀	描述	明细文档
fluidpower	246	mxgraph.fluid_power	液压 / 气动工程符号	fluidpower.md
electrical	50	mxgraph.electrical	电路符号——电阻、电容	electrical.md
pid	18	mxgraph.pid2	管道仪表流程图（P&ID）符号	pid.md
cabinets	53	mxgraph.cabinets	电气柜组件——断路器、端子	cabinets.md
floorplan	44	mxgraph.floorplan	平面图家具与固定设施	floorplan.md

2.8 图标与图形（Icons & Graphics）

库名	形状数	前缀	描述	明细文档
webicons	176	mxgraph.webicons	Web / 社交 Logo——GitHub、Twitter、AWS 等	webicons.md
un-ocha-icons	242	mxgraph.un-ocha-icons	联合国人道协调厅（UN OCHA）人道主义图标	（当前仓库快照中暂无独立文档页）

合计：33 个库，4 281 个形状（该汇总数来自 README；个别库的汇总表行数与明细页标题计数存在 ±1 量级的口径差异，例如 aws4 明细页标注 1 032 个而表格写 1 031、flowchart 明细页罗列 35 个而表格写 34，引用时应以各明细页的 Shapes 清单为准）。

三、明细文档的四种典型用法模板

逐个阅读各库明细页可以发现，虽然结构一致，但按形状引擎不同，style 拼法可分为四类。下面给出可直接套用的 XML 模板。

3.1 直接形状类（最通用，如 flowchart、basic、webicons、arrows2）

这是最简单的一类：shape=mxgraph.<library>.<shape_name> 直接决定渲染结果。以 flowchart.md 为例：

<mxCell value="label" style="shape=mxgraph.flowchart.{shape};fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="60" height="60" as="geometry" />
</mxCell>

{shape} 替换为目标形状名。fillColor、strokeColor、width、height 等均为 draw.io 通用样式属性，可在模板基础上自由调整。同一套模式也适用于基础图形库 basic.md（shape=mxgraph.basic.{shape}，内置 4_point_star、6_point_star、cloud_callout、heart、banner、document、flash、half_circle 等 31 个形状）与社交 Logo 库 webicons.md（内置 github、twitter、amazon、apple、android、apache、atlassian、adobe_pdf 等 177 个形状）。

3.2 云资源双属性类（aws4：resourceIcon + resIcon）

AWS 库的图标大多拆成"资源容器 + 子图标"两层，需要同时给两个属性赋值。以 aws4.md 提供的模板为例：

<mxCell value="label" style="shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{shape};fillColor=#ED7100;strokeColor=#ffffff;verticalLabelPosition=bottom;verticalAlign=top;align=center;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="60" height="60" as="geometry" />
</mxCell>

外层 shape=mxgraph.aws4.resourceIcon 是统一资源承载形状，内层 resIcon=mxgraph.aws4.{shape} 才是真正决定"画的是 EC2 还是 S3"的子属性。文档同时提示，简单形状也可退化为单属性写法：

style="shape=mxgraph.aws4.{shape};fillColor=#232F3D;"

aws4 是全仓库最大也是最"新"的库（截至文档标注的 2025 版资源集），明细页罗列了超过 1 000 个名称，覆盖从 ec2、s3、lambda、api_gateway、dynamodb、bedrock、amplify 等热门服务，到各类 *_instance 计算实例族与 group 系列分组容器，完整清单见 aws4.md。

3.3 专用前缀图标类（kubernetes：icon + prIcon）

Kubernetes 库走的是另一套 prIcon 属性，模板如下（kubernetes.md）：

<mxCell value="label" style="shape=mxgraph.kubernetes.icon;prIcon={shape};fillColor=#326CE5;strokeColor=none;verticalLabelPosition=bottom;verticalAlign=top;align=center;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="60" height="60" as="geometry" />
</mxCell>

{shape} 部分直接写形状短名即可，例如 deploy、pod、svc、ds、cm、ep、cronjob、etcd、crd、crb、c_role、api、frame 等 41 个名称。这类"容器形状 + 子图标键"的设计提醒我们：不要跨库套用属性名，aws4 用 resIcon、kubernetes 用 prIcon，一律以对应明细页 Usage 段落为准。

3.4 图片前缀类（azure2）

azure2 属于位图资源型，Prefix 为 img/lib/azure2/，与上述所有 mxgraph.* 引擎不同，样式书写与图片装载路径有关，具体示例以 azure2.md 的 Usage 段落为准。

3.5 一个完整示例：flowchart 全部 35 个形状清单

为确保"可用形状可穷举、可检索"，明细页会给出全部形状名。以 flowchart.md 为例，其 35 项清单完整罗列如下，覆盖 ANSI/ISO 流程图的绝大多数语义节点：

annotation_1、annotation_2、card、collate、data、database、decision、delay、direct_data、display、document、extract_or_measurement、internal_storage、loop_limit、manual_input、manual_operation、merge_or_storage、multi-document、mxgraph.flowchart、off-page_reference、on-page_reference、or、paper_tape、parallel_mode、predefined_process、preparation、process、sequential_data、sort、start_1、start_2、stored_data、summing_function、terminator、transfer

（注意其中 multi-document 使用连字符而非下划线、start_1/start_2 有数字后缀、还包含一个与库同名的 mxgraph.flowchart 兜底项——这些小细节正是"宁可查库、不可臆测"的理由。）

四、底层原理：文档如何被 get_shape_library 工具在运行时消费

这套 Markdown 文档并不是给人看的"死资料"，而是被 AI 会话作为函数工具的动态检索源打通了。调用链路在源码中有完整证据。

4.1 提示词层：强制"先查库、后绘图"

在 lib/system-prompts.ts 中，系统提示词显式声明了工具契约：

• 第 53 行附近声明工具 get_shape_library，说明其作用是"获取形状 / 图标库文档，用于在创建带特殊图标的图形之前发现可用形状（AWS、Azure、GCP、Kubernetes、Material Design 等）"；
• 第 64 行要求：使用任何图标库绘制前先调用 get_shape_library 进行发现，且必须在 display_diagram 之前调用；
• 第 95 行以近乎强制的口吻强调：绘制云/技术架构图或使用图标库（material_design、webicons 等）时，必须先查 get_shape_library，绝不猜测图标样式语法（"NEVER guess icon style syntax — always look it up first"）。

从提示工程角度看，docs/shape-libraries 这套文档正好充当了工具可读的"受控词表"，把大模型从"幻觉图标名"的风险中约束回可验证的真实形状集合。

4.2 实现层：读取、清洗与路径安全

get_shape_library 工具在 app/api/chat/route.ts 第 716 行起注册。其 execute 实现（第 737-777 行）值得细读，它体现了直接暴露文件系统给 LLM 时的安全编码范式：

1. 参数清洗（第 739-745 行）：将 library 参数转小写并剔除所有非 [a-z0-9_-] 字符；若清洗前后不一致，直接返回 Invalid library name ...，从根上拦截路径穿越载荷；
2. 路径拼接与越界校验（第 747-760 行）：以 process.cwd() + "docs/shape-libraries" 为 baseDir，拼出 ${sanitizedLibrary}.md 后通过 path.resolve 再用 startsWith 校验真实路径仍落在 baseDir 之内，构成第二道防线；
3. 读取与容错（第 762-777 行）：用 fs.readFile 读取明细文档并原样返回给模型；若 ENOENT 未找到，则返回一条包含可用库名单的 Library "..." not found. Available: ... 消息（其中点名了 aws4、azure2、gcp2、alibaba_cloud、cisco19、kubernetes、network、bpmn、flowchart、basic、arrows2、vvd、salesforce、citrix、sap、mscae、atlassian、fluidpower、electrical、pid、cabinets、floorplan、webicons、infographic、sitemap、android、material_design、lean_mapping、openstack、rack 等可加载库）；其他 IO 异常则返回提示重试的错误信息。

将两份清单对照可以发现细节：运行时"可加载"列表以实际存在的 md 文件为准（包含 README 首页未收录的 material_design），而 README 表格中 digitalocean、arista、eip、un-ocha-icons 四个库在当前仓库快照中尚无对应明细文件，若直接调用会命中 ENOENT 分支。

4.3 前端交互：工具调用对用户可见

工具调用会作为结构化消息流转到前端：components/chat/ToolCallCard.tsx 负责渲染这类"AI 正在查库/调用工具"的卡片。换句话说，当用户对着聊天框说"画一张 AWS 架构图"时，用户通常能看到模型先触发 get_shape_library 查 aws4、随后再产出图元的完整过程。

4.4 端到端佐证：缓存的真实 AWS 示例 XML

这套形状语法在项目里不是"理论可行"，而是已有真实产出佐证。lib/cached-responses.ts 第 257-282 行内置了一份 AWS 架构示例 XML（作为响应缓存/兜底示例），其中就大量使用 aws4 形状：

<mxCell id="2" value="AWS" style="...shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud;strokeColor=#232F3E;fillColor=none;..." vertex="1" parent="1">
<mxCell id="3" value="User" style="...shape=mxgraph.aws4.user;rounded=1;" vertex="1" parent="1">
<mxCell id="4" value="EC2" style="...aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2;rounded=1;" vertex="1" parent="1">
<mxCell id="5" value="S3" style="...shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.s3;..." vertex="1" parent="1">

这段缓存可见三个关键事实：其一，mxgraph.aws4.group + grIcon=mxgraph.aws4.group_aws_cloud 用于绘制"云边界"容器；其二，shape=mxgraph.aws4.user 这类简单形状走单属性路线；其三，EC2/S3/Bedrock/DynamoDB 等资源全部走 resourceIcon + resIcon 双属性路线，与 aws4.md 模板完全一致。它证明了"文档模板 → 模型调用 → 可渲染 XML"的整条链路真实闭环。

五、实战建议与扩展指南

结合上述源码证据，给出落地建议：

1. 按语义域选库，不跨域硬凑：云架构优先 aws4 / azure2 / gcp2 / alibaba_cloud / kubernetes；网络拓扑用 cisco19 / network；业务流用 bpmn / flowchart / eip；界面原型用 android / material_design；装饰与 Logo 用 basic / webicons。跨领域混用虽语法兼容，但视觉语言（配色、线型、比例）会显著不协调。
2. 永远先查库再写 style：形状名以明细页 Shapes 清单为准，注意三类"坑"——下划线命名（lean_mapping）、连字符例外（multi-document）、数字后缀（start_1）。若自行搭建 Agent，应把 get_shape_library 声明为"必须在绘图工具前调用"的前置工具，并在提示词中禁止臆测图标语法。
3. 复用模板时只改关键属性：resIcon/prIcon/grIcon 这类属性是库专属的，套用模板时不要删除，只替换其中的 {shape} 占位符；尺寸、填充色、标签位置可按 draw.io 通用规则调整。
4. 扩展新库的最小改动集：从源码调用链可以推断，新增一个库只需要三处配合——(a) 在 docs/shape-libraries 下新建 <library>.md（沿用"Type / Prefix / Usage / Shapes"四段式）；(b) 若要在目录页露出，同步更新 docs/shape-libraries/README.md 的分类表格；(c) 更新 app/api/chat/route.ts 第 719-727 行工具描述中的库清单及 ENOENT 回退名单（第 769 行），保证"文档-提示词-工具"三者一致。
5. 以明细页为唯一事实源：汇总表的总形状数与明细页清单存在细微口径差异（如 aws4 的 1 031 与 1 032、flowchart 的 34 与 35），任何涉及精确可用性的决策都应直接核对对应 .md 的 Shapes 段落。

六、相关源码与测试入口

• 目录索引与 33 库清单：docs/shape-libraries/README.md
• 明细文档示例（四类语法范式）：aws4.md（resIcon）、kubernetes.md（prIcon）、flowchart.md（直接形状 + 全量清单）、webicons.md（社交 Logo）、azure2.md（图片前缀）
• 工具注册与安全实现：app/api/chat/route.ts（第 716-778 行）
• 强制"先查库后绘图"的提示词规则：lib/system-prompts.ts（第 53、64、95 行）
• 真实 aws4 XML 产出样本：lib/cached-responses.ts（第 257-282 行）
• 工具调用前端可视化：components/chat/ToolCallCard.tsx