next-ai-draw-io 液压与气动符号库（fluidpower）接入参考：mxgraph.fluid_power 图形风格、247 个形状清单与 AI 生成集成

2026-09-08 16:41:47作者：庞眉杨Will

A next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.

项目地址：https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io

本指南围绕 fluidpower.md 展开，介绍 next-ai-draw-io 内置的液压/气动工程符号库：它属于 draw.io 的 mxgraph 形状体系，以 mxgraph.fluid_power 为统一前缀，为 AI 自然语言生成液压原理图、气动回路图等工程图提供可直接引用的样式与形状名。读完本文，你将掌握该库的完整用法（XML 语法、247 条形状名称）、在整页 draw.io XML 中的嵌套规则，以及 AI 侧通过 get_shape_library 工具在运行时加载这份参考文档的底层调用链（对应 app/api/chat/route.ts 的实现）。

一、文档定位：fluidpower 是工程图纸素材库之一

在 next-ai-draw-io 中，绘制画布基于 draw.io 的 XML/样式体系，而各类专业符号（云厂商图标、网络设备、电气元件、液压符号等）被组织在 docs/shape-libraries 目录下，作为“可被 AI 查询的形状字典”。总览见 docs/shape-libraries/README.md，其中 fluidpower 被归类在 Engineering（工程） 分组的表格中：

库名	形状数	前缀	说明	文档
fluidpower	246	`mxgraph.fluid_power`	Hydraulic/pneumatic engineering symbols	fluidpower.md

需要特别指出：README 汇总表记录为 246 个形状，而 fluidpower.md 头部标题写的是 Shapes (247)。差异的原因是文档的 247 条列表把“库本身的根入口 mxgraph.fluid_power”也算作第 1 条，其后跟随 246 条形如 x10010、x10020 的实际图形条目（经统计：以 x 开头的条目恰好 246 条，且无重复）。下文统称“246 个具体图形符号 + 1 个库根符号”。

二、基本规格：Type 与 Prefix

fluidpower 库的核心规格如下，它决定了该库所有图形的 style 书写方式：

Type（形状类型）：mxgraph shapes——即这些图形并非 rounded=1、ellipse 之类的内置几何形状，而是 draw.io/mxgraph 注册的扩展渲染形状，必须通过 shape=mxgraph.xxx.yyy 才能触发对应的矢量渲染逻辑。
Prefix（统一前缀）：mxgraph.fluid_power——库内每个图形的完整样式名 = 前缀 + 具体图形名，如 mxgraph.fluid_power.x10010。

也就是说，只要在样式字符串中出现以 mxgraph.fluid_power. 开头的 shape=，draw.io 渲染引擎就会加载流体动力符号的绘制代码来绘制该单元格。

三、XML 用法模板与逐字段拆解

文档给出的标准用法模板如下：

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

把它落地到真实形状（例如 x10010）就是：

<mxCell id="2" value="Pump" style="shape=mxgraph.fluid_power.x10010;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="120" y="80" width="60" height="60" as="geometry" />
</mxCell>

模板中的关键字段作用如下：

value：单元格显示的文字标签（示例中的 label 是占位，可按需替换为空串或元件描述文字）。
style：核心是 shape=mxgraph.fluid_power.{shape}，其中 {shape} 用第四节清单中的形状名（如 x10010、x12170）替换。文档模板保留了 fillColor=strokeColor; 的字样，它表示颜色区通常与描边色联动或可统一替换；实际使用时建议像上面的示例一样为 fillColor 与 strokeColor 显式指定 draw.io 颜色值，例如以浅色填充区分泵/阀/缸等不同回路元件。
vertex="1"：声明该 mxCell 是一个图形顶点（形状）而不是连线。
parent="1"：父容器为默认图层单元格。
<mxGeometry>：x/y 为左上角坐标，width/height 为宽高。文档示例默认使用 60×60 的正方形包围盒，这也是多数液压符号的较合适初始尺寸；可按需要调整（例如细长阀件可拉宽为 80×40）。

补充说明：mxCell、mxGeometry 的完整语义、连线（edge="1"、source/target）以及 style 语法可进一步参考项目的 XML 指南。fluidpower 文档本身只给出符号的形状名与基础用法，每个编号对应的图形外观由 draw.io/mxgraph 运行时按 mxgraph.fluid_power.* 定义解析渲染，仓库中的这份 md 仅作为名称/样式清单供 AI 与开发者检索引用。

四、嵌入整页 draw.io XML 的规范

单独一个符号单元格并不构成可渲染的图纸，还需要外层容器。依据 app/api/chat/xml_guide.md 的约束，一个可用的最小页面结构为：

<mxfile>
  <diagram name="Fluid-Power-Circuit">
    <mxGraphModel dx="1" dy="1" 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" />
        <!-- 液压符号从此处开始，id 从 2 起 -->
        <mxCell id="2" value="P1" style="shape=mxgraph.fluid_power.x10010;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
          <mxGeometry x="120" y="120" width="60" height="60" as="geometry" />
        </mxCell>
        <mxCell id="3" value="V" style="shape=mxgraph.fluid_power.x12160_simplified;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
          <mxGeometry x="120" y="240" width="60" height="60" as="geometry" />
        </mxCell>
        <!-- 用连线把泵与阀连接 -->
        <mxCell id="4" style="edgeStyle=orthogonalEdgeStyle;endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="2" target="3">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

两条必须遵守的硬性规则（同样来自 app/api/chat/xml_guide.md）：

只需提供业务 mxCell，根容器 id="0"、默认图层 id="1" 通常由项目自动补全；自定义 id 请从 "2" 起。
所有 mxCell 必须是同级兄弟节点，严禁把符号 mxCell 嵌套进另一个 mxCell 内部；连线（edge）也不要嵌进符号里。

五、命名规律：从 x10010 到 x12430

文档明确指出 “Shapes are named like x10010, x10020, etc.”。观察全部 246 条名称可得出如下编号特征（属从名称结构得出的推断）：

名称统一采用 x + 5 位数字，且大多按 +10 步进排列（如 x10010 → x10020），说明该库使用“编号段”对液压/气动符号家族做机器可读编码。
按“百位段”可自然划分为 x10xxx、x11xxx、x12xxx 三大组，大体对应不同的元件功能族。注意：仓库中的这份文档只提供名称，不提供逐条编号与符号图形的对应图例；若需确认某个编号的最终外观，应依据 draw.io 运行时的 mxgraph 渲染结果（或实际拖入画布后预览）。
存在个别非规则编号与同名变体：
- x10440 / x10441 / x10442：同组内派生编号，一个组件族含三个相近符号；
- x12160_detailed 与 x12160_simplified：同一个组件提供详细版/简化版两套外观，写样式时需带后缀，即 shape=mxgraph.fluid_power.x12160_detailed 或 ...x12160_simplified。

六、完整形状清单（247 条，含库根条目）

以下为 fluidpower.md 中的完整清单原文级复刻，供 AI 生成、人工核对与二次开发使用。第 1 条 mxgraph.fluid_power 是库根入口（用于从库中弹出整个符号面板），其余 246 条均可直接作为 shape= 的后缀使用。

6.1 库根条目

mxgraph.fluid_power

6.2 x10xxx 段：x10010 – x11000

6.3 x11xxx 段：x11010 – x11990

6.4 x12xxx 段：x12000 – x12430

x12000
x12010
x12020
x12030
x12040
x12050
x12060
x12070
x12080
x12090
x12100
x12110
x12120
x12130
x12140
x12150
x12160_detailed
x12160_simplified
x12170
x12180
x12190
x12200
x12210
x12220
x12230
x12240
x12250
x12260
x12270
x12280
x12290
x12300
x12310
x12320
x12330
x12340
x12350
x12360
x12370
x12380
x12390
x12400
x12410
x12420
x12430

七、AI 侧调用链：get_shape_library 如何加载 fluidpower.md

这篇参考文档不只是给人看的：在 AI 生成图表时，它会被作为“工具查询”的实时内容注入模型上下文。核心实现在 app/api/chat/route.ts 的 get_shape_library 工具：

库的归类：工具描述把 28 个可用库按域分组，其中工程域被声明为 Engineering: fluidpower, electrical, pid, cabinets, floorplan。模型需要液压/气动符号时，会以 library: "fluidpower" 调用本工具。
库名清洗：入参先 toLowerCase()，再用正则 /[^a-z0-9_-]/g 剔除所有非法字符；若清洗后与原始小写名称不一致，直接返回非法提示，从入口上杜绝路径穿越。
路径拼接与二次校验：baseDir 指向 docs/shape-libraries，拼接出 ${library}.md 后通过 path.resolve + startsWith 再次确认解析路径仍落在 baseDir 内，防止 ../ 逃逸读取任意文件。
读取并返回：fs.readFile 读出 md 全文返回给模型；若文件不存在（ENOENT），工具会返回可用库清单，其中明确包含 fluidpower：Library "fluidpower" not found. Available: ... fluidpower, electrical, pid, ...。

也就是说，模型在回答“帮我画一个液压回路”这类需求时，可先调用 get_shape_library(library="fluidpower") 获得本文所整理的清单与语法，再通过 display_diagram/append_diagram 等工具输出前几节那样的完整 XML，实现“先查字典、再落笔画图”的流程。

八、常见误用排查

形状不渲染但普通矩形正常：检查 shape= 值是否完整等于 mxgraph.fluid_power. + 第六节清单中的名称（含 _detailed/_simplified 后缀），漏掉 mxgraph.fluid_power. 前缀是最常见原因。
AI 反馈“Library not found”：库名必须是小写 fluidpower（工具端会清洗非法字符并强制小写，传入 FluidPower 等大小写或空格都会被拦截）。
符号方向/比例不对：符号外观由 mxgraph 渲染器按固定矢量绘制，请通过 <mxGeometry> 调整尺寸或对单元格做几何翻转，不要试图修改 shape= 名称来改变方向（名称是符号族编码而非方向参数）。
编号与符号对不上：仓库文档只保证名称与编号的存在性，具体图形语义以实际渲染预览为准，编码某个具体元件前建议先在画布上验证一次目标编号。