Remotion Agent Plugin（Cursor）安装与开发指南：让 AI 编码助手学会用 React 制作视频

Remotion Agent Plugin（Cursor）安装与开发指南：让 AI 编码助手学会用 React 制作视频

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion

导读

Remotion Agent Plugin 是 Remotion 官方维护的便携式（portable）Agent 插件，它把"用 React 编程式制作视频"的领域知识——动画、音频、字幕、3D、转场、图表、文字特效与渲染——封装成可被兼容编码代理（coding agent）读取的技能包（Skills）。本文以仓库中面向 Cursor 的官方说明 packages/agent-plugin/README.cursor.md 为核心，讲解该插件的两种安装路径（Agent Plugins 市场安装与 Cursor 本地安装）、安装后实际写入磁盘的文件结构，以及如何以 Remotion monorepo 为唯一事实来源进行本地开发与验证。

什么是 Remotion Agent Plugin

根据 README.cursor.md 的定义，该插件是Remotion 官方提供的便携式 Agent Plugin，作用是"教会"兼容的编码代理如何用 React 创建视频，覆盖能力包括：

• 动画（animations）
• 音频（audio）
• 字幕（captions）
• 3D 场景
• 转场（transitions）
• 图表（charts）
• 文字特效（text effects）
• 渲染（rendering）

它不是一段普通提示词，而是一套按标准目录组织、带清单文件（manifest）的技能集合。仓库中的 packages/agent-plugin/plugin.json 给出了它的"元信息"：

提示：该清单遵循 agent-plugins.org 的1.0.0schema（见plugin.json中的$schema字段），版本号与包版本强一致，这一约束同时由单元测试固定（见下文"测试验证"）。

安装 Remotion Agent Plugin

官方文档给出了两种安装途径。README.cursor.md 明确指出：该便携式包面向 GitHub Copilot 与 Cursor 这类 Agent 客户端。

方式一：从兼容的 Agent Plugins 市场安装

最直接的路径是从兼容的Agent Plugins marketplace中安装 Remotion。市场化的安装通常在客户端内部完成（搜索插件 → 一键安装），无需手动操作文件系统。仓库内附带的 packages/agent-plugin/marketplace.json 展示了市场清单的组织形态：

{ "name": "remotion", "interface": { "displayName": "Remotion" }, "plugins": [ { "name": "remotion", "source": { "source": "local", "path": "./.codex/plugins/remotion" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Design" } ] }

可以观察到几个设计决策：

• policy.installation = "AVAILABLE"：插件允许被安装；
• policy.authentication = "ON_INSTALL"：鉴权在安装时触发；
• category = "Design"：在市场中归类于设计类。

方式二：在 Cursor 中本地安装

官方为Cursor 本地开发给出了明确命令，将插件克隆到 Cursor 的本地插件目录：

git clone <cursor-plugin 发布仓库地址> ~/.cursor/plugins/local/remotion

随后重启 Cursor即可生效。README.cursor.md 特别强调了这一点：

Restart Cursor after installing the local plugin.

需要注意的目录约定：

• Cursor 会把~/.cursor/plugins/local/下的每个子目录识别为一个本地插件，插件目录名（这里为remotion）对应清单中的name；
• 因为克隆会带上仓库的版本文件，本地安装适合跟随最新改动做体验/调试，正式使用仍建议走市场安装以获取自动更新的版本。

安装后你会得到什么：技能目录结构

仓库中的 packages/codex-plugin/skills/ 与 agent-plugin 的构建产物同源，展示了技能包落地后的形态：顶层每个技能目录内都有一份SKILL.md（技能入口），技能内部再细分为能力清单。以remotion-markup为例，其目录中还包含按主题拆分的参考文档（compositions.md、transitions.md、audio.md、timing.md、lottie.md、ffmpeg.md等）。技能覆盖主题的完整清单可参考 packages/skills/README.md：

安装插件后，Agent 会在需要时调用这些技能来指导"写代码—预览—渲染"的完整闭环。

本地开发：monorepo 是唯一事实来源

README.cursor.md 的 "Development" 一节揭示了该项目一个关键工程约定：

This repository is generated from thepackages/agent-pluginpackage in the Remotion monorepo. Changes made directly in this repository will be overwritten by the release pipeline.

即：Cursor 插件发布仓库的内容是由 Remotion monorepo 中的packages/agent-plugin包生成的。若直接在发布仓库内修改，改动会被发布流水线覆盖；问题反馈与代码贡献应提交到 Remotion monorepo（本仓库）。换句话说，你要改的不是某个 Cursor 专用副本，而是 monorepo 里唯一的知识源。

构建脚本：一次构建，适配多个客户端

packages/agent-plugin/build.mts 是理解"便携化"的钥匙。它以--client=区分目标客户端，目前仅支持codex与cursor两个取值：

# 默认构建 Codex 版（输出到 ./skills） bun build.mts # 构建 Cursor 版并指定输出目录 bun build.mts --client=cursor --output=./dist-cursor

其核心逻辑是：从packages/skills/skills/复制各技能目录 → 预处理内嵌技能（prepareEmbeddedSkills）→ 按客户端注入差异内容。两个客户端的行为差异由构建期"改写"实现：

• Codex 专属：向remotion-best-practices/SKILL.md追加 "Codex troubleshooting" 章节，指导用npx remotion studio --no-open启动 Studio、用--webpack-poll 1000规避EMFILE: too many open files, watch文件监听上限（对应 build.mts）；
• Cursor/通用版：不含 Codex 专属排错章节，且remotion-create技能被改写为"默认启动预览服务器，并在 Agent 客户端可用的浏览器中打开精确 URL"（对应 build.mts）。

也就是说，同一套知识在不同 Agent 上会呈现为适配各自交互习惯的行为，Cursor 用户会体验到"创建后自动在代理浏览器打开预览"，而不会被引导去操作 Codex 专属的系统浏览器开关。

测试验证：可移植构建的自动化保障

仓库用一套 Bun 测试保证发布质量，入口见 packages/agent-plugin/package.json 的test脚本与 test/plugin.test.ts。它验证的关键不变量包括：

1. 清单版本一致性：plugin.json与package.json的版本号、与 Codex 清单版本必须一致；
2. schema 完整性：plugin.json顶层键集合必须精确等于 schema 规定的字段集合；
3. Vally 校验通过：调用@microsoft/vally的runLint检查技能包是否合规，且lint出的技能名与构建产物目录一一对应；
4. 目录/链接纪律：只有顶层技能使用SKILL.md作为发现文件名，内嵌技能改用REFERENCE.md；技能内 Markdown 的相对链接不允许越出所属技能目录；
5. Cursor 可移植构建可过 lint：真实执行bun build.mts --client=cursor --output=<临时目录>并断言其不包含 "Codex troubleshooting"、且remotion-create含"在 Agent 客户端浏览器打开精确 URL"的指令；
6. 显示名与斜杠命令一致：每个技能的agents/openai.yaml中display_name必须形如/技能名。

本地开发操作流

若要在本仓库中开发并验证 Cursor 版插件，可参考以下流程（需先安装 Bun，仓库根目录使用 bun.lock 锁定依赖）：

# 1. 构建 Cursor 版技能包到临时目录 cd packages/agent-plugin && bun build.mts --client=cursor --output=/tmp/remotion-cursor-skills # 2. 运行格式 / Lint / 测试 bun run formatting bun run lint bun run test

由于 build.mts 每次构建都会先清空并重建输出目录，重复构建是幂等安全的；产物目录（默认packages/agent-plugin/skills）只应作为生成物对待，不应手工改动。

与 Agent Skills 生态的关系

README.cursor.md 强调的"便携式"并非孤例。Remotion 在 monorepo 中还维护了面向其他 Agent 的适配包，例如packages/codex-plugin、packages/claude-code-plugin、packages/kimi-code-plugin，它们与packages/agent-plugin共享同一套知识源packages/skills。这套技能同时以独立的 Agent Skills 形式分发（见 packages/skills/README.md），可通过npx skills add直接加入项目，也可在bun create video创建新项目时按提示选择添加。因此可以这样理解本插件在整个体系中的位置：

• 知识层（packages/skills）：唯一的技能内容源；
• 打包层（packages/agent-plugin）：把技能编译为符合 Agent Plugins 规范的便携插件，并按codex/cursor等客户端裁剪行为；
• 发布层（cursor-plugin 等发布仓库）：README.cursor.md 就是随 Cursor 发布仓库附带的说明文件，但其内容源头在本 monorepo。

常见问题与注意事项

• 本地安装后插件不生效：按官方说明，克隆到~/.cursor/plugins/local/remotion后必须重启 Cursor；
• 想改插件内容却找不到入口：不要直接改发布仓库，改动会被流水线覆盖；应回到本仓库的packages/agent-plugin（行为适配）与packages/skills（知识内容）提交，再经发布流程生成新的插件版本；
• 版本号对不上：plugin.json与包的版本必须与package.json同步，plugin.test.ts已把该约束固化为失败即报错的测试；
• Cursor 与 Codex 行为为何不同：这是设计使然——构建脚本会为 Codex 追加系统浏览器相关的排错指引，而为 Cursor 生成"在代理浏览器打开预览"的默认行为，Cursor 构建的产物已经过测试保证不含 Codex 专属内容。

结语

Remotion Agent Plugin 的工程实践值得借鉴：它把"AI 如何帮开发者做视频"沉淀为单一知识源 + 按客户端裁剪 + 自动化校验的发布流水线。对使用者而言，只需在 Agent Plugins 市场中安装、或在 Cursor 中克隆到~/.cursor/plugins/local/remotion并重启；对二次开发者而言，一切修改都应回到本仓库的 packages/agent-plugin 与 packages/skills，再交由构建与测试管线产出稳定的便携插件。想深入探究清单结构、技能组织或 Cursor/Codex 行为差异的读者，可直接阅读 plugin.json、marketplace.json、build.mts 与 test/plugin.test.ts。

【免费下载链接】remotion🎥 Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion