Draw.io 命令行驱动方案解析基于 mxGraph XML 的 CLI-Anything Drawio Harness 架构与实践【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingDraw.iodiagrams.net作为一款开源免费的可视化绘图工具其基于 mxGraph 的 XML 文件格式天然适合被命令行与 AI Agent 直接读写。本文以 DRAWIO.md 为核心结合 CLI-Anything 仓库中drawio/agent-harness下的源码实现系统讲解该 Harness 的架构设计、XML 操作原理、CLI 命令用法、样式与形状注册表以及测试覆盖帮助读者掌握一套从零创建、编辑并导出.drawio图表的完整无 GUI 工作流。软件概述为什么 Draw.io 适合 CLI 化Draw.iodiagrams.net是免费、开源的图表绘制工具桌面版基于 Electron 构建支持流程图flowchart、架构图architecture diagram、ER 图、UML 图、网络拓扑图等多种类型。其核心价值在于文件即纯文本 XML.drawio文件是可解析、可写入的普通 XMLCLI 无需启动 GUI 即可完成全部编辑跨端兼容同一文件既可由 draw.io 桌面版、网页版打开也可由命令行工具直接操纵多页支持一个文件内可容纳多个diagram页面适合组织大型架构文档。在 CLI-Anything 项目中cli-anything-drawio以有状态 CLI 的形式封装了这些能力专为 AI Agent 与高阶用户设计其入口实现在 drawio_cli.py。图通过 CLI-Anything Drawio Harness 在命令行中驱动 draw.io 创建与导出图表的演示。架构mxGraph XML 文件格式文件结构示例.drawio文件是基于 mxGraph 库的 XML 格式一个最小但完整的文件结构如下mxfile hostcli-anything agentcli-anything-drawio/1.0.0 diagram id... namePage-1 mxGraphModel dx1200 dy800 grid1 gridSize10 page1 pageWidth850 pageHeight1100 root mxCell id0/ !-- root container -- mxCell id1 parent0/ !-- default layer -- mxCell idv_123 valueServer !-- shape (vertex) -- stylerounded1;fillColor#dae8fc; vertex1 parent1 mxGeometry x100 y100 width120 height60 asgeometry/ /mxCell mxCell ide_456 valuequery !-- connector (edge) -- styleedgeStyleorthogonalEdgeStyle; edge1 sourcev_123 targetv_789 parent1 mxGeometry relative1 asgeometry/ /mxCell /root /mxGraphModel /diagram /mxfile关键属性要素说明纯文本 XML完全可被 CLI 解析与写入多页支持mxfile下可存在多个diagram元素系统单元id0根容器与id1默认图层始终存在形状mxCell vertex1配合mxGeometry表示位置与尺寸连接线mxCell edge1 source... target...样式style属性中以分号分隔的keyvalue键值对从源码看create_blank_diagram见 drawio_xml.py在创建空白文件时会写入hostcli-anything、agentcli-anything-drawio/1.0.0等属性并固定生成id0与id1两个系统单元保证任何新建文件都符合 draw.io 可识别的结构约定。解析与安全XML 读写封装在utils/drawio_xml.py中解析parse_drawio(path)使用defusedxml的安全解析器可防范 XML 实体注入等安全风险写出write_drawio(root, path)自动创建目标目录并输出带 UTF-8 声明的缩进 XML查询get_vertices/get_edges分别过滤出形状与连接线单元get_all_cells会自动排除id0/1的系统单元ID 生成_new_id基于time.time()微秒时间戳生成全局唯一 ID避免单元 ID 冲突。渲染管线主备双通道主路径draw.io 桌面 CLI 导出.drawio文件通过 draw.io 桌面版Electron 应用提供的无头导出能力完成渲染.drawio file → draw.io --export --format png → rendered image支持的核心命令draw.io --export input.drawio --output out.png --format pngdraw.io --export input.drawio --output out.pdf --format pdfdraw.io --export input.drawio --output out.svg --format svg后端封装位于 drawio_backend.py。export_diagram会按平台探测可执行文件draw.io/drawio/draw.io.exe以及 macOS 的/Applications/draw.io.app/Contents/MacOS/draw.io并拼接完整的--export、--output、--format参数同时透传--page-index、--scale、--width、--height、--border、--transparent、--crop等选项最后通过subprocess.run执行并校验退出码与产物文件是否存在。备路径直接写 XML 兜底当环境中未安装 draw.io 桌面 CLI 时导出命令会退化为直接保存.drawio文件并返回提示信息用户可在 draw.io 网页版或桌面版中手动导出。该逻辑实现于 export.py 的render_or_save捕获 not installed 类型的RuntimeError后将 XML 写入同名.drawio文件并给出安装提示。CLI 策略直接操纵与委托分工该 Harness 明确了哪些自己做、哪些交给 draw.io CLI的边界直接操纵无需 GUI项目生命周期创建空白 XML、解析既有文件、写入磁盘形状增删、移动、缩放mxCell vertex1元素连接线通过source/target引用增删mxCell edge1样式解析并修改style属性字符串页面增删、重命名diagram元素标签设置任意单元的value属性。委托给 draw.io CLI栅格化导出PNG、PDF 渲染依赖 Electron 应用SVG 导出具备正确字体/文本处理的矢量渲染。这一策略在代码中体现为清晰的模块分层core/目录下的project.py、shapes.py、connectors.py、pages.py全部直接操作 XML 树而只有export.py才依赖drawio_backend.py调用外部进程。安装与前置条件安装依赖 Python 3.10。draw.io 桌面应用仅在需要 PNG/PDF/SVG 导出时才必需纯创建与编辑.drawio文件无需安装。cd drawio/agent-harness pip install -e .draw.io 桌面版安装方式macOS 用brew install --cask drawioLinux 用snap install drawio或下载 .deb/.AppImageWindows 用winget install JGraph.Draw。也可通过cli-anything-drawio export render触发未安装检测并直接获得对应平台的安装命令提示见 drawio_backend.py。命令总览CLI 入口使用 Click 构建命令按领域划分为六个组见 drawio_cli.py并支持全局的--json、--session、--project、--dry-run选项命令组子命令说明projectnew、open、save、info、xml、presets项目生命周期shapeadd、remove、list、label、move、resize、style、info、types形状操作connectadd、remove、label、style、list、styles连接线操作pageadd、remove、rename、list多页管理exportrender、formats导出 PNG/PDF/SVG/XMLsessionstatus、undo、redo、save-state、list会话管理一键式命令示例# 创建新图表 cli-anything-drawio project new --preset letter -o diagram.drawio # 添加形状 cli-anything-drawio --project diagram.drawio shape add rectangle --label Server cli-anything-drawio --project diagram.drawio shape add cylinder --label Database --x 300 --y 100 # 连接形状 cli-anything-drawio --project diagram.drawio connect add source_id target_id # 导出 cli-anything-drawio --project diagram.drawio export render output.png -f png cli-anything-drawio --project diagram.drawio export render output.svg -f svg使用--project打开文件时若会话被修改CLI 会在退出时通过call_on_close钩子自动保存dry-run 模式除外。--dry-run可让 Agent 在不落盘的情况下演练操作序列。项目生命周期与页面预设project new支持通过--preset选择页面尺寸可用预设定义在 project.py 的PAGE_PRESETS中预设宽 × 高pxletter850 × 1100a4827 × 1169a31169 × 165416:91280 × 7204:31024 × 768square800 × 800custom850 × 1100除预设外--width与--height可覆盖任意尺寸。project info会汇总页面、形状、连接线数量与画布设置pageWidth、pageHeight、gridSize、grid等project xml直接打印当前 XML 树project presets列出全部可用预设。相关实现参见 project.py 与 session.py。Shape Registry形状预设shape add type支持 15 种内置形状预设其完整样式基底定义在 drawio_xml.py 的SHAPE_STYLES字典中CLI 名称样式基底说明rectanglerounded0;whiteSpacewrap;html1标准矩形roundedrounded1;whiteSpacewrap;html1圆角矩形ellipseellipse;whiteSpacewrap;html1圆/椭圆diamondrhombus;whiteSpacewrap;html1决策菱形triangletriangle;whiteSpacewrap;html1三角形hexagonshapehexagon;perimeterhexagonPerimeter2;...六边形cylindershapecylinder3;...;size15数据库圆柱体cloudellipse;shapecloud;...云形状parallelogramshapeparallelogram;perimeterparallelogramPerimeter;...平行四边形processshapeprocess;...;backgroundOutline1流程框documentshapedocument;...;size0.27文档形状calloutshapecallout;...;size30;position0.5对话气泡noteshapenote;...;size15便签actorshapemxgraph.basic.person;...人物/参与者texttext;html1;aligncenter;verticalAlignmiddle;...纯文本标签从源码看add_vertexdrawio_xml.py在形状类型命中SHAPE_STYLES时直接套用预设样式若传入未知类型则将其视作原始样式字符串写入这为高阶用户提供了透传任意 draw.io 样式的灵活性。形状操作参数# 添加位置、尺寸、标签、页面、自定义 ID 均可指定 cli-anything-drawio shape add diamond --label Decision? --x 50 --y 50 -w 100 -h 100 # 查询与修改 cli-anything-drawio shape list cli-anything-drawio shape info cell_id # 含解析后的 style 字典 cli-anything-drawio shape label cell_id 新文本 cli-anything-drawio shape move cell_id --x 200 --y 300 cli-anything-drawio shape resize cell_id -w 160 -h 80 cli-anything-drawio shape style cell_id fillColor #d5e8d4 cli-anything-drawio shape remove cell_idshape remove在底层通过remove_celldrawio_xml.py实现不仅删除目标单元还会级联删除所有source或target指向该单元的连接线避免产生悬挂边。Edge Style Registry连接线预设connect add source_id target_id支持 4 种内置连接线风格定义于 drawio_xml.py 的EDGE_STYLESCLI 名称样式说明straightedgeStylenone直线orthogonaledgeStyleorthogonalEdgeStyle;rounded0直角布线curvededgeStyleorthogonalEdgeStyle;curved1;rounded1曲线布线entity-relationedgeStyleentityRelationEdgeStyleER 图风格# 创建连接线默认 orthogonal可指定标签与自定义 ID cli-anything-drawio connect add v_123 v_789 --style curved -l query # 管理连接线 cli-anything-drawio connect list cli-anything-drawio connect label e_456 新的标签 cli-anything-drawio connect style e_456 endArrow block cli-anything-drawio connect remove e_456add_connectorconnectors.py在写边前会先校验源、目标单元均存在并对自定义 ID 做重复检查。底层add_edgedrawio_xml.py生成的mxGeometry relative1表示边几何是相对定位符合 mxGraph 对连接线的约定。Style Properties通用样式属性形状与连接线共用的常用样式键及其取值shape style/connect style均可设置键取值说明fillColor#rrggbb形状填充色strokeColor#rrggbb边框/线条颜色fontColor#rrggbb文本颜色fontSize整数字号磅值fontStyle0/1/2/40正常1粗体2斜体4下划线opacity0-100不透明度百分比rounded0/1圆角shadow0/1投影dashed0/1虚线边框/线条strokeWidth数字边框/线条宽度endArrowclassic/block/open/none箭头头部样式startArrowclassic/block/open/none箭头尾部样式样式字符串的解析与重构逻辑位于 drawio_xml.pyparse_style将key1value1;key2value2;baseStyle;按分号切分带的解析为键值对不带的视为值为空字符串的基底样式名build_style反向序列化空值直接输出裸键名set_style_property先解析、再合并写入、最后回写style属性实现单个键的增量修改。多页管理page命令组支持多页操作底层由 pages.py 与 drawio_xml.py 协作完成cli-anything-drawio page add --name 架构总览 cli-anything-drawio page list cli-anything-drawio page rename 1 部署拓扑 cli-anything-drawio page remove 1新增页面会复制一套完整的mxGraphModel含dx/dy/grid/gridSize/pageWidth/pageHeight等画布参数及id0/1系统单元。注意page remove受保护remove_page在仅剩一页时抛出RuntimeError(Cannot remove the last page)保证文件始终至少有一个有效页面。导出详解export render output_path支持png、pdf、svg、vsdx、xml五种格式见 export.pycli-anything-drawio export render out.png -f png --scale 2 --transparent --crop cli-anything-drawio export render out.pdf -f pdf cli-anything-drawio export render out.svg -f svg cli-anything-drawio export render out.xml -f xml cli-anything-drawio export formats导出流程renderexport.py将当前项目写入临时.drawio文件调用drawio_backend.export_diagram执行桌面 CLI 渲染结束后清理临时文件。其中xml格式属于特例直接以 direct-write 方式写盘无需外部依赖。可选参数包括--page导出指定页、--scale缩放倍率如 2.0 即 2 倍分辨率、--width/--heightPNG 输出尺寸、--transparent透明背景、--crop裁剪到内容边界、--overwrite覆盖已存在文件。文件已存在且未指定--overwrite时会抛出FileExistsError这一防御在前端与后端均有校验。会话、撤销与重做会话层session.py是该 CLI 的有状态核心快照式撤销/重做每次变更操作前checkpoint()将当前 XML 树序列化快照压入撤销栈上限MAX_UNDO_DEPTH 50并清空重做栈undo()/redo()通过defusedxml.fromstring反序列化快照恢复现场会话持久化save_session_state()将会话元数据session_id、项目路径、修改标记、撤销深度、时间戳以 JSON 形式写入~/.drawio-cli/sessions/并使用fcntl文件锁保证并发安全见_locked_save_json状态查询session status输出当前打开的项目、页/形状/连接线数量以及可撤销、可重做次数。对应命令cli-anything-drawio session status cli-anything-drawio session undo cli-anything-drawio session redo cli-anything-drawio session save-state cli-anything-drawio session listREPL 交互模式不带子命令直接运行cli-anything-drawio或cli-anything-drawio repl --project diagram.drawio即进入交互式 REPL。提示符会显示当前项目名与未保存标记支持命令全集见 drawio_cli.pyhelp # 显示帮助 status # 会话状态 new [preset] # 新建图表letter, a4, 16:9 ... open path # 打开 .drawio 文件 save [path] # 保存项目 info # 项目信息 xml # 打印原始 XML add type [label] # 添加形状rectangle, ellipse, diamond ... remove id # 删除形状或连接线 shapes # 列出所有形状 label id text # 更新标签 move id x y # 移动形状 resize id w h # 缩放形状 style id key val # 设置样式属性 connect src tgt [style] # 添加连接线 connectors # 列出所有连接线 pages # 列出所有页面 addpage [name] # 新增页面 export path [format] # 导出图表png, pdf, svg undo / redo # 撤销 / 重做 quit # 退出REPL 的add、remove等命令直接调用与一键模式完全相同的core层函数因此两种模式行为一致。JSON 输出模式Agent 友好为便于 AI Agent 解析所有命令都支持--json全局开关将结构化结果以 JSON 输出见 drawio_cli.pycli-anything-drawio --json project new -o diagram.drawio cli-anything-drawio --json --project diagram.drawio shape add rectangle --label API cli-anything-drawio --json --project diagram.drawio shape list错误处理统一由handle_error装饰器接管FileNotFoundError、FileExistsError、ValueError/IndexError/RuntimeError及未预期异常分别映射为带type字段的 JSON 错误对象且仅在非 REPL 模式下sys.exit(1)保证 Agent 能可靠地按错误类型分支处理。测试覆盖项目测试分布在 test_core.py 与 test_full_e2e.py 中测试说明见 TEST.md单元测试XML 操作空白图表创建、系统单元存在性、顶点/边增删、自定义 ID 与重复 ID 校验、样式解析、全部形状/连接线预设、会话撤销/重做、多页操作、复杂工作流E2E 测试文件往返roundtrip、XML 导出校验、真实 draw.io 导出PNG/SVG/PDF 的 magic byte 检查、CLI 子进程调用、真实图表场景。例如test_core.py中断言空白图表仅含一个diagram且pageWidth850、系统单元0/1必然存在、add_vertex后get_all_cells数量为 1 且vertex1、边单元的source/target与标签正确写入这些用例从行为层面印证了前述 XML 操作的正确性。代码结构导读drawio/agent-harness/ ├── DRAWIO.md # 本文依据的架构分析与 SOP 文档 ├── setup.py # 包安装配置 └── cli_anything/drawio/ ├── drawio_cli.py # Click 命令入口与 REPL ├── core/ │ ├── project.py # 项目生命周期与页面预设 │ ├── shapes.py # 形状操作 │ ├── connectors.py # 连接线操作 │ ├── pages.py # 多页管理 │ ├── export.py # 导出与兜底逻辑 │ └── session.py # 会话、快照撤销/重做、持久化 ├── utils/ │ ├── drawio_xml.py # XML 解析、样式、单元增删改查 │ ├── drawio_backend.py # draw.io 桌面 CLI 探测与调用 │ └── repl_skin.py # REPL 界面皮肤 ├── skills/SKILL.md # 供 Agent 调用的技能说明 └── tests/ # 单元与 E2E 测试总体而言这套 Harness 将 mxGraph XML 的纯文本可编辑特性发挥到了极致所有编辑操作都在 XML 层完成渲染才借助 draw.io 桌面 CLI两者之间由会话与导出模块清晰解耦。对于需要程序化生成架构图、ER 图或多页技术文档的 Agent 工作流这是一条无需任何 GUI 介入的完整链路。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考