pr-sweep

用途

pr-sweep 用于在代码审阅前批量整理 GitHub 上的 PR。它以每个 PR 一个子代理的方式并行处理（上限 100 个），对 PR 做分类、安全扫描，判断是否需要 rebase、是否需要触发 CI，并给出指派审阅的建议。默认是 dry-run（仅生成报告），变更步骤需要显式授权。

主要能力

并行审计：每个 PR 一个通用子代理，只读阶段最多 100 个并发。
安全扫描：区分外部（outside）与内部（in-house）作者，外部 PR 默认做安全检查；外部作者按“登录名是否在内部集合中”判定。
变更操作（需 --apply）：rebase 到 main、git push --force-with-lease、批准等待中的 CI 工作流。
快照与增量：在 .agent/pr-sweep/snapshot.json 记录每个 PR 的 head SHA、更新时间、安全状态、合并状态等，支持 --changed 与 --daily 的增量处理。
报告输出：写入 .agent/pr-sweep/SWEEP-YYYY-MM-DD.md，包含安全告警、需人工查看、外部/内部 PR 建议动作、跳过项、Apply 计划与结果。

使用方式

调用形式包括：

/pr-sweep：所有开放的、非草稿 PR（完整审计）。
/pr-sweep 12 34 56：仅指定编号的 PR。
/pr-sweep --apply：完整集合，然后 rebase 并推送（--force-with-lease）。
/pr-sweep --apply 12 34：仅对列出的 PR 执行 rebase 并推送。
/pr-sweep --outside-only：动作目标仅为外部作者（变更操作的默认值）。
/pr-sweep --include-in-house：同时对内部分支做 rebase/更新（仍然永不合并）。
/pr-sweep --behind：仅处理落后于基线 / BEHIND / 未及时更新的 PR。
/pr-sweep --conflicts：仅处理冲突 / DIRTY 状态的 PR。
/pr-sweep --changed：仅处理自上次快照以来有变化的 PR（无快照时按 24 小时内 updatedAt）。
/pr-sweep --daily：推荐的每日配方，取 --changed ∪ --behind ∪ --conflicts ∪ 新外部 PR 的并集。
--apply --daily --include-in-house：每日应用，预处理外部 PR，并在内部落后/冲突时 rebase 内部分支。

可自由组合参数；显式 PR 编号始终优先于筛选条件。

模式

dry-run（默认）：拉取、分类、安全扫描，判断相关性、是否需要 rebase、是否需要 CI、指派建议。不推送、不批准 CI、不评论。
apply：在 dry-run 逻辑后，对通过安全且标记可操作的 PR，在同一轮内完成 rebase、git push --force-with-lease 与 CI 批准。--apply 即视为同意，不再等待二次确认。仍然永不合并 PR，也永不在 PR 上评论。只做本地 rebase 而不推送，视为失败的 apply。结果只记录在 SWEEP-*.md 中。

每日例程

方式 A（Grok /loop，会话级，约 7 天过期）：

/loop 1d /pr-sweep --apply --daily --include-in-house

或每天早上跑 dry-run，等确认后再 apply：

/loop 1d /pr-sweep --daily --include-in-house

loop 间隔支持 Nm / Nh / Nd（最小 60s）。用 scheduler_list → scheduler_delete <id> 取消。

方式 B（手动工作日）：

/pr-sweep --daily --include-in-house          # 先 dry-run
/pr-sweep --apply --daily --include-in-house  # 浏览计划后再 apply

--daily 的动作集合为以下并集：新外部 PR（完整安全扫描）、Changed（updatedAt 或 head SHA 相比快照有变）、Behind、Conflicts、CI 等待批准。跳过项（仍在报告中计数）：草稿（除非显式列出）、快照中为 security: alert 且人工未清除的、过去 24 小时内标记为 blocked-conflicts 且 updatedAt 无变化的、机器人版本/发布 PR（除非 --include-bots）。成本目标是每日处理几十个，而非全部开放历史；完整 /pr-sweep 仍作为每周深度扫描。

前置条件

gh auth status
gh repo view --json nameWithOwner,defaultBranchRef,owner

未认证则停止。需确认位于目标仓库（或按用户指定的 owner/repo）。

安全硬规则

永不合并 PR。
永不 git push --force，只用 git push --force-with-lease。
安全发现（security: "alert"）时不做任何变更，报告后停止该 PR。
默认动作目标仅为外部；内部 rebase 需要 --include-in-house。
内部 PR 安全：除非触及 scripts/、.github/workflows/、lockfile 或安装生命周期，否则跳过恶意软件扇出；触及则仅做轻量扫描。
仅 apply 模式的 git 操作用 worktree（spawn_subagent 传 isolation: "worktree"），不在主工作区检出外部分支。
apply 子代理并发上限 8；只读扇出可到 100。
rebase 冲突若在约 10 分钟代理工作内无法干净解决，则中止、在报告中记录，不推送部分状态。
优先 rebase；仅当代理 JSON 指明时才用 merge-from-base。
推送是 rebase 的一部分；干净 rebase 后执行 git push --force-with-lease 到 PR head 远端，并用 gh pr view N --json headRefOid 验证远端 SHA 变化；未变化前不算完成。
永不在 PR 上评论（包括 review/issue 评论）；结果只写入 .agent/pr-sweep/SWEEP-*.md。

处理流程

解析仓库与“内部”集合：通过 gh repo view 取 OWNER_REPO、默认分支和 SHA；用组织成员、仓库协作者（admin/maintain/push）、CODEOWNERS 登录名以及机器人账号构建内部集合。
列出目标 PR：gh pr list --state open --limit 200 --json ...（GraphQL 报错时用 REST），按参数顺序过滤；超过 100 个时处理最近更新的 100 个，其余列入“超出预算跳过”。
只读扇出：最多 100 个并行子代理，每个 PR 返回一个 JSON 对象，包含 number、security、rebasePlan、ci、assignForReview、priority、actionsPlanned 等字段。日常或已 clean 的外部 PR 走廉价路径（仅重取可合并性与检查）。
汇总 dry-run 报告并更新快照（即使 dry-run 也更新 head SHA 与合并状态），输出简短摘要。
Apply 模式：安全门通过后，在 worktree 子代理中执行 gh pr checkout → git fetch → git rebase → git push --force-with-lease，并校验前后 headRefOid 不同；组织 fork 的 403（maintainerCanModify false）记录为 push-403，不重试循环。对等待批准的工作流调用 gh api -X POST repos/$OWNER/$REPO/actions/runs/<RUN_ID>/approve，403/404 则提示需人工批准。

适用场景与限制

适合维护者在审阅前批量整理外部贡献者的开放 PR：更新落后分支、解决冲突、批准首次贡献者 CI 门禁。
不替代 triage-github（积压排序）或 pr-babysit（持续 CI/评论修复）。
依赖 gh 已认证并位于正确仓库；需要 .agent/pr-sweep/snapshot.json 才能启用 --changed/--daily 的增量能力。
PR 少于 20 个时在主线程处理即可，无需 100 个代理。
具体价格、收费与更多平台支持情况，原文暂未提供。

参考

安全启发式规则位于 references/security-checklist.md。