Remotion 仓库 PR 工作流深度解析：基于 `pr` Agent Skill 的从分支到 Preview 深链全流程

Remotion 仓库 PR 工作流深度解析：基于prAgent Skill 的从分支到 Preview 深链全流程

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

本篇以 Remotion 单仓（monorepo）中的 Agent Skill 文件 pr/SKILL.md 为主体，完整还原该仓库为 AI 编程代理（Agent）定义的 Pull Request 提交流程：从分支保护、Oxfmt 格式化、bun run build/bun run stylecheck双校验、遵循pr-name规范的 PR 命名，到用ghCLI 以--body-file方式创建 PR，最后轮询 Vercel 评论并为packages/docs中直接改动的页面生成 Preview 深链。读完本文，你可以复现一套适用于大型 Bun + Turbo 单仓的、可审计且防呆的 PR 自动化流程，并理解其中每一步在仓库源码与配置中的对应依据。

一、这个 Skill 的定位：Agent 可执行的 PR 流程脚本

.agents/skills/pr/SKILL.md 是 Remotion 仓库中为 Agent 编写的"技能"文件，其 frontmatter 声明了名称与用途：

--- name: pr description: Open a pull request for the current feature ---

与人类阅读的贡献指南不同，这是一份面向自动化执行者的确定性操作清单：每一步给出具体命令、判断条件和失败时的降级行为（例如"无法确定 Preview URL 时保持 PR 不变并如实报告"），而不依赖执行者的临场发挥。仓库中同一目录下还有一组配套 Skill，例如 pr-name/SKILL.md（PR 标题规范）、pr-ready/SKILL.md（处理 CI 失败、合并冲突、未推送变更，把 PR 恢复到可合并状态）以及 vercel/SKILL.md（监控 Vercel 部署状态、解析 Preview URL），prSkill 在流程中显式引用了pr-name与 Element 贡献指南，形成了一套职责分离的流程体系。

以下按 Skill 原文的执行顺序逐步展开。

二、前置检查：确认不在 main，且复用已有 PR

Skill 的第一步是两条防御性检查：

1. 确保当前不在main分支上，如必要则先创建分支；
2. 检查当前分支是否已存在 PR：使用gh pr status或gh pr view。若 PR 已存在，则将本地新变更更新进该 PR，而不是重复创建。

这一步的价值在于幂等性：Agent 可以安全地对同一个功能分支反复执行整个 Skill，第二次执行只会追加变更，不会生成重复的 PR。

此外 Skill 还包含一个条件分支：如果本次变更是新增 Remotion Element（即向 Elements 画廊投稿视频元素），必须先阅读并遵循 Element 贡献指南 再继续。该指南要求将 elements-template 复制到packages/docs/elements/<category>/<slug>、在element-definitions.ts中注册 Studio composition、渲染并审查 PNG/MP4 预览、保持 "Allow edits from maintainers" 开启等。PR 流程通过引用而非内联这些细节，避免了流程文档与贡献文档的双向漂移。

三、格式化：只对受影响的文件跑 Oxfmt

Skill 明确要求：

对本次变更实际影响的文件或包目录运行 Oxfmt，传入真实路径；不要假设仓库根目录存在src目录。包含相关的根级文件，但不要格式化无关的包或整个仓库。

命令形如：

bunx oxfmt <changed-file-or-package-directory>... --write

并附加两条执行纪律：如果变更文件均不受 Oxfmt 支持，则跳过此步；提交前必须检查格式化产生的 diff。

这条规则与仓库的工具链事实完全吻合：

• 根 package.json 的devDependencies中声明了"oxfmt": "0.35.0"，且packageManager为bun@1.3.3，因此用bunx oxfmt调用的是仓库统一锁定的版本；
• 各包以包级formatting脚本接入 Turbo 任务图，例如 packages/core/package.json 声明"formatting": "oxfmt src --check"，packages/docs/package.json 声明"formatting": "oxfmt src standalone --check"——注意两个包检查的目录完全不同（srcvssrc standalone），这正是 Skill 警告"不要假设根目录有src"的原因：路径必须取自变更文件本身；
• 本地提交时还有一道自动格式化的钩子：.githooks/pre-commit的内容只有一行bun pre-commit.ts，而根 package.json 的prepare脚本通过git config core.hooksPath .githooks将其激活。pre-commit.ts 会取git diff --cached与未暂存变更的并集，匹配packages/<dir>/前缀后读取该包package.json：凡有format脚本的包目录就执行bun run --cwd <dir> format，并把原本已暂存的文件重新git add，保证格式化结果进入本次提交。

从源码结构看，Skill 的"只格式化受影响路径"策略与 pre-commit 钩子的"按包定向格式化"策略一致，目的是把 Oxfmt 的写入范围控制在最小集，防止一次提交里混入大量无关包的格式噪音，也避免 CI 的formatting检查（见下节）对无关路径做无谓的--check。

四、双校验：bun run build与bun run stylecheck

格式化之后，Skill 要求依次执行：

bun run build bun run stylecheck

以确保代码可编译、CI 的 lint 与格式检查能通过。这两个脚本在根 package.json 中的定义是：

"build": "turbo run make --no-update-notifier", "stylecheck": "turbo run lint formatting --no-update-notifier && bun run checkskills"

由此可以还原出完整的检查面：

• bun run build展开为turbo run make，即让 Turbo 按依赖图（^make拓扑序）构建所有包的make任务（以 TypeScript 项目为例，packages/core/package.json 的make为tsgo -d && bun --env-file=../.env.bundle bundle.ts），等价于 CI 中ci脚本里的turbo run make test的构建部分；
• bun run stylecheck则覆盖三层：Turbo 任务lint（各包的 ESLint，如packages/core的"lint": "eslint src"）、Turbo 任务formatting（即上文各包的oxfmt ... --check），以及checkskills——后者运行packages/skills/scripts/下的sync-agent-skills.ts --check、sync-embedded-skills.ts --check、sync-readme.ts --check与validateskills（validate-links.ts），专门校验本仓库 Agent Skill 体系的同步与链接有效性。

任务图本身由 turbo.json 描述，其中formatting任务无上游依赖、独立输出日志，说明它被设计为可单独、低开销地执行。把构建与风格检查放在推送前本地跑完，是把 CI 失败成本前移到本地的工作方式，与 pr-ready/SKILL.md 中"修复根因而非重试"的原则衔接。

五、提交与 PR 标题：一次提交，一次推送，标题有法

校验通过后，Skill 给出四条提交纪律：

1. 只提交一次（"Commit the changes once"），将功能变更收敛为单个提交；
2. PR 标题必须遵循pr-nameSkill的规范；
3. 只推送一次，且使用git push -u origin HEAD建立上游跟踪；
4. 绝不 force push，除非用户明确要求。

pr-name规范（pr-name/SKILL.md）的核心要点：

• 标题是"给开发者的 changelog 条目"，不是工作总结，也不是变更文件清单；不要直接复用 commit message；

• 前缀取自受影响包的package.json中精确的name字段，而不是目录名或 Conventional Commit scope：

  `[package-name]`: [description]

  例如`@remotion/shapes`: Add heart shape；多包受影响时，选择拥有主要用户可见变更的包，而非变更文件最多的包；

• 描述部分优先使用具体动词（add、fix、remove、rename、change），避免allow、improve、update handling、support等模糊措辞；公共 API 居中时用反引号精确点名；

• 特殊场景使用专用前缀，按用户可见影响而非所在目录分类：

  场景	前缀	示例
  仅内部测试/快照/测试基建	Internal:	Internal: Stabilize registration range test in@remotion/transitions``
  纯文档变更	Docs:	Docs: Add page about heart shape
  Remotion Elements 相关	Elements:	Elements: Add animated title element
  packages/convert相关	remotion.dev/convert:	remotion.dev/convert: Support trimming
  packages/example相关	Internal testbed:	Internal testbed: Add trimming sample composition
  增改 Skill	Skills:	Skills: Add/remotion-upgradeskill
  packages/brand相关	remotion.dev/brand:	remotion.dev/brand: Add animated logo
  packages/it-tests相关	Internal tests:	Internal tests: Add video integration test

Skill 中给出的gh pr create示例标题`@remotion/package`: Add feature正是这一格式。

六、创建 PR：用临时文件传正文，禁止内联

Skill 对创建 PR 的方式有两条硬性约束：

• 不要通过 shell 内联传递 PR 正文：避免--body "..."与 heredoc，防止转义问题与 shell 注入风险；
• 正文先写入系统临时目录下的 Markdown 文件（如/tmp/remotion-pr-body.md，或/tmp下的唯一文件名），再用文件参数创建：

gh pr create --title '`@remotion/package`: Add feature' --body-file /tmp/remotion-pr-body.md

同时要求：若工作源于、修复或关联某个 GitHub issue，正文中必须包含关闭关键字，如Closes #1234或完整的 issue URL，且当用户在原始请求中给出过 issue 编号或 URL 时必须原样保留。

七、Preview 深链：为直接改动的文档页生成可点击链接

这是整个 Skill 中最具工程细节的部分，目标是让涉及官网页面改动的 PR 正文自带可点击的 Preview 深链。流程如下。

1. 判定"直接改动的页面"

创建 PR 后，检查它是否直接新增或修改了packages/docs中的主要页面。页面公开路径必须从页面源码本身确定，并以 packages/docs/docusaurus.config.ts 作为路由信息的来源。Skill 明确排除两类情形：

• 被删除页面的路径（部署中已不存在，无法预览）；
• 仅影响共享组件、样式、数据或配置的变更（不产生独立的页面级预览意义）。

2. 有界轮询 Vercel 评论

创建 PR 后，最多轮询 60 秒PR 评论，每次间隔 5 秒（即最多 12 次检查），目标是 Vercel bot 的评论。取评论中remotion项目行的Preview链接，将每个页面路径拼接到其后；忽略bugs项目行。

当 Preview 链接不可用、部署链接只指向 Vercel dashboard 时，仅在 Vercel CLI 已安装且已认证的前提下使用vercel inspect <deployment-url>兜底。若仍无法解析，不修改 PR 正文，如实报告"预览 URL 无法解析"。

这里与 vercel/SKILL.md 的原则呼应：该 Skill 强调"绝不通过 HTTP 响应推断部署状态"、"绝不监控可变的分支 preview 别名"，并以vercel inspect ... --scope remotion --format=json读取机器可读的部署状态（配合 check-deployment.py 输出归一化 JSON）。prSkill 中"等待 Vercel 评论、但不等待部署完成、不创建心跳、不探测预览页"的约束，正是把长时监控留给专用 Skill，而 PR 流程只做短时有界轮询的体现。

3. 以文件方式回写 PR 正文

拿到 Preview URL 与页面路径后，把深链追加到 PR 正文的## Preview小节。更新方式同样是"文件进出"：

1. 拉取当前 PR 正文到临时 Markdown 文件；
2. 修改后执行：

gh pr edit <pr> --body-file <path-to-temp-md-file>

Skill 特别强调"绝不可以内联方式传递替换后的正文"。

4. 不确定即不动

收尾原则：只要页面路径或 Preview URL 中任一无法被确信地确定，就保持已创建的 PR 不变，报告"预览链接未添加"。这种"宁可缺失、不可错误"的降级策略，保证了自动化流程永远不会产出指向错误部署或不存在页面的深链。

八、流程总览与适用前提

将 Skill 全文串起来，完整的执行序列是：

确认不在 main（必要时建分支） → gh pr status / gh pr view 复用已有 PR → 若新增 Element，先遵循 Element 贡献指南 → bunx oxfmt <受影响路径>... --write（不支持则跳过；提交前检查 diff） → bun run build # turbo run make → bun run stylecheck # turbo run lint formatting && bun run checkskills → 提交一次；标题按 pr-name 规范 → git push -u origin HEAD（一次；不 force push） → 正文写入 /tmp/*.md → gh pr create --title "..." --body-file /tmp/xxx.md（关联 issue 时含 Closes #n） → 判定直接改动的 packages/docs 页面（路由来源：docusaurus.config.ts） → 轮询 PR 评论 ≤60s、间隔 5s，取 remotion 行的 Preview（忽略 bugs 行） → 追加 ## Preview 深链，gh pr edit <pr> --body-file 回写 → 无法确定则不改 PR，如实报告

适用前提与限制需要说明：该流程绑定 Remotion 仓库的具体环境——Bun 1.3.3 作为包管理器、Turbo 2.9.14 任务图、Oxfmt 0.35.0 格式化器、ghCLI 与（可选的）已认证的 Vercel CLI；checkskills依赖packages/skills/scripts/下的同步脚本。把这套 Skill 迁移到其他仓库时，命令名与任务名需要按目标仓库的package.json/ 任务图重新对齐，但"定向格式化、构建与风格双校验、文件化 PR 正文、有界轮询、不确定即降级报告"这一骨架是通用的。

九、延伸阅读

• pr/SKILL.md：本文主体，PR 创建全流程 Skill；
• pr-name/SKILL.md：PR 标题前缀与措辞规范；
• pr-ready/SKILL.md：CI 失败、冲突、未推送变更的恢复流程；
• vercel/SKILL.md 与 check-deployment.py：Vercel 部署状态监控与 Preview 解析；
• packages/docs/elements/contributing.mdx：Element 投稿的前置贡献指南；
• package.json、pre-commit.ts、.githooks/pre-commit、turbo.json：build/stylecheck/checkskills与本地格式化钩子的实现依据。

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