github-pr-review-workflow

GitHub PR 审查工作流

使用 agynio/gh-pr-review 提供的 gh-pr-review 扩展，完成对 GitHub 拉取请求的审查、处理反馈和解决评论线程的整个工作流。

gh-pr-review 文档请参阅： https://github.com/agynio/gh-pr-review

---

安装

安装 gh-pr-review 扩展（如果尚未安装）：

gh extension install agynio/gh-pr-review

验证安装：

gh pr-review --help

---

工作流概览

PR Review Request
  ├─ Get PR number/repo context
  ├─ List all review threads
  ├─ Analyze feedback and comments
  ├─ Validate whether each comment applies and explain decisions
  ├─ Implement fixes in code
  ├─ Run tests (unit + lint + typecheck)
  ├─ Reply to all open review threads with explanations
  ├─ Wait up to 5 minutes for follow-up
  ├─ Resolve review threads (or address follow-ups)
  └─ Commit and push changes

---

分步流程

1. 获取 PR 上下文

获取当前 PR 详情：

# Get PR number
gh pr view --json number

# Get PR title and status
gh pr view --json title,author,state,reviews

# Get repository info (for gh pr-review)
git remote get-url origin

输出： PR 编号（例如 <PR_NUMBER>）和仓库（例如 <OWNER/REPO>）

---

2. 列出审查线程

列出所有审查线程（未解决和已过时）：

# From PR root directory
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>

# Example:
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>

响应格式：

[
  {
    "threadId": "<THREAD_ID>",
    "isResolved": false,
    "updatedAt": "2026-01-17T22:48:36Z",
    "path": "path/to/file.ts",
    "line": 42,
    "isOutdated": false
  }
]

关键字段：

• threadId：用于解决或回复的 GraphQL 节点 ID
• isResolved：当前状态
• isOutdated：评论发布后代码是否发生了变化
• path + line：文件位置

如果所有审查线程都已解决，或没有审查线程，请搜索普通评论并进行分析：

gh pr view <PR_NUMBER> --comments --json author,comments,reviews

---

3. 阅读并分析反馈

通过 GitHub API 获取审查评论：

# Get all review comments for PR
gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments

# With jq for cleaner output
gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
  --jq '.[] | {id,body,author,created_at,line,path}'

阅读评论中提到的具体文件：

# Read the file context to understand feedback
cat <path>
# or use Read tool

对反馈分类：

• 高优先级：安全问题、错误、破坏性变更
• 中优先级：代码质量、可维护性、测试覆盖率
• 低优先级：代码风格、文档、锦上添花的改进

修改代码前验证建议是否适用（必需）：

• 确认每条评论都准确且与当前代码相关。
• 如果建议不正确、已过时，或不适用于当前代码库，请详细回复说明未采纳的原因。
• 不要仅仅因为修改耗时就跳过；要么实施修改，要么清楚说明不应进行修改的原因。

---

4. 实施修复

编辑审查中提到的文件：

# Use Edit tool or bash
edit <file_path> <oldString> <newString>

遵循仓库规范：

• 检查类似文件中的现有模式
• 遵循 AGENTS.md 指南
• 保持代码风格一致
• 为新增逻辑添加或更新测试

---

5. 验证更改（至关重要）

回复前务必运行测试：

# Run project tests
bun run test

# Or specific test suites
bun run test:unit
bun run test:unit:watch
bun run test:e2e

运行类型检查：

bun run typecheck
# or
tsc --noEmit

运行代码检查：

bun run lint
# or
eslint

确认全部通过：

• ✓ 没有 TypeScript 错误
• ✓ 没有 ESLint 警告或错误
• ✓ 所有单元测试均通过
• ✓ E2E 测试通过（如适用）

---

6. 提交并推送更改

暂存并提交更改：

# Check status
git status

# Stage modified files
git add <files>

# Commit with clear message
git commit -m "<type>(<scope>): <description>

# Example:
git commit -m "refactor(emails): centralize from name logic and improve sanitization

- Extract RESEND_FROM_NAME constant to lib/emails/from-address.ts
- Replace duplicated logic in lib/auth.ts and app/actions/contact.ts
- Improve formatFromAddress sanitization (RFC 5322 chars)
- Add test cases for additional sanitization patterns"

推送到远程仓库：

git push

检查工作区：

git status
# Should show: "nothing to commit, working tree clean"

---

7. 回复审查线程

回复并说明修复内容：

gh pr-review comments reply \
  --pr <PR_NUMBER> \
  --repo <OWNER/REPO> \
  --thread-id <THREAD_ID> \
  --body "<your explanation>"

回复最佳实践：

• 感谢对方的反馈
• 说明所做的更改
• 在适用时注明具体提交
• 简洁明了
• 使用代码围栏展示代码片段

回复示例：

gh pr-review comments reply \
  --pr <PR_NUMBER> \
  --repo <OWNER/REPO> \
  --thread-id <THREAD_ID> \
  --body "$(cat <<'EOF'
@reviewer Thanks for the feedback! I've addressed your suggestions:

1. Applied the requested refactor in the relevant module
2. Removed duplicated logic in the affected call sites
3. Improved sanitization to match the project’s expectations
4. Added/updated tests for the new behavior

Changes committed in abc1234, all tests pass.
EOF
)"

注意： 多行内容请使用 heredoc，以避免 Shell 转义问题。 注意： 推送更改后，回复始终以 @reviewer 开头（例如 @gemini-code-assist ... 或 @greptile …）。审查者可能不止一位，因此务必确认具体评论来自哪位审查者。

如果这是普通评论而非审查评论（参见第 2 步），可以使用以下方式回复：

gh pr comment <PR_NUMBER> --body "$(cat <<'EOF'
@reviewer … <same as above>
EOF
)"

如果合适，也可以只对评论作出回应。

先回复所有未解决的线程：

1. 回复每条未解决的评论，说明你做了什么或未处理的原因。
2. 发布所有回复后，再进入等待或解决阶段。

---

8. 等待后续反馈并解决讨论串

修复问题、推送提交并回复所有未解决的评论后，最多等待 5 分钟以接收后续反馈：

# Wait for a minute for reviewer response
sleep 60

# Re-check for new replies or new threads
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>

最多执行此步骤 5 次，等待时间最长为 5 分钟。

如果收到后续反馈提示，请处理该反馈（步骤 3-7），然后解决讨论串。

如果收到确认，请解决讨论串：

gh pr-review threads resolve \
  --pr <PR_NUMBER> \
  --repo <OWNER/REPO> \
  --thread-id <THREAD_ID>

回复：

{
  "thread_node_id": "PRRT_kwDOQkQlKs5p24lu",
  "is_resolved": true
}

批量解决多个讨论串：

# Resolve outdated threads first
gh pr-review threads resolve --pr <PR_NUMBER> --repo <OWNER/REPO> --thread-id <THREAD_ID_OUTDATED_1>
gh pr-review threads resolve --pr <PR_NUMBER> --repo <OWNER/REPO> --thread-id <THREAD_ID_OUTDATED_2>

# Then resolve active threads after replying
gh pr-review threads resolve --pr <PR_NUMBER> --repo <OWNER/REPO> --thread-id <THREAD_ID_ACTIVE>

策略：

1. 解决过时的讨论串（isOutdated: true）——无需回复
2. 回复有效讨论串，说明已修复（或未作更改）
3. 最多等待 5 分钟以接收回复
4. 收到确认或无人回复后，解决有效讨论串

---

9. 确认所有讨论串均已解决

最终检查：

gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>

预期输出： 所有讨论串均显示 isResolved: true

---

完整工作流示例

# 1. Get PR context
gh pr view --json number
git remote get-url origin

# 2. List review threads
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>

# 3. Read comments and files
gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments --jq '.[] | {id,body,path,line}'
cat path/to/file.ts

# 4. Implement fixes
edit path/to/file.ts <oldString> <newString>

# 5. Run tests
bun run test:unit -- tests/path/to/file.test.ts
bun run typecheck
bun run lint

# 6. Commit and push
git add lib/emails/from-address.ts
git commit -m "fix: address PR review feedback"
git push

# 7. Reply to threads
gh pr-review comments reply --pr <PR_NUMBER> --repo <OWNER/REPO> \
  --thread-id <THREAD_ID> --body "$(cat <<'EOF'
@reviewer Thanks for review! I've addressed all feedback:
1. Centralized logic
2. Improved sanitization
3. Added tests

Changes in abc1234.
EOF
)"

# 8. Wait then resolve threads
sleep 300
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>
gh pr-review threads resolve --pr <PR_NUMBER> --repo <OWNER/REPO> \
  --thread-id <THREAD_ID>

# 9. Verify
gh pr-review threads list --pr <PR_NUMBER> --repo <OWNER/REPO>
git status

---

gh-pr-review 命令参考

命令	用途
gh pr-review threads list	列出所有审查讨论串
gh pr-review threads resolve	解决指定讨论串
gh pr-review threads unresolve	重新打开已解决的讨论串
gh pr-review comments reply	回复审查讨论串
gh pr-review review	管理待处理的审查

常用标志：

• --pr <number>：Pull Request 编号
• -R, --repo <owner/repo>：代码库标识符
• --thread-id <id>：GraphQL 讨论串节点 ID

---

故障排查

问题	解决方案
command not found: gh-pr-review	安装扩展：gh extension install agynio/gh-pr-review
must specify a pull request via --pr	在 PR 目录中运行，或添加 --pr <number>
--repo must be owner/repo when using numeric selectors	添加 -R <owner/repo>，或在已验证身份的代码库中运行
使用 --body 时遇到 Shell 转义问题	使用 heredoc：--body "$(cat <<'EOF'\n...\nEOF)"
找不到讨论串	确认 threadId 是准确的 GraphQL ID，而非 PR 编号

---

最佳实践

回复前：

• ✓ 仔细阅读所有审查评论
• ✓ 理解其意图（建议还是阻塞性问题）
• ✓ 检查其他位置是否存在类似问题

实施修复时：

• ✓ 遵循现有代码模式
• ✓ 针对更改更新或添加测试
• ✓ 运行完整测试套件
• ✓ 检查 lint 和类型错误

回复时：

• ✓ 保持礼貌并表达感谢
• ✓ 说明更改内容
• ✓ 指明具体文件和行号
• ✓ 保持简洁

解决前：

• ✓ 确保所有问题均已处理
• ✓ 确认测试通过
• ✓ 将更改提交到分支

---

资源

• gh-pr-review GitHub
• GitHub GraphQL API：Pull Request
• gh CLI 文档