asyncreview

AsyncReview CLI

适用场景

在以下情况下使用此技能：

• 用户要求审查 GitHub 拉取请求
• 用户希望获得 AI 对 PR 中代码更改的反馈
• 用户需要检查 PR 是否破坏了现有功能
• 用户询问有关 GitHub Issue 或 PR 的问题
• 用户想确认代码更改中是否有遗漏

使用方法

1. 检查先决条件 — 确认已设置 GEMINI_API_KEY
2. 检查仓库是否为私有仓库 — 使用 gh repo view 确定是否需要 GITHUB_TOKEN
3. 按需设置 GITHUB_TOKEN — 对于私有仓库，使用 gh auth token
4. 获取 PR/Issue URL — 如果用户未提供，请向其询问
5. 拟定问题 — 将用户的请求转化为具体问题
6. 运行审查命令 — 执行 npx asyncreview review --url <URL> -q "<question>"
7. 呈现结果 — 分享 AI 的发现及来源

先决条件

1. 检查 GEMINI_API_KEY（必需）

运行任何命令前，请检查是否已设置 GEMINI_API_KEY：

echo $GEMINI_API_KEY

如果未设置或为空，请用户提供其 Gemini API 密钥：

“AsyncReview 需要 Gemini API 密钥。请在环境中设置 GEMINI_API_KEY，或现在提供密钥。”

然后设置它：

export GEMINI_API_KEY="user-provided-key"

2. 检查仓库是否为私有仓库（至关重要）

重要：审查 PR/Issue 前，必须检查仓库是否为私有仓库。如果是，则必须设置 GITHUB_TOKEN。

步骤 1：从 URL 提取所有者和仓库名称

从类似 https://github.com/owner/repo/pull/123 的 URL 中提取：

• 所有者：owner
• 仓库：repo

步骤 2：检查仓库的可见性

选项 A：使用 GitHub CLI（如果可用）

gh repo view owner/repo --json isPrivate -q '.isPrivate'

选项 B：不使用 GitHub CLI（使用 curl）

# Try to access the repo via GitHub API without authentication
curl -s -o /dev/null -w "%{http_code}" https://api.github.com/repos/owner/repo

可能的结果：

• 使用 gh：

  • true → 仓库是私有仓库，必须设置 GITHUB_TOKEN
  • false → 仓库是公开仓库，GITHUB_TOKEN 可选
  • 错误（例如“未找到”）→ 可能表示仓库是私有仓库但未进行身份验证，或者仓库不存在

• 使用 curl：

  • 200 → 仓库是公开仓库，GITHUB_TOKEN 可选（但建议设置，以获得更高的速率限制）
  • 404 → 仓库是私有仓库或不存在，必须设置 GITHUB_TOKEN
  • 403 → 触发速率限制，需要设置 GITHUB_TOKEN

步骤 3：如果是私有仓库，请确保已设置 GITHUB_TOKEN

# Check if GITHUB_TOKEN is already set
echo $GITHUB_TOKEN

如果未设置或为空，可通过以下任一方式获取：

选项 A：使用 GitHub CLI（如果可用）

# Get token from GitHub CLI (must be authenticated with `gh auth login` first)
export GITHUB_TOKEN=$(gh auth token)

# Verify it's set
echo $GITHUB_TOKEN

如果 gh auth token 失败，请先进行身份验证：

gh auth login

选项 B：不使用 GitHub CLI（通过网页创建令牌）

1. 前往 GitHub：https://github.com/settings/tokens
2. 点击 “Generate new token” → “Generate new token (classic)”
3. 为其设置一个描述性名称（例如“AsyncReview CLI”）
4. 选择权限范围：
   • ✅ repo（对私有仓库的完全控制权）
5. 点击 “Generate token”
6. 复制令牌（之后将无法再次查看！）
7. 在终端中设置令牌：

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Verify it's set
echo $GITHUB_TOKEN

**安全提示：**为了提高安全性，可考虑创建权限最小化的细粒度令牌：

• 前往：https://github.com/settings/personal-access-tokens/new
• 选择特定仓库
• 仅授予“Contents”读取权限

然后使用令牌运行审查：

npx asyncreview review --url <URL> -q "question" --github-token $GITHUB_TOKEN

或者将其设置为会话的环境变量：

export GITHUB_TOKEN=$(gh auth token)
npx asyncreview review --url <URL> -q "question"

快速开始

npx asyncreview review --url <PR_URL> -q "question"   # Review a PR
npx asyncreview review --url <PR_URL> --expert        # Expert code review
npx asyncreview review --url <PR_URL> --output markdown     # Markdown output

核心工作流

1. 向用户获取 PR URL
2. 使用具体问题运行审查
3. 阅读逐步推理输出
4. 模型可以自主获取差异内容之外的文件

命令

审查

npx asyncreview review --url <url> -q "question"      # Review with question
npx asyncreview review --url <url> -q "q" --output markdown # Markdown output
npx asyncreview review --url <url> -q "q" -o json     # JSON output

支持的 URL 格式：

• https://github.com/owner/repo/pull/123
• https://github.com/owner/repo/issues/456

环境变量

GEMINI_API_KEY="your-key"         # Required: Google Gemini API key
GITHUB_TOKEN="ghp_xxx"            # Optional: For private repos / higher rate limits

示例：审查 PR

npx asyncreview review \
  --url https://github.com/stanfordnlp/dspy/pull/9223 \
  -q "Does this change break any existing callers?"

输出包含：

• 步骤编号
• 💭 推理（AI 的思考内容）
• 📝 代码（正在执行的 Python 代码）
• 📤 输出（REPL 结果）
• 附带来源的最终答案

示例：检查其他位置是否存在该功能

npx asyncreview review \
  --url https://github.com/owner/repo/pull/123 \
  -q "Fetch src/utils.py and check if deprecated_func is still used"

AI 将会：

1. 搜索文件路径
2. 通过 GitHub API 获取文件
3. 在 Python 沙盒中分析内容
4. 提供带有证据的调查结果

示例：审查私有仓库中的 PR

私有仓库的完整工作流：

# Step 1: Extract owner/repo from URL
# URL: https://github.com/myorg/private-repo/pull/42
# owner="myorg", repo="private-repo"

# Step 2: Check if repository is private

## Option A: With GitHub CLI
gh repo view myorg/private-repo --json isPrivate -q '.isPrivate'
# Output: true (it's private!)

## Option B: Without GitHub CLI (using curl)
curl -s -o /dev/null -w "%{http_code}" https://api.github.com/repos/myorg/private-repo
# Output: 404 (likely private or doesn't exist)

# Step 3: Ensure GITHUB_TOKEN is set
echo $GITHUB_TOKEN

## If empty, Option A: Get from GitHub CLI
export GITHUB_TOKEN=$(gh auth token)

## If empty, Option B: Create via web (https://github.com/settings/tokens)
## Then:
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Step 4: Run the review with the token
npx asyncreview review \
  --url https://github.com/myorg/private-repo/pull/42 \
  -q "Does this PR introduce any security vulnerabilities?" \
  --github-token $GITHUB_TOKEN

# Alternative: Token is already in environment, no flag needed
npx asyncreview review \
  --url https://github.com/myorg/private-repo/pull/42 \
  -q "Does this PR introduce any security vulnerabilities?"

**如果遇到 404 或身份验证错误：**该仓库可能是私有的，你需要提供 GITHUB_TOKEN。

输出格式

格式	标志	说明
美化输出	（默认）	带边框的丰富终端输出
Markdown	--output markdown or -o markdown	Markdown 格式
JSON	--output json or -o json	机器可读格式

专家代码审查

使用 --expert 标志进行全面的 PR 审查，涵盖 SOLID 原则、安全性、性能和代码质量：

# Full expert review (no question needed)
npx asyncreview review --url <PR_URL> --expert

# Expert review with additional custom question
npx asyncreview review --url <PR_URL> --expert -q "Also check for breaking API changes"

专家审查会分析：

• SOLID 原则 - SRP、OCP、LSP、ISP、DIP 违规
• 安全性 - XSS、注入、身份验证漏洞、竞态条件、机密信息
• 代码质量 - 错误处理、N+1 查询、边界条件
• 待移除项 - 死代码、未使用的导入

输出包含：

• 标注严重程度的调查结果（P0 严重 → P3 低）
• 针对 P0/P1 问题的修复建议
• 总体评估：批准 / 请求修改 / 评论