remotion-bits

Remotion Bits

使用此技能时，应优先根据实时 Remotion Bits 示例进行构建；只有在示例不足以满足需求时，才使用基础组件。

默认工作流

1. 根据用户的视觉目标、运动风格或场景描述，先使用 find_remotion_bits。
2. 使用 fetch_remotion_bit 获取最匹配的一两个示例。
3. 先改编最接近的示例，再使用基础组件进行组合。
4. 如果有多个示例匹配，优先选择能满足需求的最简单示例。
5. 如果请求包含多个步骤、由摄像机驱动，或类似演示文稿，则优先选择 Scene3D 示例。
6. 改编文档示例时，保留响应式尺寸、主题颜色用法和自包含的示例结构。

将文档示例视为可用模式的首选库。只有在确认现有示例无法提供所需的构图形式、时间模型和布局结构后，才使用基础组件。

回退顺序

1. 优先使用 MCP。 使用 find_remotion_bits 进行发现，使用 fetch_remotion_bit 获取完整源码。
2. 其次使用 CLI。 使用 npx remotion-bits find "hero intro" --tag scene-3d --json 和 npx remotion-bits fetch bit-fade-in --json。
3. 最后直接检查文档。 检查 docs/src/bits/catalog.ts 和 docs/src/bits/examples/**，然后手动改编最接近的示例。

如果 MCP 接口可用，优先使用它，再使用 CLI。如果 CLI 可用，优先使用它，再直接读取文件。

CLI 和 MCP 设置

如果不想使用仓库本地的工作流，可直接使用已发布的软件包：

# No install
npx remotion-bits find 3d cards
npx remotion-bits fetch bit-fade-in --json

# Global install
npm i -g remotion-bits
remotion-bits find 3d cards
remotion-bits fetch bit-fade-in --json

以相同方式从已发布的软件包启动 MCP 服务：

# No install
npx remotion-bits mcp

# Global install
remotion-bits mcp

当 Agent 或 MCP 客户端需要 stdio 命令时，将其指向以下任一命令：

{
  "command": "npx",
  "args": ["-y", "remotion-bits", "mcp"]
}

{
  "command": "remotion-bits",
  "args": ["mcp"]
}

在此仓库中，等效的仓库本地命令仍然是：

npm run bits:find -- --query "hero intro" --tag scene-3d --json
npm run bits:fetch -- bit-fade-in --json
npm run mcp:bits

如何有效搜索

• 按视觉效果搜索：flying camera through cards、counter with confetti、typewriter terminal、gradient background、staggered grid reveal。
• 如果形式明显，可添加标签：scene-3d、text、particles、gradient、code、counter。
• 如果请求含糊，获取一个强匹配项和一个备用项。
• 优先选择能满足需求且活动部件最少的示例。

改编规则

• 保留 useViewportRect 尺寸设置。优先使用 rect.vmin、rect.vmax、rect.width 和 rect.height，而不是硬编码像素值。
• 保留 docs/src/styles/custom.css 中的主题颜色。除非用户要求使用新的调色板，否则不要随意替换颜色。
• 确保文档示例的 Component 函数完全自包含。如果示例会用于文档 Playground 路径，不要将辅助函数、常量或数据数组留在模块作用域。
• 文档示例已预先封装好，可直接用于展示。如果要将其转换为独立的 Remotion 合成，请自行添加外层布局和背景。
• 对于分阶段的入场和退场动效，优先使用 StaggeredMotion 排序，而不是手动计算帧阶段。
• 对于演示流程，先保留示例的步骤结构，再更改内容、摄像机目标和时间安排。

基础组件速查

• AnimatedText：用于淡入、滑动、按词拆分、按字符拆分和文本循环，是这些效果的入口。主要实现文本显现动效时使用。避免手动重建文本交错效果。
• AnimatedCounter：支持前缀和后缀的数值插值。用于 KPI、定价和统计数据的显现效果。避免自行对格式化字符串制作动画。
• TypeWriter：带光标效果的文本输入和删除。用于终端、CLI 和逐步显示标题的效果。避免用于密集的代码布局，此时真正适用的基础组件是 CodeBlock。
• CodeBlock：带语法高亮、逐行交错、聚焦和高亮区域的代码显现效果。用于编辑器和代码演示场景。除非布局有意采用自定义设计，否则避免手动渲染代码行。
• MatrixRain：现成的矩阵风格文字雨。明确要求矩阵或黑客雨主题时使用。避免将其用作通用粒子背景。
• GradientTransition：动画 CSS 渐变背景和过渡。动效主要涉及背景颜色和渐变变化时使用。除非效果并非渐变过渡，否则避免改用手动颜色插值。
• StaggeredMotion：用于重复子元素的通用编排基础组件。用于列表、网格、卡片堆叠和多元素入场效果。若动画只是交错的变换和不透明度变化，避免逐个子元素计算帧数。
• Particles 和粒子系统基础组件：使用 Particles、Spawner 和 Behavior 实现环境动效、喷泉、雪花、萤火虫和场域效果。避免用于文本编排或布局过渡。
• Scene3D：相机、步骤和 3D 空间构图。需求类似演示、飞行浏览、多步骤演示或由相机驱动的展示时使用。如果相机移动是核心，避免用简单序列重建。
• useViewportRect：尺寸和布局的基础。几乎所有响应式部分都应使用。除非要匹配特定的固定渲染目标，否则避免使用硬编码像素尺寸。

常见决策规则

• 重复子元素需要相同动效：使用 StaggeredMotion。
• 需要文本专属的显现效果：从 AnimatedText 入手。
• 需要计数：使用 AnimatedCounter。
• 需要打字效果：使用 TypeWriter。
• 需要在屏幕上显示代码：使用 CodeBlock。
• 需要环境发射器或粒子：使用粒子系统基础组件。
• 需要场景之间的相机移动：使用 Scene3D。

示例优先模式

• 文本需求：找到一个文本片段，获取它，然后替换文案、时间设置和拆分模式。
• 计数器需求：找到一个计数器示例，然后调整数值、标签和粒子点缀。
• 代码需求：找到一个代码块或打字机示例，然后调整代码样例和高亮区域。
• 背景需求：找到一个渐变或粒子示例，然后调整配色、密度和持续时间。
• 演示需求：先找到一个 Scene3D 示例，然后调整步骤位置、标题和卡片内容，再引入任何新的基础组件。

最简操作示例

# MCP
find_remotion_bits {"query":"camera flythrough product showcase","tags":["scene-3d"],"limit":2}
fetch_remotion_bit {"id":"bit-carousel-3d"}

# CLI
npx remotion-bits find "camera flythrough product showcase" --tag scene-3d --limit 2 --json
npx remotion-bits fetch bit-carousel-3d --json

参考资料

• references/components.md
• references/utilities.md
• references/patterns.md