FunwayHQ/quar-design

在 Quar Animator 中进行设计与动画制作

Quar Animator 是一个 2D 矢量动画编辑器；其 MCP 工具可以读取和编辑用户的云端项目。您的工作方式就像一位能够看到自己作品的运动设计师：规划、构建、查看、修正、动画制作、查看运动效果、导出。每一次查看都是从服务器获取的快照——请相信它，而不是您预期的效果。

如果 quar-animator 工具不可用，请告知用户，并引导他们参考本技能的 README（连接 MCP 至 https://api.animator.quar.pro/mcp）进行设置；不要尝试其他方式操作文件。

工作循环

1. 读取。 list_projects（或 create_project {name} 用于全新开始——向用户提供其 editorUrl，该链接会在其编辑器中打开；标记为 stillUploading 的项目尚无版本，其视频仍在从编辑器中上传：直到上传完成才能打开），然后 get_scene_context {project_id}。注意 seq——将其作为 base_seq 传递给每次编辑，这样如果变更落在您尚未看到的更改上，编辑将失败。注意 frameRate、duration、artboardTimelines 以及哪些内容被锁定（用户的内容：除非被要求，否则不要触碰）。
2. 规划 在您动手之前：画框（画板尺寸）、布局、调色板、字体、什么移动以及何时移动。为用户简要记录规划。使用 reference/design.md 和 reference/motion.md；对于已知类型的作品，请遵循 recipes/ 中的配方。
3. 通过试运行构建。 使用一个 apply_edit_batch 处理连贯的步骤（背景、布局、字体……），设置 dry_run: true。它不会保存任何内容，但会返回将要发生的变更——placed——即每个新增或更改节点的 at 和 bounds（在假设结果中），以便在保存前测量布局——以及一张图片（preview_frame；preview_node 用于显示一个画板或节点；preview_size 最大 1024）。为您的 add_node 提供自定义 id（"id": "title"），以便批次中的后续操作可以引用它们。
4. 查看并修复。 根据 reference/design.md 中的清单评估图片：对齐、间距、层次、对比度，确保没有内容被裁剪。修复批次并再次试运行，直到正确为止。然后在不带 dry_run 的情况下发送，并附带 message（“布局：标题、副标题和标志”）。
5. 动画制作 同样方式：使用 animate 操作（每个属性一次，一次性完成整个曲线）组成一个批次，在关键时间点上使用 preview_frame 试运行，然后提交。
6. 查看运动效果。 使用 render_preview，参数为 count: 8–12（均匀分布在其绘制内容的整个时间轴上——即画板自身的时间轴）或指定发生关键变化的 frames（最多 16 个），可生成带标签的缩略图网格（使用 count 时，最后一个单元格为第 N 帧，导出时不会播放）。检查时间、重叠、停顿、是否有跳动，以及循环动画的最后一帧是否与第一帧匹配。使用 animate、move_keyframes、set_easing 修复。
7. 导出 在用户要求时进行（export，然后执行 get_export {export_id, wait: true}），并读取其详细信息：Lottie 无法保留的内容（unsupported：节点类型、带效果的图层、混合模式）、帧数、尺寸。立即向用户提供链接——该链接有效一次，有效期为一小时；再次执行 get_export 可获得新链接。
8. 告知用户 简要说明您制作的内容，并告知每一步都是一个可以撤销的版本（list_versions、restore_version）。

保持批次的目的性：每个有意义的步骤一个版本（不是每个形状一个版本，也不是一次性盲目完成整个作品）。一个批次最多包含 500 个操作，且为全有或全无。

调用方式

参数并列排列——从不嵌套在 options 对象中。

create_project      {name}
get_scene_context   {project_id, page?, node?, depth?}
get_node            {project_id, node, page?}          (每个存储的属性及其关键帧)
get_timeline        {project_id, page?, node?, property?} (每个关键帧及其缓动；单个属性)
get_animatable_properties {node_type}                  (某类型可动画化的属性：骨骼还额外包括 x、y)
list_fonts          {}                                 (可绘制文本的字体族及其字重)
measure_text        {text, font_family?, font_weight?, font_size?, letter_spacing?, line_height?, box_width?}
                                                       (每个字形的 x 和 advance、行宽、上升、下降)
apply_edit_batch    {project_id, ops: [...], base_seq?, message?, dry_run?, preview_frame?,
                     preview_page?, preview_node?, preview_size?}
render_frame        {project_id, frame?, node?, page?, size?, transparent?}
render_preview      {project_id, frames? | count?, node?, page?, size?, transparent?}
capture_canvas      {project_id, frame?, page?}        (用户打开的编辑器绘制它；若未响应则使用已保存版本)
export              {project_id, format, node?, frame?, start_frame?, end_frame?, fps?, width?, height?}
get_export          {export_id, wait?, include_file?}
list_versions       {project_id}
restore_version     {project_id, seq}

一个操作是 {"op": <名称>, ...其参数}；每个操作可附带自己的可选 page（批次本身没有 page）。操作是编辑工具的名称：add_node、update_node、set_style、delete_node、duplicate_node、group_nodes、mask_nodes、ungroup_node、reorder_node、set_pivot、convert_to_outlines、add_keyframe、animate、remove_keyframe、move_keyframes、set_easing、clear_animation、add_page、delete_page、rename_page、duplicate_page、set_document、set_artboard_duration、add_bone、pose_bone、set_ik_target、bind_mesh（一个批次中最多 20 个 bind_mesh 操作和 60 层：可一次性绑定多个形状）、unbind_mesh、set_video_clip（见下方）。get_bindings 读取每个绑定层跟随的骨骼；绑定层可被删除（其绑定也随之消失）。当名称重复时（例如一个形状和一个骨骼都叫“左大腿”），请使用 id。

[
  { "op": "add_node", "type": "rectangle", "id": "card", "parent": "frame", "x": 0, "y": 0,
    "width": 640, "height": 360, "cornerRadius": 24, "fill": "#1f1d29" },
  { "op": "set_style", "node": "card",
    "effects": [{ "type": "drop-shadow", "color": "#07060b", "offsetY": -16, "blur": 40, "opacity": 0.4 }] },
  { "op": "animate", "node": "card", "property": "y",
    "keyframes": [{ "frame": 0, "value": -120 }, { "frame": 18, "value": 0, "easing": "easeOutCubic" }] },
  { "op": "animate", "node": "card", "property": "scale",
    "keyframes": [{ "frame": 0, "value": { "x": 0.9, "y": 0.9 } }, { "frame": 18, "value": { "x": 1, "y": 1 } }] },
  { "op": "animate", "node": "card", "property": "fill",
    "keyframes": [{ "frame": 0, "value": "#1f1d29" }, { "frame": 18, "value": "#a855f7" }] }
]

值：x、y、rotation、opacity、尺寸使用数字；position 和 scale 使用 {x, y}；fill 和 stroke 使用 "#rrggbb"。效果：drop-shadow 和 inner-shadow 接受 color、offsetX、offsetY、blur、spread、opacity；layer-blur 接受 radius。

容易出错的事实

• Y轴向上。 节点的 x、y 是其锚点——对于大多数形状（包括画板）而言是中心。Y值越大，在屏幕上位置越高。（svg 路径数据是例外：在节点自身空间（相对于其中心）中，Y轴向下，与 SVG 文件一致。）
• 两个坐标系。 at 和 bounds（在 get_scene_context 和试运行的 placed 中）是页面坐标；节点的 x、y——以及基于它们的关键帧——位于其父空间。在非页面中心的画板或组内部，两者不同：关键帧应基于节点自身的 x/y（通过 get_node 获取），而非其 at。
• 子元素按从前到后的顺序绘制：后面的兄弟元素位于上方。先添加背景，最后添加焦点形状，或使用 reorder_node {node, to: "front"|"back"|…, index?} 重新堆叠。
• 画板默认白色，除非赋予填充："fill": "none" 用于透明画板（例如应用的 Lottie、贴纸）。
• 枢轴。 缩放和旋转围绕节点的位置（即其枢轴）进行——对于大多数形状而言是中心。若要改变枢轴位置——例如关节处的肢体、在地面挤压的 logo、向右生长的文字——使用 set_pivot {node, at: "bottom"}（其自身盒子的一个位置：left、top-right……）或 {node, x, y}（页面上的一个点）；枢轴在屏幕上位置保持不变。组、矩形和图像接受枢轴；将其他内容先放入组中（group_nodes {nodes: [它], id}——其组位于其父级原点，直到设置枢轴），然后为组设置枢轴。在动画化旋转或缩放之前设置枢轴：动画化的旋转围绕枢轴。（update_node 无法更改父级：reorder_node {node, parent} 可移动节点进入新父级，并保持其位置不变。）
• 蒙版。 mask_nodes {nodes, mask?, mode?} 将节点和一个蒙版（形状、文本或图像；当未命名时，取节点中位于最前方的那个）放入一个组中，仅在其内部显示它们——用于揭示、渐变、画框中的图片、边缘的物体。蒙版本身不被绘制；动画化其大小、位置、缩放以实现揭示效果。mode：clip（轮廓）、alpha（不透明度：渐变淡入）、luminance（白色显示，黑色隐藏）。
• rotation 以度数为单位，逆时针方向，按书写值插值：0→360 为一整圈；−360 顺时针转一圈。
• 渐变：angle 0° 从左到右，90° 从下到上（270° 从上到下）。
• 阴影：offsetY 为负值时，阴影位于下方。
• letterSpacing 以像素为单位（100px 处 -2 适用于紧凑型显示文本）。
• 路径保持其自身中心作为位置：关键帧的 x/y 应围绕其当前值（通过 get_scene_context 的 at 读取），切勿围绕 0。
• 文本与字体。 文本在其自身字体系列中绘制、布局和测量，无论是 Inter（始终可用：字重 100 至 900，400 和 700 有斜体）还是编辑器中的 Google Fonts（list_fonts：字体系列及其字重——仅正体；缺少的字重将使用最接近的）。服务器在文档首次使用某个 Google 字体时获取该字体。其宽度精确（字距调整、字母间距、字符间距）；高度为行盒（行数 × 字号 × lineHeight）。列表中不存在的字体系列会以 Inter 绘制和测量，回复中会说明（fonts）：请从列表中选择，或通过 capture_canvas 检查用户自己的字体（当项目在其编辑器中打开时）。measure_text 设置文本但不放置它：每个字形的 x 和 advance、每行的宽度、字体的上升和下降——用于光标、下划线和将单词适配到宽度。convert_to_outlines {node} 将文本转换为字母路径组（<id>-1…，按字母命名），用于逐字母动画：交错排列、改变某个字母的颜色、弹跳某个字母。单向操作。
• 时间线。 duration 和 frameRate 是文档的属性。页面顶部的每个画板播放其自己的时间线——其图层的关键帧，长度为自身长度（artboardTimelines；set_artboard_duration {artboard, duration}；若未设置，则使用文档的长度）。N 帧的时间线包含关键帧 0…N；导出和幻灯片播放帧 0…N−1，因此对于循环动画，关键帧 N 应等于帧 0。在关键帧超出时间线末端之前，先延长时间线（使用 set_document {duration} 设置页面时间线）。
• 幻灯片。 在编辑器的演示文稿和视频导出中，以及带有多个画板（未指定 node、未指定范围）的页面导出为 GIF 和 PNG 序列时，画板依次播放——最前方的画板先播放（图层面板顶部），每个画板播放其自身长度，并适配到第一个画板的尺寸。稍后添加的画板位于前方，因此会先播放：请使用 index: 0 添加稍后的幻灯片，或使用 reorder_node 调整顺序。artboardTimelines 按播放顺序列出它们。使用 node 导出单个画板。MP4 和 WebM 从编辑器（文件>导出）导出，而非通过 MCP。
• easing 是进入某个关键帧（其前一个关键帧之后）的曲线。名称见 reference/motion.md；[x1, y1, x2, y2] 表示三次贝塞尔曲线。一个过冲缓动（easeOutBack）进入一个已经是过冲结果的关键帧会导致二次过冲：请使用 easeOutCubic 进入峰值，然后使用弹性缓动进行回弹。
• 视频。 视频图层（"type": "video"：MP4、MOV、WebM，或用户导入的动画 GIF）是一幅图片，在其剪辑播放期间播放，超出剪辑范围则不显示任何内容（除非设置了 hold）。get_scene_context 提供其 video：file、gif、其 length（秒），以及其 clip——start（其开始的帧）、end（其停止的帧）、offset（从视频开头修剪的秒数）、duration（一次播放的视频秒数）、speed、loop 和 loopFor（它循环播放的秒数）、hold（结束后其最后一帧保持显示）——以及其关联的 sound（时间线上随之移动的剪辑）。使用 set_video_clip {node, moveTo?, trimStart?, trimEnd?, speed?, loop?, hold?, stopAt?, unlinkSound?} 更改剪辑——参数为图层所在时间线的帧，按循环、速度、moveTo、trimStart、trimEnd、hold、stopAt 的顺序应用：
  • moveTo 设置其开始的帧；trimStart 将某帧设为其第一帧，其结束帧保持不变（较晚的值会从视频开头修剪更多内容，较早的值会播放更多内容）；trimEnd 设置其停止的帧（较早的值会修剪结尾更多内容，较晚的值会播放更多内容，直到视频结束——或者，当设置 loop 时，循环播放直到该帧：{loop: true, trimEnd: 300} 可填满 10 秒的幻灯片）。
  • speed 范围为 0.25–4（音高保持不变）；hold: true 保持最后一帧显示；stopAt 在某帧结束，并保持该帧显示的内容（GIF 冻结在中间）；loop: false 对于 GIF 同样保持冻结。
  • 其声音会跟随每次变化，并且其播放的时间线会延长以播放至结束（结果中会说明 timelineLengthened）。unlinkSound: true 将使声音独立。 除此之外，视频图层是图像：移动、调整大小（width、height）、圆角（cornerRadius）、淡入、adjustments、效果、混合模式、蒙版（它也可以作为蒙版）、枢轴和关键帧——但不能拉伸角落，也不能绑定骨骼。duplicate_node 会连带复制其声音；delete_node 会删除其声音。

……

[因翻译需要已截断]