Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

docs: surface v1.18 Mermaid authoring + version recommendation in READMEs (#62)

Agents365.ai62972139f249
diff --git a/README.md b/README.md
index bb1e314..0515f8c 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,7 @@ A skill that turns natural-language descriptions into `.drawio` XML and exports
## ✨ Highlights
- **7 diagram type presets** — ERD, UML Class, Sequence, C4, Architecture, ML/Deep Learning, Flowchart
+- **Mermaid → native .drawio** (draw.io ≥ 30) — author 28 standard types as Mermaid text (**mindmap, gantt, timeline, journey, pie, sankey, kanban**…) and the CLI converts them into a laid-out, editable `.drawio` — structure in, layout free
- **Visualize a codebase** — extract and auto-lay-out the structure of a Python / JS-TS / Go / Rust project (import graphs) or a Python class hierarchy — Graphviz placement, transitive reduction, nested module containers
- **IaC → architecture diagram** — turn **Terraform** configs, **Kubernetes** manifests, or **docker-compose** files into an architecture diagram where every resource renders as its **official AWS / Azure / GCP / K8s icon**, edges derived from actual references (role ARNs, selectors, volume mounts)
- **SQL DDL → ER diagram** — parse `CREATE TABLE` statements into per-table nodes with PK/FK markers and crow's-foot foreign-key edges
@@ -82,7 +83,7 @@ Full walkthrough in [docs/USAGE.md](docs/USAGE.md).
| **Windows** | [Download installer](https://github.com/jgraph/drawio-desktop/releases) |
| **Linux** | `.deb`/`.rpm` from [releases](https://github.com/jgraph/drawio-desktop/releases); `sudo apt install xvfb` for headless |
-Verify with `drawio --version`. On **WSL2** the CLI is the Windows desktop exe reached via `/mnt/c` — the skill detects this automatically (see [troubleshooting](skills/drawio-skill/references/troubleshooting.md)). Full recipes in [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md).
+Verify with `drawio --version`. **Version ≥ 30 recommended** — it unlocks Mermaid → `.drawio` conversion and the ELK `--layout` pass (both unavailable on ≤ 29). On **WSL2** the CLI is the Windows desktop exe reached via `/mnt/c` — the skill detects this automatically (see [troubleshooting](skills/drawio-skill/references/troubleshooting.md)). Full recipes in [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md).
### 2. Install the skill
@@ -212,7 +213,8 @@ Layout needs Graphviz (`brew install graphviz` / `apt install graphviz`) — opt
| Flowcharts | business processes, workflows, decision trees, state machines | Semantic shapes (parallelogram I/O, diamond decisions) |
| UML | class diagrams, sequence diagrams | Inheritance / composition / aggregation arrows; lifelines + activation boxes |
| Data | ER diagrams, data flow diagrams (DFD) | Table containers, PK/FK notation |
-| Other | org charts, mind maps, wireframes | — |
+| Mermaid-authored | mind maps, gantt, timeline, journey, pie, sankey, kanban + 20 more | Native CLI conversion (≥ v30) — structure only, layout free |
+| Other | org charts, wireframes | — |
## 🔍 Shape Search
@@ -280,6 +282,7 @@ Behind the scenes: **check dependencies → plan layout → generate `.drawio` X
| Self-check after export | ❌ | ✅ reads PNG, auto-fixes 6 issue types |
| Iterative review loop | ❌ manual re-prompt | ✅ targeted edits, 5-round safety valve |
| Diagram type presets | ❌ | ✅ 7 presets (ERD, UML, Seq, C4, Arch, ML, Flow) |
+| Mermaid → editable .drawio | ❌ | ✅ 28 types via native CLI conversion (≥ v30) |
| Visualize a codebase | ❌ | ✅ import graphs (Py/JS/Go/Rust) + class diagrams |
| IaC → architecture diagram | ❌ | ✅ Terraform / K8s / compose → official cloud icons |
| SQL DDL → ER diagram | ❌ | ✅ `CREATE TABLE` → PK/FK tables, crow's-foot edges |
@@ -303,6 +306,7 @@ Behind the scenes: **check dependencies → plan layout → generate `.drawio` X
| **Self-check + auto-fix** | ✅ 2-round (reads PNG) | ❌ | ✅ validation + strict mode | ❌ screenshot only |
| **Iterative review** | ✅ 5-round loop | ❌ generate once | ✅ 3 workflows | ❌ |
| **Diagram presets** | ✅ 7 types | ❌ | ✅ paper-mode classifier | ❌ |
+| **Mermaid authoring** | ✅ 28 types (CLI ≥ 30) | ✅ | ❌ | ❌ |
| **ML/DL diagrams** | ✅ tensor shapes, layer colors | ❌ | ❌ | ❌ |
| **Color system** | ✅ 7-color semantic | ❌ | ✅ 6 themes | ❌ |
| **Official shape search** | ✅ 10k+ shapes (local) | ✅ 10k+ shapes (MCP) | ❌ | ❌ |
diff --git a/README_CN.md b/README_CN.md
index 1b11bee..fb682db 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -23,6 +23,7 @@
## ✨ 核心亮点
- **7 种图表类型预设** —— ER 图、UML 类图、序列图、C4、架构图、ML/深度学习、流程图
+- **Mermaid → 原生 .drawio**(draw.io ≥ 30)—— 28 种标准类型直接用 Mermaid 文本作图(**mindmap、gantt、timeline、journey、pie、sankey、kanban**……),CLI 原生转成已布局、可编辑的 `.drawio` —— 只管结构,布局白送
- **可视化代码库** —— 提取并自动布局一个 Python / JS-TS / Go / Rust 项目的结构(导入关系图)或 Python 类继承层级 —— Graphviz 布点、传递约简、按子包嵌套的容器
- **IaC → 架构图** —— 把 **Terraform** 配置、**Kubernetes** manifest 或 **docker-compose** 文件直接变成架构图,每个资源渲染为**官方 AWS / Azure / GCP / K8s 图标**,连线来自真实引用(role ARN、selector、volume 挂载)
- **SQL DDL → ER 图** —— 解析 `CREATE TABLE` 语句,生成带 PK/FK 标记的表节点和鸦爪外键连线
@@ -81,7 +82,7 @@ Skill 在多种图表拓扑中尽量保持线条清晰路由,避免穿越无
| **Windows** | [下载安装包](https://github.com/jgraph/drawio-desktop/releases) |
| **Linux** | 从 [releases](https://github.com/jgraph/drawio-desktop/releases) 下载 `.deb`/`.rpm`;无头导出需 `sudo apt install xvfb` |
-用 `drawio --version` 验证。在 **WSL2** 上,CLI 是通过 `/mnt/c` 访问的 Windows 桌面版 exe —— Skill 会自动识别(见[故障排查](skills/drawio-skill/references/troubleshooting.md))。完整方案见 [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md)。
+用 `drawio --version` 验证。**推荐 ≥ 30 版本** —— 解锁 Mermaid → `.drawio` 转换和 ELK `--layout` 布局(≤ 29 两者均不可用)。在 **WSL2** 上,CLI 是通过 `/mnt/c` 访问的 Windows 桌面版 exe —— Skill 会自动识别(见[故障排查](skills/drawio-skill/references/troubleshooting.md))。完整方案见 [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md)。
### 2. 安装技能
@@ -210,7 +211,8 @@ python3 scripts/autolayout.py graph.json -o diagram.drawio
| 流程图 | 业务流程、工作流、决策树、状态机 | 语义形状(平行四边形 I/O、菱形判断) |
| UML | 类图、序列图 | 继承 / 组合 / 聚合箭头;生命线 + 激活框 |
| 数据图 | ER 图、数据流图(DFD) | 表容器、PK/FK 标记 |
-| 其他 | 组织架构图、思维导图、线框图 | — |
+| Mermaid 作图 | 思维导图、甘特图、timeline、journey、饼图、桑基图、看板等 28 种 | CLI(≥ v30)原生转换 —— 只写结构,布局白送 |
+| 其他 | 组织架构图、线框图 | — |
## 🔍 形状搜索
@@ -278,6 +280,7 @@ Skill 会提取配色、形状、字体和连线风格,渲染预览图,**确
| 导出后自检 | ❌ | ✅ 读取 PNG 自动修复 6 类问题 |
| 迭代审查循环 | ❌ 需手动重新提问 | ✅ 定向编辑,5 轮安全阀 |
| 图表类型预设 | ❌ | ✅ 7 种(ERD、UML、序列、C4、架构、ML、流程) |
+| Mermaid → 可编辑 .drawio | ❌ | ✅ 28 种类型,CLI 原生转换(≥ v30) |
| 可视化代码库 | ❌ | ✅ 导入关系图(Py/JS/Go/Rust)+ 类图 |
| IaC → 架构图 | ❌ | ✅ Terraform / K8s / compose → 官方云图标 |
| SQL DDL → ER 图 | ❌ | ✅ `CREATE TABLE` → PK/FK 表节点 + 鸦爪连线 |
@@ -301,6 +304,7 @@ Skill 会提取配色、形状、字体和连线风格,渲染预览图,**确
| **自检 + 自动修复** | ✅ 2 轮(读取 PNG) | ❌ | ✅ 校验 + 严格模式 | ❌ 仅截图 |
| **迭代审查** | ✅ 5 轮循环 | ❌ 一次生成 | ✅ 3 种工作流 | ❌ |
| **图表预设** | ✅ 7 种 | ❌ | ✅ 论文模式分类 | ❌ |
+| **Mermaid 作图** | ✅ 28 种(CLI ≥ 30) | ✅ | ❌ | ❌ |
| **ML/DL 图** | ✅ 张量标注、层配色 | ❌ | ❌ | ❌ |
| **配色系统** | ✅ 7 色语义 | ❌ | ✅ 6 种主题 | ❌ |
| **官方形状搜索** | ✅ 1 万+ 形状(本地) | ✅ 1 万+ 形状(MCP) | ❌ | ❌ |