next-ai-draw-io 基础图形库（mxgraph.basic）完全指南：30 种 draw.io 形状的 XML 引用与 AI 绘图实战

本指南以 docs/shape-libraries/basic.md 为核心文档，系统讲解 next-ai-draw-io 中 mxgraph.basic 基础图形库的引用语法、30 种可用形状的名称与语义分组、以及它们在 draw.io 原生 XML（mxCell/mxGeometry）中的落地写法。读完你将掌握：如何手工或借助 AI 在 draw.io 画布中精确放置星形、心形、标注气泡、文档等基础元素，并理解这份 shape library 文档在项目"AI 生成图表"链路中扮演的角色。

basic 图形库在项目中的定位

在 next-ai-draw-io 中，draw.io 图形以大量第三方形状库（shape library）的方式组织，总索引见 docs/shape-libraries/README.md，共收录 33 个库、4000+ 形状。basic 库归属 "General Diagrams"（通用图形）分类，索引中的定位是：

Basic shapes - stars, banners, callouts, hearts（星形、横幅、标注气泡、心形等基础形状），共 30 个形状，前缀 mxgraph.basic。

basic 库的特点是不依赖任何云厂商或行业语境，由纯几何图形与通用符号构成，适合做流程图节点、重点标注、装饰性强调，也常被 AI 用作"艺术化表达"（如拼出简单插画）的素材，这与 lib/system-prompts.ts 中要求模型"creatively compose them using standard diagram shapes and connectors"（用标准图形与连接线进行创造性组合）的能力描述相吻合。

这些库文档不仅是给人看的参考，更是运行时被 AI 调用的数据源：后端在 app/api/chat/route.ts 注册了名为 get_shape_library 的工具，其 execute 逻辑会读取 docs/shape-libraries/{library}.md 并把全文返回给大模型。也就是说，basic.md 的每一个形状名都会被真实注入到模型的上下文中，成为其生成合法 mxgraph.basic.* 样式语法的事实依据。

快速上手：一个形状的最小 XML

以官方用法为例，要在 draw.io 画布上放置一个 60×60 的基础图形，只需一条独立的 <mxCell> 顶点元素（下划线部分为占位符，替换为下文的形状名即可）：

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

把占位符换成实际形状，例如 star，即得到一张可渲染的黄底描边星形：

<mxCell value="重点" style="shape=mxgraph.basic.star;fillColor=#fff2cc;strokeColor=#d6b656;strokeWidth=2;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="80" y="120" width="120" height="120" as="geometry" />
</mxCell>

对照 components/dev-xml-simulator.tsx 中内置的模拟 XML 片段可以看出，style 支持追加 html=1;whiteSpace=wrap; 让文字自动换行、strokeWidth 控制描边粗细等常规 draw.io 样式键；value 即图形内文字标签，可为中文或任意文本。mxgraph.basic 形状本质仍是 mxgraph 顶点，因此样式键与 mxGraphModel 图元的规则完全一致。

mxCell 结构逐字段拆解

• vertex="1"：声明该 mxCell 是一个顶点（图形节点）而非连线，连线使用 edge="1"（edge 定义可见 app/api/chat/route.ts）。
• parent="1"：声明父容器为顶层根单元格（id 为 1），若需把图形嵌套进泳道或容器，可将 parent 指向对应容器 cell 的 id（app/api/chat/route.ts 中泳道与步骤的嵌套即为此模式）。
• value="label"：图形上显示的文字。
• style：关键样式串。shape=mxgraph.basic.<shapeName> 决定调用哪一个基础图形；fillColor 为填充色、strokeColor 为描边色，示例采用的 #fff2cc / #d6b656 是一组柔和的暖黄色配色。
• <mxGeometry>：定义几何信息，x/y 为该元素左上角在画布中的像素坐标，width/height 为宽高，as="geometry" 是 mxgraph 固定写法。

项目对"由 AI 生成"的 XML 有明确约束：模型只输出 <mxCell> 元素本身，不得包含 <mxfile>、<mxGraphModel>、<root> 等外层包装标签（见 app/api/chat/route.ts），前端在解析时再统一包裹为标准结构：<mxfile><diagram ...><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>（实现于 components/chat-message-display.tsx）。因此你在手工编写或向 AI 下达绘图指令时，只需提供完整的 mxCell 元素即可。

全部形状清单与语义分组

basic.md 原始列表标题为 "Shapes (31)"，但逐条核对后可见其中第 15 项是 mxgraph.basic——即库名前缀本身而非具体形状，因此实际可用形状为 30 个，恰好与 docs/shape-libraries/README.md 中 "basic | 30" 的统计一致。全部形状名可直接用于 style="shape=mxgraph.basic.<name>;..."，按命名语义大致可分为以下几组。

星形与发光类

形状名	语义（从命名推断）	典型用途
4_point_star	四角星	闪光点缀、地图标记
6_point_star	六角星	魔法/强调元素、旗帜上的星
8_point_star	八角星	装饰性强调
star	通用五角星	评分、重点标注、标题点缀
flash	闪电	提示危险/高性能/即刻执行
sun	太阳	能量、状态、时段表达
moon	月亮	夜间/休眠状态表达

多边形与几何体

形状名	语义（从命名推断）	典型用途
cone	圆锥	漏斗、金字塔抽象表达
cross	十字	医疗、阻断、位置标记
half_circle	半圆	拱形、容器盖等组合素材
octagon	八边形	停止/警示流程节点（欧美交通语义）
orthogonal_triangle	直角（正交）三角	台阶/增长示意、流程选择变体
parallelepiped	平行六面体（斜立方）	3D 立体感的容器/对象表达
pentagon	五边形	安全/审批类流程节点
pointed_oval	尖角椭圆（泪滴形）	标注起点、动线表达
trapezoid	梯形	泳道首行、转换/汇聚节点

标注气泡类（callout）

形状名	语义（从命名推断）	典型用途
cloud_callout	云朵形对话气泡	想法、评论、异步消息
loud_callout	尖角大声气泡	强调性提醒、报警
oval_callout	椭圆气泡	温和的旁注解释
rectangular_callout	矩形气泡	结构化注释框
rounded_rectangular_callout	圆角矩形气泡	更现代柔和的注释框

文档与横幅类

形状名	语义（从命名推断）	典型用途
document	文档（折角页）	文件、需求、报告节点
banner	横幅	章节标题、宣传条

符号与图案类

形状名	语义（从命名推断）	典型用途
no_symbol	禁止符（圆圈斜杠）	禁用、不可达状态
tick	对勾	通过、验证完成
x	叉号	拒绝、失败、删除
heart	心形	喜欢、健康、情感标记
smiley	笑脸	满意度、状态、人格化节点
wave	波浪	水/声波/流动感
cloud_rect	云形圆角矩形	混合图形、柔和容器

需要说明：上述分组与"语义推断"仅基于形状命名词义，供构图选型时参考，具体外观请以 draw.io 渲染结果为准。引用任意形状时统一格式为 shape=mxgraph.basic.<name>，形状名中不要加空格或引号。

颜色与样式定制

示例中给出的基础配色可直接沿用，也可按 draw.io 任意 hex 色值替换：

<mxCell value="OK" style="shape=mxgraph.basic.tick;fillColor=#d5e8d4;strokeColor=#82b366;strokeWidth=2;" vertex="1" parent="1">
  <mxGeometry x="20" y="20" width="60" height="60" as="geometry" />
</mxCell>

fillColor 与 strokeColor 同时省略时，图形将回落到主题默认样式；若只想保留外框线条（如把标注气泡用作纯注释框），可设 fillColor=none。参考 components/dev-xml-simulator.tsx 中内置示例，常规 draw.io 样式键（rounded、whiteSpace、html、strokeWidth 等）均可与 shape=mxgraph.basic.* 混合使用。兄弟库示例（如 docs/shape-libraries/flowchart.md 使用绿色 #d5e8d4/#82b366）也采用了同样的"库前缀 + 几何 + 配色"三段式结构，便于跨库保持视觉一致。

在 AI 绘图工作流中的实战用法

next-ai-draw-io 的右栏是对话式 AI 绘图入口。系统提示词 lib/system-prompts.ts 明确要求模型：凡涉及图标/图形库，必须先调用 get_shape_library 工具查证语法，绝不凭空猜测（"NEVER guess icon style syntax — always look it up first"，见 lib/system-prompts.ts 与 L95）。basic 库与 flowchart、arrows2、infographic、sitemap 一并被列为 "General" 通用库（见 app/api/chat/route.ts）。

因此实际使用中并不需要人肉记忆全部 30 个形状名，可这样与 AI 协作：

1. 用自然语言下达任务，例如"给我画一张使用流程草稿图，用太阳表示开始、闪电表示加速环节、禁止符标出不可操作步骤"；
2. 模型会先调用 get_shape_library(library="basic") 读取 docs/shape-libraries/basic.md 的完整形状清单，校验 sun/flash/no_symbol 这些名称是否真实存在及其正确拼写；
3. 确认后模型通过 display_diagram / edit_diagram / append_diagram 工具输出仅含 <mxCell> 的 XML（工具语义见 lib/system-prompts.ts），前端自动完成包装与渲染。

对人工编写 XML 的场景，同样遵循"先查文档后写样式"：先在 docs/shape-libraries/basic.md 中确认形状名，再用上文的最小 XML 模板替换即可。若想让基础图形在图中承担结构化角色，可把 parent 指向泳道等容器实现嵌套，或把多个基础图形分别以 id 关联起来、再增加一条 edge="1" 的连线表示流向。

延伸阅读

• 总索引与全部 33 个库的对照表：docs/shape-libraries/README.md
• 同分类通用库：docs/shape-libraries/flowchart.md（流程图标准符号）、docs/shape-libraries/arrows2.md（箭头与连接线）
• 工具实现源码：get_shape_library 读取与路径防护逻辑见 app/api/chat/route.ts；模型端工具说明与"先查询再生成"约束见 lib/system-prompts.ts
• XML 组装细节：mxCell 嵌套与 wrapper 自动包裹见 components/chat-message-display.tsx；可运行的本地模拟片段见 components/dev-xml-simulator.tsx