handdrawn‑architecture‑video：开源SVG架构图转手绘4K动画视频｜本地AI Agent Skill

handdrawn‑architecture‑video：开源SVG架构图转手绘4K动画视频｜本地AI Agent Skill

🔗项目Gitee地址：Handdrawn Architecture Video

一、痛点：架构图做手绘动画为什么这么麻烦？

在做科创答辩、项目路演、技术分享视频的时候，很多开发者都会遇到同一个难题：手里已经有系统架构SVG框图，希望实现模块逐笔浮现、箭头数据流流动的手绘动画效果。

如果使用AE、剪映手动制作：需要调整手绘样式、编排动画时序、调试视频导出参数，整套流程耗时很久。

市面上部分开源工具，仅支持输出静态手绘图片，动画需要二次加工；部分在线工具需要上传源文件到云端，架构、业务素材存在泄露风险；还有一些脚本方案导出视频卡顿、背景发白，调参耗费大量精力。

针对这些现实痛点，我把2026 vivo AIGC创作大赛------墨塑Morpheus参赛项目的实战素材生产流程，封装成一套可复用的开源工具：handdrawn‑architecture‑video。

提示：项目名称中architecture代表软件系统架构，不是建筑手绘，工具面向IT技术框图，不用于建筑效果图绘制。

二、什么是 handdrawn‑architecture‑video？

handdrawn‑architecture‑video 是一套开箱即用的AI Agent Skill，同时支持脱离Agent独立脚本运行，全程本地处理，不需要调用任何云端接口。

整套工具遵循四阶段流水线：

SVG手绘化 → 动画HTML → 细节调整 → 4K MP4导出

只需要输入原始架构SVG，或者一段业务描述文本，就可以一次性交付三份成品素材：

输入内容	输出交付物
深色科技风格SVG架构图	✅ 米色草稿纸手绘风格SVG矢量图，Logo自动内嵌
Markdown/业务描述文本	✅ 自包含动画HTML，纯CSS+SMIL实现动画，无CDN无第三方依赖，双击浏览器即可播放，刷新自动重播
业务处理指令	✅ 3840×2160 4K H.264 MP4视频，遵循bt709色彩标准，高帧率流畅输出

统一手绘视觉规范：暖米底色#FBF7EF、楷体字体、卡片轻微旋转、墨线质感描边、手绘箭头、圆点流动模拟数据流，整体观感适配答辩、路演正式场景。

2.1 项目背景

本项目来源于2026 vivo AIGC创作大赛墨塑（Morpheus）团队 参赛实践。

比赛过程中，我们需要批量产出大量4K动画素材，包括系统架构图、创新卡片、行业趋势图表。实战踩过大量坑：动画时序错乱、录屏帧率过低、MP4色彩异常、元素错位重叠、离线环境动画页面无法打开。

于是将整套生产流程工程化，封装自检脚本、规范文档，开源出来，减少其他开发者的重复造轮子成本。

2.2 和同类工具简单对比

很多同学会拿Excalidraw做手绘框图，这里做简单对比，方便大家选型：

工具	手绘风格	输出产物	本地运行	原生4K视频导出	Agent Skill支持
handdrawn‑architecture‑video	草稿纸手绘速写	SVG+动画HTML+4K MP4	✅完全本地	✅完整流水线	✅
Excalidraw	黑板手绘风格	静态SVG/PNG	✅浏览器本地	❌不支持视频导出	❌

Excalidraw适合快速画静态草图；本项目优势在于自动时序动画 + 一键4K成片，面向视频素材生产。

三、核心特性

3.1 纯本地运行，零云端依赖，保护业务素材隐私

全部转换、渲染、录屏编码流程都在本机完成，不会上传架构图、业务文档到第三方服务器。

生成的动画HTML不依赖任何CDN、外部JS库，可以拷贝到离线电脑直接演示，对比赛现场、内网演示场景十分友好。

3.2 高质量4K导出，解决卡顿、背景发白经典问题

很多无头浏览器截图方案，直接逐帧截屏帧率仅有4‑5fps，视频画面严重卡顿。

本项目采用 Chrome CDP screencast高帧率录制 + Lanczos算法放大至4K ，实测帧率24‑50fps，PSNR达到46.9dB，画质接近原生4K渲染。

同时内置ffmpeg色彩参数配置，专门解决导出MP4背景发白、色彩偏色的问题。

3.3 全套自动化自检工具链，提前规避布局与动画错误

项目不只是转换脚本，把实战踩过的坑固化为自动检测程序：

• selfcheck.py：项目整体自检，校验目录结构、脚本语法，CI流水线自动执行；
• check_overlap.py：自动检测文字越界、卡片元素重叠；
• verify_animation.py、verify_sync.py：校验SVG源文件与动画HTML元素一致性，校验动画时序是否正常。

不需要肉眼反复排查，运行脚本就可以提前发现大部分问题。

3.4 双模式运行：AI Agent调用 / 独立脚本执行

两种使用路径，适配不同用户：

1. Agent Skill模式：给Claude Code、Codex、AtomCode这类AI Agent调用，一句话指令走完完整流水线；
2. 独立脚本模式：不依赖任何大模型，已有动画HTML的前提下，直接运行PowerShell/Bash脚本一键导出4K视频。

3.5 全平台兼容Windows / macOS / Linux

同时提供PowerShell脚本与Bash脚本，适配三大操作系统。仓库FAQ整理大量踩坑经验：CSS Transform冲突、dasharray描边动画、opacity与fill‑opacity区别、PowerShell编码、反斜杠转义等问题。

四、快速上手教程

4.1 环境依赖准备

使用前本机需要安装：

1. Python3环境
2. Chrome 或者 Edge浏览器（无头模式用于录屏采集）
3. ffmpeg，用于视频编码合成

4.2 克隆项目仓库

git clone shturl.cc/kbszR6Dd0PFdCjlRUUiIJMhv7AS5eGRTzNMBftSWioMOEQ74DQxB.git
cd handdrawn-architecture-video

4.3 方式一：作为AI Agent Skill使用

把项目文件夹放到对应Agent的skills目录：

Agent类型	存放路径
Claude Code	~/.claude/skills/handdrawn‑architecture‑video/
Codex	~/.codex/skills/handdrawn‑architecture‑video/
AtomCode	~/.atomcode/skills/handdrawn‑architecture‑video/

执行自检脚本确认安装完整：

python scripts/selfcheck.py .

看到输出 OK selfcheck 全部通过，说明Skill部署成功。

之后直接向Agent下发指令，示例：

把架构图_深色版.svg重绘为手绘风格，生成动画HTML，模块依次出场，箭头配置圆点流动动画，导出4K MP4。

也可以显式指定Skill强制调用：

使用handdrawn‑architecture‑video处理这个SVG，走完整流水线。

4.4 方式二：不依赖Agent，命令行一键导出4K视频

如果你已经得到处理完成的动画HTML文件，可以直接调用导出脚本生成MP4。

Windows PowerShell：

.\scripts\export_4k.ps1 -Html "..\架构图_动画.html" -Out "架构图_4K.mp4" -DurationMs 14000

macOS / Linux：

./scripts/export_4k.sh ../架构图_动画.html 架构图_4K.mp4 14000

参数‑DurationMs代表动画总时长，单位毫秒。
💡提示：项目下examples/preview目录存放完整演示样例，包含手绘SVG、动画HTML、4K成片，克隆仓库之后可以直接打开体验效果。

五、实战产出效果

这套流水线已经在墨塑项目45秒比赛视频中完成实战落地，批量生成15+份4K素材：

• 系统架构动画，提供16s完整版、12s快节奏两个版本；
• AI创新卡片动画（蓝图+记忆、VibeWorking、多角色智能配音闭环）；
• 行业赛道趋势柱状图生长动画；
• 产业价值四面板、项目总结卡片动画。

每一份素材都会同时产出：手绘SVG、可独立播放动画HTML、4K MP4三件套，可以直接用于剪辑、答辩演示。

六、项目文档说明

仓库references目录存放全套参考文档，开发调试、自定义样式的时候可以查阅：

1. SKILL.md：Agent工作流入口，阶段定义、验收清单、FAQ；
2. handdrawn‑style.md：手绘设计令牌，配色、字体、描边、箭头布局规范；
3. animation‑html.md：动画基元、串行时序设计、动画开发踩坑清单；
4. from‑description.md：阶段0，如何从文字描述生成架构元素与布局模板；
5. export‑4k.md：4K导出原理，帧率画质实测对比、调参指南。

七、常见问题FAQ

很多使用者遇到的报错都集中在这里，整理高频问题方便快速排查。

7.1 导出视频画面卡顿

不要使用普通逐帧截图模式，该模式帧率仅4‑5fps。使用项目默认的1080p CDP screencast录制，配合lanczos算法放大，可达到24‑50fps流畅视频。

7.2 MP4导出之后背景发白

需要在ffmpeg配置scale=in_range=full:out_range=tv，写入bt709/tv色彩元数据，仓库导出脚本已经内置该配置。

7.3 SVG动画元素跑到左上角、发生错位

keyframes内部不要混用复合transform属性，尽量单独使用translate属性完成位移。

7.4 半透明底色下文字显示异常

半透明底色优先使用fill‑opacity，不要直接修改整体opacity，避免子元素透明度被连带改变。

7.5 卡片重叠、文字超出边框

运行检测脚本：

python scripts/check_overlap.py 你的动画.html --cards

自动检测布局问题，提前修改源SVG。

7.6 Windows下PowerShell脚本解析报错

ps1脚本需要UTF‑8 BOM编码，不要使用PowerShell7的??运算符。

八、适用场景与能力边界

✅ 适合场景

• 科创比赛、毕业设计答辩视频素材；
• 开源项目、产品路演架构讲解短片；
• 技术分享PPT配套动画；
• 项目汇报手绘风格框图视频。

❌ 不适合场景

• 3D动画、艺术向自由手绘插画；

补充：从文字描述生成架构框图属于阶段0，该部分依赖AI Agent大模型，本项目核心负责样式转换、编排动画、视频导出，不内置大模型。

九、参与开源

本项目采用MIT开源协议，欢迎提交Issue反馈bug，提交PR贡献代码。

提交代码之前，请务必运行自检脚本：

python scripts/selfcheck.py .

总结

想要做架构图手绘动画，过去要么依赖付费工具，要么手动调试大量参数，耗费很多时间。

handdrawn‑architecture‑video把整套视频素材生产流程做成开源可复用流水线，本地运行保护隐私，支持Agent调用也支持独立脚本执行，希望可以帮开发者把精力聚焦到业务内容，而不是动画与导出调参。

如果对你有帮助，欢迎到Gitee仓库点Star，遇到问题欢迎提交Issue交流。

🔗项目地址：Handdrawn Architecture Video