项目2026-11-17 · 智涌AI

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

stack-diagram 项目头图:左侧大字「stack-diagram 架构图 Skill」与钩子「一句话描述技术栈,带官方 logo 的架构图」,三张数据卡为 2,555 GitHub 星、最新版本 v0.6.0、MIT 开源许可;右侧节点图以 Next.js 为中心连接 Vercel、Hono、Neon、Clerk、Stripe、GitHub Actions(Actions),标注输出 HTML、PNG、TSX,底部说明 logo 取自官方来源不改色不重画

写技术方案、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。

流程里写明「画完先截图看一遍」,有问题改完再交。

装之前看这几条

适合谁,不适合谁

适合经常写技术文档、方案评审材料、开源项目 README 的开发者,尤其是图里有很多云服务和开源组件的场景。要画流程图、时序图或者可交互的系统图,它不合适,可以看站内介绍过的 Archify。只需要文本形式的图,Mermaid 更轻。

最后

装上以后,用一句话把你手头项目的技术栈描述给 Agent,看它交回的 HTML 里 logo 和箭头是否准确,再决定要不要写进团队的文档流程。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。