前言

在 AI 时代，PRD、TDD 等各类技术文档已经可以由 AI 自动生成较为完整的流程图，大幅减少了人工绘制的时间成本。开发者更多需要关注的是内容审核与调整，而不是重复性的绘图工作。🐶 AI 会以一种“不墨迹”的方式，稳稳接住你的需求。

不过，截至目前，飞书文档仍然无法原生支持 mermaid、Sequence Diagram 等代码绘图格式。即使将文档分享给团队成员，也可能因为不同客户端、版本差异等因素，出现各种兼容性问题。

因此，在最终交付和分享阶段，相比依赖客户端解析的代码图形，更推荐直接输出 PNG、JPG 等静态图片格式。图片无需额外解析环境，可以做到打开即展示，最大程度降低协作过程中的兼容成本。

基于这个思路，今天尝试利用 Skill 实现一套自动化流程：

解析 AI 生成文档中的流程图代码；
自动转换为图片格式；
上传至 OSS；
生成公网可访问地址，并插入到文档对应位置替换掉原来的代码画图；
为了方便二次编辑，默认不动原文档，而是产生一个 -imgconvert.md 的副本文档，拿来直接分享展示。

说白了就是 AI 负责生图，Skill 负责把图变成能直接发出去的文档，从文本到成品一条龙。

成品展示

代码画图文档展示

这个是 Typora 软件提供的预览功能+代码块的展示，可以清晰的看到下方的图是 AI 产出的，上面是代码块

运行 skill 赋能

对着一份带代码画图块的文档，直接跑：

1
2
3

python3 ~/.cursor/skills/markdown-diagram-render/scripts/doctor.py      # 先体检，全绿再干活
python3 ~/.cursor/skills/markdown-diagram-render/scripts/render_md.py path/to/source.md
# → path/to/source-imgconvert.md   （source.md 原样保留）

查看运行效果

转换成功后，会转变为网络的地址，可以在公网直接访问的 oss 地址

技术细节

整个流程拆开就是四步：解析代码块 → 渲染成图 → 传 OSS → 回填文档。主流程就是 Python 标准库写的，没引第三方 pip 包，各种渲染器交给 bootstrap.py 去装。

1. 解析代码块

先把 markdown 扫一遍，语言标记是 mermaid / plantuml / d2 / dot 的代码块才捞出来，正文和 java、sql 这种普通代码块碰都不碰。

2. 渲染成图片

几种画图语言各有各的渲染器：

画图类型	渲染方式
mermaid	mermaid-cli，丢进无头浏览器里渲成 PNG
plantuml	java 跑 plantuml.jar
d2	官方 d2 CLI
graphviz	有系统 `dot` 就优先用，没有则走 `@viz-js/viz` WASM

这里踩过一个坑：浏览器最初用的是完整的 Chrome for Testing，结果每渲染一张图，macOS 的 Dock 就闪一下，跑十张闪十次，相当搞心态。后来换成了 chrome-headless-shell，这是专为无头模式裁剪的版本，全程静默，推荐有类似需求的同学直接用这个。

3. 画质：默认 2x，为 Retina 准备的

图渲出来是给人看的，糊了等于白干。这里默认 scale=2，也就是按 2 倍像素渲染，这个值是冲着 Retina 屏去的——macOS 上 2x 缩放时，逻辑上的 1 个点要由 2x2 共 4 个物理像素来显示，图片按 1x 渲染的话相当于被拉伸放大，字就发虚了。按 2 倍渲染，在 Retina 屏上正好一个像素对一个物理点，清晰；放大看也不糊。嫌不够锐可以 --scale 3，Mermaid 的视口宽高、PlantUML / Graphviz 的 DPI 也都开了参数，按需调。

4. 上传 OSS

渲好的 PNG 用 uuid 命名传到 OSS，拿回公网地址，本地生成的中间图片用完就删。AK/SK 放在 config.local.json 里（已 gitignore），没配 OSS 的同学加 --local，图片就落在文档旁边的 diagrams/ 目录里。

5. 替换与旁路输出

这块是我自己最满意的设计：默认不动原文档。代码块是图的“源头”，要是直接覆盖成图片链接，下次想改个箭头、调个文案就没得改了。所以默认产出一份 source-imgconvert.md 副本，替换只发生在副本上；真想覆盖也行，显式加 --overwrite。

某张图渲挂了也不影响大局：失败的块会被替换成一个 ⚠️ Diagram Render Failed 标记，失败原因和原代码都在里面，其余图照常输出。改完源码重跑一遍就好。

依赖问题

本机要准备的就三样：Python ≥ 3.9、Node ≥ 18、Java ≥ 8（不用 plantuml 可以不装 Java）。剩下的 plantuml.jar、d2 二进制、node_modules、chrome-headless-shell，都是 bootstrap.py 按当前系统下到 skill 目录里的，不污染系统环境。装完跑一遍 doctor.py，全绿了再干活。

想发给队友用，千万别直接拷目录，装完能有一个 G。用 pack.py 打个几十 KB 的 slim 包，对方解压后自己 bootstrap 一遍。node_modules 分平台，Mac 装好的拷给 Windows 必挂，这个坑别踩。

整活环节

本次分享采用整活方式，不分享源码，只分享思路。快交给你的 vibe coding 软件来帮你实现吧～