Markdy：像 Mermaid 一样简单，但用于定义动画

背景

在 Web 开发和内容创作领域，动画一直是提升用户体验和表达复杂逻辑的重要工具。然而，传统的动画制作往往面临两个极端：要么是使用代码（如 CSS 动画、Web Animations API 或 GSAP）进行精细控制，但语法繁琐、难以维护；要么是使用可视化的拖拽编辑器，虽然直观但难以版本控制、难以通过代码生成或集成到自动化工作流中。

Mermaid 等图表 DSL（领域特定语言）的成功证明了“文本即图表”的理念在静态可视化中的有效性。Markdy 正是这一理念的延伸，它试图将这种简洁、基于文本的定义方式引入到动态动画领域。Markdy 是一个开源的动画 DSL，旨在让开发者能够通过简单的文本语言定义角色、时间轴和交互，而无需处理复杂的 Keyframes（关键帧）或拖拽操作。它特别强调与 AI 的兼容性，旨在成为“Vibe Coding”（氛围编码/直觉式编码）时代的理想工具。

核心内容

Markdy 的核心在于其轻量级的架构和高度结构化的 MarkdyScript 语言。它不依赖 Canvas 渲染或庞大的运行时库（如 GSAP），而是基于 Web Animations API 和 CSS 变换，确保极小的包体积和零运行时依赖。

1. 基础场景与演员定义

动画始于场景（Scene）的定义，这是 .markdy 文件的第一行，用于设定画布尺寸、帧率和背景色。例如：

scene width=800 height=400 fps=30 bg=#fafafa

“演员”（Actors）是场景中的基本对象，可以是图形（figure）、文本（text）或盒子（box）。它们通过坐标 at (x, y) 定位，并支持透明度、缩放、旋转等修饰符。

actor a = figure(#c68642, m, 😎) at (300, 150)
actor label = text("Hello") at (200, 130) size 40 opacity 0

2. 时间轴与动作调度

Markdy 使用基于时间的调度语法 @time: actor.action()。时间单位为十进制秒数，支持缓动函数（easing）如 linear, in, out, inout。

• 入场/出场：enter, fade_in, fade_out。
• 移动：move(to=(x,y), dur=1.0, ease=out)。
• 交互：say("Hello!") 生成对话气泡，shake 产生震动效果。

3. 高级角色控制

对于 figure 类型的演员，Markdy 支持肢体级别的精细控制，允许制作富有表现力的动画：

• 肢体旋转：rotate_part(part=arm_right, to=130)。
• 内置手势：为了简化操作，提供了 wave（挥手）、nod（点头）、jump（跳跃）、bounce（弹跳）等高级动作，无需手动组合多个旋转指令。
• 表情与姿态：face("😵") 改变表情，pose 可同时设置多个肢体角度。

4. 资产加载与复用

• 外部资源：支持加载 GIF 图片或矢量图标（如 Lucide 图标），并将其渲染为 Sprite 演员。
• 变量与模板：使用 var 定义颜色等值，使用 def 创建可复用的角色工厂模板，无需编写 JavaScript 即可构建角色系统。
• 序列块（Seq）：将多步动作打包为可复用的 seq 块，通过 play() 触发，支持相对时间偏移（@+0.0），极大提升了复杂动画的可维护性。

5. 生态系统与集成

Markdy 提供了轻量级的包结构，开发者只需按需安装核心解析器和渲染器：

• 核心：@markdy/core 和 @markdy/renderer-dom，纯 TypeScript 解析，无 DOM 依赖。
• Astro 集成：通过 @markdy/astro 包，Markdy 可以作为 Astro 的岛屿组件（Island Component）直接使用，支持服务端渲染和静态生成。
• 交互性：提供在线 Playground，允许实时编辑代码并预览动画。

关键要点

• AI 原生友好（Vibe Coding）：MarkdyScript 是一种结构化 DSL，LLM（大语言模型）可以轻松地生成、验证和迭代代码。用户只需描述自然语言场景（如“一个人拿着咖啡杯走路，绊倒，咖啡洒了”），AI 即可生成完整的 .markdy 代码。官方提供了 AGENT.md 作为 AI 的参考文档。
• 技术栈极简：
  • 基于 Web Animations API 和 CSS Transforms，不使用 Canvas。
  • 不依赖 GSAP 等重型动画库。
  • 纯 TypeScript 解析器，无运行时依赖。
• 模块化与轻量化：
  • 采用分体式包设计（Core, Renderer, Astro 等），仅打包所需部分，实现零冗余。
  • 支持 Astro 框架，可直接作为组件嵌入现代 Web 应用。
• 功能丰富且直观：
  • 支持从简单的文本淡入到复杂的肢体动画（挥手、踢腿、表情变化）。
  • 支持资产加载（图片、图标）和变量/模板复用。
  • 提供相对时间轴和序列块，便于管理复杂的多步动画。
• 跨平台与通用性：
  • 兼容 Claude, ChatGPT, GitHub Copilot, Cursor, Windsurf 等主流 AI 工具。
  • 任何接受 URL 上下文的 AI 均可利用其文档生成动画代码。

意义与影响

Markdy 的出现标志着动画开发范式的一次潜在转变。它将动画从“视觉编辑”和“复杂代码”的束缚中解放出来，回归到“文本定义”的本质。

1. 降低动画创作门槛：通过类似 Mermaid 的简洁语法，非专业动画师或后端开发者也能快速创建复杂的交互式动画。
2. 赋能 AI 驱动开发：Markdy 的设计哲学与当前 AI 辅助编程的趋势高度契合。它证明了结构化 DSL 是 AI 生成内容的最佳载体之一，因为 AI 擅长处理语法明确的文本，而非像素级的视觉调整。
3. 提升工程化水平：基于文本的动画定义天然支持版本控制（Git Diff 清晰可见）、代码复用和自动化测试。这对于需要频繁迭代动画内容的产品（如营销页面、教育软件、数据可视化仪表盘）具有极高的工程价值。
4. 性能优化：摒弃 Canvas 和重型运行时，利用浏览器原生的 CSS 和 Web Animations API，确保了动画在移动端和低端设备上的流畅运行，同时保持了极小的 Bundle 体积。

总之，Markdy 不仅是一个工具，更是一种新的动画创作思路：让机器理解意图，让人专注于创意。