Remotion 单仓（Monorepo）中 Dependabot PR 的修复流程：fix-dependabot 技能详解

Remotion 官方仓库是一个包含 100+ 子包、以 Bun 作为包管理器的 monorepo，Dependabot 自动依赖升级 PR 在其中会天然产生两类问题：锁文件 bun.lock 过期、兄弟包仍引用旧版本。.agents/skills/fix-dependabot/SKILL.md 这一技能文件（SKILL）把修复流程固化成了 7 步可执行清单。读完本文，你能完整复现"从拉取 Dependabot 分支到推送修复"的全流程，理解为什么单仓中一次依赖升级必须同步所有 package.json，并掌握用 ripgrep 定位旧版本引用、用 bun install 重生成锁文件的实战方法。

问题背景：为什么 Dependabot 的 PR 在单仓中不完整

SKILL 文件开头直接点明了核心矛盾（见 SKILL.md）：

Dependabot PRs only update one package.json and never run bun install, so the bun.lock file is out of date and other packages in the monorepo still reference the old version.

也就是说 Dependabot 存在两个固有缺陷：

1. 只改一个 package.json：Dependabot 检测到某个包有新版本时，只会更新它扫描到的那一个包声明文件。而 Remotion 仓库中同一个依赖往往出现在多个子包里（例如 react、zod、eslint 都通过根目录 catalog 被各子包以 catalog: 形式引用），只改一处意味着其余包仍然声明旧版本。
2. 从不执行 bun install：因此根目录的 bun.lock 不会重生成，锁文件与新声明的版本不一致，后续 CI 或本地安装都可能基于陈旧锁文件解析出错误版本。

这个背景可以从仓库结构得到印证：根目录 package.json 声明 "name": "remotion-monorepo"、"packageManager": "bun@1.3.3"，其 workspaces.packages 覆盖 packages/** 下的全部子包，并通过 workspaces.catalog 对 react、zod、eslint、@aws-sdk/*、mediabunny 等高频依赖做集中版本管理；overrides 字段还强制锁定了 caniuse-lite、@rspack/core 等若干传递依赖版本。此外根目录 bunfig.toml 配置了 linker = "isolated" 安装模式。在这种"多包共享、集中管控"的结构下，任何依赖版本变更都天然是全仓级操作，这也正是需要一套修复流程的原因。

值得说明的是，该技能文件在仓库中的实际组织方式是符号链接机制：sync-agent-skills.ts 会把 packages/skills/skills/<name> 目录下的技能同步为 .agents/skills/<name> 的符号链接，供不同 Agent 运行时读取；根目录 package.json 中的 checkskills 脚本（bun packages/skills/scripts/sync-agent-skills.ts --check 等）会在 CI 风格检查中校验这些链接的一致性。

修复流程总览：7 步清单

SKILL 将修复动作拆成 7 个步骤。下面按原顺序完整给出每一步的说明与命令，并结合仓库实际情况补充了细节。

第 1 步：获取 PR 信息

使用 GitHub CLI 查看 PR 的分支名、被升级的依赖以及新旧版本号：

gh pr view <number> --json headRefName,files,title,body

需要确认的三个关键信息：

• 分支名（headRefName）：Dependabot 的分支名通常形如 dependabot/npm_and_yarn/...，后续 checkout 需要用到；
• 被升级的依赖名：例如 zod、vite、sharp；
• 旧版本 → 新版本：例如 4.4.3 → 4.4.4，或 major 升级 5 → 6。

这一步的信息决定了第 3 步的搜索模式怎么写，务必先记录准确。

第 2 步：检出 Dependabot 分支

git fetch origin <branch>
git checkout <branch>

注意在 Remotion 仓库中一切操作应在仓库根目录进行，因为 bun.lock 位于根目录，而所有依赖解析以根目录的 workspace 为边界。

第 3 步：更新单仓内所有引用该依赖的 package.json

这是整个流程中最关键的一步。Dependabot 只改了一个包，你需要用 ripgrep 找出所有仍在旧版本的 package.json：

rg '"<dependency>": "[~^]?<old-version>"' --glob '**/package.json'

例如要把 zod 从 4.4.3 升到 4.4.4，就运行：

rg '"zod": "[~^]?4.4.3"' --glob '**/package.json'

更新规则（SKILL 原文强调）：

• 每一个匹配项都要更新为新版本，不能只更新 Dependabot 已改的那个；
• 保留每个包原有的前缀风格：原本是 ^、~ 还是精确版本号，升级时保持同样的写法（^4.4.4、~4.4.4 或 4.4.4），避免意外改变版本解析语义。

结合当前仓库结构看，搜索时需要关注几类位置：

• 各子包（如 packages/core/package.json）的 dependencies / devDependencies / peerDependencies；
• 根目录 package.json 的 workspaces.catalog——这里集中了 zod、react、eslint 等版本的"事实来源"，子包普遍以 "catalog:" 形式引用它；
• 根目录 overrides 中若涉及该依赖的传递版本，也需一并核对。

从源码结构看，当同一个依赖在 catalog 与各子包中同时出现字面量版本时，rg 的 glob 搜索能把它们全部暴露出来，这正是"逐包精确匹配 + 保留前缀"策略的意义：它不需要理解每个包的依赖语义，只需机械地做版本字符串替换。

第 4 步：在仓库根目录执行 bun install

bun install

这一步的目的是重生成 bun.lock，使其与所有更新后的 package.json 声明一致。仓库 AGENTS.md 也明确将 bun install 列为该仓库安装依赖的标准命令，并要求用 bunx（而非 npx）运行包二进制。

第 5 步：校验改动范围

git status

预期结果：只有 bun.lock 和被更新的若干 package.json 处于修改状态。如果出现了意料之外的文件变更（例如某个脚本生成物、lockfile 之外的源码文件），SKILL 要求先停下来调查原因再继续，不要盲目提交。这一步是防止 bun install 的 postinstall/prepare 逻辑（本仓库根目录定义了 "prepare": "git config core.hooksPath .githooks"）或其他副作用污染 PR 内容。

第 6 步：提交并推送

git add -u
git commit -m "Update <dependency> to <version> across all monorepo packages"
git push

提交信息模板明确写出 "across all monorepo packages"，与第 3 步的"全仓同步"目标呼应，便于后续审阅者一眼识别这是一次修复性补全提交。

第 7 步：切回原分支

git checkout main

避免停留在 Dependabot 分支上继续其他开发工作。

Notes：三个边界情况的处理策略

SKILL 的 Notes 部分给出了三条经验性约束，值得逐条理解：

1. 手动改动 PR 不会"弄坏" Dependabot 的自动冲突解决。

Dependabot 的 PR 描述中会写 "Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself"。SKILL 指出：更新锁文件和兄弟包正是期望的工作流，不会造成问题。换句话说，这里的 "don't alter it yourself" 针对的是会引入版本回退或语义变更的改动，而不是补全 lockfile 这类机械性同步。

2. major 版本升级需要人工判断。

如果 Dependabot 升级的是 major 版本（SKILL 举例 vite 5 → 6），应先评估升级是否合适、是否存在破坏性变更（breaking changes），再决定修复还是忽略该 PR。在 Remotion 仓库中，catalog 里同时锁定了大量相互关联的版本（例如 react/react-dom 与 @types/react/@types/react-dom、mediabunny 全家桶、@aws-sdk/* 系列），单个 major 升级往往牵动整组版本，盲目同步旧策略风险更高。

3. bun install 失败时的退出路径。

如果 bun install 因依赖冲突而失败，说明新版本与其他包不兼容。SKILL 给出的处置是：关闭该 PR 并留下评论解释原因，而不是强行合并或手工编辑 bun.lock。这符合仓库"以 lockfile 为准、可复现安装"的维护纪律。

适用前提与可迁移性

• 适用前提：这套流程针对的是以 Bun + workspaces 管理的 monorepo，核心前提是仓库存在根级 bun.lock（见 bun.lock），且依赖声明分散在 packages/** 下多个 package.json 中。Remotion 仓库的 packageManager 声明为 bun@1.3.3，Bun 版本不一致可能影响 lockfile 格式，操作前建议核对。
• 可迁移性：步骤本身与 Remotion 业务无关，可迁移到任何同类结构的仓库：把 bun install 换成对应包管理器（如 npm install、pnpm install），把 rg 搜索的目标文件换成对应清单文件即可，"全仓搜索旧版本 → 统一升级 → 重生成锁文件 → 校验 diff 范围"的四段式逻辑保持不变。
• 与仓库工具链的衔接：修复推送后，后续验证可走 AGENTS.md 中的标准命令，例如 bunx turbo run lint test 确认新版本下测试套件仍然通过，bun run clean 清理构建缓存以排除陈旧产物干扰。

小结

fix-dependabot SKILL 把"Dependabot 在 monorepo 中不完整"这一共性痛点固化为 7 步清单：gh pr view 取信息 → checkout 分支 → rg 全仓搜索旧版本并逐包升级（保留 ^/~ 前缀）→ 根目录 bun install 重生成 bun.lock → git status 校验改动面 → 统一提交推送 → 切回 main，并配套了 major 升级评估、安装失败关 PR 两条兜底规则。对于维护 Remotion 这类大型单仓的开发者（或为仓库配置 Agent 的工程师），这份 SKILL 文件既是一份可直接执行的 runbook，也展示了"用技能文件沉淀运维流程"的文档组织方式。