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(pages): document codebase viz, shape search & AI logos (#29)

Agents365.ai8d0c9d396d6d
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
index 74bd3c7..5a62dd2 100644
--- a/docs/COMPARISON.md
+++ b/docs/COMPARISON.md
@@ -13,6 +13,11 @@
| Layout guidelines | None — varies by run | Complexity-scaled spacing, routing corridors, hub placement |
| Grid alignment | No | Yes — all coordinates snap to 10px multiples |
| Diagram type presets | No | Yes — 6 presets (ERD, UML, Sequence, Architecture, ML/DL, Flowchart) |
+| Visualize a codebase | No | Yes — import graphs (Py/JS/Go/Rust) + class diagrams |
+| Auto-layout for large graphs | No — hand-places, overlaps | Yes — Graphviz placement, ortho routing, nested containers |
+| Structural validation | No | Yes — deterministic `.drawio` linter |
+| Official shape search | No — guesses, blank boxes | Yes — exact style for 10k+ AWS/Azure/GCP/UML shapes |
+| AI/LLM brand logos | No — none | Yes — 321 logos (OpenAI/Claude/Gemini/…) via aiicons.py |
| Animated connectors | No | Yes — `flowAnimation=1` for data-flow visualization |
| ML model diagrams | No | Yes — tensor shape annotations, layer-type color coding |
| Color palette | Random/inconsistent | 7-color semantic system (blue=services, green=DB, purple=auth...) |
@@ -36,6 +41,8 @@
| **Animated edges** | ✅ `flowAnimation=1` | ❌ | ❌ | ❌ |
| **ML/DL diagrams** | ✅ tensor shapes, layer colors | ❌ | ❌ | ❌ |
| **Color system** | ✅ 7-color semantic | ❌ | ✅ 6 themes | ❌ |
+| **Official shape search** | ✅ 10k+ shapes (local) | ✅ 10k+ shapes (MCP) | ❌ | ❌ |
+| **AI/LLM brand logos** | ✅ 321 (lobe-icons) | ❌ | ❌ | ❌ |
| **Container/group** | ✅ swimlane + group | ✅ detailed | ❌ | ❌ |
| **Embed diagram** | ✅ `--embed-diagram` | ✅ | ❌ | ❌ |
| **Edge routing** | ✅ corridors + waypoints | ✅ arrowhead rules | ❌ | ❌ |
diff --git a/docs/COMPARISON_CN.md b/docs/COMPARISON_CN.md
index c44b8c7..b32afac 100644
--- a/docs/COMPARISON_CN.md
+++ b/docs/COMPARISON_CN.md
@@ -13,6 +13,11 @@
| 布局规范 | 无 — 每次结果不一致 | 按复杂度分级间距、路由走廊、hub 居中策略 |
| 网格对齐 | 否 | 是 — 所有坐标对齐到 10px 倍数 |
| 图表类型预设 | 否 | 是 — 6 种预设(ERD、UML、序列图、架构图、ML/DL、流程图) |
+| 可视化代码库 | 否 | 是 — 导入关系图(Py/JS/Go/Rust)+ 类图 |
+| 大图自动布局 | 否 — 手动摆放、易重叠 | 是 — Graphviz 布点、正交路由、嵌套容器 |
+| 结构校验 | 否 | 是 — 确定性 `.drawio` linter |
+| 官方形状搜索 | 否 — 靠猜、变空白框 | 是 — 1 万+ AWS/Azure/GCP/UML 形状的精确 style |
+| AI/LLM 品牌图标 | 否 — 没有 | 是 — 321 个 logo(OpenAI/Claude/Gemini/…)经 aiicons.py |
| 动画连接线 | 否 | 是 — `flowAnimation=1` 数据流可视化 |
| ML/DL 模型图 | 否 | 是 — 张量形状标注、层类型配色 |
| 配色方案 | 随机/不一致 | 7 色语义系统(蓝=服务、绿=数据库、紫=安全…) |
@@ -36,6 +41,8 @@
| **动画连线** | ✅ `flowAnimation=1` | ❌ | ❌ | ❌ |
| **ML/DL 图** | ✅ 张量标注、层配色 | ❌ | ❌ | ❌ |
| **配色系统** | ✅ 7 色语义 | ❌ | ✅ 6 种主题 | ❌ |
+| **官方形状搜索** | ✅ 1 万+ 形状(本地) | ✅ 1 万+ 形状(MCP) | ❌ | ❌ |
+| **AI/LLM 品牌图标** | ✅ 321 个(lobe-icons) | ❌ | ❌ | ❌ |
| **容器/分组** | ✅ swimlane + group | ✅ 详细 | ❌ | ❌ |
| **嵌入式导出** | ✅ `--embed-diagram` | ✅ | ❌ | ❌ |
| **连线路由** | ✅ 走廊 + waypoints | ✅ 箭头间距规则 | ❌ | ❌ |
diff --git a/docs/USAGE.md b/docs/USAGE.md
index f05b618..2df7385 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -43,3 +43,42 @@ E-commerce architecture with 2 cross-connections: Order→Product (same-tier hor
CI/CD pipeline with a closed loop and 2 spur branches. Edges flow along the perimeter without crossing the interior.
![Ring cycle](../assets/demo-ring.png)
+
+## Visualize a codebase
+
+Turn an existing project into an auto-laid-out structure diagram — no manual coordinates. Just ask: *"Visualize the module structure of this Python project"* or *"Draw the class hierarchy of `mypackage`"*. Under the hood it runs a bundled extractor → auto-layout → validate pipeline:
+
+```bash
+# Import graph — Python / JS-TS / Go / Rust
+python3 scripts/pyimports.py myproject --group -o graph.json
+python3 scripts/jsimports.py ./src --group -o graph.json
+python3 scripts/goimports.py ./module --group -o graph.json
+python3 scripts/rustimports.py ./crate --group -o graph.json
+
+# Python class-inheritance hierarchy
+python3 scripts/pyclasses.py mypackage --group -o graph.json
+
+# any extractor → auto-layout → editable .drawio
+python3 scripts/autolayout.py graph.json -o diagram.drawio
+```
+
+Graphviz places nodes and routes orthogonal edges around them, transitive reduction thins dense graphs, `--group` boxes modules by sub-package, and `validate.py` lints the `.drawio` (dangling edges, duplicate ids, overlaps) before the visual self-check. Layout needs Graphviz (`brew install graphviz` / `apt install graphviz`) — optional; everything else works without it.
+
+## 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:
+
+```bash
+python3 scripts/shapesearch.py "aws lambda" --limit 5
+# → Lambda (77x93)
+# outlineConnect=0;...;shape=mxgraph.aws3.lambda;fillColor=#F58534;...
+```
+
+## AI / LLM brand logos
+
+draw.io ships no modern AI/LLM logos, so an LLM-app diagram renders as generic boxes. `aiicons.py` resolves a brand name to a draw.io image style for any of 321 logos (OpenAI, Claude, Gemini, Mistral, Llama, Ollama, LangChain…) from [lobe-icons](https://github.com/lobehub/lobe-icons) (MIT):
+
+```bash
+python3 scripts/aiicons.py "claude" --json # CDN-referenced (default)
+python3 scripts/aiicons.py "openai" --embed # self-contained data URI
+```
diff --git a/docs/USAGE_CN.md b/docs/USAGE_CN.md
index 73a01d8..58408bd 100644
--- a/docs/USAGE_CN.md
+++ b/docs/USAGE_CN.md
@@ -44,3 +44,42 @@ Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification
CI/CD 流水线,包含闭合回路和 2 个分支。线条沿矩形外围流动,不穿越内部区域。
![环形拓扑](../assets/demo-ring-cn.png)
+
+## 可视化代码库
+
+把现有项目变成自动布局的结构图 —— 无需手动摆坐标。直接说:*"可视化这个 Python 项目的模块结构"* 或 *"画出 `mypackage` 的类继承层级"*。幕后是一条 提取器 → 自动布局 → 校验 的流水线:
+
+```bash
+# 导入关系图 —— Python / JS-TS / Go / Rust
+python3 scripts/pyimports.py myproject --group -o graph.json
+python3 scripts/jsimports.py ./src --group -o graph.json
+python3 scripts/goimports.py ./module --group -o graph.json
+python3 scripts/rustimports.py ./crate --group -o graph.json
+
+# Python 类继承层级
+python3 scripts/pyclasses.py mypackage --group -o graph.json
+
+# 任一提取器 → 自动布局 → 可编辑的 .drawio
+python3 scripts/autolayout.py graph.json -o diagram.drawio
+```
+
+Graphviz 自动布点,正交连线绕开节点,传递约简把密集图变清晰,`--group` 按子包给模块分框,`validate.py` 在视觉自检前先做结构 lint(悬空边、重复 id、重叠)。布局需要 Graphviz(`brew install graphviz` / `apt install graphviz`)—— 可选,其余功能无需它。
+
+## 形状搜索
+
+需要真实的 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN 图标?Skill 会在 10,000+ 个官方 draw.io 形状中搜出精确的 style 字符串 —— 厂商图标正确渲染,而不是因为猜错 `shape=mxgraph.*` 名称而退化成空白方框:
+
+```bash
+python3 scripts/shapesearch.py "aws lambda" --limit 5
+# → Lambda (77x93)
+# outlineConnect=0;...;shape=mxgraph.aws3.lambda;fillColor=#F58534;...
+```
+
+## AI / LLM 品牌图标
+
+draw.io 没有任何现代 AI/LLM 品牌图标,所以画 LLM 应用架构时只能是一堆方框。`aiicons.py` 能把品牌名解析成 draw.io 图片样式,覆盖 [lobe-icons](https://github.com/lobehub/lobe-icons)(MIT)的 321 个图标(OpenAI、Claude、Gemini、Mistral、Llama、Ollama、LangChain……):
+
+```bash
+python3 scripts/aiicons.py "claude" --json # CDN 引用(默认)
+python3 scripts/aiicons.py "openai" --embed # 内联为自包含 data URI
+```