drawio-academic-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Draw.io Academic Skill

Draw.io 学术专用技能

Create, edit, replicate, validate, and export publication-ready draw.io figures.

This skill merges two workflows:

The upstream pure
```
drawio-skill
```
workflow: direct
```
.drawio
```
XML generation, Desktop export, self-check, style presets, diagrams.net URL fallback, and diagram-type presets.
This repository's
```
skills/drawio
```
workflow: YAML-first authoring, offline sidecars, academic quality gates, formula handling, and SVG conversion.

创建、编辑、复制、验证并导出可直接用于发表的Draw.io图表。

本技能融合了两种工作流：

上游纯
```
drawio-skill
```
工作流：直接生成.drawio XML、桌面端导出、自检、样式预设、diagrams.net URL备选方案以及图表类型预设。
本仓库的
```
skills/drawio
```
工作流：优先使用YAML创作、离线辅助文件、学术质量管控、公式处理以及SVG转换。

Non-Negotiable Contract

不可协商的约定

Keep this fork academic-first and offline-first.
Never create, require, or route through
```
.mcp.json
```
or an MCP backend.
Treat the YAML spec plus
```
.drawio
```
,
```
.arch.json
```
, and
```
.svg
```
outputs as the normal editable bundle.
Use draw.io Desktop only as an optional export enhancer for PNG/PDF/JPG or embedded
```
.drawio.svg
```
.
When a requested export cannot be produced locally, still deliver the editable bundle and report the unavailable export clearly.

保持此分支优先面向学术场景且支持离线使用。
绝不创建、要求或通过
```
.mcp.json
```
或MCP后端进行路由。
将YAML规范加上.drawio、.arch.json和.svg输出视为标准可编辑包。
仅将draw.io Desktop作为生成PNG/PDF/JPG或嵌入型
```
.drawio.svg
```
的可选导出增强工具。
当无法本地生成请求的导出文件时，仍需交付可编辑包，并明确告知该导出不可用。

Runtime Decision

运行时决策

Default to the offline academic path.

Priority	Runtime	Use for
1	YAML/CLI offline bundle	New academic figures, paper diagrams, repeatable edits
2	draw.io Desktop CLI	PNG/PDF/JPG, embedded `.drawio.svg` , final raster export
3	direct XML fallback	Tiny one-off diagrams, CLI unavailable, handoff-only XML
4	diagrams.net URL fallback	User cannot install Desktop but can open browser URL

This skill intentionally ships without

.mcp.json

. Use Desktop CLI or the diagrams.net URL fallback for handoff and refinement.

默认采用离线学术路径。

优先级	运行环境	适用场景
1	YAML/CLI离线包	新学术图表、论文配图、可重复编辑操作
2	draw.io Desktop CLI	PNG/PDF/JPG、嵌入型 `.drawio.svg` 、最终栅格化导出
3	直接XML备选方案	小型一次性图表、CLI不可用、仅需交付XML的场景
4	diagrams.net URL备选方案	用户无法安装桌面端但可打开浏览器URL的场景

本技能刻意不附带

.mcp.json

。使用Desktop CLI或diagrams.net URL备选方案进行交付和优化。

Preflight Checklist

预检查清单

Before generating or editing, decide and state:

Input type: new prompt,
```
.spec.yaml
```
,
```
.drawio
```
, image/SVG reference, or style preset.
Route from the table below, then load only the referenced files.
Deliverables needed: default bundle, plus any requested PNG/PDF/JPG.
Whether draw.io Desktop is required for the requested export.
Fallback plan if Desktop or validation is unavailable.

生成或编辑之前，需确定并说明：

输入类型：新提示、.spec.yaml、.drawio、图片/SVG参考或样式预设。
从下表选择路由，仅加载相关文件。
需要交付的内容：默认包，加上任何请求的PNG/PDF/JPG。
请求的导出是否需要draw.io Desktop。
若Desktop或验证不可用的备选方案。

Task Routing

任务路由

Choose one route first, then load only the referenced files.

Route	Trigger	Load
`academic-create`	paper, thesis, IEEE, manuscript, journal figure	`references/docs/academic-figure-playbook.md` , `references/docs/academic-export-checklist.md` , `references/workflows/create.md`
`math-formula`	formula, equation, LaTeX, AsciiMath, MathJax, 公式	`references/docs/math-typesetting.md` , `references/docs/design-system/formulas.md`
`edit`	modify an existing `.drawio` , YAML bundle, or previous output	`references/workflows/edit.md` , `references/docs/migration-readiness.md`
`replicate`	redraw screenshot, image, SVG, or reference diagram	`references/workflows/replicate.md` , `references/docs/design-system/color-guide.md`
`stencil-heavy`	cloud, network, AWS, Azure, GCP, Cisco, Kubernetes	`references/docs/stencil-library-guide.md` , `references/official/xml-reference.md`
`style-preset`	learn/use/list/delete/rename visual style presets	`references/docs/style-presets.md` , `references/docs/upstream-pure-drawio-skill.md`

先选择一个路由，再仅加载相关文件。

路由	触发条件	加载文件
`academic-create`	论文、学位论文、IEEE、手稿、期刊图表	`references/docs/academic-figure-playbook.md` , `references/docs/academic-export-checklist.md` , `references/workflows/create.md`
`math-formula`	公式、方程式、LaTeX、AsciiMath、MathJax、公式	`references/docs/math-typesetting.md` , `references/docs/design-system/formulas.md`
`edit`	修改现有.drawio、YAML包或之前的输出	`references/workflows/edit.md` , `references/docs/migration-readiness.md`
`replicate`	重绘截图、图片、SVG或参考图表	`references/workflows/replicate.md` , `references/docs/design-system/color-guide.md`
`stencil-heavy`	云、网络、AWS、Azure、GCP、Cisco、Kubernetes	`references/docs/stencil-library-guide.md` , `references/official/xml-reference.md`
`style-preset`	学习/使用/列出/删除/重命名可视化样式预设	`references/docs/style-presets.md` , `references/docs/upstream-pure-drawio-skill.md`

Academic Defaults

学术场景默认设置

For academic-paper requests, set these before rendering:

```
meta.profile: academic-paper
```

meta.figureType

: exactly one of

architecture

roadmap

, or

workflow

```
meta.theme
```
:
```
academic
```
by default, or
```
academic-color
```
when color is useful
```
meta.title
```
: caption-ready figure title
```
meta.description
```
: one sentence explaining the figure intent

Default deliverables:

```
<name>.drawio
```
```
<name>.spec.yaml
```
```
<name>.arch.json
```
```
<name>.svg
```

Add

<name>.png

only when the user asks for PNG, Word, thesis/A4, raster-first, or screenshot matching, and draw.io Desktop export is available.

对于学术论文请求，渲染前需设置以下内容：

```
meta.profile: academic-paper
```

meta.figureType

：精确设置为

architecture

、

roadmap

或

workflow

中的一种

```
meta.theme
```
：默认
```
academic
```
，当需要色彩时设为
```
academic-color
```
```
meta.title
```
：可直接作为图注的图表标题
```
meta.description
```
：一句话说明图表用途

默认交付内容：

```
<name>.drawio
```
```
<name>.spec.yaml
```
```
<name>.arch.json
```
```
<name>.svg
```

仅当用户要求PNG、Word、学位论文/A4格式、优先栅格化或匹配截图时，且draw.io Desktop导出可用的情况下，才添加

<name>.png

。

Create Flow

创建流程

Classify the figure as
```
architecture
```
,
```
roadmap
```
, or
```
workflow
```
.
Draft the YAML spec as the canonical source.
Use concise labels; shorten labels before shrinking fonts.

Validate before rendering:

bash

node <skill-dir>/scripts/cli.js input.yaml output.drawio --validate --write-sidecars
node <skill-dir>/scripts/cli.js input.yaml output.svg --validate --write-sidecars

Use
```
--strict
```
or
```
--strict-warnings
```
for publication-grade checks.
Self-check the exported SVG/PNG when vision is available.
Apply targeted edits to YAML or XML, re-render, and repeat until approved.

将图表分类为
```
architecture
```
、
```
roadmap
```
或
```
workflow
```
。
起草YAML规范作为权威源。
使用简洁标签；先缩短标签再缩小字体。

渲染前进行验证：

bash

node <skill-dir>/scripts/cli.js input.yaml output.drawio --validate --write-sidecars
node <skill-dir>/scripts/cli.js input.yaml output.svg --validate --write-sidecars

使用
```
--strict
```
或
```
--strict-warnings
```
进行发表级检查。
若具备视觉能力，对导出的SVG/PNG进行自检。
针对性编辑YAML或XML，重新渲染，重复操作直至通过审核。

Edit and Replicate Flow

编辑与复制流程

If a
```
.spec.yaml
```
sidecar exists, edit the YAML spec first.

If only

.drawio

exists, import it before editing:

bash

node <skill-dir>/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars

After import, inspect the generated
```
.spec.yaml
```
and
```
.arch.json
```
, apply edits to the YAML spec, then regenerate the requested
```
.drawio
```
or
```
.svg
```
with
```
--write-sidecars
```
.
Keep all regenerated files on the same basename so the bundle remains round-trippable.
For image/SVG replication, extract palette intent first and preserve the source palette unless the user asks for paper-safe recoloring.
For major structural changes, show an ASCII logic draft before rendering.

Preserve

<name>.drawio

<name>.spec.yaml

, and

<name>.arch.json

together.

若存在
```
.spec.yaml
```
辅助文件，优先编辑YAML规范。

若仅存在

.drawio

文件，先导入再编辑：

bash

node <skill-dir>/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars

导入后，检查生成的
```
.spec.yaml
```
和
```
.arch.json
```
，对YAML规范进行编辑，然后使用
```
--write-sidecars
```
重新生成请求的
```
.drawio
```
或
```
.svg
```
。
所有重新生成的文件使用相同的基础名称，确保包可双向转换。
对于图片/SVG复制，先提取调色板意图，除非用户要求适配论文的重新配色，否则保留源调色板。
对于重大结构变更，渲染前先展示ASCII逻辑草稿。

将

<name>.drawio

、

<name>.spec.yaml

和

<name>.arch.json

放在一起保存。

Export Policy

导出策略

Use the local CLI for deterministic exports.

bash

undefined

使用本地CLI进行确定性导出。

bash

undefined

Offline SVG and sidecars

离线SVG和辅助文件

node <skill-dir>/scripts/cli.js input.yaml figure.svg --validate --write-sidecars

Editable .drawio bundle

可编辑.drawio包

node <skill-dir>/scripts/cli.js input.yaml figure.drawio --validate --write-sidecars

Desktop-enhanced exports

桌面端增强导出

node <skill-dir>/scripts/cli.js input.yaml figure.drawio.svg --validate --write-sidecars --use-desktop node <skill-dir>/scripts/cli.js input.yaml figure.png --validate --use-desktop node <skill-dir>/scripts/cli.js input.yaml figure.pdf --validate --use-desktop


Desktop CLI supports PNG/SVG/PDF/JPG. PNG/SVG/PDF exports can embed the editable diagram XML.

If Desktop is unavailable, generate a diagrams.net URL:

```bash
node <skill-dir>/scripts/runtime/diagrams-net-url.js figure.drawio

The diagram XML is encoded after

#R

in the URL fragment. The fragment is client-side and is not sent to diagrams.net servers.

If Desktop is unavailable for PNG/PDF/JPG, do not pretend those files exist. Deliver

.drawio

.spec.yaml

.arch.json

, and

.svg

, then include the diagrams.net URL or the exact Desktop command the user can run later.


Desktop CLI支持PNG/SVG/PDF/JPG。PNG/SVG/PDF导出可嵌入可编辑的图表XML。

若Desktop不可用，生成diagrams.net URL：

```bash
node <skill-dir>/scripts/runtime/diagrams-net-url.js figure.drawio

图表XML编码在URL片段的

#R

之后。该片段在客户端处理，不会发送至diagrams.net服务器。

若Desktop不可用无法生成PNG/PDF/JPG，请勿谎称这些文件存在。交付.drawio、.spec.yaml、.arch.json和.svg，然后提供diagrams.net URL或用户稍后可运行的准确Desktop命令。

Style Presets

样式预设

Use user presets from

~/.drawio-academic-skills/styles/

first, then bundled presets from

styles/built-in/

Supported operations:

learn a style from
```
.drawio
```
,
```
.xml
```
,
```
.svg
```
,
```
.png
```
,
```
.jpg
```
, or
```
.jpeg
```
preview a generated sample before saving
list presets
set one user preset as default
rename or delete user presets

Never mutate bundled presets. Copy a bundled preset into

~/.drawio-academic-skills/styles/

before making it a default.

优先使用

~/.drawio-academic-skills/styles/

中的用户预设，再使用

styles/built-in/

中的内置预设。

支持的操作：

从.drawio、.xml、.svg、.png、.jpg或.jpeg中学习样式
保存前预览生成的示例
列出预设
将一个用户预设设为默认
重命名或删除用户预设

绝不修改内置预设。将内置预设复制到

~/.drawio-academic-skills/styles/

后再设为默认。

Failure Recovery

故障恢复

Use these fallbacks before stopping:

Failure	Recovery
YAML validation fails	Fix the YAML spec first, then rerun the same CLI command with `--validate` .
`.drawio` import is incomplete	Preserve the original file, export the partial spec, and report unsupported shapes or styles explicitly.
Desktop export fails or Desktop is missing	Regenerate the offline bundle and SVG, then provide a diagrams.net URL fallback.
Formula rendering is wrong	Recheck delimiters against the math reference, then simplify the label before changing layout.
SVG/PNG self-check finds overlap	Edit labels or routing in YAML/XML and re-render; do not only describe the issue.

停止前使用以下备选方案：

故障类型	恢复方案
YAML验证失败	先修复YAML规范，再使用 `--validate` 重新运行相同的CLI命令。
.drawio导入不完整	保留原始文件，导出部分规范，并明确报告不支持的形状或样式。
Desktop导出失败或Desktop缺失	重新生成离线包和SVG，然后提供diagrams.net URL备选方案。
公式渲染错误	根据数学参考重新检查分隔符，然后先简化标签再更改布局。
SVG/PNG自检发现重叠	在YAML/XML中编辑标签或路由并重新渲染；不要仅描述问题。

Quality Gate

质量管控

Do not claim completion until:

```
.drawio
```
,
```
.spec.yaml
```
,
```
.arch.json
```
, and
```
.svg
```
are aligned
academic profile has a valid
```
figureType
```
labels are readable at paper/A4 scale
formulas use official delimiters:
```
$$...$$
```
,
```
$...$
```
, or AsciiMath backticks
connector routing is readable
colors are not the only carrier of meaning
requested PNG/PDF/JPG exports were attempted through draw.io Desktop or clearly reported as unavailable
no MCP config, MCP server, or live backend is required for the result

满足以下条件才可声称完成：

.drawio、.spec.yaml、.arch.json和.svg内容一致
学术配置文件包含有效的
```
figureType
```
标签在论文/A4尺寸下清晰可读
公式使用官方分隔符：
```
$$...$$
```
、
```
$...$
```
或AsciiMath反引号
连接线路由清晰可读
颜色不是唯一的含义载体
请求的PNG/PDF/JPG导出已尝试通过draw.io Desktop生成，或明确报告不可用
结果无需MCP配置、MCP服务器或实时后端

Completion Report

完成报告

End with a concise report:

Deliverables written, with paths.
Commands run for validation/export.
Any unavailable exports and the fallback provided.
Remaining manual checks, if visual inspection or Desktop export could not run.

结尾附上简洁报告：

已写入的交付内容及路径。
用于验证/导出的命令。
任何不可用的导出及提供的备选方案。
剩余的手动检查项（若无法进行视觉检查或Desktop导出）。

Reference Files

参考文件

references/docs/upstream-pure-drawio-skill.md

: preserved upstream pure SKILL.md workflow

references/docs/academic-figure-playbook.md

: academic figure typing and delivery rules

references/docs/academic-export-checklist.md

: paper-ready checklist

```
references/docs/math-typesetting.md
```
: formula syntax and export guidance
```
references/official/xml-reference.md
```
: draw.io XML mirror
```
references/official/style-reference.md
```
: draw.io style mirror
```
references/examples/
```
: reusable YAML examples
```
styles/built-in/
```
: upstream pure-skill style presets
```
assets/themes/
```
: YAML/CLI design-system themes

references/docs/upstream-pure-drawio-skill.md

：保留的上游纯SKILL.md工作流

references/docs/academic-figure-playbook.md

：学术图表分类和交付规则

references/docs/academic-export-checklist.md

：论文就绪检查清单

```
references/docs/math-typesetting.md
```
：公式语法和导出指南
```
references/official/xml-reference.md
```
：draw.io XML镜像
```
references/official/style-reference.md
```
：draw.io样式镜像
```
references/examples/
```
：可复用的YAML示例
```
styles/built-in/
```
：上游纯技能样式预设
```
assets/themes/
```
：YAML/CLI设计系统主题