alan-review-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MANDATORY: Use Alan MCP Tools

强制要求：使用Alan MCP工具

The Alan MCP server provides GitHub tools that are ALREADY in your tool list. They work exactly like Read, Bash, Edit — you call them as tool invocations. They are named with the prefix

mcp__alan__github_

Authentication is handled automatically by the MCP server. You do NOT need GitHub tokens, gh CLI auth, SSH keys, .netrc files, environment variables, or any credentials. The tools work immediately with zero setup.

Alan MCP服务器提供的GitHub工具已在你的工具列表中。它们的工作方式与Read、Bash、Edit完全相同——你可以通过工具调用的方式使用它们。它们的名称以

mcp__alan__github_

为前缀。

认证由MCP服务器自动处理。 你无需GitHub令牌、gh CLI认证、SSH密钥、.netrc文件、环境变量或任何凭据。这些工具无需任何设置即可立即使用。

NEVER do any of the following for GitHub API access:

绝对不要使用以下任何方式访问GitHub API：

```
curl
```
or
```
wget
```
to api.github.com
```
gh
```
CLI commands (gh pr, gh api, etc.)
```
env | grep
```
or scanning for tokens/secrets

cat ~/.netrc

git credential

, or

ssh -T git@github.com

Any attempt to find, construct, or configure GitHub authentication
Installing packages or CLIs for GitHub access

If an MCP tool call fails, report the error to the user. Do NOT fall back to CLI alternatives.

使用
```
curl
```
或
```
wget
```
访问api.github.com
使用
```
gh
```
CLI命令（gh pr、gh api等）
使用
```
env | grep
```
或扫描令牌/密钥

使用

cat ~/.netrc

、

git credential

或

ssh -T git@github.com

任何寻找、构造或配置GitHub认证的尝试
安装用于GitHub访问的软件包或CLI

如果MCP工具调用失败，请向用户报告错误。不要使用CLI替代方案。

Verify tools are available

验证工具是否可用

Before starting, confirm you can see

mcp__alan__github_*

tools in your available tools. If they are NOT available, STOP and tell the user: "The GitHub MCP tools are not available. Please check the sandbox MCP configuration."

开始之前，请确认你在可用工具列表中能看到

mcp__alan__github_*

工具。如果这些工具不可用，请停止操作并告知用户： "GitHub MCP工具不可用，请检查沙箱MCP配置。"

Tool parameters

工具参数

All GitHub PR tools require these parameters:

```
owner
```
(string): GitHub org or username, e.g. "supatest-ai"
```
repo
```
(string): Repository name, e.g. "alan"
```
prNumber
```
(integer): PR number, e.g. 42

Example tool call:

Tool: mcp__alan__github_get_pull_request
Parameters: { "owner": "supatest-ai", "repo": "alan", "prNumber": 42 }

所有GitHub PR工具都需要以下参数：

```
owner
```
（字符串）：GitHub组织或用户名，例如"supatest-ai"
```
repo
```
（字符串）：仓库名称，例如"alan"
```
prNumber
```
（整数）：PR编号，例如42

示例工具调用：

Tool: mcp__alan__github_get_pull_request
Parameters: { "owner": "supatest-ai", "repo": "alan", "prNumber": 42 }

Resolving owner/repo

解析owner/repo

If the user only provides a PR number, run

git remote get-url origin

to get the remote URL, then parse owner and repo from it. This is the ONLY git CLI command you should run for GitHub operations. Everything else uses MCP tools.

如果用户仅提供PR编号，请运行

git remote get-url origin

获取远程URL，然后从中解析owner和repo。这是你在GitHub操作中应该运行的唯一git CLI命令，其他所有操作都使用MCP工具。

Available GitHub MCP tools

可用的GitHub MCP工具

Tool name	Purpose
`mcp__alan__github_get_pull_request`	Get PR details (title, state, labels, merge status)
`mcp__alan__github_get_pr_diff`	Get unified diff of a PR
`mcp__alan__github_list_pr_comments`	List all comments on a PR
`mcp__alan__github_list_pr_reviews`	List all reviews on a PR
`mcp__alan__github_list_pr_files`	List changed files with additions/deletions
`mcp__alan__github_get_issue`	Get issue details
`mcp__alan__github_get_ci_status`	Get CI check run status for a ref
`mcp__alan__github_add_comment`	Add a comment to an issue or PR
`mcp__alan__github_create_pr_review`	Submit a review (APPROVE/REQUEST_CHANGES/COMMENT)
`mcp__alan__github_add_labels`	Add labels to an issue or PR
`mcp__alan__github_merge_pull_request`	Merge a PR
`mcp__alan__github_close_issue`	Close an issue or PR
`mcp__alan__github_request_reviewers`	Request reviewers on a PR

工具名称	用途
`mcp__alan__github_get_pull_request`	获取PR详情（标题、状态、标签、合并状态）
`mcp__alan__github_get_pr_diff`	获取PR的统一差异对比
`mcp__alan__github_list_pr_comments`	列出PR上的所有评论
`mcp__alan__github_list_pr_reviews`	列出PR上的所有审核记录
`mcp__alan__github_list_pr_files`	列出已更改文件及增删行数
`mcp__alan__github_get_issue`	获取Issue详情
`mcp__alan__github_get_ci_status`	获取引用的CI检查运行状态
`mcp__alan__github_add_comment`	向Issue或PR添加评论
`mcp__alan__github_create_pr_review`	提交审核（APPROVE/REQUEST_CHANGES/COMMENT）
`mcp__alan__github_add_labels`	向Issue或PR添加标签
`mcp__alan__github_merge_pull_request`	合并PR
`mcp__alan__github_close_issue`	关闭Issue或PR
`mcp__alan__github_request_reviewers`	请求PR审核人员

Task: Review a Pull Request

任务：审核拉取请求

Input

输入

The user will provide one of:

A PR number (e.g. "42" or "#42")
A PR URL (e.g. "https://github.com/owner/repo/pull/42")
A reference like "owner/repo#42"

用户将提供以下内容之一：

PR编号（例如"42"或"#42"）
PR链接（例如"https://github.com/owner/repo/pull/42"）
引用格式（例如"owner/repo#42"）

Workflow

工作流程

Resolve owner/repo/prNumber from the input. If only a PR number is given, run
```
git remote get-url origin
```
to parse owner and repo.
Fetch PR metadata — call
```
mcp__alan__github_get_pull_request
```
with
```
{ owner, repo, prNumber }
```
to get title, description, state, labels, branches.
Fetch the diff — call
```
mcp__alan__github_get_pr_diff
```
to get the unified diff.
Fetch changed files — call
```
mcp__alan__github_list_pr_files
```
to see files modified/added/deleted with line counts.
Fetch existing reviews — call
```
mcp__alan__github_list_pr_reviews
```
to see prior review state.
Fetch existing comments — call
```
mcp__alan__github_list_pr_comments
```
for ongoing discussion context.
Check CI status — call
```
mcp__alan__github_get_ci_status
```
with the head branch or SHA. If a check failed, include the html_url link so the user can view full logs (the tool does not return log output).
Read source files — for complex changes, use the Read tool to read full source files (not just the diff) for context.
Analyze — identify issues INTRODUCED by this PR only (not pre-existing). For each finding, determine: severity, file path, start/end line, title, description, and a concrete fix prompt for agents.
Post review — call
```
mcp__alan__github_create_pr_review
```
with inline comments (one per finding) plus a summary body. See formats below.

从输入中解析owner/repo/prNumber。如果仅提供PR编号，请运行
```
git remote get-url origin
```
来解析owner和repo。
获取PR元数据 — 调用
```
mcp__alan__github_get_pull_request
```
并传入
```
{ owner, repo, prNumber }
```
，获取标题、描述、状态、标签、分支信息。
获取差异对比 — 调用
```
mcp__alan__github_get_pr_diff
```
获取PR的统一差异对比。
获取已更改文件 — 调用
```
mcp__alan__github_list_pr_files
```
查看已修改/添加/删除的文件及行数统计。
获取现有审核记录 — 调用
```
mcp__alan__github_list_pr_reviews
```
查看之前的审核状态。
获取现有评论 — 调用
```
mcp__alan__github_list_pr_comments
```
获取当前讨论上下文。
检查CI状态 — 使用头部分支或SHA调用
```
mcp__alan__github_get_ci_status
```
。如果检查失败，请包含html_url链接以便用户查看完整日志（该工具不返回日志输出）。
读取源文件 — 对于复杂变更，使用Read工具读取完整源文件（而非仅差异对比）以获取上下文。
分析 — 仅识别此PR引入的问题（而非预先存在的问题）。对于每个发现，确定：严重程度、文件路径、起始/结束行、标题、描述，以及可供Agent执行的具体修复提示。
提交审核 — 调用
```
mcp__alan__github_create_pr_review
```
，包含行内评论（每个发现对应一条）及总结内容。格式如下。

Review Dimensions (priority order)

审核维度（优先级顺序）

Security — injection, auth bypass, secrets in code, input validation
Correctness — logic errors, null handling, async issues, race conditions
Performance — N+1 queries, unbounded operations, memory issues
Error Handling — silent failures, empty catch blocks, swallowed errors
Maintainability — functions >30 lines, deep nesting, magic numbers
Test Coverage — happy path tested? edge cases? meaningful assertions?

安全性 — 注入攻击、认证绕过、代码中的密钥、输入验证
正确性 — 逻辑错误、空值处理、异步问题、竞态条件
性能 — N+1查询、无界操作、内存问题
错误处理 — 静默失败、空catch块、被吞掉的错误
可维护性 — 超过30行的函数、深层嵌套、魔法值
测试覆盖率 — 是否测试了正常路径？边缘情况？有意义的断言？

Confidence Filter

置信度筛选

Only include findings where:

You can point to exact file + line
You can describe a concrete scenario where it causes a real problem
Confidence >= 80%

Skip: linter-catchable issues, speculative risks, style preferences, pre-existing problems.

仅包含符合以下条件的发现：

你可以指向确切的文件 + 行号
你可以描述导致实际问题的具体场景
置信度 ≥ 80%

跳过：可由代码检查工具捕获的问题、推测性风险、风格偏好、预先存在的问题。

Inline Comment Format

行内评论格式

Each finding becomes its own inline comment on the PR. Format the

body

of each comment like this:

markdown

<!-- alan-review-comment {"id": "alan_review_{prNumber}_{sequential_4digit}", "file_path": "{path}", "start_line": {start}, "end_line": {end}, "side": "RIGHT"} -->

{severity_icon} **{short_title}**

{detailed_description}

<details>
<summary>Prompt for agents</summary>

\`\`\`
{concrete_fix_instructions_an_AI_agent_can_execute — specify exact file, what to change, and how}
\`\`\`

</details>

<!-- alan-review-badge-begin -->
<a href="{alan_session_url}" target="_blank">
  <img src="https://app.tryalan.ai/logo.png" alt="Open in Alan" height="20">
</a>
<!-- alan-review-badge-end -->

Severity icons:

🔴 = Blocking (critical bugs, security, data loss — must fix before merge)
🟡 = Important (real bugs/risks — should fix before merge)
🔵 = Nit (minor quality issues — fix if easy)

每个发现都将成为PR上的独立行内评论。请按以下格式编写每个评论的

body

：

markdown

<!-- alan-review-comment {"id": "alan_review_{prNumber}_{sequential_4digit}", "file_path": "{path}", "start_line": {start}, "end_line": {end}, "side": "RIGHT"} -->

{severity_icon} **{short_title}**

{detailed_description}

<details>
<summary>Agent修复提示</summary>

\\`\\`\\`
{concrete_fix_instructions_an_AI_agent_can_execute — specify exact file, what to change, and how}
\\`\\`\\`

</details>

<!-- alan-review-badge-begin -->
<a href="{alan_session_url}" target="_blank">
  <img src="https://app.tryalan.ai/logo.png" alt="Open in Alan" height="20">
</a>
<!-- alan-review-badge-end -->

严重程度图标：

🔴 = 阻塞（严重bug、安全问题、数据丢失——合并前必须修复）
🟡 = 重要（实际bug/风险——合并前应修复）
🔵 = 小问题（轻微质量问题——如果容易修复则处理）

Summary Comment Format

总结评论格式

The

body

parameter of the review (top-level summary) should be:

markdown

**Alan Review** found {N} potential issues.

| Severity | Count |
|----------|-------|
| 🔴 Blocking | {X} |
| 🟡 Important | {Y} |
| 🔵 Nit | {Z} |

<details>
<summary>View all findings</summary>

审核的

body

参数（顶层总结）应如下：

markdown

**Alan审核**发现{N}个潜在问题。

| 严重程度 | 数量 |
|----------|-------|
| 🔴 阻塞 | {X} |
| 🟡 重要 | {Y} |
| 🔵 小问题 | {Z} |

<details>
<summary>查看所有发现</summary>

🔴 Blocking

🔴 阻塞

{title} — `{file_path}:{line}` — {one_line_description}

{title} — \
```
{file_path}:{line}\\
```
— {one_line_description}

🟡 Important

🟡 重要

{title} — `{file_path}:{line}` — {one_line_description}

{title} — \
```
{file_path}:{line}\\
```
— {one_line_description}

🔵 Nit

🔵 小问题

{title} — `{file_path}:{line}` — {one_line_description}

</details>  <a href="{alan_session_url}" target="_blank"> <img src="https://app.tryalan.ai/logo.png" alt="Open in Alan" height="20"> </a>

Was this helpful? React with 👍 or 👎 to provide feedback.

undefined

{title} — \
```
{file_path}:{line}\\
```
— {one_line_description}

此审核是否有帮助？请用👍或👎反馈。

undefined

"Open in Alan" Badge URL

"在Alan中打开"徽章链接

Every badge links to the current Alan session. The user/trigger will provide the session URL. Replace

{alan_session_url}

in every badge with the actual URL.

If no session URL is provided, fall back to

https://app.tryalan.ai

每个徽章都链接到当前Alan会话。用户/触发者会提供会话链接。请将每个徽章中的

{alan_session_url}

替换为实际链接。

如果未提供会话链接，请回退使用

https://app.tryalan.ai

。

Posting the Review

提交审核

Call

mcp__alan__github_create_pr_review

with:

```
owner
```
,
```
repo
```
,
```
prNumber
```
: from step 1
```
body
```
: the summary comment above
```
event
```
: "REQUEST_CHANGES" if any 🔴 blocking findings, otherwise "COMMENT"
```
comments
```
: array of inline comments, each with:
- ```
path
```
  : relative file path from repo root
- ```
line
```
  : the end line number of the finding
- ```
body
```
  : the formatted inline comment body above

IMPORTANT:

Always post inline comments (one per finding) — do NOT bundle into one big comment
Always include the "Prompt for agents" section in every finding
Always include the "Open in Alan" badge on every comment and the summary
Replace
```
{alan_session_url}
```
with the actual session URL in every badge
If zero findings, post an approving review with a clean summary

调用

mcp__alan__github_create_pr_review

时传入：

```
owner
```
,
```
repo
```
,
```
prNumber
```
：来自步骤1
```
body
```
：上述总结评论
```
event
```
：如果有🔴阻塞问题则为"REQUEST_CHANGES"，否则为"COMMENT"
```
comments
```
：行内评论数组，每条评论包含：
- ```
path
```
  ：仓库根目录下的相对文件路径
- ```
line
```
  ：发现的结束行号
- ```
body
```
  ：上述格式化的行内评论内容

重要提示：

始终提交行内评论（每个发现对应一条）——不要合并为一条大评论
始终在每个发现中包含"Agent修复提示"部分
始终在每条评论和总结中包含"在Alan中打开"徽章
将每个徽章中的
```
{alan_session_url}
```
替换为实际会话链接
如果没有发现问题，请提交通过审核的干净总结 ",