DrawIO 绘图台

是什么

零后端的浏览器绘图工作台：drawio 文件格式（.drawio XML）双向兼容，离线可用（内核为 maxgraph——drawio 上游 mxGraph 的官方现代版）。文件经统一 $fs 文件视图读写 （云端 UFS / 浏览器本地 / 主机三端），支持绘制、编辑、样式、撤销重做、缩放平移、 网格吸附、导出（.drawio / PNG / SVG）。

能力边界（v1）：

• 官方 stencil 图标集（AWS/K8s/UML 成套图标）不渲染——退化为矩形（文件不损坏）
• 多页 .drawio 只编辑第一页，其余页面保存时原样保留
• 渲染形状集、样式键、边标记的准确清单见 references/shapes.md

什么时候用

• 用户要「画个图」（流程图 / 架构图 / 思维导图 / 网络图 / ER / 时序图…）→ 你直接写 .drawio XML 文件，再 drawio_open 打开展示给用户
• 用户给了现成 .drawio 文件要看/改 → drawio_open；或用户改完后你 fs 读同一文件
• 用户想自己画 → 把页面打开给他

操作方式（AI 标准流程）

1. 打开页面：open /skills/cloud/{skill_id}（skill_id 取自 skill 列表；url_prefix 同前缀，用于资源与 API）
2. 探测指令：使用 open 返回的 events 查看 drawio_*；需要重新查看时执行不带窗口前缀的 list
3. 出图：fs 工具直接写 .drawio 文件（默认目录 /u/{uid}/drawio/；先读 references/xml-authoring.md，本文末尾有快速骨架）
4. 展示/刷新：drawio_open --path <页面 $fs 路径>——写完文件页面不会自动感知，必须调它 （用户手动改过文件的场景同理）。云端文件在 fs 工具里是 /u/{uid}/...，传给页面指令时改成 /cloud/u/{uid}/...
5. 导出成图：drawio_export --format png|svg --path <输出路径>
6. 页面是用户的编辑舞台：用户可随时改图并保存；你 fs 读文件即拿到最新内容

典型流程（用户说「画一个 XX 架构图」）：

1. 读 references/diagram-types.md 选图形套路 + 本文速记规则
2. fs 写 /u/{uid}/drawio/xx-架构图.drawio（JSON 无关；就是 XML 文本，2 空格缩进）
3. drawio_open --path /cloud/u/{uid}/drawio/xx-架构图.drawio 打开给用户看
4. 一两句话总结；后续用户说「改成 YY」→ fs 读 → 改 → 写回 → drawio_open 刷新

指令表

返回统一为 {content: "<JSON 字符串>"}：成功 {ok: true, ...}，失败 {ok: false, error}。 argv 形如 ["--path", "/cloud/u/admin/drawio/x.drawio"]（--key val 成对）。指令的 --path / --dir 都使用页面 $fs 完整树路径，不要直接照抄 fs 工具的云端物理路径。

页面交互（人类操作，了解即可）

形状面板点击/拖拽放置 → 拖动连接点拉线 → 双击形状改文本 → 右侧属性面板调样式； 右键拖动平移、滚轮缩放；Ctrl/Cmd+S 保存、Z 撤销、Shift+Z 重做、A 全选、C/X/V 复制剪切粘贴、Delete 删除。顶部按钮：打开 / 另存为走平台文件选择器（$fs.pickFiles / $fs.pickSavePath，与 /fs 管理器同一棵三端树），导出 PNG/SVG 为浏览器下载（不写入 $fs）。

响应式：窗口宽度变化自适应（@container 查询）。工具栏按钮按需自动换行；窗口较窄 （≤860px）时形状/属性面板收为左右抽屉，由工具栏右侧的两个图标按钮开合（画布占满全宽）； 画布尺寸随窗口实时重算。

文件与格式约定

• 位置：默认目录 /u/{uid}/drawio/（约定，非强制——页面文件对话框支持统一的 /cloud、/page、/{host_id} 三端路径）；文件名用中文/英文均可，建议语义化
• 格式：<mxfile> 包 <mxGraphModel>（未压缩）；读取压缩文件 （compressed="true"，raw-deflate/zlib + base64）没有问题；导出默认不压缩
• 写出规范（必读）：references/xml-authoring.md。速记：
  • id="0"、id="1" 根单元格必写；形状 id 从 "2" 起递增；parent="1"
  • 边必须带 <mxGeometry relative="1" as="geometry" /> 子元素
  • 坐标取 10 的整数倍；html=1；
 换行；XML 注释禁 --
• 快速骨架：

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="NDrawio" version="24">
  <diagram name="Page-1">
    <mxGraphModel grid="1" gridSize="10" page="1" pageWidth="850" pageHeight="1100">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <mxCell id="2" value="服务" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
          <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

references 索引（按需读取）

注意

• 页面指令仅在页面打开时就绪；drawio_status 的 ready:false 表示尚未就绪（先 open）
• 写完/改完文件后必须 drawio_open 让画布刷新
• 用户正在画布上编辑时（未保存），drawio_new 会丢弃其改动（UI 侧有确认，指令侧直接执行）—— 尊重用户的未保存改动，避免在用户编辑时强行重载