架构图往往是团队最后才更新的东西。代码改了,README改了,图还停在六个月前的一张截图里。Diagram Design 换了个思路:不让每个开发者去学一个图表编辑器,而是给编码代理一套可复用的技能,用来生成和修订可视化说明。

打开网易新闻 查看精彩图片

这个仓库出现在 11月21日 GitHub Trending 日榜快照的第 9 位,该快照显示 636 颗星。这代表当下的关注度,并不构成对维护状态或正确性的保证。项目官网目前标称 50 种图表类型和 6 种代理集成,而仓库 README 快照里仍写着 45 种。目录在持续变化,以在线文档为准。

仓库地址为 cathrynlavery/diagram-design,项目站点与图库在 diagramdesign.dev,安装与代理支持见官方设置指南。

这个技能做什么

Diagram Design 是一个代理技能,不是独立的图表编辑器。把它装进受支持的编码代理环境,描述你想说明的系统或工作流,代理就会调用这套技能的视觉规则和图表模式来产出图。

输出被设计成可移植的:一个内联 SVG 的自包含 HTML 文档,而不是只能在某一个应用里编辑的截图。项目还记录了导入现有 Mermaid、draw.io 和 Excalidraw 素材、再套用更统一视觉处理的工作流。

在线图库包含架构图、流程图、时序图、实体关系视图、时间线等视觉格式。具体目录一直在变,所以看当前首页和文档,比照抄旧 README 里的数字更有用。

技能和图表应用差在哪

传统图表编辑器给你一块画布,指望你拖动形状。技能给代理的是一组指令和约束,让它把已有的技术上下文变成图。

当事实来源本来就躺在代码、文档或 issue 里时,这个差别很关键:

  • 让代理检查某个服务边界或一组路由;
  • 提供目标读者,以及这张图要回答的问题;
  • 由技能挑选合适的视觉结构;
  • 复核标签、方向、分组和遗漏的边界情况;
  • 把生成的 HTML 或 SVG 放在它所解释的代码或文档旁边。

这套流程适用于新人上手、架构评审、API 流程、数据库关系、事故复盘和解释一个拉取请求。它不能替代人工架构评审:代理可能基于不完整或被误解的源码,产出一张视觉上很有说服力的图。

装进代理

仓库记录了 Skills CLI 的安装路径:

npx skills add cathrynlavery/diagram-design

安装后,如果你的环境只在启动时加载技能,就开一个新的代理会话。向它要一个具体的交付物,而不是含糊的请求。例如:检查本仓库中的 API 路由和服务模块,画一张时序图,展示用户请求如何从浏览器经过认证、API 处理器、数据库到响应,标出外部服务和错误路径,结果保存为自包含 HTML 文件。

对 Claude Code,仓库还记录了插件市场流程:

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

项目在设置指南里列出了更多代理集成。按你所用的具体代理的文档执行命令,不要假设每个宿主都用同一套插件语法。

CLI 可以更新已安装的技能:npx skills update diagram-design。基础的 HTML/SVG 输出不需要单独的图表服务器或构建流水线,方便把生成的产物挂到拉取请求上,或与文档一起发布。

怎么拿到一张真有用的图

提示词本身就是工程工作的一部分。要写清系统边界、读者、要回答的问题,以及应当省略什么。一份好的架构提示词可以指定:

  • 在范围内的服务和数据库;
  • 哪些调用是同步的,哪些是异步的;
  • 信任边界和第三方依赖;
  • 主成功路径和至少一条失败路径;
  • 读者是新贡献者、运维人员还是评审者。

然后拿输出对照源码核验。检查每个服务是否真实存在、箭头方向是否正确、数据存储有没有和缓存搞混、错误路径有没有消失。如果图描述的是 API,就把端点和载荷方向与实际处理器或 OpenAPI 规范比对。

对架构评审来说,一个有用的检验是:另一位工程师能否不看提示词,仅凭这张图回答某个具体问题。如果不能,就简化视觉或补上缺失的上下文。

取舍与替代方案

当图从代理可检查的技术上下文出发时,Diagram Design 最强。如果工作需要对像素级的手动布局、复杂的协作编辑,或严格的图表即代码评审流水线,它就不太合适。

生成的 HTML/SVG 格式可移植,但它不等同于每个图表编辑器的原生工程文件。在把它纳入长期文档工作流之前,应先测试导入导出的保真度。

还要看仓库的隐私说明和你所用代理的数据处理规则。一张图可能暴露内部服务名、网络边界和基础设施细节。除非组织政策允许,不要把私有架构材料喂给外部模型。

如果你在真实代码库上试用,先从一个图开始,回答一个工程问题:你系统里哪一部分最难向新贡献者讲清楚?