manage-prs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage PRs

管理PR

Use

gh

for all operations. Stop and ask the user on: 401, 403, 422, or network timeout. Default merge:

--squash --delete-branch

. Check

AGENTS.md

if it exists — it overrides merge defaults.

所有操作均使用

gh

工具。遇到401、403、422错误或网络超时，请停止操作并询问用户。默认合并策略：

--squash --delete-branch

。若存在

AGENTS.md

文件，其内容将覆盖默认合并策略。

DO NOT

禁止操作

Explore the repo (
```
ls
```
,
```
tree
```
,
```
git branch
```
, check directories) — irrelevant to PR management
Do exploratory research before triaging — go straight to gathering PRs
Ask the user to confirm or choose a merge strategy — write the plan, then execute it
Mark a PR "diff verified" without running
```
gh pr diff <n>
```
— read every diff before classifying
Re-fetch individual PR metadata via
```
gh pr view
```
when
```
prs.json
```
already has the data
Merge when mergeable is
```
UNKNOWN
```
— re-query until it resolves (see gotchas below)

探索仓库（执行
```
ls
```
、
```
tree
```
、
```
git branch
```
命令，查看目录）——这与PR管理无关
在分类前进行探索性研究——直接获取PR信息即可
要求用户确认或选择合并策略——制定计划后直接执行
未运行
```
gh pr diff <n>
```
就标记PR“差异已验证”——分类前需查看每一处差异
当
```
prs.json
```
已包含数据时，通过
```
gh pr view
```
重新获取单个PR元数据
当mergeable状态为
```
UNKNOWN
```
时进行合并——重新查询直到状态明确（详见下方常见陷阱）

Gotchas

常见陷阱

UNKNOWN
mergeability is a hard block. GitHub computes this async. Re-query up to 3×:

gh pr view <n> --json mergeable

— wait a few seconds between. Never merge

UNKNOWN

--json comments
crashes
gh pr view
. Use

--json body,comments

— not the

--comments

flag.

gh pr update-branch
does not exist. Use the API instead:

gh api repos/{owner}/{repo}/pulls/{n}/update-branch -f merge_method=squash

gh pr list
silently caps at 100. Always use

--limit 100

. Warn user if count hits 100.

Always comment when closing.

gh pr close <n> --comment "Closing because..."

— never silently.

gh pr create
body must use
--body-file
. Write body to a tmpfile, pass

--body-file

. Never inline

--body

"Base branch was modified" on merge. Each merge changes the base branch, so the next merge may fail. Merge PRs one at a time. On this error, simply retry the same merge command.

UNKNOWN
合并状态是硬性阻塞。 GitHub会异步计算该状态。最多重新查询3次：

gh pr view <n> --json mergeable

——每次查询间隔几秒。绝对不要合并状态为

UNKNOWN

的PR。

--json comments
会导致
gh pr view
崩溃。使用

--json body,comments

——不要使用

--comments

参数。

gh pr update-branch
命令不存在。请改用API：

gh api repos/{owner}/{repo}/pulls/{n}/update-branch -f merge_method=squash

gh pr list
默认最多返回100条结果。务必添加

--limit 100

参数。如果结果数量达到100，需提醒用户。

关闭PR时必须添加评论。

gh pr close <n> --comment "Closing because..."

——绝对不要静默关闭。

gh pr create
命令的正文必须使用
--body-file
参数。将正文写入临时文件，再传入

--body-file

参数。绝对不要直接使用

--body

参数内嵌正文。

合并时出现“Base branch was modified”错误。 每次合并都会修改基准分支，因此下一次合并可能失败。请逐个合并PR。遇到此错误时，只需重试相同的合并命令即可。

Single-PR Workflow

单个PR处理流程

Use when the user names a specific PR (e.g. "merge PR #42", "close PR #7").

Health check:

gh pr view <n> --json number,title,author,isDraft,mergeable,reviewDecision,statusCheckRollup,body

— Verify mergeable is

MERGEABLE

. If

UNKNOWN

, re-query up to 3×.

Read diff:
```
gh pr diff <n>
```
— verify logic, imports, API usage. For bot/AI PRs, grep unfamiliar identifiers.
Act: merge (
```
gh pr merge <n> --squash --delete-branch
```
), close with comment, or hand off to
```
review-pr
```
.

当用户指定具体PR时使用（例如“合并PR #42”“关闭PR #7”）。

健康检查：执行

gh pr view <n> --json number,title,author,isDraft,mergeable,reviewDecision,statusCheckRollup,body

——验证mergeable状态为

MERGEABLE

。若为

UNKNOWN

，最多重新查询3次。

查看差异：执行
```
gh pr diff <n>
```
——验证逻辑、导入项、API使用是否正确。对于机器人/AI生成的PR，需搜索陌生标识符。
执行操作：合并（
```
gh pr merge <n> --squash --delete-branch
```
）、添加评论后关闭，或移交至
```
review-pr
```
处理。

Batch Triage Workflow

批量PR分类流程

Use when managing multiple PRs (e.g. "triage PRs", "clean up PR queue").

当管理多个PR时使用（例如“分类PR”“清理PR队列”）。

Step 1: Gather and detect overlaps

步骤1：收集PR并检测文件重叠

bash

gh pr list --json number,title,author,isDraft,mergeable,reviewDecision,statusCheckRollup,baseRefName,files \
  --limit 100 | tee prs.json | python3 -c "
import json, sys, collections
data = json.load(sys.stdin)
by_file = collections.defaultdict(list)
for pr in data:
    for f in pr.get('files', []):
        if isinstance(f, dict) and 'path' in f:
            by_file[f['path']].append(pr['number'])
overlaps = [(p, ns) for p, ns in by_file.items() if len(ns) > 1]
if overlaps:
    print('OVERLAPPING FILES:')
    for p, ns in sorted(overlaps, key=lambda x: -len(x[1])):
        print(f'  {p}: PRs {ns}')
else:
    print('No file overlaps detected.')
"

This saves

prs.json

AND pipes to overlap detection in one shot. Overlapping PRs need sequenced merging — merge the simpler one first, re-check conflicts on the other. Also read

AGENTS.md

for merge overrides if it exists.

bash

gh pr list --json number,title,author,isDraft,mergeable,reviewDecision,statusCheckRollup,baseRefName,files \
  --limit 100 | tee prs.json | python3 -c "
import json, sys, collections
data = json.load(sys.stdin)
by_file = collections.defaultdict(list)
for pr in data:
    for f in pr.get('files', []):
        if isinstance(f, dict) and 'path' in f:
            by_file[f['path']].append(pr['number'])
overlaps = [(p, ns) for p, ns in by_file.items() if len(ns) > 1]
if overlaps:
    print('OVERLAPPING FILES:')
    for p, ns in sorted(overlaps, key=lambda x: -len(x[1])):
        print(f'  {p}: PRs {ns}')
else:
    print('No file overlaps detected.')
"

此命令会保存

prs.json

文件，同时完成文件重叠检测。存在重叠的PR需要按顺序合并——先合并较简单的PR，再重新检查另一个PR的冲突。若存在

AGENTS.md

文件，需查看其中的合并覆盖规则。

Step 2: Read every diff

步骤2：查看每一处差异

For each PR, run

gh pr diff <n>

and verify logic, imports, no obvious breakage. For bot/AI PRs, grep unfamiliar identifiers in the codebase. Do NOT skip this step — a PR cannot be classified as merge-ready without a diff read.

对每个PR执行

gh pr diff <n>

，验证逻辑、导入项是否正确，无明显问题。对于机器人/AI生成的PR，需在代码库中搜索陌生标识符。绝对不要跳过此步骤——未查看差异的PR不能被归类为可合并状态。

Step 3: Triage report

步骤3：分类报告

Use data from

prs.json

(mergeability, CI, review) plus your diff reads to classify each PR. Write results to a plan file:

✅ Merge-ready —
```
MERGEABLE
```
, CI green, diff read and verified
⚠️ Needs action — blocked by conflict / CI / review
🔁 Stale — no activity >14 days
🔀 Overlapping — file conflict risk with merge order specified
❌ Close candidates — superseded, duplicate, or abandoned

After writing the plan, proceed to merge — do not stop and ask for confirmation.

结合

prs.json

中的数据（合并状态、CI状态、审核结果）以及差异查看结果，对每个PR进行分类。将结果写入计划文件：

✅ 可合并 ——
```
MERGEABLE
```
状态、CI通过、已查看并验证差异
⚠️ 需处理 ——存在冲突/CI失败/待审核
🔁 陈旧 ——超过14天无活动
🔀 重叠 ——存在文件冲突风险，需指定合并顺序
❌ 建议关闭 ——已被替代、重复或已废弃

编写完计划后直接执行合并操作——无需停止并请求确认。

Cross-Skill Routing

跨技能路由

Situation	Hand off to
PR needs structured code review before merge	`review-pr`
PR has unresolved review threads to address	`resolve-pr-feedback`

场景	移交至
PR合并前需要结构化代码审核	`review-pr`
PR存在未解决的审核反馈	`resolve-pr-feedback`