review-dependabot

审查 Dependabot PR

适用于 FMC 地理应用的工作流。Dependabot 配置（分组、计划、忽略项、dependabot.yml 更改）位于技能 tech-stack → references/dependabot.md 中。此技能涵盖审查和合并决策。

仓库范围

仅在当前工作区的 Git 仓库中操作——绝不审查或合并其他仓库的 Dependabot PR。从项目根目录运行 gh，不要使用 --repo。如果工作区不是 Git 仓库，或者没有 .github/dependabot.yml，请停止。

典型的 FMC 应用仓库以 develop 为目标分支——绝不要将 Dependabot PR 合并到 main。确认每个 PR 的 baseRefName；如果看起来不对，请使用 AskUserQuestion。

策略：每个生态系统最多有一个未关闭的 Dependabot PR——在下一个 PR 打开之前，先合并或明确延期（关闭 + 忽略）。

审查工作流

1. 收集上下文

gh pr list --author app/dependabot --state open --json number,title,baseRefName,headRefName,labels

对于每个未关闭的 PR：

gh pr view <number> --json title,body,baseRefName,headRefName,mergeable,statusCheckRollup,author,labels
gh pr diff <number> --name-only

PR 正文就是变更日志。 使用 gh pr view 中的 body 进行分类——除非正文为空，或者对于必须做出决策的包而言明显不完整，否则不要获取 GitHub 发布说明、npm 页面或其他外部变更日志。

对于分组 PR，每个包都有各自的部分——请逐一查看；其中一个有风险的条目就可能阻止整个分组。阅读差异或在代码库中搜索之前，先查看正文中的重大变更、迁移和弃用标题。

注意标题中的分组名称（例如 app-framework-minor-patch）。

还要列出未关闭的安全警报——PR 列表为空并不代表没有未关闭的警报：

gh api repos/{owner}/{repo}/dependabot/alerts \
  --jq '.[] | select(.state=="open") | "\(.dependency.package.name) \(.security_advisory.severity) \(.dependency.manifest_path) fixed in \(.security_vulnerability.first_patched_version.identifier)"'

2. 风险分类

等级	示例	操作
低	补丁版开发工具（knip、husky）、类型定义、独立实用工具	CI 通过 → 合并
中	分组的框架次要/补丁依赖、vite、oxlint/oxfmt、Playwright	阅读 PR 正文中的发布说明；抽查用法；如果说明提到行为变更，则在本地运行 bun run build + bun oxlint
高	react、@tanstack/*、maplibre-gl、react-map-gl、prisma、better-auth、zod、tailwindcss、typescript 主版本	阅读 PR 正文中的所有说明和迁移部分；在代码库中搜索受影响的 API；运行构建、lint、单元测试；如果涉及地图/身份验证/路由，则运行 Playwright；全部通过后再合并
关键决策	Semver 主版本、明确的重大变更、peer 依赖冲突、CI 失败或变更日志不清楚	AskUserQuestion——在人工做出选择之前不要合并（只有此等级需要询问）

安全更新：至少按中级处理——仍需阅读说明；即使标记为安全更新，也不要盲目合并。它们会绕过冷却期，并且可能建议升级到非常新的版本。

3. 在代码中调查

当 PR 正文中的发布说明或风险等级要求调查时：

1. gh pr diff <number> — 重点检查 package.json，不要只关注锁文件噪声。
2. 在本地检出代码中搜索重大变更部分提及的 API（已弃用的属性、重命名的导出项、配置键）。
3. 如果升级涉及相关领域，加载对应的 FMC 技能（react-dev、react-map-gl、tanstack-router-conventions、tanstack-start-conventions、playwright-skill 等）。
4. 检查 CI 日志中的 peer dependency 警告。

browserslist 升级：Dependabot 不会更改 browserslist 查询 — 但锁文件可能会更新 caniuse-lite。合并后，确保 bun oxlint 和 bun run build 仍然通过（技能 tech-stack → references/browser-target.md）。

GitHub Actions 升级：优先选择分组的次要版本／补丁版本升级；检查操作的发布说明，确认运行器／输入项是否重命名；工作流必须与组织密钥和 permissions 保持兼容。

Docker 升级：每月更新基础镜像 — 检查 OS／软件包变更；如果应用会发布容器，请在本地重新构建。

4. 没有 PR 的安全警报（Bun）

在 Bun 仓库中，Dependabot 无法创建安全更新 PR。GitHub 会将警报归入 npm 生态系统，因此安全任务会以 npm_and_yarn 身份运行，忽略 package-ecosystem: bun 条目，并在 bun.lock 处中止。在默认分支上，这会显示为名为 npm_and_yarn in /<dir> for <packages> - Update #… 的失败运行；只要警报仍未关闭，每次推送都会重复出现。

这无法通过 dependabot.yml 或工作流修复 — 不要尝试。我们保留失败运行作为手动升级的信号：

1. 从上方的警报列表中获取软件包、目录和修复版本。
2. 直接依赖：在 package.json 中设置修复版本，然后在该目录运行 bun install。传递依赖（bun why <package>）：升级父级软件包，或在添加 overrides 条目之前使用 AskUserQuestion。
3. 风险等级至少为 medium，与任何安全更新相同；阅读安全公告（gh api repos/{owner}/{repo}/dependabot/alerts/<number>），因为没有 PR 正文。
4. 运行项目检查，使用技能 finish-work 提交，提交标题为 Dev: Bump <package> to <version>，并在正文中说明这是安全修复，然后按仓库通常的方式推送更改。
5. 确认警报列表为空，且下一次推送没有失败的 npm_and_yarn 运行。

5. 何时使用 AskUserQuestion

当 Agent 无法安全地独自作出决定时，使用 AskUserQuestion：

• 任何生产环境或框架依赖的 Semver 主版本升级
• 重大变更影响到无法在当前会话中完全验证的代码路径
• CI 失败，且修复方式不明显，或会使范围超出此次升级
• 分组 PR 混合了安全和高风险的软件包 — 全部合并、拆分，还是关闭并重新配置分组
• 必须作出决定的软件包缺少 PR 正文发布说明，或说明相互矛盾
• 是采用拟议的 ignore 规则，还是立即进行更新
• 是合并，还是等待相关 PR／上游修复
• 已知版本发布，但尚无版本更新 PR — 可能正处于冷却期，或等待下一次计划检查

提供具体选项，例如本地构建通过后合并、关闭并添加 ignore，或推迟到下周。

6. 合并

要求：

• 所有必需检查均成功（绝不要为了“疏通队列”而合并失败的检查）
• 按上表处理风险等级
• 没有阻止合并的未解决评审讨论

使用 rebase 合并以保持历史线性：

gh pr merge <number> --rebase --delete-branch

如果仓库不允许通过 CLI 进行 rebase，请使用 GitHub UI 中的 Rebase and merge。

不要 squash Dependabot PR — 每次依赖升级保留一个提交，以便更轻松地进行二分查找。

在 develop 上合并后，无需进一步操作，除非基分支上的 CI 失败（届时按紧急修复后续处理）。

7. 延后处理，而不是合并

遇到以下情况时，关闭 PR，不要合并：

• Major 版本升级需要专门安排迁移时间
• 变更组过大，无法一次性完成审查
• 已知上游回归问题（在 PR 评论中附上 issue 链接）

相比让 PR 一直处于打开状态，更建议在 .github/dependabot.yml 中添加有针对性的 ignore（在 PR 评论中说明原因）——请记住，open-pull-requests-limit: 1 会阻塞队列。

不要这样做

• 除非常规 Dependabot 合并必须修改应用代码，否则不要在同一时段重构应用代码
• 不要为了让有问题的升级通过而修改 CI 工作流——应标记出来
• 安全警报仍未解决时，不要声称“Dependabot 工作已全部完成”，也不要试图屏蔽失败的 npm_and_yarn 安全检查
• 未逐一审查每个 PR 前，不要批量合并多个处于打开状态的 Dependabot PR