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: CI rendering recipe (xvfb + Docker renderer, validate gate) (#57)

Agents365.ai0858eb0017d1
diff --git a/docs/CI.md b/docs/CI.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 b
python3 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.md
index 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)。