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 是草稿时使用）

安装指南

复制下方命令，在终端运行即可安装：

# 安装到当前项目

npx skills add github-code-review

# 全局安装 — 所有项目可用

npx skills add github-code-review -g

使用指南

安装完成后，在对话框中直接使用此技能。

基本信息

作者 Community 分类 coding 难度 Intermediate 时长 1 hour

🛠️ 安装命令

# 安装到当前项目

npx skills add github-code-review

# 全局安装

npx skills add github-code-review -g

欢迎回来

创建账号

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 评论

安装指南

使用指南

发表评论 取消回复

发表评论取消回复