GitHub Code Review
GitHub 代码审查
Perform code reviews on local changes before pushing, or review open PRs on GitHub. Most of this skill uses plain
— the
/
split only matters for PR-level interactions.
在推送前对本地变更进行代码审查,或在GitHub上审查已开启的PR。本技能大部分功能基于原生
——仅在PR级别的交互中,
/
的选择才会产生影响。
- Authenticated with GitHub (see skill)
- Inside a git repository
- 已通过GitHub认证(查看技能)
- 处于git仓库目录内
Setup (for PR interactions)
配置(用于PR交互)
bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; 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 '\n\r')
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)
bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; 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 '\n\r')
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. Reviewing Local Changes (Pre-Push)
1. 审查本地变更(推送前)
This is pure
— works everywhere, no API needed.
这完全基于
——可在任何环境下使用,无需调用API。
Staged changes (what would be committed)
已暂存的变更(即将提交的内容)
All changes vs main (what a PR would contain)
与main分支相比的所有变更(即PR包含的内容)
git diff main...HEAD --name-only
git diff main...HEAD --name-only
Stat summary (insertions/deletions per file)
统计摘要(每个文件的新增/删除行数)
git diff main...HEAD --stat
git diff main...HEAD --stat
- Get the big picture first:
bash
git diff main...HEAD --stat
git log main..HEAD --oneline
- Review file by file — use on changed files for full context, and the diff to see what changed:
bash
git diff main...HEAD -- src/auth/login.py
- Check for common issues:
- 先把握整体情况:
bash
git diff main...HEAD --stat
git log main..HEAD --oneline
- 逐文件审查——对变更文件使用查看完整上下文,通过差异内容了解具体修改:
bash
git diff main...HEAD -- src/auth/login.py
- 检查常见问题:
Debug statements, TODOs, console.logs left behind
遗留的调试语句、TODO、console.log
git diff main...HEAD | grep -n "print(|console.log|TODO|FIXME|HACK|XXX|debugger"
git diff main...HEAD | grep -n "print(|console.log|TODO|FIXME|HACK|XXX|debugger"
Large files accidentally staged
意外暂存的大文件
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10
git diff main...HEAD --stat | sort -t'|' -k2 -rn | head -10
Secrets or credential patterns
密钥或凭证相关模式
git diff main...HEAD | grep -in "password|secret|api_key|token.*=|private_key"
git diff main...HEAD | grep -in "password|secret|api_key|token.*=|private_key"
Merge conflict markers
合并冲突标记
git diff main...HEAD | grep -n "<<<<<<|>>>>>>|======="
4. **Present structured feedback** to the user.
git diff main...HEAD | grep -n "<<<<<<|>>>>>>|======="
Review Output Format
审查输出格式
When reviewing local changes, present findings in this structure:
Code Review Summary
代码审查总结
- src/auth.py:45 — SQL injection: user input passed directly to query.
Suggestion: Use parameterized queries.
- src/auth.py:45 — SQL注入:用户输入直接传入查询语句。
建议:使用参数化查询。
- src/models/user.py:23 — Password stored in plaintext. Use bcrypt or argon2.
- src/api/routes.py:112 — No rate limiting on login endpoint.
- src/models/user.py:23 — 密码以明文存储。请使用bcrypt或argon2加密。
- src/api/routes.py:112 — 登录接口未做限流处理。
- src/utils/helpers.py:8 — Duplicates logic in . Consolidate.
- tests/test_auth.py — Missing edge case: expired token test.
- src/utils/helpers.py:8 — 与逻辑重复,建议合并。
- tests/test_auth.py — 缺失边缘用例:过期令牌测试。
- Clean separation of concerns in the middleware layer
- Good test coverage for the happy path
2. Reviewing a Pull Request on GitHub
2. 在GitHub上审查Pull Request
With gh:
bash
gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only
With git + curl:
使用gh工具:
bash
gh pr view 123
gh pr diff 123
gh pr diff 123 --name-only
使用git + curl:
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
| python3 -c "
import sys, json
pr = json.load(sys.stdin)
print(f"标题: {pr['title']}")
print(f"作者: {pr['user']['login']}")
print(f"分支: {pr['head']['ref']} -> {pr['base']['ref']}")
print(f"状态: {pr['state']}")
print(f"描述:\n{pr['body']}")"
Check Out PR Locally for Full Review
拉取PR到本地进行全面审查
This works with plain
— no
needed:
Fetch the PR branch and check it out
拉取PR分支并切换到该分支
git fetch origin pull/123/head:pr-123
git checkout pr-123
git fetch origin pull/123/head:pr-123
git checkout pr-123
Now you can use read_file, search_files, run tests, etc.
现在你可以使用read_file、search_files、运行测试等操作
View diff against the base branch
查看与基准分支的差异
git diff main...pr-123
**With gh (shortcut):**
```bash
gh pr checkout 123
git diff main...pr-123
**使用gh工具(快捷方式):**
```bash
gh pr checkout 123
Leave Comments on a PR
在PR上添加评论
General PR comment — with gh:
bash
gh pr comment 123 --body "Overall looks good, a few suggestions below."
General PR comment — with curl:
bash
curl -s -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
-d '{"body": "Overall looks good, a few suggestions below."}'
PR全局评论——使用gh工具:
bash
gh pr comment 123 --body "整体看起来不错,以下是一些建议。"
PR全局评论——使用curl:
bash
curl -s -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
https://api.github.com/repos/$OWNER/$REPO/issues/$PR_NUMBER/comments \
-d '{"body": "整体看起来不错,以下是一些建议。"}'
Leave Inline Review Comments
添加行内审查评论
Single inline comment — with gh (via API):
bash
HEAD_SHA=$(gh pr view 123 --json headRefOid --jq '.headRefOid')
gh api repos/$OWNER/$REPO/pulls/123/comments \
--method POST \
-f body="This could be simplified with a list comprehension." \
-f path="src/auth/login.py" \
-f commit_id="$HEAD_SHA" \
-f line=45 \
-f side="RIGHT"
Single inline comment — with curl:
单行内评论——使用gh工具(通过API):
bash
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:
Get the head commit SHA
获取头部提交SHA
Submit a Formal Review (Approve / Request Changes)
提交正式审查意见(批准/请求修改)
With gh:
bash
gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "See inline comments."
gh pr review 123 --comment --body "Some suggestions, nothing blocking."
With curl — multi-comment review submitted atomically:
bash
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\": \"Code review from Hermes Agent\",
\"comments\": [
{\"path\": \"src/auth.py\", \"line\": 45, \"body\": \"Use parameterized queries to prevent SQL injection.\"},
{\"path\": \"src/models/user.py\", \"line\": 23, \"body\": \"Hash passwords with bcrypt before storing.\"},
{\"path\": \"tests/test_auth.py\", \"line\": 1, \"body\": \"Add test for expired token edge case.\"}
]
}"
The
field refers to the line number in the
new version of the file. For deleted lines, use
.
使用gh工具:
bash
gh pr review 123 --approve --body "LGTM!"
gh pr review 123 --request-changes --body "查看行内评论。"
gh pr review 123 --comment --body "一些建议,无阻塞问题。"
使用curl——批量提交多条评论的审查意见:
bash
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\": \"添加过期令牌边缘用例测试。\"}
]
}"
字段指的是文件
新版本中的行号。对于已删除的行,使用
。
3. Review Checklist
3. 审查检查清单
When performing a code review (local or PR), systematically check:
进行代码审查(本地或PR)时,需系统检查以下内容:
- Does the code do what it claims?
- Edge cases handled (empty inputs, nulls, large data, concurrent access)?
- Error paths handled gracefully?
- 代码是否实现了预期功能?
- 是否处理了边缘情况(空输入、空值、大数据量、并发访问)?
- 错误路径是否处理得当?
- No hardcoded secrets, credentials, or API keys
- Input validation on user-facing inputs
- No SQL injection, XSS, or path traversal
- Auth/authz checks where needed
- 无硬编码密钥、凭证或API密钥
- 面向用户的输入已做验证
- 无SQL注入、XSS或路径遍历漏洞
- 必要位置已做权限校验
- Clear naming (variables, functions, classes)
- No unnecessary complexity or premature abstraction
- DRY — no duplicated logic that should be extracted
- Functions are focused (single responsibility)
- 命名清晰(变量、函数、类)
- 无不必要的复杂度或过早抽象
- 遵循DRY原则——无应提取的重复逻辑
- 函数职责单一
- New code paths tested?
- Happy path and error cases covered?
- Tests readable and maintainable?
- 新代码路径是否已测试?
- 是否覆盖了正常流程和错误场景?
- 测试用例是否易读且可维护?
- No N+1 queries or unnecessary loops
- Appropriate caching where beneficial
- No blocking operations in async code paths
- 无N+1查询或不必要的循环
- 必要位置已做合理缓存
- 异步代码路径中无阻塞操作
- Public APIs documented
- Non-obvious logic has comments explaining "why"
- README updated if behavior changed
- 公共API已做文档说明
- 非直观逻辑有注释解释设计意图
- 若行为变更,README已更新
4. Pre-Push Review Workflow
4. 推送前审查流程
When the user asks you to "review the code" or "check before pushing":
git diff main...HEAD --stat
— see scope of changes
- — read the full diff
- For each changed file, use if you need more context
- Apply the checklist above
- Present findings in the structured format (Critical / Warnings / Suggestions / Looks Good)
- If critical issues found, offer to fix them before the user pushes
当用户要求你“审查代码”或“推送前检查”时:
git diff main...HEAD --stat
— 查看变更范围
- — 阅读完整差异内容
- 对每个变更文件,若需更多上下文则使用
- 应用上述检查清单
- 按结构化格式呈现结果(严重问题/警告/建议/良好项)
- 若发现严重问题,主动提出在用户推送前协助修复
5. PR Review Workflow (End-to-End)
5. PR全流程审查步骤
When the user asks you to "review PR #N", "look at this PR", or gives you a PR URL, follow this recipe:
当用户要求你“审查PR #N”、“查看这个PR”或提供PR链接时,遵循以下步骤:
Step 1: Set up environment
步骤1:配置环境
bash
source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
bash
source "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/gh-env.sh"
Or run the inline setup block from the top of this skill
或运行本技能顶部的内联配置代码块
Step 2: Gather PR context
步骤2:收集PR上下文
Get the PR metadata, description, and list of changed files to understand scope before diving into code.
With gh:
bash
gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123
With curl:
获取PR元数据、描述和变更文件列表,在深入代码前先了解整体范围。
使用gh工具:
bash
gh pr view 123
gh pr diff 123 --name-only
gh pr checks 123
使用curl:
PR details (title, author, description, branch)
PR详情(标题、作者、描述、分支)
Changed files with line counts
带行数统计的变更文件
Step 3: Check out the PR locally
步骤3:拉取PR到本地
This gives you full access to
,
, and the ability to run tests.
bash
git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER
bash
git fetch origin pull/$PR_NUMBER/head:pr-$PR_NUMBER
git checkout pr-$PR_NUMBER
Step 4: Read the diff and understand changes
步骤4:阅读差异内容并理解变更
Full diff against the base branch
与基准分支的完整差异
Or file-by-file for large PRs
若PR较大,可逐文件查看
git diff main...HEAD --name-only
git diff main...HEAD --name-only
Then for each file:
然后对每个文件执行:
git diff main...HEAD -- path/to/file.py
For each changed file, use `read_file` to see full context around the changes — diffs alone can miss issues visible only with surrounding code.
git diff main...HEAD -- path/to/file.py
对每个变更文件,使用`read_file`查看变更周围的完整上下文——仅看差异内容可能会遗漏只有结合周边代码才会发现的问题。
Step 5: Run automated checks locally (if applicable)
步骤5:本地运行自动化检查(若适用)
Run tests if there's a test suite
若有测试套件则运行测试
python -m pytest 2>&1 | tail -20
python -m pytest 2>&1 | tail -20
or: npm test, cargo test, go test ./..., etc.
或:npm test, cargo test, go test ./..., 等
Run linter if configured
若配置了代码检查工具则运行
ruff check . 2>&1 | head -30
ruff check . 2>&1 | head -30
or: eslint, clippy, etc.
或:eslint, clippy, 等
Step 6: Apply the review checklist (Section 3)
步骤6:应用审查检查清单(第3节)
Go through each category: Correctness, Security, Code Quality, Testing, Performance, Documentation.
逐一检查各个类别:正确性、安全性、代码质量、测试、性能、文档。
Step 7: Post the review to GitHub
步骤7:在GitHub上提交审查意见
Collect your findings and submit them as a formal review with inline comments.
With gh:
整理你的发现,以正式审查意见的形式提交,并附带行内评论。
使用gh工具:
If no issues — approve
若无问题——批准
gh pr review $PR_NUMBER --approve --body "Reviewed by Hermes Agent. Code looks clean — good test coverage, no security concerns."
gh pr review $PR_NUMBER --approve --body "由Hermes Agent审查。代码整洁——测试覆盖率充足,无安全隐患。"
If issues found — request changes with inline comments
若发现问题——请求修改并附带行内评论
gh pr review $PR_NUMBER --request-changes --body "Found a few issues — see inline comments."
**With curl — atomic review with multiple inline comments:**
```bash
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'])")
gh pr review $PR_NUMBER --request-changes --body "发现一些问题——查看行内评论。"
**使用curl——批量提交多条行内评论的审查意见:**
```bash
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'])")
Build the review JSON — event is APPROVE, REQUEST_CHANGES, or COMMENT
构建审查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 Review\n\nFound 2 issues, 1 suggestion. See inline comments.",
"comments": [
{"path": "src/auth.py", "line": 45, "body": "🔴
Critical: User input passed directly to SQL query — use parameterized queries."},
{"path": "src/models.py", "line": 23, "body": "⚠️
Warning: Password stored without hashing."},
{"path": "src/utils.py", "line": 8, "body": "💡
Suggestion: This duplicates logic in core/utils.py:34."}
]
}"
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审查意见\n\n发现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重复。"}
]
}"
Step 8: Also post a summary comment
步骤8:同时提交总结评论
In addition to inline comments, leave a top-level summary so the PR author gets the full picture at a glance. Use the review output format from
references/review-output-template.md
.
With gh:
bash
gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
除了行内评论,还需添加顶层总结评论,让PR作者能快速了解整体情况。使用
references/review-output-template.md
中的审查输出格式。
使用gh工具:
bash
gh pr comment $PR_NUMBER --body "$(cat <<'EOF'
Code Review Summary
代码审查总结
Verdict: Changes Requested (2 issues, 1 suggestion)
- src/auth.py:45 — SQL injection vulnerability
- src/models.py:23 — Plaintext password storage
- src/models.py:23 — 明文存储密码
- src/utils.py:8 — Duplicated logic, consider consolidating
- src/utils.py:8 — 逻辑重复,建议合并
- Clean API design
- Good error handling in the middleware layer
Reviewed by Hermes Agent
EOF
)"
Step 9: Clean up
步骤9:清理本地分支
bash
git checkout main
git branch -D pr-$PR_NUMBER
bash
git checkout main
git branch -D pr-$PR_NUMBER
Decision: Approve vs Request Changes vs Comment
决策:批准/请求修改/仅评论
- Approve — no critical or warning-level issues, only minor suggestions or all clear
- Request Changes — any critical or warning-level issue that should be fixed before merge
- Comment — observations and suggestions, but nothing blocking (use when you're unsure or the PR is a draft)
- 批准——无严重或警告级问题,仅存在微小建议或完全符合要求
- 请求修改——存在任何严重或警告级问题,需在合并前修复
- 仅评论——提出观察和建议,但无阻塞问题(当你不确定或PR为草稿时使用)