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: CI rendering recipe (xvfb + Docker renderer, validate gate) (#57)
Agents365.ai0858eb0017d1
diff --git a/docs/CI.md b/docs/CI.mdnew file mode 100644index 0000000..da91097--- /dev/null+++ b/docs/CI.md@@ -0,0 +1,105 @@+# Rendering diagrams in CI++[中文](CI_CN.md)++Keep diagram **sources** in the repo (graph JSON from the importers, `seq.json`, `c4.json`, or hand-written `.drawio`) and let CI regenerate, lint, and export them — the diagram-as-code loop:++```+source (.tf / manifests / schema.sql / seq.json / graph.json)+ → extractor (tfimports / k8simports / sqlerd / seqlayout / …)+ → autolayout.py → validate.py --strict (gate) → drawio -x (render) → artifact+```++Importer node ids are stable (module paths, `type.name`, `kind/name`), so regenerated `.drawio` files produce reviewable diffs when the underlying code or infra changes.++## Option A — draw.io desktop + xvfb (GitHub Actions)++The desktop CLI works headless under `xvfb`. Complete workflow:++```yaml+name: diagrams+on:+ push:+ paths: ["infra/**", "diagrams/**"]++jobs:+ render:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ # The skill's scripts (importers, autolayout, validate)+ - run: git clone --depth 1 https://github.com/Agents365-ai/drawio-skill /tmp/drawio-skill+ - run: sudo apt-get update && sudo apt-get install -y graphviz xvfb++ # draw.io desktop (latest release .deb)+ - name: Install draw.io+ run: |+ URL=$(curl -s https://api.github.com/repos/jgraph/drawio-desktop/releases/latest \+ | grep -o 'https://[^"]*amd64[^"]*\.deb' | head -1)+ curl -sL "$URL" -o /tmp/drawio.deb+ sudo apt-get install -y /tmp/drawio.deb++ - name: Regenerate, lint, render+ run: |+ S=/tmp/drawio-skill/skills/drawio-skill/scripts+ python3 $S/tfimports.py infra -o /tmp/graph.json+ python3 $S/autolayout.py /tmp/graph.json -o diagrams/infra.drawio+ python3 $S/validate.py diagrams/infra.drawio --strict # gate: fail on any warning+ export HOME=${HOME:-/tmp}+ xvfb-run -a --server-args="-screen 0 1280x1024x24" \+ drawio -x -f png -e -s 2 -o diagrams/infra.drawio.png \+ diagrams/infra.drawio --disable-gpu --no-sandbox+ python3 $S/repair_png.py diagrams/infra.drawio.png # fix -e IEND truncation++ - uses: actions/upload-artifact@v4+ with: {name: diagrams, path: "diagrams/*.png"}+```++Notes (all from the skill's troubleshooting experience):++- `--no-sandbox` must be the **last** argument — earlier positions make drawio treat it as the input file. Required when running as root (CI containers).+- `export HOME=/tmp` if the runner has no home; add `--disable-gpu` on servers.+- After any `-e` PNG export, run `repair_png.py` — the CLI truncates the IEND chunk (issue #8).+- `--page-index <n>` (1-based) exports one page of a multi-page file (e.g. `c4.py` output).+- If the `.deb` install fails on missing libs: `sudo apt-get install -y libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64`.++## Option B — Docker REST renderer (no desktop install)++[`tomkludy/drawio-renderer`](https://hub.docker.com/r/tomkludy/drawio-renderer) exposes headless export as a REST API — useful on runners where installing a `.deb` is not an option:++```yaml+jobs:+ render:+ runs-on: ubuntu-latest+ services:+ drawio:+ image: tomkludy/drawio-renderer:latest+ ports: ["5000:5000"]+ steps:+ - uses: actions/checkout@v4+ - name: Render via REST+ run: |+ curl -s -X POST http://localhost:5000/convert \+ -H 'Content-Type: application/json' \+ -d "$(python3 -c 'import json,sys;print(json.dumps({+ "source": open("diagrams/infra.drawio").read(),+ "format": "png", "scale": 2}))')" \+ -o diagrams/infra.png+```++Validation (`validate.py --strict`) needs only Python — it runs the same way in both options.++## Committing rendered images back++Prefer uploading artifacts or publishing to Pages over committing PNGs. If you do commit them (e.g. README images), guard against loops:++```yaml+ - name: Commit refreshed diagrams+ run: |+ git config user.name github-actions+ git config user.email [email protected]+ git add diagrams/*.png+ git diff --cached --quiet || git commit -m "ci: refresh diagrams [skip ci]"+ git push+```diff --git a/docs/CI_CN.md b/docs/CI_CN.mdnew file mode 100644index 0000000..aae256b--- /dev/null+++ b/docs/CI_CN.md@@ -0,0 +1,105 @@+# 在 CI 中渲染图表++[English](CI.md)++把图表的**源**放进仓库(importer 产出的 graph JSON、`seq.json`、`c4.json`,或手写的 `.drawio`),由 CI 负责重新生成、校验、导出 —— 完整的 diagram-as-code 闭环:++```+源 (.tf / manifests / schema.sql / seq.json / graph.json)+ → 提取器 (tfimports / k8simports / sqlerd / seqlayout / …)+ → autolayout.py → validate.py --strict(门禁)→ drawio -x(渲染)→ 产物+```++Importer 的节点 id 是稳定的(模块路径、`type.name`、`kind/name`),代码或基础设施变更后重新生成的 `.drawio` diff 可读、可 review。++## 方案 A —— draw.io 桌面版 + xvfb(GitHub Actions)++桌面版 CLI 在 `xvfb` 下可无头运行。完整 workflow:++```yaml+name: diagrams+on:+ push:+ paths: ["infra/**", "diagrams/**"]++jobs:+ render:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4++ # 本 skill 的脚本(importer、autolayout、validate)+ - run: git clone --depth 1 https://github.com/Agents365-ai/drawio-skill /tmp/drawio-skill+ - run: sudo apt-get update && sudo apt-get install -y graphviz xvfb++ # draw.io 桌面版(最新 release 的 .deb)+ - name: Install draw.io+ run: |+ URL=$(curl -s https://api.github.com/repos/jgraph/drawio-desktop/releases/latest \+ | grep -o 'https://[^"]*amd64[^"]*\.deb' | head -1)+ curl -sL "$URL" -o /tmp/drawio.deb+ sudo apt-get install -y /tmp/drawio.deb++ - name: Regenerate, lint, render+ run: |+ S=/tmp/drawio-skill/skills/drawio-skill/scripts+ python3 $S/tfimports.py infra -o /tmp/graph.json+ python3 $S/autolayout.py /tmp/graph.json -o diagrams/infra.drawio+ python3 $S/validate.py diagrams/infra.drawio --strict # 门禁:任何警告即失败+ export HOME=${HOME:-/tmp}+ xvfb-run -a --server-args="-screen 0 1280x1024x24" \+ drawio -x -f png -e -s 2 -o diagrams/infra.drawio.png \+ diagrams/infra.drawio --disable-gpu --no-sandbox+ python3 $S/repair_png.py diagrams/infra.drawio.png # 修复 -e 的 IEND 截断++ - uses: actions/upload-artifact@v4+ with: {name: diagrams, path: "diagrams/*.png"}+```++注意事项(均来自本 skill 的踩坑记录):++- `--no-sandbox` 必须放在**最后一个**参数 —— 放前面会被当成输入文件名。CI 容器以 root 运行时必需。+- Runner 没有 home 目录时 `export HOME=/tmp`;服务器上加 `--disable-gpu`。+- 任何 `-e` PNG 导出之后都要跑 `repair_png.py` —— CLI 会截断 IEND chunk(issue #8)。+- `--page-index <n>`(1-based)导出多页文件的指定页(如 `c4.py` 的输出)。+- `.deb` 安装报缺库时:`sudo apt-get install -y libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64`。++## 方案 B —— Docker REST 渲染器(无需安装桌面版)++[`tomkludy/drawio-renderer`](https://hub.docker.com/r/tomkludy/drawio-renderer) 把无头导出封装成 REST API,适合不方便装 `.deb` 的 runner:++```yaml+jobs:+ render:+ runs-on: ubuntu-latest+ services:+ drawio:+ image: tomkludy/drawio-renderer:latest+ ports: ["5000:5000"]+ steps:+ - uses: actions/checkout@v4+ - name: Render via REST+ run: |+ curl -s -X POST http://localhost:5000/convert \+ -H 'Content-Type: application/json' \+ -d "$(python3 -c 'import json,sys;print(json.dumps({+ "source": open("diagrams/infra.drawio").read(),+ "format": "png", "scale": 2}))')" \+ -o diagrams/infra.png+```++校验(`validate.py --strict`)只需要 Python,两种方案下用法完全一致。++## 把渲染结果提交回仓库++优先用 artifact 或发布到 Pages,而不是提交 PNG。确实要提交(比如 README 配图)时,注意防循环:++```yaml+ - name: Commit refreshed diagrams+ run: |+ git config user.name github-actions+ git config user.email [email protected]+ git add diagrams/*.png+ git diff --cached --quiet || git commit -m "ci: refresh diagrams [skip ci]"+ git push+```diff --git a/docs/USAGE.md b/docs/USAGE.mdindex 2df7385..8b8029f 100644--- a/docs/USAGE.md+++ b/docs/USAGE.md@@ -82,3 +82,7 @@ draw.io ships no modern AI/LLM logos, so an LLM-app diagram renders as generic bpython3 scripts/aiicons.py "claude" --json # CDN-referenced (default)python3 scripts/aiicons.py "openai" --embed # self-contained data URI```++## Rendering in CI++Regenerate, lint (`validate.py --strict`), and export diagrams headlessly in GitHub Actions — via draw.io desktop under `xvfb` or the Docker REST renderer. Full workflow recipes in [CI.md](CI.md).diff --git a/docs/USAGE_CN.md b/docs/USAGE_CN.mdindex 58408bd..fc576fb 100644--- a/docs/USAGE_CN.md+++ b/docs/USAGE_CN.md@@ -83,3 +83,7 @@ draw.io 没有任何现代 AI/LLM 品牌图标,所以画 LLM 应用架构时python3 scripts/aiicons.py "claude" --json # CDN 引用(默认)python3 scripts/aiicons.py "openai" --embed # 内联为自包含 data URI```++## 在 CI 中渲染++在 GitHub Actions 里无头地重新生成、校验(`validate.py --strict`)并导出图表 —— 走 xvfb 下的 draw.io 桌面版或 Docker REST 渲染器。完整 workflow 配方见 [CI_CN.md](CI_CN.md)。