drawio-visuals-skill

Drawio Visuals 技能

无需服务器、MCP、固定模板、场景 IR 或自定义渲染器，即可创建、重构和编辑原生、用户可编辑的 Draw.io 文件。

默认使用对象，而非文本模块

对于 新解释性流程——流程、管道、泳道、请求生命周期或架构流程——默认使用可识别的可编辑对象和可见变化。诸如“绘制工作流”的简单请求即可激活此规则；用户无需要求“图形化”、“具体”或“图示”图形。需将此视觉处理与图表类型的选择分开。

在放置节点之前，确定哪些元素在移动、哪些在变化以及谁在执行操作。然后为每个主要业务对象和处理阶段选择轮廓、有意义的内部内容或小物件场景：队列具有单独的任务卡和入口/出口；解析器显示文档如何分解为提取的部分；退款区分待处理和已退回的资金。首先绘制这些原生部分，然后添加简短名称/操作。即使标签简短且布局清晰，仅包含步骤名称的一系列矩形也不符合此默认要求。重复的服务器机架、表情符号或无关图标放在文卡上，不能替代可见的含义。在编写这些流程之前，请阅读 visual-storytelling.md。

从捆绑的图形开始： 查阅组件索引，阅读 assets/components/ 下相关的 .drawio XML，并选择是重用其原生派生组件、调整/组合其部分，还是将其构建作为生成新原生对象的参考。根据任务需要组合浏览器、文档、消息、队列、工作器、存储、块、表格、向量、审查、决策和通知对象。例如，组合浏览器 + 文档 → 存储，然后单独的 消息 → 队列 → 工作器；不要仅将这些名称写在矩形内。这 12 个启动组件是一个可扩展的种子库，而非完整的模板或能力限制；在生成额外对象时，借用一个相关的构建思路，如轮廓、有意义的内部内容、状态标记、嵌套和连接端口，然后根据领域进行调整。不要强制使用启动组件的样本调色板或强制精确复制。

内置组件语言： 在添加、生成或维护 assets/components/ 下的可重用资源时，所有标题、字段名称、说明性文本值、状态、页面名称和工具提示均保持英文。数字、公式和符号可以保留原样。这是库编写规则：为用户生成的图表仍遵循其请求/源语言，启动文本需相应调整。

异常遵循任务而非便利性： 保留忠实重构、局部编辑的范围、显式纯文本/最小框请求以及所需的正式符号。类/ER 分区、序列生命线、决策/分叉/合并符号和状态边界具有实际语义；保留它们。通用的“流程图”请求、“简单”图表、缺少启动组件或 Mermaid 的可用性不构成异常。尽可能用可见对象变化解释状态；不要用图片替换正式关系。这些默认值适用于每个页面，并在方向/类型更改后保持不变。

核心规则

• 将当前 .drawio 文件视为内部可编辑的真相来源。默认仅提供每页 PNG 图像和一个 HTML 预览；将原生文件保存在内部工作目录中（交付目录之外），不要在移交中链接它们。仅在显式请求时才交付原生文件、SVG、PDF 或其他格式。
• 绝不要覆盖输入。每次机械写入必须使用新的输出路径，包括内部工作文件。
• 不要强加主题、形状列表、图表类型、坐标网格或布局规则。
• 遵循用户指定的图表类型、符号和方向。若未指定，选择最能回答任务实际问题的表示形式，包括 UML 和非 UML 形式；不要默认将每个请求设为流程图或泳道。在选择或大幅更改表示形式时，请使用 diagram-selection.md。
• 对新的解释性流程应用上述对象优先默认规则；标准控制符号和可重用组件启动器支持此功能，但不强加固定图标目录。
• 对于垂直流程图，从顶部到底部运行主路径，并行分支并排放置，标签决策菱形的出口，并将辅助检查分组在浅灰色虚线框内，附有平实语言的目的。
• 当中央引擎协调外部模块时，将核心放在中央，输入和工作器分组在两侧，并使用带动作标签的编号箭头引导读者完成一个任务。在相关时，将反馈路由到核心上方，将人类决策和通知渠道放在核心下方，沿底部显示一个示例工作流。选择适合主题的颜色。
• 保留任意原生 Draw.io 形状、模板、样式、几何、路径点、图层、组和包装元数据。
• 优先选择更大的画布或容器，而不是压缩的节点、标签或路由通道。无冲突的文件不一定具有空间、易读性或良好的构图。
• 在放置相邻节点之前预算连接器标签空间。长标签必须适合连接形状之间并有可见间距，或使用显式换行/另一个清晰的标签位置。在将图表标记为就绪前，解决端点标签风险并检查实际渲染文本范围；请参阅 连接器标签间距。
• 对于新创建或大幅重新设计的内容，默认在定向语义流边缘设置原生 flowAnimation=1，包括正常、次要、数据、异常和重试流。保持参考、注释、包含、分组和纯结构关系静态。显式用户意图可覆盖此策略。
• 在局部编辑期间保留无关的动画样式，除非请求动画规范化。如果运动干扰层次结构，在渲染质量检查期间将较低优先级的语义流设为静态，而不是更改其拓扑。
• 将连接器动画视为视觉效果，而非路由或碰撞避免。
• 仅将捆绑的 CLI 用于检查、查询、修补、验证、布局/拓扑检查、桌面/Web 导出编排、配套 HTML、页面 CRUD、版本列表、发布和恢复。它不负责创作、布局或实现渲染器；render 委托给 Draw.io Desktop，web-svg-bridge 将选定页委托给官方 Draw.io Web，预览 HTML 委托给官方远程查看器。
• 将 <base>-vNNN 视为由其图像和 HTML 共享的逻辑交付版本，而非每次内部写入。本地版本保持内部状态，除非请求源交付。默认情况下，一个用户批准的更改最多消耗一个新同级版本。
• 保持每个公共 CLI --page-index 从零开始，与 inspect 返回的 index 匹配。对于多页工作，优先使用稳定的页面 ID。
• 每个文档限制为 15 页。CLI 会拒绝超出此限制的更大文档和添加操作，并显示 PAGE_COUNT_LIMIT；绝不要截断页面以满足此限制。
• 不要将此技能与官方的 drawio@drawio 技能一起启用；此技能已包含相同的原生 Mermaid/XML 创作路径。

选择表示形式

将图表类型与创作工具分开。基于读者需要理解的内容进行选择：进展、职责、交互、状态、结构、部署、数据移动或比较。提供的图表、显式格式或请求的局部编辑会限制该选择。当用户未指定时，自主做出选择，在有用时简要解释，然后继续；不要要求用户从目录中选择。阅读 diagram-selection.md 了解问题到形式的指南和权衡。

在所有页面和修订中应用默认视觉处理或任务的显式异常。不要添加纯文本配套页面作为基于对象解释的替代。

然后选择适合该表示形式的对象和符号。具体图示可以解释负载和转换，而正式 UML、ER 和其他既定符号应保留其语义约定。不要将每个带标签的类、状态或模式框视为文本密集型流程缺陷。

选择工作流

请求	工作流
解释流程、管道、泳道、生命周期或架构流程	证据/所有权 → 视觉故事讲述 → 对象/状态构建 → 直接原生 XML → 官方渲染器质量保证
创建正式结构图或显式最小框图表	保留符号/内容 → 如果 Mermaid 能保留预期表示且桌面可用则使用 Mermaid；否则使用原生 XML
使用自定义形状/样式/位置创建	直接原生 XML → .drawio
从 PDF 或文本创建	读取源 → 提取支持的结构 → 使用相同默认值选择表示 → 原生 XML 或合适的 Mermaid
从图像重构	以原始分辨率检查 → 可编辑原生单元格 → 可选预览比较
检查视觉冲突	check-layout → 桌面 render → 检查图像 → 小修补 → 重新渲染；回退到查看器 HTML
检查业务流	check-topology（已知起点、终点和必需边）
无桌面查看	preview → 配套 .html（带有可见页面计数/名称，使用官方远程查看器）
无桌面导出 SVG	优先使用一个 web_svg_session.py 回环会话；保留 web-svg-bridge → commit-web-svg 用于手动恢复
导出或应用请求的布局	首先创建 .drawio → 通过 Draw.io Desktop CLI 执行
编辑，目标未知	inspect → query → patch
编辑，页面和单元格 ID 已知	query → patch
编辑，新鲜且可信的 CLI 结果已有修订和目标	patch
添加、重命名或删除页面	inspect → page add/rename/delete
列出或恢复文件版本	versions 或 versions → inspect old → restore
发布完成的工作文件	inspect working → publish
查看一个或多个已知单元格	query
独立检查文件	validate

阅读 references/authoring.md 了解创建、预览、桌面检测、布局和导出。仅当桌面不可用且显式请求的 SVG 必须通过官方 Draw.io Web 导出时，才阅读 references/web-svg-export.md。当创作拥挤图表、维护跨页视觉一致性、解释 check-layout 或执行渲染视觉质量检查时，阅读 references/layout-authoring.md。当流程、生命周期或请求路径必须连接时，阅读 references/topology.md。当源为 PDF、文本或图像时，阅读 references/source-to-diagram.md。仅在直接 XML 创作时阅读 references/drawio-xml.md。在构造修补之前阅读 references/patch-contract.md。阅读 references/versioning.md 了解页面命令和不可变历史。

规划逻辑交付

• 在编写之前，将每个请求的更改映射到其页面/单元格、所需决策出口、关键起点/终点/边缘约束、副作用或错误路径、术语以及所有受影响的页面。
• 对于新多页文档，在创作之前定义文档级别的视觉角色，并在各页中复用页面基础、排版、重复组件样式和关系样式。在添加或编辑内容时，在请求范围内继承现有文档约定。遵循文档视觉一致性进行角色选择、有意例外和跨页验收。
• 对于不需要后续拓扑、布局或视觉修正的单一原子编辑，直接写入新的内部原生版本。
• 对于多页编辑或任何可能需要质量保证修正的任务，创建代理拥有的临时目录并依次写入 working-01.drawio、working-02.drawio 等。在此完成所有请求的编辑和检查；publish 是可选的，用于内部最终快照或显式请求的原生交付。
• 从相同的最终检查过的原生快照生成交付 HTML 和每页 PNG；不要求发布 .drawio 可交付物。对于面向用户的 HTML，使用 preview --fallback-png 嵌入每页的已验证渲染（按页面顺序重复）。在远程查看器被阻止的情况下检查交付的 HTML，包括在窄宽度下。仅成功的在线渲染不能验证接收方的预览。如果没有官方渲染器可用，将 HTML 标记为仅在线并披露限制。临时预览是质量保证工件，不是可交付物。
• 在验证自包含图像和 HTML 后，仅删除此任务创建的可丢弃质量保证文件；保留最终原生快照在内部以供后续编辑。未经用户明确授权，绝不要清理现有正式版本。

创建

1. 阅读 references/authoring.md 并在选择语法之前选择表示形式。对于新的解释性流程，使用对象优先默认和直接原生 XML；桌面可用性更改导出，但不更改视觉要求。仅当 Mermaid 能保留所选语义/表示形式（如正式结构图或显式最小框图表）时使用它。检测桌面以进行转换/导出。
2. 选择描述性的小写连字符基名称，保留 <base>-v001 用于初始图像/HTML 交付，并将其 .drawio 快照保留在内部。