提示词工程揭秘:拆解MotionGraphicsBench的GSAP System/User Prompt设计与输出契约技巧
提示词工程揭秘:拆解MotionGraphicsBench的GSAP System/User Prompt设计与输出契约技巧
MotionGraphicsBench 是 Figma 开源的 LLM 动态图形生成评测基准。它的提示词工程藏在 scripts/prompts/ 下的两份 GSAP 提示词模板(System Prompt 与 User Prompt)中,配合一套可机器解析的输出契约,把"给静态 SVG 配动画"这道题问得滴水不漏。这篇文章带你逐段拆解这两份模板的设计套路,帮你掌握可复用的 LLM 提示词技巧。
1️⃣ 先看懂任务:MotionGraphicsBench 如何评测"SVG 动画生成"
在拆提示词之前,先理解题目本身。基准包含 100 个任务,每个任务给模型三样东西:一份静态 SVG、一段运动编辑提示词(motion edit prompt)、以及时长与帧率要求;模型要输出一段用 GSAP 编写的 JavaScript 动画程序。随后渲染器把程序跑成一串 SVG 帧,由确定性的 Python 验证程序逐帧检查元素几何、外观与运动是否满足提示词要求。
关键点:模型只能看到题目(SVG + 提示词),看不到参考动画,也看不到验证程序。所以提示词必须把"允许什么、禁止什么、输出什么格式"全部写死——这正是它值得拆解的原因。
2️⃣ 提示词双模板设计:System 定规矩,User 给题目
scripts/generate_animations.py 中的 build_generation_messages 用 Jinja2 渲染两个模板,最终发给模型的只有两条消息:
- System 消息 ← gsap_system.jinja2:角色设定 + 全套规则(与具体任务无关,只注入 GSAP 版本号);
- User 消息 ← gsap_user.jinja2:本任务的"题目",用 XML 标签分区装填。
这种"规则与题目分离"的拆分,让 100 个任务共享同一份 System Prompt,只替换 User 里的三个变量,维护成本极低,也便于跨模型公平对比。
2.1 System Prompt:一份写给 LLM 的"验收合同"
gsap_system.jinja2 全文约 60 行,按功能切成 8 个小节,每一节都是一个可复用的设计技巧:
| 小节 | 作用 | 新手能学到的技巧 |
|---|---|---|
| 角色锚定(第 1 行) | "expert SVG animator and JavaScript programmer using GSAP 3.14.1",并声明"运动提示词是唯一的运动规格" | 角色 + 版本一次性钉死,同时切断模型臆造"我能访问 Lottie/文件/视频"的幻觉 |
| OUTPUT CONTRACT(L3-L9) | 输出格式硬契约,详见下一节 | 把格式写成命令式清单,而不是"请尽量输出代码" |
| SVG TARGETING AND PRESERVATION | 只能动已有节点,禁止增删克隆节点,尊重绘制顺序与隐藏元素 | 明确"不许做什么"比"该做什么"更能防止破坏 DOM |
| GSAP PROGRAM RULES | 限定 GSAP 3.x API,列出已预加载插件,禁止 gsap.registerPlugin |
与运行环境对齐:模型只能使用脚手架已注册的插件 |
| GEOMETRY AND TRANSFORMS | 区分 transformOrigin 与 svgOrigin,禁止混用坐标系 |
对易错 API 给出参数级说明 |
| MOTION, FRAME ZERO, AND TIMING | 第 0 帧状态必须用 tl.set(..., ..., 0) 显式建立;禁止无限 repeat |
把"确定性、可 seek、可重置"写进约束 |
| SAFETY AND BOUNDED EXECUTION | 禁用 fetch、eval、Worker、定时器、CSS 动画等一长串 API |
提示词禁令与渲染沙箱的 CSP 一一对应 |
| SYNTAX GOTCHAS(L53-L58) | 列出"直接导致整段程序报废"的经典错误,附 GOOD/BAD 对照 | 见下文,这是全文最精彩的部分 |
最亮眼的是 SYNTAX GOTCHAS 小节:它不写抽象规则,而是直接给出致命错误的正误对照,例如 svgOrigin 必须是空格分隔的字符串 svgOrigin: "1050 540",而不是对象或数组;以及"绝不用 attr: { transform: "none" } 清掉 transform,否则后续 tween 会抛异常"。这些都是真实失败模式反推回来的教训——用线上事故喂养提示词,比堆砌最佳实践更有效。
结尾还有一句"发出前静默自查"(L60):要求模型在输出前默检选择器存在性、运动是否齐全、是否只有一个 tl、时长是否在容差内、是否只有一个合法代码围栏。相当于让模型自己做了一遍 code review,但不允许把推理过程写进回答。
2.2 User Prompt:用 XML 标签给输入分区
gsap_user.jinja2 只有 17 行,却示范了多模态输入的标准切法——用三个 XML 风格标签把三类信息物理隔开:
<motion_prompt>:运动需求(唯一的"题目");<static_input_svg>:静态 SVG 几何与外观参考(入库前已用strip_base64剥离 base64 大段,节省 token);<non_visual_timing>:非视觉参数——required_duration_seconds、source_fps、one_source_frame_tolerance_seconds,全部从源 Lottie 元数据(ip/op/fr)确定性计算。
首尾两句话都在强调同一个认知陷阱:"SVG 只是几何与外观参考,不是时间轴锚点"(L1 与 L17 各出现一次)。模型天然倾向于把输入图当"第 0 帧",这里用双重声明掐断了它。标签分区 + 首尾复述关键约束,是多输入提示词里性价比最高的两个手法。
3️⃣ 输出契约技巧:让 GSAP 程序可以被机器直接解析
OUTPUT CONTRACT 是整套提示词的"地基",核心条款只有 6 条,但条条都有下游代码背书:
- 只返回一个小写 ```javascript 围栏,围栏外什么都不能写——无 HTML、无 SVG、无 import、无散文、无备选实现;
- 围栏内是一段原始经典脚本,且顶层有且只有一个自播放时间线,声明必须逐字是
const tl = gsap.timeline();; - 所有 setup 与动画都挂在
tl上; - 注释可以引用提示词原句,但绝不暴露推理过程。
这些条款不是洁癖,而是被 extract_program 的正则解析逻辑硬约束的:解析器只接受"最后一个闭合的 javascript 围栏"(未闭合直接报错),实在没有围栏时才退而接受含 gsap.timeline( 的裸脚本。提示词写得多严,解析器才能写得多么简单——输出契约的本质是让"模型输出"和"程序输入"之间零歧义。
另一个隐藏收益是可确定性:契约禁止随机数、禁止无限循环时间线、要求总时长落在"一个源帧"容差内。渲染器甚至内置了 Infinite GSAP animation detected 兜底(见 SYNTAX GOTCHAS 第 56 行)。只有输出确定,5.3 万条模型输出才能被统一重放、逐帧验证、横向对比。
下面这张图来自基准官方的 Scissor 任务示例:LLM 生成的剪刀动画成功开合,但刃口停得离"近乎闭合"太远,8 项检查通过 7 项,整体判定为 false。它正好说明:契约保证的是"程序能被解析和执行",而"动得对不对"由逐帧几何检查说了算——提示词管前者,验证程序管后者。
4️⃣ 流水线落地:提示词如何从模板变成模型请求
模板不是孤本,它被 benchmark_pipeline.py 整条流水线消费。最小上手路径:
git clone https://gitcode.com/hf_mirrors/figma-ai/motion-graphics-bench
cd motion-graphics-bench
uv sync --locked --no-dev && npm ci && uv run playwright install chromium
然后用现成的 GSAP 程序跑"渲染 + 验证"两段(跳过模型调用):
uv run python scripts/benchmark_pipeline.py \
--animation-id 10175370 --program program.js --output-dir outputs/scissor
两个值得注意的工程细节:
- 可复现:每次生成前,完整的 system + user 消息都会落盘为
messages.json(见 run_generation),事后能精确还原"模型当时看到了什么"; - 可扩展:
--system-prompt-suffix参数(L168)允许在不改主模板的前提下,为特定模型追加个性化补充说明,且同样被记录在案——模板保持稳定,差异被显式化。
数据侧的 100 个任务存放在 data/benchmark/ 的 Parquet 文件中,字段定义见 README.md。
5️⃣ 新手可直接复用的 5 个提示词工程技巧
把这套设计抽象出来,任何"让 LLM 写代码/配置/结构化输出"的场景都适用:
- 📋 输出格式写成硬契约:逐条列出"只允许什么、禁止什么",并让下游解析器与契约一一对应。格式约束越接近"合同条款",解析越简单。
- 🏷️ 用 XML 标签给输入分区:
<motion_prompt>、<static_input_svg>这类标签让指令与数据物理隔离,多输入场景下几乎不会再发生"指令串味"。 - 🚫 禁令清单与执行环境对齐:System Prompt 里的每条禁止(fetch、eval、定时器……)都能在渲染沙箱里找到对应物。模型不知道的环境限制,必须写进提示词。
- 💥 用真实事故做 GOOD/BAD 对照:把"一个参数写错就全盘崩溃"的错误模式(如
svgOrigin传对象)原样写进提示词,比十条抽象最佳实践都管用。 - ✅ 要求输出前静默自查:给模型一份"发射前检查清单",让它自检选择器、完整性、格式,但不许把推理写进回答——免费的最后一道质检。
6️⃣ 常见问题 FAQ
为什么强制"有且只有一个" const tl = gsap.timeline();?
因为验证器要在任意时间点 seek、重置时间线。多个时间线或事件驱动动画无法被确定性回放,评测就失去了可比性。
为什么要把 SVG 里的 base64 剥离再喂给模型?
strip_base64(verify_animations.py 提供)去掉内嵌图片等二进制数据,既省 token,又防止模型无脑复制大段无意义内容。
我可以改提示词做自己的实验吗?
可以。除了 --system-prompt-suffix 追加说明外,仓库是只读的数据集镜像,建议复制 scripts/prompts/ 模板到自己的工作区修改;改动后的消息会被记录在 messages.json,方便对照。
这套提示词对本地模型也适用吗? 适用。流水线通过 LiteLLM 同时支持云端与本地模型(Ollama、vLLM 示例见 README.md),System Prompt 与模型供应商完全解耦。
小结:MotionGraphicsBench 的提示词工程给出的启示很纯粹——规则进 System、题目进 User、格式当合同、事故当教材。把"输出契约"从建议变成条款,再把每条条款落到解析与沙箱代码上,提示词就从"玄学"变成了可复现的工程组件。


