一句话画出带官方Logo的架构图：stack-diagram上手

写技术文档最磨人的环节，往往不是写字，而是画那张架构图：Visio里拖完框要对线，线穿过了文字要手动绕，图里十几个服务的Logo得一张张去官网扒，扒完还要统一尺寸。图好不容易画完，三个月后架构改了，没人在愿意重画，文档里那张图就成了谎言。

和传统画图工具比，省在哪

GitHub上的开源项目stack-diagram（近1800星，MIT协议）把整件事压成了一句话：用自然语言描述你的技术栈，Agent直接交付一张带官方Logo、亮暗双主题的专业架构图。项目地址：https://github.com/caru-ini/stack-diagram 。

拿最常见的三种方案对照一下就清楚了：

1. Visio、draw.io 这类手工工具：自由度最高，但每张图都要从空白画布开始，拖框、对线、找Logo、配色全部手动，一张像样的图起步半小时起步，改架构等于重画。
2. Mermaid、PlantUML 这类文本生图工具：图跟着文本走，维护性解决了，但渲染结果是极简线框，没有品牌视觉，拿去给客户看不够体面。
3. stack-diagram：输入端和 Mermaid 一样轻（一句话），输出端却接近手工水准——官方Logo、自动绕线、亮暗双主题、可直接发布的HTML。

也就是说，它精准卡在“维护性”和“专业观感”之间过去没人占的位置上。

它是怎么工作的

stack-diagram本体不是一个网站，而是一个Agent Skill（技能包）。装好之后，你对Claude Code、Codex、Cursor这类支持Skills的Agent说一句：

画出我们的技术栈：Vercel上跑Next.js和一个Hono API，数据库用Neon的Postgres，鉴权用Clerk，支付用Stripe，GitHub Actions负责部署。

Agent就会解析这句话里的组件和调用关系，然后执行三件事：

1. 抓取官方Logo：按svgl、devicon、gilbarbara/logos的优先级检索图标，AWS、谷歌云、Azure的图标则直接取三家云厂商自己的官方图标包，全程不重新着色、不重绘，保证Logo原色原样。
2. 生成图并自检：连线自动绕开文字标签，Agent渲染完成后还会检查一遍成品再交付。
3. 多格式交付：默认给一个自包含的HTML文件——字体和Logo全部内联，断网也能打开，扔进Wiki、README或者发给同事都行；也可以导出PNG、无依赖的React组件，或直接发布为Claude Artifact。

什么场景轮到它出场

最典型的三个场景：给新同事写入职文档，一张图胜过三段文字；给客户或合作方讲系统方案，带Logo的图明显比线框图有说服力；写技术方案或复盘时补架构说明。反过来说，如果你要画的是UML时序图、ER图或者流程图，它不是干这个的——它只专注“组件加调用关系”的系统架构图这一件事。

亮暗双主题与公共画廊

每个图都会同时渲染亮色和暗色两套主题。细节上有个聪明的处理：Logo所在的小方块始终保持白底，这样品牌色在暗色模式下也不会失真；分组的标签和边框则跟随主题切换。

画完后Agent会问一次是否把图发布到公共画廊（stacks.caru.moe），发布前会明确展示将公开的内容，并且要你确认两次，你的原始提示词不会被上传。不想公开就拒绝，完全本地留存。

上手四步

1. 环境准备：Python 3.9以上，外加任意一个支持Skills的Agent（Claude Code、Codex、Cursor等）；如果要导出PNG，还需要Playwright和Chromium，只要HTML输出则可以不装。
2. 安装技能：在终端执行 npx skills add caru-ini/stack-diagram ，Claude网页版用户则从项目Releases页下载stack-diagram.zip手动上传为技能。
3. 一句话描述：把你的技术栈用大白话说清楚——谁调用谁、什么协议、部署在哪，描述越具体，图越准确。
4. 检查并导出：让Agent渲染后逐项核对组件与连线，确认无误后选择要的格式；架构有变动时，改一句话重新生成，三十秒拿到新图。

我的看法

这类工具真正的价值，不在“画得快”，而在架构图终于可以像代码一样被维护。传统画图工具里，图是死的，改架构等于重画；而stack-diagram的“源文件”就是那句自然语言描述，存在README或Wiki里，架构一变改几个词重新生成，图和现实永远同步。对个人开发者，向客户或合作方解释自己的系统时也足够体面——官方Logo加统一的视觉规范，观感远超手绘框线图。

局限也要说清楚：它擅长的是“组件加调用关系”级别的架构图，不是UML全套图，也不是时序图；Logo覆盖不全的小众服务会退化成通用图标；生成质量依赖Agent的发挥，复杂描述偶尔需要多轮修正。但在“给项目画一张能看、能维护、能分享的架构图”这个具体场景里，它已经是目前最省事的方案，值得一装。