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.
Python agent-skillsarchitecturearchitecture-diagramasyncapibpmnc4-modelclaude-codediagramdiagrams-as-codedrawioflowchartgithub-actionsgraphqlimage-to-diagramkubernetesmcp-serverprotobufsysmlterraformuml
docs(pages): document codebase viz, shape search & AI logos (#29)
Agents365.ai8d0c9d396d6d
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.mdindex 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.mdindex 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.mdindex 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 horCI/CD pipeline with a closed loop and 2 spur branches. Edges flow along the perimeter without crossing the interior.++## 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.mdindex 73a01d8..58408bd 100644--- a/docs/USAGE_CN.md+++ b/docs/USAGE_CN.md@@ -44,3 +44,42 @@ Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,NotificationCI/CD 流水线,包含闭合回路和 2 个分支。线条沿矩形外围流动,不穿越内部区域。++## 可视化代码库++把现有项目变成自动布局的结构图 —— 无需手动摆坐标。直接说:*"可视化这个 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+```