next-ai-draw-io 箭头图元库指南：掌握 mxgraph.arrows2 的 18 种箭头形状与 AI 绘图集成

arrows2 是 next-ai-draw-io 所集成 draw.io 形状库体系中的「通用箭头图元」库，属于 mxgraph shapes 模板类型，前缀为 mxgraph.arrows2。本文以 docs/shape-libraries/arrows2.md 为主体，系统讲解它的 style 语法、18 种可用图元、XML 落地写法，并结合本仓库 AI 聊天后端如何动态读取这些图元文档供大模型绘制图表，帮助你既能在人工编辑时手写箭头，也能理解并校验 AI 生成的箭头 XML。

一、认识 arrows2：draw.io 的 mxgraph 模板图元库

1.1 形状库在仓库中的位置与作用

在 next-ai-draw-io 仓库中，docs/shape-libraries/ 目录集中存放了 draw.io 各形状库的图元文档，整体索引见 形状库总览，其中把 arrows2 归类为「通用图形（General Diagrams）」下的箭头与连接图形状库。

这些 Markdown 文档并非仅供人阅读的静态说明，而是被后端以“运行时可查询文档”的方式暴露给 AI 模型：当模型需要绘制带箭头图元的图表时，会通过工具调用读取对应文件获得准确的形状名与 style 写法，从而避免凭空猜测图元语法（详见后文“与 AI 绘图流程的集成”）。

1.2 元信息解读

arrows2.md 首部给出了三个关键元信息：

• Type: mxgraph shapes：指明该库图元属于 draw.io 的 mxgraph 模板类型（stencil）。在 draw.io 中，这类图元与基础几何形状（rounded=1、ellipse 等）不同，它们由独立的 SVG 模板注册而来，style 中必须通过 shape=mxgraph.<库名>.<图元名> 指定；
• Prefix: mxgraph.arrows2：这是 style 值中的库前缀，实际引用某个图元时，写成 shape=mxgraph.arrows2.<shape_name>；
• Shapes (18)：该库共收录 18 个箭头类图元。

一致性提示：根级索引表 README 中标注 arrows2 的图元总量为 34，而本文件声明并逐一列举了 18 个；两者统计口径存在差异。AI 通过 get_shape_library 工具实际读取到的是本文件内容，因此以 arrows2.md 内列举的 18 个为准。

二、style 语法与完整 XML 解析

2.1 文档给出的最小可用示例

<mxCell value="label" style="shape=mxgraph.arrows2.arrow;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="100" height="60" as="geometry" />
</mxCell>

逐段拆解这个示例，它就是理解全部 18 个图元的基础：

片段	含义
value="label"	图元上显示的文本标签，可为空字符串
shape=mxgraph.arrows2.arrow	指定渲染该图元的模板：shape= + 库前缀 mxgraph.arrows2 + . + 图元名 arrow
fillColor=#dae8fc	填充色。#dae8fc 是 draw.io 默认的浅蓝，推荐与 draw.io 内置默认色板保持一致
strokeColor=#6c8ebf	描边色，#6c8ebf 是与 #dae8fc 配套的深蓝描边
vertex="1"	该 cell 是顶点（图形）而非连线（edge）
parent="1"	挂在 id 为 1 的默认根 cell 下
<mxGeometry ... as="geometry" />	几何信息：x/y 为画布坐标，width/height 为尺寸，单位均为像素

style 中各属性用分号 ; 分隔，末尾保留一个分号是 draw.io 的常见风格，但不是必须。颜色推荐直接沿用示例中的 draw.io 经典色板：浅蓝填充 #dae8fc 配描边 #6c8ebf；同类默认色还有浅绿（#d5e8d4/#82b366）、浅橙（#ffe6cc/#d79b00）、浅黄（#fff2cc/#d6b656）、浅红（#f8cecc/#b85450）、浅紫（#e1d5e7/#9673a6）等，可用于区分不同的箭头语义。

2.2 关键点：这些图元是 vertex，不是 edge

arrows2 的 18 个图元全部通过 vertex="1" 挂在画布上，属于独立图形符号——它们不像 endArrow=classic 那样依附于连接线，而是可以放置在流程图的任意位置，充当“单/双向箭头块”“标注箭头”“转向/汇入标记”等装饰性或流程性符号。

这与本仓库对连线的约定是两套体系，lib/system-prompts.ts 中对连线（edge）的要求是 endArrow=classic 配合 edgeStyle=orthogonalEdgeStyle 等属性（第 152-155 行），而本文件的箭头图元则走 shape=mxgraph.arrows2.xxx 的模板路径，二者不要混用。

三、18 种箭头图元全清单与用途参考

arrows2.md 按字母顺序完整列出 18 个图元名，它们全部以 shape=mxgraph.arrows2.<name> 的方式引用。按命名语义可大致分为三类（用途为命名推断，最终视觉效果请以 draw.io 渲染为准）：

3.1 基础箭头类

shape 名称	命名语义参考
arrow	基础单箭头，文档示例所用图元
sharpArrow	锐利直边的箭头，风格更硬朗
sharpArrow2	sharpArrow 的变体，细节轮廓不同
stripedArrow	带条纹纹理的箭头
stylisedArrow	造型化/装饰化箭头
tailedArrow	带“尾巴”（尾部延长杆）的箭头
tailedNotchedArrow	尾部带缺口/锯齿造型的箭头
triadArrow	三叉箭头造型
twoWayArrow	双向箭头（两个方向都可指示）

3.2 弯曲/转折类

shape 名称	命名语义参考
bendArrow	弯折一次的单箭头
bendDoubleArrow	弯折的双向箭头
uTurnArrow	U 形掉头箭头

3.3 标注/多向类

shape 名称	命名语义参考
calloutArrow	带引出/标注性质的箭头
calloutDoubleArrow	双侧标注箭头
calloutDouble90Arrow	呈 90° 分布的双侧标注箭头
calloutQuadArrow	四向标注箭头
jumpInArrow	“跳入/汇入”形态箭头
quadArrow	四向箭头

引用清单时最稳妥的做法是先查文档再写 style：本仓库系统提示词也明确要求模型“当使用图标库时必须先调用 get_shape_library 获取正确语法，绝不猜测图标样式语法”（lib/system-prompts.ts 第 95-96 行），这正是 arrows2.md 这类文档存在的意义。

四、可直接运行的完整 XML 示例

4.1 单图元（可直接粘贴到 draw.io 编辑器）

下面是一段完整的可导入 XML，画布上包含 4 种代表性箭头图元：

<mxfile host="app.diagrams.net" type="device">
  <diagram id="arrows2_demo" name="arrows2-demo">
    <mxGraphModel dx="900" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="a1" value="arrow" style="shape=mxgraph.arrows2.arrow;fillColor=#dae8fc;strokeColor=#6c8ebf;fontColor=#333333;" vertex="1" parent="1">
          <mxGeometry x="60" y="80" width="120" height="60" as="geometry" />
        </mxCell>
        <mxCell id="a2" value="twoWayArrow" style="shape=mxgraph.arrows2.twoWayArrow;fillColor=#d5e8d4;strokeColor=#82b366;fontColor=#333333;" vertex="1" parent="1">
          <mxGeometry x="60" y="200" width="120" height="60" as="geometry" />
        </mxCell>
        <mxCell id="a3" value="bendArrow" style="shape=mxgraph.arrows2.bendArrow;fillColor=#ffe6cc;strokeColor=#d79b00;fontColor=#333333;" vertex="1" parent="1">
          <mxGeometry x="60" y="320" width="140" height="90" as="geometry" />
        </mxCell>
        <mxCell id="a4" value="calloutQuadArrow" style="shape=mxgraph.arrows2.calloutQuadArrow;fillColor=#e1d5e7;strokeColor=#9673a6;fontColor=#333333;" vertex="1" parent="1">
          <mxGeometry x="60" y="460" width="160" height="160" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

其中 id="0"、id="1" 是 draw.io 必需的根节点结构：id="0" 为模型根，id="1" 为默认图层，业务图元统一 parent="1"。这段结构与本仓库 public/aws_demo.svg 等内置演示文件内嵌的 mxfile → diagram → mxGraphModel → root 结构一致。

4.2 在流程图中组合使用（箭头图元 + 文本框 + 连线）

箭头图元最常见的用法是充当流程方向指示块，例如表示“过程 A → 过程 B”之间的双向数据流，可与普通文本框、orthogonal 连线自由混排：

<mxCell id="p1" value="请求方" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="80" y="140" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="p2" value="服务方" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
  <mxGeometry x="500" y="140" width="120" height="60" as="geometry" />
</mxCell>
<mxCell id="sync" value="双向同步" style="shape=mxgraph.arrows2.bendDoubleArrow;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="260" y="150" width="180" height="40" as="geometry" />
</mxCell>
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;exitX=1;exitY=0.5;entryX=0;entryY=0.5;endArrow=classic;html=1;" edge="1" parent="1" source="p1" target="p2">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

上例说明两类元素的协作关系：箭头图元负责“承载语义符号与文字”，edge 负责“把各节点真正连接起来”，两者在 XML 中可以共存。

五、与 next-ai-draw-io 的 AI 绘图流程集成

本仓库的特色在于：以上文档不只在人工绘图中生效，还会在 AI 对话式绘图时被实时查询。整个调用链如下：

5.1 运行时工具读取（服务端）

app/api/chat/route.ts 在向模型注册的 tools 中定义了 get_shape_library（第 716-777 行）。该工具：

1. 描述中显式列出可用库，其中「General」分组包含 arrows2（第 723 行）；
2. 对传入的 library 名做小写化并过滤非 [a-z0-9_-] 字符（第 739-745 行），再将路径拼接限定在 docs/shape-libraries 目录内并做 path.resolve 前缀校验（第 747-760 行），防止路径穿越攻击；
3. 读取对应 .md 文件全文并原样返回给模型（第 762-764 行），即模型拿到的是与本文同源的 arrows2.md 清单；
4. 若库不存在，返回包含全部可用库名的提示，其中同样包含 arrows2（第 769 行）。

因此，当用户在 next-ai-draw-io 的聊天框中要求绘制含箭头符号的图时，模型可先调用该工具拿到 shape=mxgraph.arrows2.xxx 的准确写法，再按 XML 生成规范输出图元。

5.2 系统提示词侧配合

lib/system-prompts.ts 对模型的约束与之呼应：绘制云端/技术类或需要使用图标库的图表时，必须先调用 get_shape_library 查找可用图元与语法，“绝不猜测图标样式语法”（第 95-96 行）。这说明像 arrows2.md 这样的图元清单承担着防幻觉数据源的角色——把“18 个图元叫什么、怎么写”从模型记忆迁移到文档检索。

同时系统提示词中的通用样式说明（lib/system-prompts.ts 第 194-199 行）与 arrows2.md 的示例完全兼容：fillColor、strokeColor、fontSize 等均为 draw.io 通用样式属性，可直接叠加在 shape=mxgraph.arrows2.* 上。

六、使用与排查要点

1. 库前缀要写全：是 shape=mxgraph.arrows2.xxx 而非 shape=arrows2.xxx。漏掉 mxgraph. 前缀会导致 draw.io 无法解析该 stencil。
2. 图元名大小写敏感：如 bendArrow、calloutDouble90Arrow、stylisedArrow、uTurnArrow 等均为驼峰式，书写必须与清单一致；模型查询返回的清单（本文件）就是唯一权威来源。
3. 区分图元与连线：箭头图元放在 vertex="1" 的 cell 中；若需“可吸附的连接线箭头”，应使用 edge（edge="1" + endArrow）。二者适用场景不同，不要互相替代。
4. 旋转/朝向调整：不同图元模板对宽度、高度的渲染比例不同（如 bendArrow 需要较高高度才能呈现弯折形态），画布预览时如形态比例不对，优先调整 mxGeometry 的宽高；具体每个模板支持哪些额外样式参数，以 draw.io 实际渲染效果为准。
5. 颜色遵循 draw.io 默认色板：示例中 #dae8fc（填充）与 #6c8ebf（描边）来自 draw.io 默认样式，混搭其他默认配色可让 AI 生成或人工书写的箭头在明暗主题下都保持良好的对比度（本仓库支持深浅主题切换，见 lib/system-prompts.ts 第 28 行附近对主题切换的描述）。

七、小结

arrows2 库以 mxgraph.arrows2 为前缀、通过 shape= 样式属性提供了 18 种开箱即用的箭头符号。在 next-ai-draw-io 中，arrows2.md 既是人工写图时的手册，也是 AI 模型通过 get_shape_library 工具 实时查询的数据源。掌握「先查文档 → 再写 style」的工作流，就能在自然语言绘图、XML 校验与手动调参之间无缝衔接，稳定产出符合 draw.io 规范的箭头图形。