alan-review-pr

强制要求：使用 Alan MCP 工具

Alan MCP 服务提供的 GitHub 工具已经在你的工具列表中。 它们的使用方式与 Read、Bash、Edit 完全相同——直接以工具调用的形式调用。 它们的名称以 mcp__alan__github_ 为前缀。

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

访问 GitHub API 时，绝不可执行以下操作：

• 使用 curl 或 wget 访问 api.github.com
• 执行 gh CLI 命令（gh pr、gh api 等）
• 执行 env | grep 或扫描令牌／密钥
• 执行 cat ~/.netrc、git credential 或 ssh -T [email protected]
• 尝试查找、创建或配置 GitHub 身份验证
• 安装用于访问 GitHub 的软件包或 CLI 工具

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

确认工具是否可用

开始前，确认你能看到可用工具中的 mcp__alan__github_* 工具。如果没有，请停止并告知用户： “GitHub MCP 工具不可用。请检查沙盒 MCP 配置。”

工具参数

所有 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 }

确定 owner/repo

如果用户只提供 PR 编号，请运行 git remote get-url origin 获取远程 URL，然后从中解析 owner 和 repo。这是 GitHub 操作中唯一应运行的 git CLI 命令。其他所有操作都使用 MCP 工具。

可用的 GitHub MCP 工具

工具名称	用途
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	获取议题详情
mcp__alan__github_get_ci_status	获取某个引用的 CI 检查运行状态
mcp__alan__github_add_comment	在议题或 PR 中添加评论
mcp__alan__github_create_pr_review	提交评审（APPROVE/REQUEST_CHANGES/COMMENT）
mcp__alan__github_add_labels	为议题或 PR 添加标签
mcp__alan__github_merge_pull_request	合并 PR
mcp__alan__github_close_issue	关闭议题或 PR
mcp__alan__github_request_reviewers	请求 PR 评审人

---

任务：评审拉取请求

输入

用户会提供以下其中一项：

• PR 编号（例如 "42" 或 "#42"）
• PR URL（例如 "https://github.com/owner/repo/pull/42"）
• 类似 "owner/repo#42" 的引用

工作流

1. 从输入中解析 owner/repo/prNumber。如果只提供 PR 编号， 运行 git remote get-url origin 以解析 owner 和 repo。

2. 获取 PR 元数据 — 调用 mcp__alan__github_get_pull_request，传入 { owner, repo, prNumber }，获取标题、描述、状态、标签和分支。

3. 获取差异 — 调用 mcp__alan__github_get_pr_diff 获取统一差异。

4. 获取变更文件 — 调用 mcp__alan__github_list_pr_files，查看 已修改／新增／删除的文件及行数。

5. 获取现有评审 — 调用 mcp__alan__github_list_pr_reviews 查看 之前的评审状态。

6. 获取现有评论 — 调用 mcp__alan__github_list_pr_comments，了解 当前讨论的上下文。

7. 检查 CI 状态 — 调用 mcp__alan__github_get_ci_status，传入头部分支 或 SHA。如果某项检查失败，请附上 html_url 链接，方便用户查看完整日志（该工具不会返回日志内容）。

8. 阅读源文件 — 对于复杂变更，使用 Read 工具阅读完整的 源文件（不只是差异），以了解上下文。

9. 分析 — 仅识别此 PR 引入的问题（而非已有问题）。 对于每项发现，确定：严重程度、文件路径、起始／结束行、标题、 描述，以及给 Agent 的具体修复提示词。

10. 发布评审 — 调用 mcp__alan__github_create_pr_review，附上行内 评论（每项发现一条）和摘要正文。格式见下文。

评审维度（按优先级排序）

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

置信度筛选

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

• 能指出确切的文件和行
• 能描述导致实际问题的具体场景
• 置信度 >= 80%

跳过：可由 linter 捕获的问题、推测性风险、风格偏好、已有问题。

行内评论格式

每项发现都应作为 PR 的单独行内评论。每条评论的 body 按以下格式编写：

{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>


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

严重程度图标：

• 🔴 = 阻塞（严重错误、安全问题、数据丢失 — 合并前必须修复）
• 🟡 = 重要（实际错误／风险 — 合并前应修复）
• 🔵 = 小问题（轻微质量问题 — 容易修复时再修复）

摘要评论格式

评审的 body 参数（顶层摘要）应为：

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

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

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

### 🔴 Blocking
- **{title}** — \`{file_path}:{line}\` — {one_line_description}

### 🟡 Important
- **{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.*

“在 Alan 中打开”徽章 URL

每个徽章都链接到当前 Alan 会话。用户／触发方会提供 会话 URL。将每个徽章中的 {alan_session_url} 替换为实际 URL。

如果未提供会话 URL，则使用 https://app.tryalan.ai。

发布评审

调用 mcp__alan__github_create_pr_review，并传入：

• owner、repo、prNumber：来自第 1 步
• body：上文的摘要评论
• event：如果存在任何 🔴 阻塞问题，则为 "REQUEST_CHANGES"，否则为 "COMMENT"
• comments：行内评论数组，每条评论包含：
  • path：相对于仓库根目录的文件路径
  • line：问题的结束行号
  • body：上文格式的行内评论正文

重要：

• 始终发布行内评论（每项发现一条）——不要将所有内容合并为一条大评论
• 每项发现都必须包含“给 Agent 的提示词”部分
• 每条评论和摘要中都必须包含“在 Alan 中打开”徽章
• 将每个徽章中的 {alan_session_url} 替换为实际会话 URL
• 如果没有发现问题，则发布通过评审，并附上无问题的摘要