给同事发架构图,我改成发一个能双击打开的网页

283次阅读
没有评论

共计 4177 个字符,预计需要花费 11 分钟才能阅读完成。

Diagram Design 是一套给编程助手用的开源技能,用来把架构图、流程图这类图,写成一个可以双击打开的 HTML 文件。图就画在这个文件里,用内联的 SVG,不必先导出一张放大就发糊的截图。

项目由 Cathryn Lavery 维护,仓库在 cathrynlavery/diagram-design,许可证是 MIT。官方主页是 diagramdesign.dev,示例展览在 GitHub Pages。

2026年11月21日上午,我在自己的 Linux 测试机上浅克隆了当前默认分支。plugin.json 里的版本是 2.6.168,对应提交 d74d8c2,提交时间换算成北京时间是 11月19日 08:17:04。我没有在某个编程助手里执行官方的安装命令,而是按仓库里的技能说明,自己写了三张简体中文图,并用自带脚本做了检查。

同一天 07:58(北京时间)用 GitHub 接口读到这个仓库有 69,267 星、4,652 个 fork,未关闭的 issue 有 44 个。大约 07:50 打开 GitHub 日榜页面时,它排在第 9,页面写着当天加了 634 星。星数只说明关注度,下面仍以这三张图和两条检查命令为准。

🍎 技能说明把官方默认外观的纸色写成 #f5f5f5,文字色 #2d3142,强调色 #bf4520。这是第一次在一个项目里画图时的默认值。我明确沿用这套默认值,没有做品牌定制,也没有从某个网站抽取配色。

· · ·

PART 1

它交出的是一个可以打开的文件

对支持 Agent Skills 的编程助手来说,常见用法是先安装技能,再用一句话说清要画什么。助手选定图的类型,写出一个 .html 文件。你用浏览器打开,就能看到完整的图。

官方 README 给出的安装命令是:

npx skills add cathrynlavery/diagram-design

它还为 Claude Code、Codex 等宿主写了插件市场里的安装方式。这次我没有在这些宿主里点安装,所以后面的步骤,对应的是「已经拿到技能目录之后,怎么画出文件、怎么检查」。

技能说明里的工作顺序可以缩成这条线:

选定图的类型 → 复制对应模板 → 换上标题和 SVG → 跑自检脚本

给同事发架构图,我改成发一个能双击打开的网页

▲ 配图示意,蓝图风格。后面三张预览才是本机检查通过后的实际产出。

如果手头已有 Mermaid、draw.io、Excalidraw 或 PlantUML,官方要求先用自带脚本抽取节点和连线,再按规范重画,而不是把原来的布局和配色原样转进去。

· · ·

PART 2

我用的版本,以及两条检查命令

技能目录在仓库的 skills/diagram-design/。检查命令要从这个目录运行,这样脚本才能找到它附带的模板和规则。

我写完三张图之后,在技能目录下执行:

python3 scripts/self_check.py /path/to/watch-cn-video.html
python3 scripts/self_check.py /path/to/four-steps.html
python3 scripts/self_check.py /path/to/open-html.html
python3 scripts/verify_geometry.py /path/to/watch-cn-video.html /path/to/four-steps.html /path/to/open-html.html

self_check.py 三次都打印 OK,退出码是 0。verify_geometry.py 打印 Summary: 3 file(s) checked, 0 finding(s).,退出码同样是 0。

self_check.py 会检查无障碍 SVG 的基本约定、是不是单个文件(除了官方允许的 Google Fonts,不能再拉别的远程资源)、文件是否写完整,以及图形是否画在 viewBox 里面。verify_geometry.py 会检查连线是不是正交、箭头标签的遮罩会不会被后面的节点挡住、两个箭头会不会贴在一起。

技能说明还要求用 scripts/export_png.py 导出一张 1 倍预览图,在图上看有没有字被切掉、箭头指空。这个导出脚本会启动 Playwright。我这次没有跑它。预览改用本机的 rsvg-convert 2.60.0,按 144 dpi 把同一份 SVG 栅格化,再用眼睛看了一遍。第一次预览里,流程图的 YES 标签贴在菱形边缘上,步骤图的圆里是空的。我改了这两处,重新跑上面两条检查,仍然通过,然后重新出图。

🍎 技能说明自己也写了:如果环境里没有 Playwright,可以跳过那一步,并在说明里写清「自动检查已通过;未按官方导出流程做目视检查」。我的情况稍有不同:自动检查通过了,目视检查是用 rsvg-convert 做的,不是官方那条导出命令。

关于「能画多少种图」,仓库里的数字并不一致。技能文件开头写 Fifty visual types,后文和目录标题写 51,GitHub 仓库简介仍写 45。我对着技能文件里的 Visual-type guide 表格逐行数,得到 50 行。下面按当场数到的 50 种来写,同时保留这处不一致,供你对照文件。

这次只画了其中三种:架构图、步骤图,以及从一份 Mermaid 流程图重画的流程图。

· · ·

PART 3

三张简体中文图

三张图都从官方的浅色模板 assets/template.html 复制而来,语言写成 zh-Hans,框里的名称用简体中文,分区眉题和箭头上的短标签仍用拉丁文。技能说明把后一种位置规定为 7–8 像素的等宽字母,汉字在这个尺寸上既没有对应字体,也不容易认。

架构图:海外电脑看国内视频的常见路径

类型是 Architecture。从左到右只有一条主路径:

播放器 → 加速客户端 → 节点 → 视频网站

加速客户端是唯一的强调节点。分区眉题分别是 LOCAL、RELAY、SITE。这不是某一家具体产品的接线说明书,只用来练习「组件 + 关系」这种架构图。

给同事发架构图,我改成发一个能双击打开的网页

▲ 架构图预览。预览由 rsvg-convert 从同一份 SVG 转出,不是官方 Playwright 导出。

步骤图:从安装技能到打开一张图

类型是 Steps。四个等宽阶段,第三步「得到单个 HTML」是强调项:

安装技能 → 说明要画什么 → 得到单个 HTML → 自检并打开

阶段下面的说明仍用拉丁文技术标签,对应 npx skills add、one sentence、one .html file、self_check.py。圆里的图标是后补的,第一次预览时这些圆是空的。

给同事发架构图,我改成发一个能双击打开的网页

▲ 步骤图预览。圆里的图标是第一次预览后补上的。

流程图:HTML 打不开时先查什么

这一张是从一份自写的 Mermaid 重画的,类型是 Flowchart。源文件只有 5 个节点、4 条边,抽取脚本也读成同样的数量。决策节点是「浏览器能打开吗」:能,就把文件发给对方;不能,先看是不是用记事本打开了,再考虑离线时中文是否走系统字体。

给同事发架构图,我改成发一个能双击打开的网页

▲ 从自写 Mermaid 重画后的流程图预览。箭头标签按规范写成 YES / NO。

· · ·

PART 4

从 Mermaid 重画时,保留了什么

我把源文件存成 open-html.mmd,在技能目录运行:

python3 scripts/mermaid_extract.py /path/to/open-html.mmd

脚本输出里写着:1 张流程图,5 个可画节点,4 条边,其中 2 条带标签,没有环,预算内。入口是「得到单个 HTML」,终点是「把文件发给对方」和「离线时中文可能走系统字体」。这和源文件一致。

按技能说明,抽取之后要丢掉 Mermaid 渲染器的坐标、颜色和形状细节,只保留内容,再按流程图规范重画。我实际改动如下:

  • 5 个节点和 4 条边都保留了,没有增加,也没有丢掉。
  • 源文件里的边标签是「能」「不能」。重画时改成 YES 和 NO,因为箭头标签属于 7–8 像素等宽字母的位置。
  • 「先看是不是用记事本打开了」「离线时中文可能走系统字体」两行比较长,在框里拆成两行,意思不变。
  • 布局按自上而下的判定来排,不是 Mermaid 自动排出来的那种间距。

· · ·

PART 5

简体中文会碰到的字体问题

技能说明把繁体中文的 Noto Sans TC、Noto Serif TC 写进了模板的 Google Fonts 链接,并写明:简体中文使用同样的三条规则,字体栈是 Noto Sans SC、PingFang SC、Microsoft YaHei,但这一套简体字体不在官方链接里,所以会落到浏览者电脑上已有的字体。

我这台 Linux 测试机装着 Noto Sans CJK SC。预览图上的「播放器」「加速客户端」等字是靠本机字体画出来的。如果你把同一份 HTML 发到一台没有简体黑体的电脑上,又恰好不能访问 Google Fonts,框里的中文就可能变成系统兜底字体,和标题里的西文衬线对不齐。

官方隐私说明还写了:技能本身没有服务器、没有账号、也没有遥测;打开生成的文件时,默认会向 Google Fonts 请求字体。不需要这项请求时,可以按说明改成系统字体,或在离线时打开。

汉字名称还有一个尺寸下限:技能说明要求中文不用小于 12 像素,放不下就改短名字,不要把字改小。这三张图里的中文名称都按 12 像素写。

· · ·

PART 6

这次没做的事

我没有执行 npx skills add cathrynlavery/diagram-design,也没有在 Cursor、Claude Code 或 Codex 里把技能装进助手后再出图。所以本文证明的是:按仓库里的规范手写 HTML,自带检查能通过。它不能代替「你在自己的助手里说一句话,助手是否画出同样合格的文件」。

我没有跑官方的 export_png.py,因此也没有用它的 Playwright 流程导出 PNG 或 SVG 发行稿。正文里的预览图来自 rsvg-convert。我没有在图形界面的浏览器里双击打开这些 HTML,Windows 和 macOS 上的双击行为没有测过。

我没有做品牌配色、深色模板、完整社论版模板,也没有做动画。50 种类型里只画了 3 种,没有把仓库展览里的示例改称自己的图。

如果要把技能装进自己的编程助手,以官方 README 和你所用宿主的说明为准。画出文件之后,仍然建议先跑 self_check.py 和 verify_geometry.py,再决定要不要发给别人。

站内相关阅读:把技能装进助手之前,先看质量分和会不会被砍半加载。那一篇检查的是技能说明写得清不清楚、会不会被助手完整加载;本篇做的是按一套画图规范,交出能打开的文件。

正文完
 0

版权声明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。

科技喵仔
版权声明:本站原创文章,由 科技喵仔 于2026-11-21发表,共计4177字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(没有评论)
验证码
    中文English