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.mdPR 标题规范、pr-ready/SKILL.md处理 CI 失败、合并冲突、未推送变更把 PR 恢复到可合并状态以及 vercel/SKILL.md监控 Vercel 部署状态、解析 Preview URLprSkill 在流程中显式引用了pr-name与 Element 贡献指南形成了一套职责分离的流程体系。以下按 Skill 原文的执行顺序逐步展开。二、前置检查确认不在 main且复用已有 PRSkill 的第一步是两条防御性检查确保当前不在main分支上如必要则先创建分支检查当前分支是否已存在 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 流程通过引用而非内联这些细节避免了流程文档与贡献文档的双向漂移。三、格式化只对受影响的文件跑 OxfmtSkill 明确要求对本次变更实际影响的文件或包目录运行 Oxfmt传入真实路径不要假设仓库根目录存在src目录。包含相关的根级文件但不要格式化无关的包或整个仓库。命令形如bunx oxfmt changed-file-or-package-directory... --write并附加两条执行纪律如果变更文件均不受 Oxfmt 支持则跳过此步提交前必须检查格式化产生的 diff。这条规则与仓库的工具链事实完全吻合根 package.json 的devDependencies中声明了oxfmt: 0.35.0且packageManager为bun1.3.3因此用bunx oxfmt调用的是仓库统一锁定的版本各包以包级formatting脚本接入 Turbo 任务图例如 packages/core/package.json 声明formatting: oxfmt src --checkpackages/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与validateskillsvalidate-links.ts专门校验本仓库 Agent Skill 体系的同步与链接有效性。任务图本身由 turbo.json 描述其中formatting任务无上游依赖、独立输出日志说明它被设计为可单独、低开销地执行。把构建与风格检查放在推送前本地跑完是把 CI 失败成本前移到本地的工作方式与 pr-ready/SKILL.md 中修复根因而非重试的原则衔接。五、提交与 PR 标题一次提交一次推送标题有法校验通过后Skill 给出四条提交纪律只提交一次Commit the changes once将功能变更收敛为单个提交PR 标题必须遵循pr-nameSkill的规范只推送一次且使用git push -u origin HEAD建立上游跟踪绝不 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 inremotion/transitions纯文档变更Docs:Docs: Add page about heart shapeRemotion Elements 相关Elements:Elements: Add animated title elementpackages/convert相关remotion.dev/convert:remotion.dev/convert: Support trimmingpackages/example相关Internal testbed:Internal testbed: Add trimming sample composition增改 SkillSkills:Skills: Add/remotion-upgradeskillpackages/brand相关remotion.dev/brand:remotion.dev/brand: Add animated logopackages/it-tests相关Internal tests:Internal tests: Add video integration testSkill 中给出的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 --formatjson读取机器可读的部署状态配合 check-deployment.py 输出归一化 JSON。prSkill 中等待 Vercel 评论、但不等待部署完成、不创建心跳、不探测预览页的约束正是把长时监控留给专用 Skill而 PR 流程只做短时有界轮询的体现。3. 以文件方式回写 PR 正文拿到 Preview URL 与页面路径后把深链追加到 PR 正文的## Preview小节。更新方式同样是文件进出拉取当前 PR 正文到临时 Markdown 文件修改后执行gh pr edit pr --body-file path-to-temp-md-fileSkill 特别强调绝不可以内联方式传递替换后的正文。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 CLIcheckskills依赖packages/skills/scripts/下的同步脚本。把这套 Skill 迁移到其他仓库时命令名与任务名需要按目标仓库的package.json/ 任务图重新对齐但定向格式化、构建与风格双校验、文件化 PR 正文、有界轮询、不确定即降级报告这一骨架是通用的。九、延伸阅读pr/SKILL.md本文主体PR 创建全流程 Skillpr-name/SKILL.mdPR 标题前缀与措辞规范pr-ready/SKILL.mdCI 失败、冲突、未推送变更的恢复流程vercel/SKILL.md 与 check-deployment.pyVercel 部署状态监控与 Preview 解析packages/docs/elements/contributing.mdxElement 投稿的前置贡献指南package.json、pre-commit.ts、.githooks/pre-commit、turbo.jsonbuild/stylecheck/checkskills与本地格式化钩子的实现依据。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考