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(readme): document shape search, editable URL, WSL2 (v1.11.0) (#21)

Agents365.ai651ffaea0b9f
diff --git a/README.md b/README.md
index 65375dc..f833db0 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ A skill that turns natural-language descriptions into `.drawio` XML and exports
- **6 diagram type presets** — ERD, UML Class, Sequence, Architecture, ML/Deep Learning, Flowchart
- **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
+- **Search 10,000+ official shapes** — resolve the exact AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN icon style instead of guessing (no more blank-box `shape=mxgraph.*` typos)
- **Self-check + auto-fix** — reads its own PNG output and auto-fixes overlaps, clipped labels, stacked edges, and more (up to 2 rounds)
- **Iterative feedback loop** — up to 5 rounds of targeted refinement
- **Style presets** — capture your visual style from a `.drawio` file or image, reuse on demand
@@ -76,7 +77,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`. Full recipes in [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md).
+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).
### 2. Install the skill
@@ -163,6 +164,20 @@ Layout needs Graphviz (`brew install graphviz` / `apt install graphviz`) — opt
| Data | ER diagrams, data flow diagrams (DFD) | Table containers, PK/FK notation |
| Other | org charts, mind maps, wireframes | — |
+## 🔍 Shape Search
+
+Need a real AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN icon? The skill searches **10,000+ official draw.io shapes** for the exact style string — so vendor icons render correctly instead of falling back to a blank box from a guessed `shape=mxgraph.*` name.
+
+> *"Add an AWS Lambda wired to an S3 bucket"* · *"Use the real Kubernetes pod icon"*
+
+```bash
+python3 scripts/shapesearch.py "aws lambda" --limit 5
+# → Lambda (77x93)
+# outlineConnect=0;...;shape=mxgraph.aws3.lambda;fillColor=#F58534;...
+```
+
+Covers AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN / ER / electrical / P&ID and the general shape sets. Hand-writable style cheatsheet + search usage in [references/shapes.md](skills/drawio-skill/references/shapes.md).
+
## 🎨 Style Presets
Capture a visual style once, reuse it everywhere. Three presets are built in — `default`, `corporate`, `handdrawn` — and you can teach the skill your own style from a `.drawio` file or a flat image:
@@ -197,6 +212,7 @@ Behind the scenes: **check dependencies → plan layout → generate `.drawio` X
| Visualize a codebase | ❌ | ✅ import graphs (Py/JS/Go/Rust) + class diagrams |
| Auto-layout for large graphs | ❌ hand-places, overlaps | ✅ Graphviz placement, ortho routing, nested containers |
| Structural validation | ❌ | ✅ deterministic `.drawio` linter |
+| Official shape search | ❌ guesses, blank boxes | ✅ exact style for 10k+ AWS/Azure/GCP/UML shapes |
| Grid-aligned layout | ❌ | ✅ 10px snap, routing corridors |
| Color palette | random / inconsistent | ✅ 7-color semantic system |
| Style presets | ❌ | ✅ learn from `.drawio` file or image |
@@ -213,7 +229,8 @@ Behind the scenes: **check dependencies → plan layout → generate `.drawio` X
| **Diagram presets** | ✅ 6 types | ❌ | ✅ paper-mode classifier | ❌ |
| **ML/DL diagrams** | ✅ tensor shapes, layer colors | ❌ | ❌ | ❌ |
| **Color system** | ✅ 7-color semantic | ❌ | ✅ 6 themes | ❌ |
-| **Browser fallback** | ✅ diagrams.net URL | ❌ inline preview only | ✅ via optional MCP | ✅ diagrams.net viewer (primary) |
+| **Official shape search** | ✅ 10k+ shapes (local) | ✅ 10k+ shapes (MCP) | ❌ | ❌ |
+| **Browser fallback** | ✅ diagrams.net URL (viewer + editable) | ❌ inline preview only | ✅ via optional MCP | ✅ diagrams.net viewer (primary) |
| **Zero-config** | ✅ copy `skills/drawio-skill/` | ✅ | ✅ desktop-only mode | ❌ needs plugin install |
Full comparison + key-advantages summary in [docs/COMPARISON.md](docs/COMPARISON.md) (with audit timestamp).
diff --git a/README_CN.md b/README_CN.md
index 9dc07f1..29ac211 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -24,6 +24,7 @@
- **6 种图表类型预设** —— ER 图、UML 类图、序列图、架构图、ML/深度学习、流程图
- **可视化代码库** —— 提取并自动布局一个 Python / JS-TS / Go / Rust 项目的结构(导入关系图)或 Python 类继承层级 —— Graphviz 布点、传递约简、按子包嵌套的容器
+- **搜索 10,000+ 个官方形状** —— 直接拿到 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN 图标的精确 style,不靠猜(杜绝 `shape=mxgraph.*` 拼错变空白框)
- **自检 + 自动修复** —— 读取自己导出的 PNG,自动修复重叠、截断标签、连线堆叠等问题(最多 2 轮)
- **迭代反馈循环** —— 最多 5 轮定向优化
- **样式预设** —— 用 `.drawio` 文件或图片"教会"Skill 你的风格,命名保存后随时复用
@@ -75,7 +76,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` 验证。完整方案见 [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md)。
+用 `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)。
### 2. 安装技能
@@ -161,6 +162,20 @@ python3 scripts/autolayout.py graph.json -o diagram.drawio
| 数据图 | ER 图、数据流图(DFD) | 表容器、PK/FK 标记 |
| 其他 | 组织架构图、思维导图、线框图 | — |
+## 🔍 形状搜索
+
+需要真实的 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN 图标?Skill 会在 **10,000+ 个官方 draw.io 形状**中搜出精确的 style 字符串 —— 厂商图标正确渲染,而不是因为猜错 `shape=mxgraph.*` 名称而退化成空白方框。
+
+> *"加一个 AWS Lambda 连到 S3 桶"* · *"用真正的 Kubernetes pod 图标"*
+
+```bash
+python3 scripts/shapesearch.py "aws lambda" --limit 5
+# → Lambda (77x93)
+# outlineConnect=0;...;shape=mxgraph.aws3.lambda;fillColor=#F58534;...
+```
+
+覆盖 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN / ER / 电气 / P&ID 以及通用形状集。可手写的 style 速查表 + 搜索用法见 [references/shapes.md](skills/drawio-skill/references/shapes.md)。
+
## 🎨 样式预设
把视觉风格"教"给 Skill 一次,所有图表自动复用。内置三种预设:`default`、`corporate`、`handdrawn`;也可以从 `.drawio` 文件或图片学习你的风格:
@@ -195,6 +210,7 @@ Skill 会提取配色、形状、字体和连线风格,渲染预览图,**确
| 可视化代码库 | ❌ | ✅ 导入关系图(Py/JS/Go/Rust)+ 类图 |
| 大图自动布局 | ❌ 手动摆放、易重叠 | ✅ Graphviz 布点、正交路由、嵌套容器 |
| 结构校验 | ❌ | ✅ 确定性 `.drawio` linter |
+| 官方形状搜索 | ❌ 靠猜、变空白框 | ✅ 1 万+ AWS/Azure/GCP/UML 形状的精确 style |
| 网格对齐布局 | ❌ | ✅ 10px 对齐、路由走廊 |
| 配色方案 | 随机 / 不一致 | ✅ 7 色语义系统 |
| 样式预设 | ❌ | ✅ 从 `.drawio` 文件或图片学习 |
@@ -211,7 +227,8 @@ Skill 会提取配色、形状、字体和连线风格,渲染预览图,**确
| **图表预设** | ✅ 6 种 | ❌ | ✅ 论文模式分类 | ❌ |
| **ML/DL 图** | ✅ 张量标注、层配色 | ❌ | ❌ | ❌ |
| **配色系统** | ✅ 7 色语义 | ❌ | ✅ 6 种主题 | ❌ |
-| **浏览器降级** | ✅ diagrams.net URL | ❌ 仅内联预览 | ✅ 通过可选 MCP | ✅ diagrams.net viewer(主要) |
+| **官方形状搜索** | ✅ 1 万+ 形状(本地) | ✅ 1 万+ 形状(MCP) | ❌ | ❌ |
+| **浏览器降级** | ✅ diagrams.net URL(查看 + 可编辑) | ❌ 仅内联预览 | ✅ 通过可选 MCP | ✅ diagrams.net viewer(主要) |
| **零配置** | ✅ 复制 `skills/drawio-skill/` | ✅ | ✅ 桌面版模式 | ❌ 需安装插件 |
完整对比 + 核心优势总结见 [docs/COMPARISON_CN.md](docs/COMPARISON_CN.md)(含核查时间戳)。