GitHub 代码审查

2026-05-20 · Skills中心

GitHub 代码审查

在推送前对本地更改进行代码审查，或审查 GitHub 上的 PR。本技能大部分使用纯 git——gh/curl 的区分仅影响 PR 级别的交互。

前置条件

已通过 GitHub 认证（见 github-auth 技能）
在 git 仓库内

安装配置（用于 PR 交互）


if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
  AUTH="gh"
else
  AUTH="git"
  if [ -z "$GITHUB_TOKEN" ]; then
    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d 'nr')
    elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
      GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:([^@]*)@.*|1|')
    fi
  fi
fi

REMOTE_URL=$(git remote get-url origin)
OWNER_REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github.com[:/]||; s|.git$||')
OWNER=$(echo "$OWNER_REPO" | cut -d/ -f1)
REPO=$(echo "$OWNER_REPO" | cut -d/ -f2)

1. 审查本地更改（推送前）

这是纯 git——任何地方都可用，无需 API。

获取 Diff


# 已暂存的更改（将被提交的内容）
git diff --staged

# 相对于 main 的所有更改（PR 会包含的内容）
git diff main...HEAD

# 仅文件名
git diff main...HEAD --name-only

# 统计摘要（每个文件的增删行数）
git diff main...HEAD --stat

审查策略

先看大局：


git diff main...HEAD --stat
git log main..HEAD --oneline

逐文件审查——对有更改的文件使用 read_file 获取完整上下文，结合 diff 查看具体更改：
```
git diff main...HEAD -- src/auth/login.py
```

检查常见问题：


# 遗留的调试语句、TODO、console.log
git diff main...HEAD | grep -n "print(|console.log|TODO|FIXME|HACK|XXX|debugger"

# 意外暂存的大文件
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10

# 密钥或凭证模式
git diff main...HEAD | grep -in "password|secret|api_key|token.*=|private_key"

# 合并冲突标记
git diff main...HEAD | grep -n "<<<<>>>>|=======""

向用户呈现结构化反馈。

审查输出格式

审查本地更改时，按以下结构呈现发现：

## 代码审查总结

### 严重问题
- **src/auth.py:45** — SQL 注入：用户输入直接传入查询。
  建议：使用参数化查询。

### 警告
- **src/models/user.py:23** — 密码明文存储。使用 bcrypt 或 argon2。
- **src/api/routes.py:112** — 登录端点无速率限制。

### 建议
- **src/utils/helpers.py:8** — 与 `src/core/utils.py:34` 逻辑重复。请合并。
- **tests/test_auth.py** — 缺少边界情况：过期令牌测试。

### 良好
- 中间件层关注点分离清晰
- 主流程测试覆盖良好

2. 审查 GitHub 上的 Pull Request

查看 PR 详情

用 gh：


gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only

用 git + curl：


PR_NUMBER=123

# 获取 PR 详情
curl -s 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER 
  | python3 -c "
import sys, json
pr = json.load(sys.stdin)
print(f"Title: {pr['title']}")
print(f"Author: {pr['user']['login']}")
print(f"Branch: {pr['head']['ref']} -> {pr['base']['ref']}")
print(f"State: {pr['state']}")
print(f"Body:n{pr['body']}")"

# 列出更改的文件
curl -s 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/files 
  | python3 -c "
import sys, json
for f in json.load(sys.stdin):
    print(f"{f['status']:10} +{f['additions']:-4} -{f['deletions']:-4}  {f['filename']}")"

本地检出 PR 进行完整审查

这用纯 git 即可——不需要 gh：


# 获取 PR 分支并检出
git fetch origin pull/123/head:pr-123
git checkout pr-123

# 现在可以使用 read_file、search_files、运行测试等

# 查看相对于基分支的 diff
git diff main...pr-123

用 gh（快捷方式）：


gh pr checkout 123

在 PR 上留评论

普通 PR 评论——用 gh：


gh pr comment 123 --body "总体不错，下面有几点建议。"

普通 PR 评论——用 curl：


curl -s -X POST 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments 
  -d '{"body": "总体不错，下面有几点建议。"}'

添加行内审查评论

单条行内评论——用 gh（通过 API）：


HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')

gh api repos/$OWNER/$REPO/pulls/123/comments 
  --method POST 
  -f body="这里可以用列表推导式简化。" 
  -f path="src/auth/login.py" 
  -f commit_id="$HEAD_SHA" 
  -f line=45 
  -f side="RIGHT"

单条行内评论——用 curl：


# 获取 head commit SHA
HEAD_SHA=$(curl -s 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER 
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments 
  -d "{
    "body": "这里可以用列表推导式简化。",
    "path": "src/auth/login.py",
    "commit_id": "$HEAD_SHA",
    "line": 45,
    "side": "RIGHT"
  }"

提交正式审查（批准 / 请求更改）

用 gh：


gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "见行内评论。"
gh pr review 123 --comment --body "一些建议，无阻塞问题。"

用 curl——原子性提交多条评论：


HEAD_SHA=$(curl -s 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER 
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

curl -s -X POST 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews 
  -d "{
    "commit_id": "$HEAD_SHA",
    "event": "COMMENT",
    "body": "来自 Hermes Agent 的代码审查",
    "comments": [
      {"path": "src/auth.py", "line": 45, "body": "使用参数化查询防止 SQL 注入。"},
      {"path": "src/models/user.py", "line": 23, "body": "存储密码前用 bcrypt 哈希。"},
      {"path": "tests/test_auth.py", "line": 1, "body": "添加过期令牌边界情况测试。"}
    ]
  }"

event 值："APPROVE"、"REQUEST_CHANGES"、"COMMENT"

line 字段指新版本文件中的行号。对于删除的行，使用 "side": "LEFT"。

3. 审查清单

进行代码审查时（本地或 PR），系统检查：

正确性

代码是否实现了它声称的功能？
边界情况是否处理（空输入、null、大数据、并发访问）？
错误路径是否优雅处理？

安全

无硬编码密钥、凭证或 API Key
面向用户的输入是否验证
无 SQL 注入、XSS 或路径遍历
需要处是否有认证/授权检查

代码质量

命名清晰（变量、函数、类）
无不必要的复杂性或过早抽象
DRY——应提取的重复逻辑
函数职责单一

测试

新代码路径是否测试？
主流程和错误情况是否覆盖？
测试是否可读可维护？

性能

无 N+1 查询或不必要的循环
有益处是否适当缓存
异步代码路径中无阻塞操作

文档

公共 API 是否文档化
非显而易见的逻辑有注释说明"为什么"
行为变更时 README 是否更新

4. 推送前审查工作流

当用户要求"审查代码"或"推送前检查"：

git diff main...HEAD --stat——查看更改范围
git diff main...HEAD——阅读完整 diff
对每个更改的文件，如需更多上下文使用 read_file
应用上述清单
按结构化格式呈现发现（严重 / 警告 / 建议 / 良好）
如发现严重问题，在用户推送前提供修复

5. PR 审查工作流（端到端）

当用户要求"审查 PR #N"、"看下这个 PR"或给你 PR URL，按此流程：

步骤 1：设置环境


source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
# 或运行本 skill 顶部的内联设置代码块

步骤 2：收集 PR 上下文

获取 PR 元数据、描述和更改文件列表，以便在深入代码前了解范围。

用 gh：


gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123

用 curl：


PR_NUMBER=123

# PR 详情（标题、作者、描述、分支）
curl -s -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER

# 带行数统计的更改文件
curl -s -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/files

步骤 3：本地检出 PR

这让你可以完整使用 read_file、search_files 并运行测试。


git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER

步骤 4：阅读 diff 并理解更改


# 相对于基分支的完整 diff
git diff main...HEAD

# 或大型 PR 逐文件查看
git diff main...HEAD --name-only
# 然后对每个文件：
git diff main...HEAD -- path/to/file.py

对每个更改的文件，使用 read_file 查看更改周围的完整上下文——单看 diff 可能遗漏需要周围代码才能发现的问题。

步骤 5：本地运行自动化检查（如适用）


# 如有测试套件则运行测试
python -m pytest 2>&1 | tail -20
# 或：npm test, cargo test, go test ./..., 等。

# 如配置了则运行 linter
ruff check . 2>&1 | head -30
# 或：eslint, clippy, 等。

步骤 6：应用审查清单（第 3 节）

逐类检查：正确性、安全、代码质量、测试、性能、文档。

步骤 7：将审查发布到 GitHub

收集发现并作为带行内评论的正式审查提交。

用 gh：


# 如无问题——批准
gh pr review $PR_NUMBER --approve --body "Hermes Agent 审查完成。代码整洁——测试覆盖良好，无安全问题。"

# 如发现问题——请求更改并附带行内评论
gh pr review $PR_NUMBER --request-changes --body "发现几个问题——见行内评论。"

用 curl——带多条行内评论的原子性审查：


HEAD_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER 
  | python3 -c "import sys,json; print(json.load(sys.stdin)['head']['sha'])")

# 构建审查 JSON——event 为 APPROVE, REQUEST_CHANGES, 或 COMMENT
curl -s -X POST 
  -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/repos/$GH_OWNER/$GH_REPO/pulls/$PR_NUMBER/reviews 
  -d "{
    "commit_id": "$HEAD_SHA",
    "event": "REQUEST_CHANGES",
    "body": "## Hermes Agent 审查nn发现 2 个问题，1 条建议。见行内评论。",
    "comments": [
      {"path": "src/auth.py", "line": 45, "body": "🔴 **严重：** 用户输入直接传入 SQL 查询——使用参数化查询。"},
      {"path": "src/models.py", "line": 23, "body": "⚠️ **警告：** 密码未哈希存储。"},
      {"path": "src/utils.py", "line": 8, "body": "💡 **建议：** 这与 core/utils.py:34 的逻辑重复。"}
    ]
  }"

步骤 8：同时发布总结评论

除行内评论外，留一条顶级总结让 PR 作者一目了然。使用 references/review-output-template.md 中的审查输出格式。

用 gh：


gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
## 代码审查总结

**结论：请求更改**（2 个问题，1 条建议）

### 🔴 严重
- **src/auth.py:45** — SQL 注入漏洞

### ⚠️ 警告
- **src/models.py:23** — 密码明文存储

### 💡 建议
- **src/utils.py:8** — 逻辑重复，建议合并

### ✅ 良好
- API 设计清晰
- 中间件层错误处理良好

---
*Hermes Agent 审查*
EOF
)"

步骤 9：清理


git checkout main
git branch -D pr-$PR_NUMBER

决策：批准 vs 请求更改 vs 评论

批准——无严重或警告级问题，仅有小建议或全部良好
请求更改——有任何严重或警告级问题应在合并前修复
评论——观察和建议，但无阻塞（不确定或 PR 是草稿时使用）

← 作为房地产经纪人 YouTube … →

GitHub 代码审查

GitHub 代码审查

前置条件

安装配置（用于 PR 交互）

1. 审查本地更改（推送前）

获取 Diff

审查策略

审查输出格式

2. 审查 GitHub 上的 Pull Request

查看 PR 详情

本地检出 PR 进行完整审查

在 PR 上留评论

添加行内审查评论

提交正式审查（批准 / 请求更改）

3. 审查清单

正确性

安全

代码质量

测试

性能

文档

4. 推送前审查工作流

5. PR 审查工作流（端到端）

步骤 1：设置环境

步骤 2：收集 PR 上下文

步骤 3：本地检出 PR

步骤 4：阅读 diff 并理解更改

步骤 5：本地运行自动化检查（如适用）

步骤 6：应用审查清单（第 3 节）

步骤 7：将审查发布到 GitHub

步骤 8：同时发布总结评论

步骤 9：清理

决策：批准 vs 请求更改 vs 评论

评论区

发表评论取消回复

欢迎回来

创建账号

GitHub 代码审查

GitHub 代码审查

前置条件

安装配置（用于 PR 交互）

1. 审查本地更改（推送前）

获取 Diff

审查策略

审查输出格式

2. 审查 GitHub 上的 Pull Request

查看 PR 详情

本地检出 PR 进行完整审查

在 PR 上留评论

添加行内审查评论

提交正式审查（批准 / 请求更改）

3. 审查清单

正确性

安全

代码质量

测试

性能

文档

4. 推送前审查工作流

5. PR 审查工作流（端到端）

步骤 1：设置环境

步骤 2：收集 PR 上下文

步骤 3：本地检出 PR

步骤 4：阅读 diff 并理解更改

步骤 5：本地运行自动化检查（如适用）

步骤 6：应用审查清单（第 3 节）

步骤 7：将审查发布到 GitHub

步骤 8：同时发布总结评论

步骤 9：清理

决策：批准 vs 请求更改 vs 评论

评论区

发表评论 取消回复

发表评论取消回复