零 npm 依赖、2 个单文件跑完整个引擎:motion-anything 架构设计原理完整剖析
零 npm 依赖、2 个单文件跑完整个引擎:motion-anything 架构设计原理完整剖析
motion-anything 是一个开源的 AI 动效引擎:零 npm 依赖、无构建步骤,两个单文件就能跑完整套本地动效引擎——403 个动效配方、8 个 AI Agent 引擎、浏览器内直接导出 MP4,一条命令即可启动,全程无需 npm install。本文剖析它"反框架"的架构设计原理。
为什么说它是真"零 npm 依赖"?
很多项目号称零依赖,其实只是不写 dependencies。motion-anything 的"零"是彻底的——打开 cli/package.json,里面连 dependencies 字段都不存在,只有 engines 声明要求 Node 18+:
"engines": {
"node": ">=16"
}
它用"手写"替代了每一个 npm 包,对照表如下:
| 常见项目的做法 | motion-anything 的做法 |
|---|---|
| React / Vue + 构建工具 | 单文件原生 DOM(app/index.html) |
| three.js / ogl 跑 GPU 着色器 | 58 行自写 WebGL 运行器(recipes/web/_fx/shaderbg.js) |
| express / vite dev server | 手写 require('http') 静态服务器 |
| js-yaml 解析配方清单 | 手写正则解析 recipe.motion.yaml |
| ffmpeg 服务端转码 | 浏览器内 WebCodecs 编码 + vendored muxer |
服务端那个 1728 行的 cli/bin/motion.js,全部依赖都是 Node 内置模块:
const fs = require('fs');
const path = require('path');
const { spawn } = require('child_process');
// 以及 http / https / os
💡 "零依赖"带来的直接收益:clone 下来就能跑,没有供应链风险、没有 lockfile 冲突,任何机器、任何会话启动行为完全一致。
单文件一:cli/bin/motion.js —— 服务端 + CLI + 引擎分发
一条命令启动整个引擎:
node cli/bin/motion.js serve 4399
# 打开 http://localhost:4399
这个单文件里藏了三重身份,也是"无构建"能成立的关键:
- 静态文件服务器:内置 MIME 类型表,直接托管
app/目录下的整个前端; - CLI 工具:
list/add/gallery子命令,其中add会把任意配方导出为一个可移植的 skill 包; - Agent 引擎分发器:内置一张
KNOWN_CLIS清单,覆盖 Claude Code、Codex、Cursor、OpenCode、Gemini 等 8 个引擎 + BYOK(自带 API Key)模式。它用command -v自动探测你机器上已安装的 CLI,再用五种传输协议(stream-json / JSONL 事件流 / 纯文本 / ACP JSON-RPC / 直连 API)在一个接口后面统一驱动——所以无论底层是哪个 AI,前端代码完全无感。
单文件二:app/index.html —— 整个前端应用
app/index.html 有 5043 行:CSS 变量主题系统(含跟随系统的暗色模式)、工作台、关键帧编辑器、时间线、4 国语言 i18n——全部内联在这一个文件里,没有一行 import。
为什么不用 React?因为单文件意味着:
- 可被 AI Agent 直接读懂和编辑——这正是动效工作台的核心场景:Agent 在"正在运行的页面"上生成动效,再把结果写回文件;
- 可被整份拷贝到任何静态托管(甚至本地双击打开),不存在模块解析问题;
- 配方预览同样如此。看这条 silk 着色器配方的 preview.html,整个"场景"就靠两个 script 标签撑起:
<script src="../_fx/shaderbg.js"></script><script src="silk.js"></script>
58 行 shaderbg.js:如何干掉 three.js
整个配方库里所有 GPU 着色器背景,都由 recipes/web/_fx/shaderbg.js 这一个 58 行文件驱动。它的文件头注释直白地写着:"Replaces ogl/three"。这 58 行做了三件大事:
- WebGL1 / WebGL2 双兼容:自动识别
#version 300 es并切换着色器语法; - 自动 uniforms:
uTime、uResolution、uMouse逐帧自动注入,配方作者只需写片元着色器本身; - 优雅降级:
prefers-reduced-motion下渲染静态帧;没有 WebGL 时回退到data-fallback背景色。
视频线:浏览器内 WebCodecs 导出,无水印不上传
app/video/ 目录是画布合成器(引擎 + 导出 + HTML 帧捕获)。MP4 导出完全发生在浏览器里:VideoEncoder 逐帧编码,再交给内置(vendored)的 mp4-muxer.js 封装成文件——两个第三方 MIT 库直接放在 app/video/vendor/ 目录下,而非通过 npm 安装。
export function canExport() {
return typeof window !== 'undefined' && 'VideoEncoder' in window && 'VideoFrame' in window;
}
没有服务器转码、没有按次计费、没有水印,导出的每一帧都留在你的机器上。
"无构建"背后的真正设计动机
这套架构的终极受益者不是人,而是 AI Agent。仓库把这一点写成了硬规则(AGENTS.md):
Plain files only. No build-time magic that locks the repo to one agent or toolchain.
纯文件 = 任何 Agent、任何新会话都能零成本接手:读 MOTION-SPEC.md 知道"品味标准",读 PROGRESS.md 知道项目状态,403 个配方每个都是自包含的 recipe.motion.yaml + SKILL.md + 可直接打开的 preview.html(AGENTS.md 中的五维分类法定义了入库标准)。
架构总结
| 部件 | 文件 | 规模 | 替代掉的生态 |
|---|---|---|---|
| 前端应用 | app/index.html | 5043 行单文件 | React + 构建链 |
| 服务端/CLI/引擎 | cli/bin/motion.js | 1728 行单文件 | express + 多包 CLI |
| WebGL 运行器 | recipes/web/_fx/shaderbg.js | 58 行 | three.js / ogl |
| 视频导出 | app/video/ | 3 文件 + 2 个 vendored 库 | ffmpeg 服务端 |
motion-anything 用"刻意的无聊"(deliberately boring)对抗了动效工具链的复杂化:没有锁定的工具链、没有构建缓存、没有依赖升级噩梦——只有一句话提示、你的本地 Agent、和两个可以随手改动的单文件。






