setup

Remotion Superpowers — 设置向导

你正在运行 Remotion Superpowers 插件的设置向导。请仔细按照以下步骤操作，并逐步引导用户完成设置。

步骤 1：检查系统依赖项

运行以下检查并报告结果：

node --version
npm --version
python3 --version 2>/dev/null || python --version 2>/dev/null
which uvx 2>/dev/null || echo "uvx not found"

必需：

• Node.js 22.18 或更高版本（Remotion 和 MCP 服务所需）
• npm（随 Node.js 一起安装）

建议：

• Python 3 + uv/uvx（仅用于可选的、已弃用的 ElevenLabs MCP 服务）
  • 如果缺少，请告知用户：curl -LsSf https://astral.sh/uv/install.sh | sh
• 字幕无需额外依赖：逐词字幕使用官方的 remotion-captions 流程（通过 WebGPU 在本地运行 Whisper）；没有 GPU 时则使用 ElevenLabs Scribe。

报告每项的结果和版本，并标记为 ✓ 或 ✗。

步骤 2：检查 Remotion 项目

检查当前目录是否已有 Remotion 项目（package.json 中有 remotion 依赖，通常还会有 remotion.config.ts）。

如果有： 告知用户已检测到 Remotion 项目。

如果没有： 询问用户要在此处创建项目，还是切换到现有项目。要创建项目，请严格按照官方 remotion-create 技能的说明进行脚手架搭建：

1. 先检查当前文件夹，包括隐藏文件（ls -la）。.env 或 .git 等文件都视为有意义的内容；只有 .DS_Store 等操作系统元数据可以删除。
2. 空文件夹（或先移除仅含的可删除元数据）：

   npx create-video@latest --yes --blank --no-tailwind .
   npm i
   

3. 含有有意义内容的文件夹：在子文件夹中搭建脚手架，然后切换到该文件夹：

   npx create-video@latest --yes --blank --no-tailwind my-video
   cd my-video
   npm i
   

除非用户提出要求，否则不要添加 TailwindCSS；官方技能搭建脚手架时不会添加它。

在用户进入 Remotion 项目目录前，不要继续操作。如果切换到了新文件夹，请从该目录重新启动 Agent：remotion-media 工具会将文件写入 Agent 启动目录下的 public/。

步骤 3：安装 Remotion 官方 Agent 技能（必需）

Remotion Superpowers 构建于 Remotion 官方 Agent 技能之上。这些技能是必需的配套组件：此插件负责生成和获取媒体，官方技能负责 Remotion 标记语言、脚手架搭建、预览、字幕和渲染。没有这些技能，工作流将缺少 Remotion API 指引。

检查是否已安装全部 12 个技能（例如位于 .claude/skills/、.agents/skills/、.codex/skills/ 或 .gemini/skills/ 中）：

remotion-best-practices、remotion-captions、remotion-create、remotion-docs、remotion-interactivity、remotion-maps、remotion-markup、remotion-multimedia、remotion-render、remotion-saas、remotion-studio、remotion-upgrade

如果缺少任何技能：

npx skills add remotion-dev/skills

npx skills 会检测已安装的 Agent（Claude Code、Codex、Gemini CLI、Cursor、Copilot……），并为每个 Agent 安装技能。如果它询问要安装哪些技能，请选择全部 12 个。

保持技能为最新版本。 Remotion 经常发布新版本，技能也会随每次发布而更新。在项目目录中运行：

npx remotion upgrade

此操作会升级 Remotion 及其软件包，也会更新项目本地的 Remotion 技能（官方 remotion-upgrade）。如果本地未安装 @remotion/cli，请直接更新技能：

npx skills update remotion-best-practices remotion-captions remotion-create remotion-docs remotion-interactivity remotion-maps remotion-markup remotion-multimedia remotion-render remotion-saas remotion-studio remotion-upgrade --yes

还要安装此插件所依赖的服务商技能：

npx skills add elevenlabs/skills   # voice, sound effects, music, transcription
npx skills add replicate/skills    # only if the user wants Replicate models

告知用户：“Remotion 官方技能已安装。你的 Agent 现在掌握了 Remotion 当前的 API、预览、字幕和渲染；Remotion Superpowers 则在此基础上增加了媒体生成功能。”

步骤 4：配置 API 密钥

引导用户逐一配置每个 API 密钥。每个密钥都要：

1. 说明该服务提供什么
2. 提供注册 URL
3. 告知用户环境变量名称
4. 请用户设置密钥：export VAR_NAME=their-key
5. 建议将其添加到 ~/.zshrc 或 ~/.bashrc，以便长期生效

**Gemini CLI：**扩展不会继承 Shell 环境变量。安装扩展时会提示输入密钥；之后如需更改，请运行 gemini extensions config remotion-superpowers "ElevenLabs API key"（或对应的设置名称），而不要通过导出环境变量来设置。

4a. ElevenLabs API 密钥（必需：语音、音效、音乐）

• 说明： 配音、音效和音乐（Eleven Music，在付费计划中获准用于商业用途），以及在没有 GPU 时生成逐词字幕所需的转录内容。通过官方 ElevenLabs 技能生成。
• 注册： https://elevenlabs.io（提供免费套餐；商业音乐需要付费计划）。或者运行 npx -y @elevenlabs/cli@latest onboard init，登录并为项目保存密钥。
• 变量： ELEVENLABS_API_KEY
• 命令： export ELEVENLABS_API_KEY=your-key-here
• 持久化： echo 'export ELEVENLABS_API_KEY=your-key-here' >> ~/.zshrc

4b. KIE API 密钥（必需：AI 图像和片段）

• 说明： 通过 remotion-media 服务生成 AI 图像（Nano Banana Pro）和 AI 视频片段（Veo 3.1）。也可以生成低成本的音频草稿，但 KIE 转售这些模型时未获得模型所有者的许可，因此最终用于商业用途的音频应由 ElevenLabs 提供。
• 注册： https://kie.ai（创建账户，然后从控制面板获取 API 密钥）
• 变量： KIE_API_KEY
• 命令： export KIE_API_KEY=your-key-here
• 持久化： echo 'export KIE_API_KEY=your-key-here' >> ~/.zshrc

4c. TwelveLabs API 密钥（必需：视频理解和 AI 审核）

• 说明： 让你的 Agent 能够观看视频：分析素材、查找精彩片段，并审核渲染后的视频，给出可执行的修改建议。
• 注册： https://www.twelvelabs.io（提供免费套餐）
• 变量： TWELVELABS_API_KEY
• 命令： export TWELVELABS_API_KEY=your-key-here
• 持久化： echo 'export TWELVELABS_API_KEY=your-key-here' >> ~/.zshrc

4d. Pexels API 密钥（推荐：免费库存素材）

• 说明： 免费的库存照片和视频。按关键词搜索，并将 HD/4K 片段下载到项目中。
• 注册： https://www.pexels.com/api/（免费，即时可用）
• 变量： PEXELS_API_KEY
• 命令： export PEXELS_API_KEY=your-key-here
• 持久化： echo 'export PEXELS_API_KEY=your-key-here' >> ~/.zshrc

4e. Replicate API 令牌（可选：特定图像/视频模型）

• 说明： 提供数百种模型（FLUX.2、Kling、Seedance、Wan 等），可在需要特定模型时使用，也可在 KIE 片段生成失败时作为备用方案。
• 注册： https://replicate.com（创建账户，然后获取 API 令牌）
• 变量： REPLICATE_API_TOKEN
• 命令： export REPLICATE_API_TOKEN=your-token-here
• 持久化： echo 'export REPLICATE_API_TOKEN=your-token-here' >> ~/.zshrc

设置每个密钥后，请先让用户确认已完成设置，再继续下一个。可跳过可选项。

步骤 5：重新加载 Shell 并验证

告诉用户重新加载 Shell：

source ~/.zshrc

然后验证环境变量是否已设置：

echo "ELEVENLABS_API_KEY: ${ELEVENLABS_API_KEY:+SET}"
echo "KIE_API_KEY: ${KIE_API_KEY:+SET}"
echo "TWELVELABS_API_KEY: ${TWELVELABS_API_KEY:+SET}"
echo "PEXELS_API_KEY: ${PEXELS_API_KEY:+SET}"
echo "REPLICATE_API_TOKEN: ${REPLICATE_API_TOKEN:+SET}"

步骤 6：验证 MCP 连接

告诉用户检查 MCP 服务状态：

/mcp

所有已配置的服务都应显示为已连接。如果有任何服务连接失败：

• 检查是否已设置 API 密钥环境变量
• 对于基于 uvx 的服务，确保已安装 uv
• 对于基于 npx 的服务，确保已安装 Node.js
• 尝试重启你的 Agent（Claude Code、Codex、Gemini CLI…）

步骤 7：完成设置

打印摘要：

🎬 Remotion Superpowers — Setup Complete!

✓ Dependencies verified
✓ Remotion project detected
✓ Remotion official skills installed (12)
✓ API keys configured
✓ MCP servers connected

🎬 Production Commands:
  /create-video      — Full video production from a prompt
  /create-short      — Short-form vertical video (TikTok/Reels/Shorts)

🎨 Asset Commands:
  /find-footage      — Search & download stock footage from Pexels
  /generate-image    — Generate AI images for your video
  /generate-clip     — Generate AI video clips

🔊 Audio Commands:
  /add-voiceover     — Generate and add narration
  /add-music         — Generate and add background music
  /transcribe        — Transcribe audio/video to text

✨ Enhancement Commands:
  /add-captions      — TikTok-style animated captions
  /add-transitions   — Professional scene transitions

👁️ Analysis Commands:
  /analyze-footage   — Analyze existing video files with AI vision
  /review-video      — AI feedback loop (renders frames and the video for review)

Keep Remotion and its skills current: npx remotion upgrade

Try it: "Create a 30-second product demo video for a todo app"