drawio-diagrams

drawio-diagrams

目标

制作、编辑、验证并交付高质量的 draw.io / diagrams.net 图表，文件需为可编辑的 .drawio 格式。优先制作可在浅色和深色模式下正常显示的独立图表。

首次回复约定

在首次实质性回复中，先展示可选的呈现方案，再开始创作：design_profile（technical、operator-grid、isometric-air、neon-hub、aurora-story 或 adapted-<short-name>）、theme_mode（adaptive、light 或 dark）、animation（on、off 或 preserve），以及图标模式（official-first，对无法解析或通用节点使用语义化回退图标）。说明选定的方案和样式选项；只有当所请求的结果存在实质性歧义时才提问；不要等到交付时才透露这些选择。

官方图标和徽标政策

优先使用官方组织、产品或服务的图稿（如果有且符合图表表示方式）；仅对通用、厂商中立或无法解析的节点使用语义化图形。保留源图稿、品牌颜色、比例、viewBox 和变体。不得随意为官方标记着色、改色、转为单色、反色、添加滤镜、裁剪、拉伸或重新设计；应通过周围的中性色表面解决对比度问题。记录每个节点的替代情况，并说明任何明确要求或必要的无障碍改色。

适用场景

当请求涉及创建、绘制、生成、编辑、修复、转换、验证或导出 draw.io 图表时，使用此技能，包括架构图、流程图、时序图、ER/UML/状态图、BPMN、SysML、ML/DL、泳道图、时间线、网络图、C4 风格图表以及包含丰富图标的技术可视化。

不适用场景

不要将此技能用于柱状图、折线图、饼图、数据分析图、照片编辑、艺术图像或不可编辑的插图，除非用户明确要求使用 draw.io 图表。

工作流选择

直接调用时，始终公开以下有限工作流：

• create：创建新图表，或将提供的语义转换为可编辑的 draw.io。
• edit-repair：编辑、修复或有意重新设计现有的 .drawio 文件。
• review：只读的语义、结构、验证或视觉评估。
• export：导出已符合要求的 .drawio 源文件，不重新设计。

没有 auto 工作流。仅根据任务意图和授权进行判断：

• 创建图表，或将语义转换为新的可编辑图表时，选择 create。
• 编辑、修复或有意重新设计现有图表时，选择 edit-repair。
• 未要求修改的语义、结构、验证或视觉评估，选择 review。
• 不重新设计、仅导出已符合要求的 .drawio 源文件时，选择 export。

意图明确时，说明全部四种工作流、所选工作流及理由、输入、请求的输出、设计配置、主题／动画／图标模式、推荐的创作／渲染路径（direct-xml | transactional-native | approved-raw-cli-manual | fixed-theme-browser-raster | browser-url-preview | html-viewer-preview）、写入范围、预期产物、受保护文件以及后续审批边界，然后继续操作。仅有笼统调用、涉及范围实质不同的混合结果，或源文件／目标位置尚未明确时，应展示选项并询问。Agent 主动启用时可无需确认而选择并告知 review；只有当用户现有请求已授权相应结果和范围时，才能选择会修改内容的工作流。安装、托管内容传输、浏览器栅格化、文件写入备用辅助工具、破坏性覆盖、付费／外部操作以及范围扩展，均需单独审批。

意图明确时，简要说明 create | edit-repair | review | export 和所选路径即可；不要重复询问选择，也不要重复对话中已确认的细节。只有在明确批准仍涵盖确切操作、目标、工具／提供方、相关费用和写入范围时，才可重用该批准。各审批边界彼此独立：一项授权绝不代表另一项也获授权。只有决定发生变化或尚未明确时，才再次询问。

要检查的输入

检查提示词、请求的输出、受众、问题、范围、抽象程度和隐私限制，以选择工作流并确定授权。选择后，先执行非修改性能力预检，再检查架构源文件、现有 .drawio 文件、当前／目标状态、图标、配置／主题、文本层级、路由风险或特定工具的输入。新的有向流程默认启用动画（on）。预检期间，使用只读辅助工具 scripts/probe-drawio-toolset.mjs [--json] 检测 Node >= 18、Python、draw.io 候选程序、浏览器／MCP 信号及缓存；能力证据不等于许可。优先选择具备 /proc/self/fd 保证的 Linux 原生 draw.io 候选程序；使用 probe-drawio-toolset.mjs 探测候选程序版本，并将过期或不可执行的 DRAWIO_BIN 候选程序交由原始／手动导出备用路径处理。浏览器栅格化仅在使用固定的绝对路径可执行文件时，才使用 rasterize-themed-svg.mjs。安装／设置需经审批，能力回执必须使用已清理的路径。

工作流

请遵循 workflow-details.md 中详细的能力阶梯和回执流程。

1. 使用已公布的选择和范围；只有新证据改变了路线或重要决策时才更新。对于会修改内容或导出的工作流，先运行不会修改内容的能力预检；review 跳过此步骤。
2. 如果选择了 review，请使用严格的只读分支：检查提供的来源和现有渲染结果，构建所需的语义模型，并且只运行只读验证器。不要创建备份、编写或修补 XML、渲染、栅格化、导出、打开托管服务或修复发现的问题。报告发现结果和证据局限，然后返回；不要执行其余工作流步骤。
3. 构建精简的语义模型，从 transactional-native | approved-raw-cli-manual | fixed-theme-browser-raster | browser-url-preview | html-viewer-preview | direct-xml 中选择路线，规划连接线间距，并保留可编辑源文件。
4. 仅在所选权限范围内编写或修补 .drawio XML。应用所选配置文件、官方优先图标策略、具体的边线路由和动画策略。仅将用户提供的视觉参考转换为可复用的设计令牌或效果；切勿复制其构图或素材，也不要在未明确请求时保存从中学习的配置文件。
5. 运行 scripts/preflight-drawio-xml.mjs、scripts/validate_drawio.py <file> --animation on|off|preserve 和 scripts/validate-drawio-diagram-rules.mjs；修复所有 ERROR，并修复或说明所有 WARN。
6. 自行检查语义、路由以及浅色/深色模式下的可访问性；仅通过获准路线渲染，并交付源文件、所请求的导出文件、回执、证据局限和有意省略的内容。

安全规则

不得仅凭含糊或不明确的调用推断具有修改权限。review 严格只读；报告发现结果，并等待获准的修改工作流。工具安装、WSL/Windows 或其他跨边界执行、浏览器使用、托管服务/MCP 传输、缓存创建、付费/提供商操作、破坏性覆盖，以及写入文件的备用辅助工具，均须分别获得批准。明确请求原生 PNG/SVG/PDF 输出，仅授权预检后写入所指明的原生格式文件。只获取选定的公开 SVG 素材，验证后再嵌入；处理敏感内容时优先使用本地路径，绝不包含机密、客户数据、私有仓库路径或内部主机名。

参考资料

• references/workflow-details.md：用于了解详细工作流、能力阶梯、图标保真度、安全和回执规范。
• references/xml-authoring.md：用于直接生成 XML 和编辑现有文件。
• references/diagram-type-playbook.md：用于语义规划和路线选择。
• references/layout-readability.md：用于了解架构图可读性、连接线标签间距、扇出通道、间距、层次结构和视觉审查。
• references/icon-catalog.md：在图表需要架构、品牌、云或产品图标时使用。
• references/routing-and-simplification.md：用于边线路由、加号/减号折叠评估，以及简化视图/详细视图。
• references/design-profiles.md：用户请求模板/样式，或作品明显需要操作员网格、等距、霓虹枢纽或极光视觉效果时使用。
• references/theming-dark-mode.md：用于颜色选择和浅色/深色模式兼容性。
• references/toolset-setup.md：用于检测或配置可选工具。
• references/verification-checklist.md：用于交付前检查，以及自动验证不可用时的检查。
• references/delivery.md：用于导出命令和浏览器 URL 交付。

脚本

• scripts/preflight-drawio-xml.mjs：在 Python lint 前，对禁止的结构进行只读严格 XML 预检。
• scripts/validate_drawio.py：对 .drawio/mxGraph XML 进行只读 lint。
• scripts/validate-drawio-diagram-rules.mjs：只读检查悬空语义连线、组件图标覆盖情况、固定宽高比的徽标，以及可能的连线路径交叉。
• scripts/render-drawio.mjs：暂存并验证浅色 PNG 和深色 SVG，然后通过提交时的防覆盖检查安装两者；中断的提交会保留部分输出和恢复备份，成功替换后会报告保留的恢复目录，供手动清理。明确请求生成规范的原生 PNG/SVG 输出，即授权预检后写入这些指定文件。
• scripts/probe-drawio-toolset.mjs [--json]：只读探测 Python、Node、draw.io 候选项、格式支持、浏览器/agent-browser、MCP/托管预览信号、包管理器，以及特定于环境的原生安装方案。它不会安装软件包或写入配置；有界的 PNG/SVG 冒烟导出为临时文件，会经过验证并在探测返回前删除，因此不会留下渲染产物。
• scripts/rasterize-themed-svg.mjs：通过用户选择的绝对路径，使用指定的本地 Chrome、Chromium 或 Edge 可执行文件，从有界、自包含、固定浅色或固定深色的 SVG 写入一个防覆盖 PNG；递归检查有界的嵌入式 SVG 图像数据中是否含有活动内容或远程内容，验证输出并保留源尺寸。使用前必须获得用户明确批准。
• scripts/open-drawio-url.mjs：只读的 .drawio 文件浏览器 URL 构建器/打开器。
• scripts/search-shapes.mjs：使用严格和模糊回退排序，在已配置或标准缓存的本地图形索引中搜索。

输出格式

返回所选工作流及其理由、输入、输出、写入范围、受保护文件、创作路径、工具集、设计配置、主题/动画/图标模式、图标来源及任何按节点替换、lint 摘要、语义/布局/明暗主题审查摘要，以及有依据的警告。每份创建/编辑修复/导出回执还必须包含以下确切字段：

• Capability status
• Renderer route
• Tool-install approval
• Cross-boundary approval
• Export status
• Visual verification
• Evidence scope
• Fallback (used/offered)

在回执中说明路径限制（包括原始 CLI/手动/Windows 桥接方式缺少事务保障，以及浏览器预览不具备规范输出的性质）。明确写出 validate_drawio.py 和 validate-drawio-diagram-rules.mjs。对于 review，报告检查的证据、发现、限制，以及建议的后续工作流，不得声称或执行任何更改。对于架构图，还需报告视图/范围、有意省略的内容、连接器轨道、标签背景、间距和图标覆盖情况。出现任何第三方徽标或图标时，请附上 references/delivery.md 中的单一责任声明；除非用户要求，否则不要逐个图标进行法律分析。

完成标准

当四种工作流均已展示、说明了基于任务的选择及理由或消除了歧义、权限始终未超出请求的结果／范围、完成了能力预检和回执字段，并交付了所选工作流的结果时，任务即告完成。review 工作流在只读证据和调查结果报告返回后即告完成，不得进行编写、渲染、导出或修复。其他工作流还要求在适用时提供有效且可编辑的 .drawio 文件、确保确定性的 lint 和图表规则均无错误、修复或说明警告、符合请求的设计风格和动画策略、涵盖相关图标／徽标、尽可能提供请求的导出文件，并如实报告自我审查结果。架构图完成还要求采用一个明确的问题／视图／抽象层级、明确标注当前／目标状态、说明有意省略的内容、确保路由和层级清晰易读，并为每个主要组件提供相关图标／徽标，除非用户选择不使用。

失败处理

如果缺少 CLI，则跳过视觉导出并说明原因。如果 MCP 不可用，则直接使用 XML。如果所选的表现风格与正式符号规范、信息密度、打印用途或无障碍要求冲突，则保留语义，并采用最接近且易读的风格呈现，同时说明调整。如果无法获取或解析品牌徽标，则为该节点使用原生语义图标，并披露替代情况；保留徽标集中的其他内容。如果浏览器 URL 过长，则交付 .drawio 文件。如果现有页面经过压缩，则先展开再编辑。如果 XML 生成内容过大，则拆分为多个页面。