submit-element

提交 Remotion Element

设计与质量标准的权威来源是 Element 贡献指南。进行更改前，请完整阅读。如果本技能与指南中的验收标准不一致，请以指南为准。

本技能负责贡献者的提交工作流。工作流从使用 scaffold-element 技能创建 Element 开始。仓库写入者会直接上传审核通过的预览。其他贡献者则提交临时审核素材，之后由维护者使用 accept-element 技能处理。

1. 确认 Element 已准备就绪

确认以下文件以及 packages/docs/src/components/Elements/element-definitions.ts 中对应的条目已存在：

• packages/docs/elements/<category>/<slug>/index.mdx
• packages/docs/elements/<category>/<slug>/<slug>.tsx

不要通过本技能启动 Studio。继续之前，必须要求开发者明确确认：他们已在文档的 Remotion Studio 中目视审核 element-<category>-<slug>，并确认效果正确。不要根据测试已完成或 Agent 自行检查来推断已获批准。如果开发者尚未批准，或者还需要进行视觉开发，请提供以下命令并停止提交工作流：

bun run build
cd packages/docs
bun run remotion

2. 选择提交路径

确定经过身份验证的 GitHub 账户在规范仓库中的权限。不要根据 Git 远程地址、分支名称或提交邮箱推断成员身份。

login=$(gh api user --jq '.login' 2>/dev/null || true)
permission=$(
  if [ -n "$login" ]; then
    gh api "repos/remotion-dev/remotion/collaborators/$login/permission" \
      --jq '.permission' 2>/dev/null || true
  fi
)
printf 'GitHub user: %s\nRepository permission: %s\n' \
  "${login:-unknown}" "${permission:-unknown}"

仅当 permission 为 write、maintain 或 admin 时，才使用直接成员路径。继续此路径之前，请验证 Bun 能读取 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY，但不要打印它们的值：

(
  cd packages/docs
  bun -e 'process.exit(Bun.env.AWS_ACCESS_KEY_ID && Bun.env.AWS_SECRET_ACCESS_KEY ? 0 : 1)'
)

这里特意使用子 shell：由于工作目录是 packages/docs，Bun 会加载 packages/docs/.env。Element 预览上传不使用 packages/remotion-media/.env；不要对它们使用通用的 upload-r2 或 offload-r2 技能。

如果仓库写入者缺少任一凭据，请停止并说明直接上传预览所需的凭据不可用。不要悄悄为他们提交临时素材。

如果权限为 read、triage、none、未知，或 GitHub 查询失败，则使用外部贡献路径。此路径不需要上传凭据。

3. 执行提交审核

根据 Element 贡献指南和 scaffold-element 技能中的技术要求，审核已完成的源文件、MDX 页面和中央定义。解决占位内容，并完善描述、显示名称、贡献者、尺寸、时长、installationMode、声明的依赖项、预览留白和海报帧。

渲染和审核时，保留本地审核 URL：

• posterUrl: '/elements/<category>-<slug>-preview.png'
• videoUrl: '/elements/<category>-<slug>-preview.mp4'
• 页面 frontmatter 中的 image: /elements/<category>-<slug>-preview.png

预览素材会合成到标准背景上，并使用 MP4，以确保与各类浏览器、社交卡片和嵌入场景广泛兼容，即使 Element 本身支持透明度也不例外。

如果 Element 有可通过 Studio 编辑的控件，也要使用交互最佳实践技能进行审核。

如果 Element 导入了 packages/docs 中不可用的软件包，请将其添加到 packages/docs/package.json，运行 bun install，并包含 bun.lock。

4. 将其添加到图库

• 确认 packages/docs/src/components/Elements/element-definitions.ts 中的条目会将该 Element 添加到生成的总览和分类库中。
• 将 '<category>/<slug>/index' 添加到 packages/docs/elements-sidebars.ts 中对应的分类。

保留侧边栏中的排序。不要手动添加分类索引链接：可视图库和原始 Markdown 库均由中央定义生成。如果任务明确要求新增分类，请创建一个用于渲染筛选后 ElementLibrary 的索引，并在此步骤中添加其侧边栏分组。

在确认图库注册完成之前，请验证该 Element 是否显示在总览页、所属分类页和生成的原始 Markdown 路由中。

不要编辑 packages/docs/src/remotion/Root.tsx；Element 合成内容源自中央定义。

5. 渲染并检查预览

仅渲染提交的 Element：

cd packages/docs
bun run render-element-previews --element=<category>/<slug>
cd ../..

不要在未筛选 Element 的情况下运行 render-element-previews，因为这会渲染所有 Element 并清空整个预览输出。

检查以下文件，并将两个路径都提供给开发者进行视觉审核：

• packages/docs/.element-previews/<category>/<slug>/preview.png
• packages/docs/.element-previews/<category>/<slug>/preview.mp4

停止并等待开发者明确确认两个预览均正确。在收到批准之前，不要上传或复制素材。

6A. 内部成员路径：上传渲染结果

不要将预览复制到 packages/docs/static/elements，也不要将其添加到 Git。上传经过审核的确切渲染结果：

cd packages/docs
bun run upload-element-preview \
  --element=<category>/<slug> \
  --source=render
cd ../..

上传器会验证本地 URL、签名、总大小、上传后大小、公开 HTTP 响应和内容类型。从 packages/docs 运行可使 Bun 加载 packages/docs/.env。只有在确认两项上传均成功后，才能继续。

然后：

1. 将 packages/docs/src/components/Elements/element-definitions.ts 中的本地 posterUrl 和 videoUrl 替换为打印出的 https://remotion.media URL。
2. 将 packages/docs/elements/<category>/<slug>/index.mdx 中的本地 image URL 替换为公开海报 URL。
3. 确认 packages/docs/static/elements 下不存在匹配文件。

如果上传后 Element 的视觉效果发生变化，请恢复本地 URL，重新渲染并审核，然后重新执行直接上传，最后再恢复公开 URL。

6B. 外部贡献路径：添加审核素材

不要上传到 R2，也不要替换本地 URL。将经过审核的确切文件复制到对应的扁平审核路径：

mkdir -p packages/docs/static/elements
cp packages/docs/.element-previews/<category>/<slug>/preview.png \
  packages/docs/static/elements/<category>-<slug>-preview.png
cp packages/docs/.element-previews/<category>/<slug>/preview.mp4 \
  packages/docs/static/elements/<category>-<slug>-preview.mp4

PNG 和 MP4 的总大小不得超过 10 MiB。不要添加被忽略的 .element-previews 目录。packages/docs/static/elements 下的两个文件是有意纳入版本控制的，必须包含在拉取请求中，这样贡献者和审核者才不会遇到 404 响应。

accept-element 技能会在审核后上传获准的素材并替换本地 URL。

7. 格式化并测试

仅格式化已更改的 TypeScript 和 TSX 文件。对于常见文件：

bunx oxfmt \
  packages/docs/elements/<category>/<slug>/<slug>.tsx \
  packages/docs/src/components/Elements/element-definitions.ts \
  packages/docs/elements-sidebars.ts \
  --write

cd packages/docs
bun test src/test/elements.test.ts
cd ../..

对于内部成员提交，针对性测试会验证确切的公开 URL，以及本地审核素材不存在。对于外部贡献，测试会验证本地 URL、扁平审核素材、文件签名和贡献文件总大小。

8. 运行最终仓库检查

bun run build
bun run stylecheck
git diff --check
git status --short

完成前，请确认该页面已列入生成的总览和分类库、生成的原始 Markdown 及侧边栏；所有检查均已通过；且变更仅包含预期文件。

对于内部成员路径，请报告两个已验证的公开预览 URL，并确认没有预览素材纳入版本控制。对于外部路径，请报告两个纳入版本控制的审核素材；如果开启了拉取请求，请保持“Allow edits from maintainers”处于启用状态。两种情况下，都应在准备好供审核的贡献后停止。