需要将 .mmd 或 Markdown 中的…

把 Mermaid 图（.mmd 文件或 Markdown 中 ```mermaid 代码块）单个或批量转成动画 GIF，用于演示、文档或社交媒体。

适用场景

解决思路

1. 准备前置依赖：安装 FFmpeg、Python 3.8+、Playwright，并执行 pip install playwright && playwright install chromium。
2. 单个 .mmd 文件转换：运行 python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd。
3. Markdown 文件转换：运行 python <skill-root>/scripts/mermaid_to_gif.py document.md -o ./images/；脚本会提取所有 ```mermaid 代码块，并为每个块生成一个 GIF。
4. 多文件批量转换：运行 python <skill-root>/scripts/mermaid_to_gif.py *.mmd -o ./gifs/；或运行 python <skill-root>/scripts/mermaid_to_gif.py doc1.md doc2.md -o ./gifs/。
5. 生成 GIF 后替换 Markdown 中的原始 ```mermaid 代码块为图片引用：；alt 文本根据图内容写描述性文字；图片路径相对于 Markdown 文件。
6. 对 .md 文件中的每个 mermaid 块，读取其周围 Markdown 上下文，理解该图在说明什么，再选择最合适的动画风格；不要盲目对所有块应用同一风格。
7. 按语义匹配风格：数据管道、ETL 流、请求/响应路径用 pulse-flow；架构层、组织图、层级用 progressive；分步流程、教程用 highlight-walk；系统概览、标题图、简单参考用 wave；带消息流的序列图用 progressive；类/ER 图（参考/静态）用 progressive 或 wave。
8. 特殊处理：周围文本说 “data flows from A to B” 时，即使简单 flowchart 也用 pulse-flow；文本描述 “three layers” 或 “two tiers” 时，用 progressive 逐层激活；图只是装饰或补充时用 wave 保持简单；很大或复杂的图优先用 wave 或更短 --duration 控制 GIF 大小。
9. 按块覆盖风格：批处理 .md 时，可能需要用不同样式多次运行脚本，只提取特定块；或用合理默认样式处理整个文件，再对需要不同处理的单个块重新运行。
10. 选择 progressive（默认）动画：所有元素起始 25% 透明度，按流方向以 node → edge → node → edge 交错顺序依次激活到全亮；边用 stroke-dashoffset 视觉绘制；每个元素激活占用了总时长约 8%；适合流程图、架构、层级。
11. 选择 highlight-walk 动画：所有元素起始 15% 透明度；带蓝色 glow 的 spotlight 按顺序移动，访问过的元素保持 90% 透明度；spotlight 到达前整图以 ghost 可见；适合分步流程、教程。
12. 选择 pulse-flow 动画：所有元素全可见；边变为流动虚线，统一 dash 尺寸和速度；边路径使用 10px dash + 6px gap，固定速度 200px/cycle，因此所有边无论长度都以同一节奏流动；适合数据流、管道、请求路径。
13. 选择 wave 动画：所有元素全可见；亮度脉冲 1.0→1.4→1.0 加蓝色 glow 顺序扫过元素；不改变位置，只是视觉涟漪；适合简单图、概览、参考。
14. 常用选项：-o/--output-dir 指定输出目录，默认与输入相同；-s/--style 选动画风格，默认 progressive；--fps 默认 10；--duration 默认 4.0 秒；--hold 默认 1.0 秒，表示循环前保持最后一帧；--theme 默认 default，可选 default、dark、forest、neutral；--bg 默认 #ffffff；--padding 默认 40；--scale 默认 2；--custom-css 指定自定义 CSS 文件；--no-loop 让 GIF 只播放一次。
15. 示例命令：暗色主题更快动画：python <skill-root>/scripts/mermaid_to_gif.py arch.mmd --theme dark --bg "#1a1a2e" --duration 3；高 FPS 更平滑：python <skill-root>/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5；批量转换文档中的 mermaid 块：python <skill-root>/scripts/mermaid_to_gif.py README.md -o ./images/；自定义 CSS：python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css；不循环：python <skill-root>/scripts/mermaid_to_gif.py intro.mmd --no-loop --duration 6；降低分辨率减小文件：python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --scale 1。
16. 自定义 CSS：创建 CSS 文件来定制动画期间图的外观；例如 .node rect { rx: 10; filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.3)); }，.edgePath path { stroke-width: 2.5; }，.actor { fill: #e8f4f8; }；通过 --custom-css 传入：python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css。
17. 脚本执行流程：解析输入，从 .mmd 或 .md 提取 Mermaid 代码；生成自包含 HTML，嵌入 Mermaid.js（CDN）+ 动画 JS/CSS；用 Playwright 在无头 Chromium 中渲染为 SVG，使用 2x 设备缩放获得 retina 质量；小 SVG 自动放大到最小 700px CSS 宽度；JS 动画引擎暴露 setProgress(t) 逐帧控制（t: 0→1），元素按位置排序（尊重 LR/TB 方向）并以 node-edge 交错顺序动画；Playwright 每帧截图；FFmpeg 两遍调色板编码（palettegen → paletteuse with Floyd-Steinberg dithering）组装 GIF。
18. 确保渲染时可访问互联网，因为 Mermaid.js 在渲染时从 CDN 加载。
19. 支持图表类型：flowchart、sequence、class、state、ER、gitgraph、mindmap、pie、gantt 等。
20. 所有 4 种样式都从第 1 帧保持整个图可见，没有元素隐藏或从零淡入。
21. 回退行为：对未识别图表类型或未检测到可动画元素时，回退为整图透明度揭示。
22. 分辨率与 GIF 大小：默认 --scale 2 生成视网膜质量图像（约 1400-1600px 宽）；需要更小文件用 --scale 1；非常大输出时降低 --fps 到 8、缩短 --duration、使用 --scale 1 或 wave 样式。

适用边界 · 注意事项

• 未安装 FFmpeg、Python 3.8+、Playwright 及 Chromium 时不能直接使用。
• 渲染时无法访问互联网/离线环境不适用，因为 Mermaid.js 从 CDN 加载。
• 需要交互式图、可缩放矢量图，或不愿通过降 --fps、缩短 --duration、降 --scale、改用 wave 来缩小 GIF 文件时，不适合用本技能。