stack-diagram 是什么:一句话让 Agent 画出架构图

写技术方案、README 或者给新人讲系统时,总要一张架构图。手动在画图工具里找各家 logo、拉箭头、对齐分组,一张图要花不少时间;让 Agent 直接画,又常常是方框加文字,logo 不对,箭头还穿过标签。stack-diagram 是一个专门画这种图的 Agent Skill:你用一句话描述技术栈,它去官方来源取 logo,按云厂商架构图的样式排版,输出一个自带字体和图标的 HTML 文件。这篇按仓库 README、SKILL.md 和发布页,讲它怎么工作、怎么装、用的时候要注意什么。
它是什么
stack-diagram 是一个遵循 Agent Skills 规范的 Skill,适用于 Claude Code、Codex、Cursor 等支持 Skill 的 Agent。输出的主文件是一个单独的 HTML,字体和图标都以 data URI 内嵌,断网也能打开;PNG、React 组件和 Artifact 都从这个 HTML 派生。
| 仓库 | github.com/caru-ini/stack-diagram |
|---|---|
| 作者 | caru-ini |
| 许可证 | 代码和文档 MIT;内置字体 SIL OFL 1.1;logo 不随 Skill 分发 |
| 热度 | GitHub 2,555 星、136 fork(GitHub API,2026-11-17 北京时间) |
| 运行要求 | Python 3.9+(脚本只用标准库),取图标要联网;PNG 需 Playwright + Chromium |
| 最新版本 | v0.6.0(2026-11-13 15:38 北京时间,新增 Kubernetes 官方图标) |
解决什么问题
让 Agent 画架构图,常见的问题有三个:logo 是凭记忆画的,颜色和形状都不对;箭头穿过文字;画完没人检查。stack-diagram 在 SKILL.md 里对这三点都定了规则:
| 问题 | stack-diagram 的做法 |
|---|---|
| logo 不对 | 按顺序从 svgl、devicon、gilbarbara/logos 或品牌官网取,云厂商用官方图标包;明确不用单色重绘的 simple-icons |
| 箭头压字 | references/geometry.md 规定节点等于图块加下方文字,连线绕开标签 |
| 画完不检查 | 第 5 步要求先渲染 PNG、看图,按清单逐项核对,有问题改完再交付 |
连线分三类:强调色实线是主请求流,灰色实线是内部调用,灰色虚线是 CI、部署这类开发期关系。每张图同时出浅色和深色两版。
怎么用
1. 安装。用 npx skills 装到本机的 Agent:
npx skills add caru-ini/stack-diagram
在 Claude 网页版或桌面 App 里,可以从发布页下载 stack-diagram.zip,作为 Skill 上传。
2. 想导出 PNG,先装浏览器依赖。
pip install playwright && python3 -m playwright install --with-deps chromium
3. 直接描述技术栈。README 的例子:
Diagram our stack: Next.js and a Hono API on Vercel. Postgres on Neon,
auth with Clerk, payments with Stripe. GitHub Actions deploys.
只给一串工具名也行,Skill 要求 Agent 按工具类型自己推断分组和数据流,只有工具含义模糊到会画错时才追问。
4. Agent 背后跑的脚本。了解这几步,图不对时容易查到是哪一环出的错:
python3 scripts/fetch_icons.py <icons-dir> hono "s3:aws/s3" "pod:k8s/pod"
python3 scripts/build.py my-diagram.html <icons-dir> out.html --fonts <skill>/assets/fonts
python3 scripts/render_png.py out.html check.png --selector .canvas --scale 2
某个 logo 所有来源都找不到时,可以用 name=URL 直接指定官方文件地址;「定时任务」「缓存」这类没有品牌的节点,用 Lucide 线条图标,例如 cron:lucide/clock。
流程里写明「画完先截图看一遍」,有问题改完再交。
装之前看这几条
- 画完会问一次要不要公开分享。Agent 交付后会提议把图发到公开图库 stacks.caru.moe,同一次对话只问一次;要你明确同意两次才提交,提交内容是两张 PNG、英文标题、技术栈和显示名,不发送你的提示词。图里有内部主机名、IP、客户名的,别发。
- 取图标要访问多个外部站点。包括 svgl.app、raw.githubusercontent.com、cdn.jsdelivr.net 和各云厂商图标站,内网或受限网络里可能取不到。
- 标签语言要设对。SKILL.md 要求把 HTML 的
lang设成标签所用的语言,默认en,日文要设ja。 - 商标归原厂。README 说明 logo 是各品牌的商标,出现在图里不代表对方认可。
适合谁,不适合谁
适合经常写技术文档、方案评审材料、开源项目 README 的开发者,尤其是图里有很多云服务和开源组件的场景。要画流程图、时序图或者可交互的系统图,它不合适,可以看站内介绍过的 Archify。只需要文本形式的图,Mermaid 更轻。
最后
装上以后,用一句话把你手头项目的技术栈描述给 Agent,看它交回的 HTML 里 logo 和箭头是否准确,再决定要不要写进团队的文档流程。