AI代码审查实战：基于GitHub Action与提示词工程提升团队开发质量

1. 项目概述：当AI成为你的代码审查搭档

在团队协作开发中，代码审查（Code Review）是保证代码质量、统一团队规范、传播知识的关键环节。但现实往往很骨感：资深同事忙得脚不沾地，没时间细看你的PR；初级同事可能抓不住重点，审查流于形式；而你自己，在提交了数百行代码后，也很难再以全新的视角去审视其中的逻辑漏洞或安全隐患。结果就是，要么审查周期被拉长，要么一些潜在问题被带到了线上。

最近，我在一个中型规模的TypeScript项目中，尝试引入了一个名为ai-pr-review-prompts的GitHub Action工具，让AI来充当第一轮“代码审查员”。它的核心思路非常直接：每当有新的Pull Request（PR）被创建或更新时，自动触发一个工作流，将本次提交的代码变更（Diff）发送给AI模型（如Claude、GPT或Gemini），然后由AI根据预设的、高度结构化的提示词（Prompt）进行分析，并将审查结果以评论的形式直接贴回到PR中。

这听起来像是给项目加了一个“永不疲倦的资深架构师”。经过几周的实战，我发现它远不止是一个“玩具”。它能精准地揪出那些容易被人类审查者忽略的细节，比如一个本应使用const却用了let的变量声明、一个可能引发竞态条件的异步操作、或者一段缺失了关键错误处理的数据库查询。更重要的是，它提供了一种标准化的审查视角，不受个人情绪或时间压力的影响。

这个项目本质上是一个精心设计的“提示词工程”集合与自动化管道的结合体。它没有重新发明轮子去调用GitHub API，而是基于成熟的AI服务，将高质量的审查逻辑封装成了可复用的GitHub Action。对于任何使用GitHub进行协作的团队，无论是前端React、后端Node.js/Python，还是全栈项目，都可以在几分钟内将其集成到开发流程中，立即获得AI辅助的代码质量洞察。

2. 核心设计思路与方案选型

2.1 为何选择“提示词驱动”的AI审查？

市面上已经存在一些基于静态分析（如SonarQube, ESLint）或机器学习模式的代码审查工具。ai-pr-review-prompts选择了一条不同的路：完全依赖大语言模型（LLM）的理解和推理能力，并通过精心构造的提示词来引导其输出。

这种设计的优势非常明显。首先，灵活性极高。静态分析工具通常需要为每种语言、每种框架编写特定的规则，而LLM经过海量代码训练，对多种语言和范式都有基础理解。通过提示词，我们可以轻松地让它关注“安全”、“性能”或“TypeScript类型安全”等不同维度，无需为每个维度单独配置一套复杂的规则引擎。其次，上下文理解能力强。LLM可以理解代码段的语义和意图，而不仅仅是语法。例如，它能判断一段加密代码是否使用了不安全的算法，或者一个React组件是否进行了不必要的重渲染，这超出了大多数Linter的能力范围。最后，迭代成本低。改进审查质量，只需要优化提示词文本，无需重新编译或部署复杂的软件。

当然，这种方案也依赖LLM的能力和稳定性，并且会产生API调用成本。但考虑到它能为团队节省的审查时间和避免的潜在缺陷，这笔投资通常是值得的。

2.2 架构解析：从PR事件到AI评论

这个Action的工作流清晰且高效，完美契合GitHub Actions的事件驱动模型。其核心流程可以拆解为以下几步：

1. 事件触发：工作流监听pull_request事件的opened（新建）和synchronize（更新，即新的commit）类型。这意味着每次PR的创建或后续代码推送都会触发审查。
2. 权限准备：工作流需要contents: read权限来获取代码库的内容和Diff，以及pull-requests: write权限来创建PR评论或审查。
3. 环境与Diff获取：Action运行在一个Ubuntu最新版的runner上。它首先会检出代码，并计算出当前PR分支与目标分支（通常是main或master）之间的差异。
4. 智能预处理：这里有一个很实用的细节——max-diff-size参数（默认60,000字符）。如果Diff过大，Action会对其进行智能截断，优先保留关键文件的变更，以确保发送给AI的上下文不会超出模型的令牌（Token）限制，避免审查失败或产生过高费用。
5. 提示词组装与AI调用：根据配置的review-type（如typescript,security），Action会从内置的提示词库中选取对应的Markdown文件。它将代码Diff和选定的提示词组合成最终的请求，调用相应提供商（Anthropic, OpenAI, Google）的API。
6. 结果解析与回帖：收到AI的回复后，Action会将其格式化为Markdown，并根据post-as配置，以普通评论（comment）或正式的GitHub审查（review）形式提交到PR中。正式的审查可以给出“批准”、“请求更改”或“评论”等状态，集成度更高。

这个架构的巧妙之处在于其“无状态性”和“可组合性”。Action本身不存储任何状态，每次运行都是独立的。你可以通过GitHub Actions的矩阵策略（matrix），轻松实现让同一个PR并行接受多种类型的审查（例如，同时进行安全审查和性能审查）。

注意：将API密钥等敏感信息存储在仓库的Secrets中是最佳实践。绝对不要将密钥硬编码在YAML文件里。Action的输入参数api-key正是设计为从secrets中读取，保证了密钥的安全性。

3. 配置详解与实战部署

3.1 基础工作流配置

要让AI审查员开始工作，你只需要在项目的.github/workflows/目录下创建一个YAML文件，例如pr-review.yml。下面是一个最精简且功能完整的配置示例，我以使用Anthropic的Claude模型为例：

name: AI PR Review on: pull_request: types: [opened, synchronize] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - name: Run AI Code Review uses: keba2503/ai-pr-review-prompts@v2 with: provider: "anthropic" api-key: ${{ secrets.ANTHROPIC_API_KEY }} review-type: "full"

逐行解析与实操要点：

• on:定义了触发条件。synchronize事件至关重要，它确保了当开发者根据反馈修改代码并再次推送后，AI会重新审查新的变更集，形成“提交-审查-修改”的闭环。
• permissions:这是GitHub Actions较新的权限控制语法，比旧的GITHUB_TOKEN配置更清晰。这里显式声明了所需的最小权限。
• uses:指定了要使用的Action仓库和版本。@v2是一个标签，指向一个稳定的发布版本，强烈建议使用版本标签而非默认分支，以避免上游变更意外破坏你的工作流。
• with:下的参数是核心：
  • provider: 根据你拥有的API密钥选择。anthropic(Claude),openai(ChatGPT),google(Gemini) 三选一。
  • api-key: 从仓库的Secrets中读取。你需要先在GitHub仓库的Settings -> Secrets and variables -> Actions页面，创建一个新的Repository Secret，名称例如ANTHROPIC_API_KEY，并将你的API密钥粘贴进去。
  • review-type: “full”: 这是一个“组合包”，它会从代码质量、安全、性能、架构、测试等多个维度进行综合审查，非常适合作为PR的默认全面检查。

创建文件并推送到仓库后，下一次你创建PR时，Actions页面就会自动运行这个工作流。完成后，你就能在PR的Conversation标签页看到AI发表的审查评论了。

3.2 高级配置与策略组合

项目的强大之处在于其丰富的review-type和灵活的配置组合。以下是我在实战中总结出的几种高效用法。

场景一：针对技术栈的精细化审查如果你的项目是Next.js前端，那么frontend组合可能比full更聚焦。它专门关注TypeScript类型、React性能与可访问性。

- uses: keba2503/ai-pr-review-prompts@v2 with: provider: "openai" api-key: ${{ secrets.OPENAI_API_KEY }} review-type: "frontend" # 可以显式指定模型，覆盖默认的 gpt-4o model: "gpt-4o-mini" # 更经济的选择，适合日常审查

场景二：并行多维度审查利用GitHub Actions的矩阵策略，可以同时启动多个审查任务，从不同视角审视同一份代码。这对于重要的功能PR或重构PR非常有用。

jobs: ai-review: runs-on: ubuntu-latest strategy: matrix: review-type: [security, performance-react, typescript] steps: - uses: keba2503/ai-pr-review-prompts@v2 with: provider: "anthropic" api-key: ${{ secrets.ANTHROPIC_API_KEY }} review-type: ${{ matrix.review-type }}

这样，一个PR会同时收到三条独立的评论，分别来自安全专家、React性能专家和TypeScript专家。这种并行的方式比串行运行更快，审查视角也更立体。

场景三：关键审查使用更强模型你可以配置多个Job，对不同的审查类型使用不同的AI提供商或模型。例如，用最强的模型（如Claude 3.5 Sonnet）进行安全和架构审查，用性价比高的模型（如GPT-4o Mini）进行代码风格审查。

jobs: critical-review: runs-on: ubuntu-latest steps: - uses: keba2503/ai-pr-review-prompts@v2 with: provider: "anthropic" api-key: ${{ secrets.ANTHROPIC_API_KEY }} review-type: "security" model: "claude-3-5-sonnet-20241022" # 使用指定的最新版模型 post-as: "review" # 以正式审查形式提交，可阻塞合并 general-review: runs-on: ubuntu-latest steps: - uses: keba2503/ai-pr-review-prompts@v2 with: provider: "openai" api-key: ${{ secrets.OPENAI_API_KEY }} review-type: "general" model: "gpt-4o-mini" post-as: "comment" # 以普通评论形式提交

配置参数速查表：

3.3 理解与选择“审查类型”

review-type是这个项目的灵魂。它不是一个模糊的指令，而是一把把针对特定问题的“手术刀”。以下是我对主要类别的解读和选型建议：

组合包（Combos）：开箱即用的最佳选择。

• full：全能型。适合大多数PR的首次自动化审查，覆盖面广。
• frontend：前端特化。专注于TS/React生态的问题，如Hooks依赖项、Memoization、ARIA属性等。
• backend：后端特化。紧盯安全漏洞、数据库查询效率、API设计规范。

代码质量（Code Quality）：根据项目主语言选择。

• typescript：强烈推荐给TS项目。它不仅能发现any类型，还能揪出类型断言as的滥用、可能为null/undefined的未处理情况、泛型使用不当等问题。我曾被它提醒过一个函数返回了联合类型Promise<ResultType \| Error>，但调用处没有做类型守卫，潜在运行时风险很高。
• python：关注Pythonic写法，比如可变默认参数（def func(arg=[]):）、低效的循环、类型注解（Type Hints）的缺失或错误。
• go：检查错误处理是否被忽略、goroutine是否可能泄漏、context是否正确传递。
• rust：聚焦内存安全，如不必要的unsafe块、unwrap()在生产环境代码中的使用等。

安全（Security）：应作为关键PR的必选项。

• security：通用安全扫描。检查硬编码的密码、密钥、可能的SQL/命令注入点、已知的易受攻击依赖版本（通过分析package.json或requirements.txt）。
• security-auth：身份验证与授权专项。对于修改登录、权限中间件、JWT处理的PR，这个审查能发现逻辑漏洞，比如缺少CSRF令牌、权限检查顺序错误等。
• security-api：API安全专项。检查输入验证是否完备、CORS设置是否过于宽松、敏感数据是否在响应中直接暴露、是否缺少速率限制。

性能（Performance）：随着业务增长，这类问题会逐渐凸显。

• performance-react：React开发者必备。它能指出哪些组件因为props或state的不必要变化导致了重渲染，建议使用useMemo,useCallback或React.memo进行优化。还会评估引入的新依赖对打包体积的影响。
• performance-database：数据库操作相关PR的守护神。能识别N+1查询问题、缺少索引的字段、一次性查询过多数据（SELECT *）等。

架构（Architecture）与测试（Testing）：适合在重构或增加复杂功能时使用，有助于维持代码库的长期健康度。

选择策略：对于日常小修小改，使用general或语言专项（如typescript）即可。对于涉及核心逻辑、安全模块或性能敏感路径的PR，建议启用security+ 对应的性能/架构审查。项目初期或定期巡检，可以使用full进行一次全面体检。

4. 实战效果与审查案例深度解析

理论说得再多，不如看看实际效果。我选取了项目中几个真实的审查案例，来展示AI如何具体地发现问题。

4.1 TypeScript类型安全审查实战

场景：在一个Next.js API路由中，我添加了一个根据查询参数获取用户资料的功能。

原始代码片段：

// app/api/user/route.ts export async function GET(request: Request) { const { searchParams } = new URL(request.url); const userId = searchParams.get('id'); // get() 返回 string | null // 问题1: 直接使用 userId 进行数据库查询 const user = await db.user.findUnique({ where: { id: userId }, }); if (!user) { return NextResponse.json({ error: 'User not found' }); } // 问题2: 返回了完整的用户对象，包含密码哈希字段 return NextResponse.json(user); }

AI审查输出摘要（使用review-type: typescript）：

🔍 Type Safety & Logic Review

• 潜在运行时错误 (High Priority):userId的类型是string | null。在第7行直接将其传递给where: { id: userId }，当id为null时，Prisma会抛出查询错误。应在查询前进行空值检查。
• 敏感数据暴露 (Medium Priority): 第14行直接返回了user对象。数据库模型User很可能包含passwordHash、email等敏感字段。这违反了最小数据暴露原则。建议使用select或omit来塑形响应数据。
• 代码建议:
  1. 添加空值检查：if (!userId) { return NextResponse.json({ error: 'Missing user id' }, { status: 400 }); }
  2. 明确查询参数类型：const userId = searchParams.get('id') as string \| null;（虽然不影响运行时，但提高可读性）。
  3. 选择返回字段：await db.user.findUnique({ where: { id: userId }, select: { id: true, name: true, avatar: true } })

我的分析与改进： AI的审查一针见血。第一个问题是典型的“类型窄化”缺失，我在编写时只考虑了正常流程，忽略了参数缺失的情况。第二个问题则是安全意识不足，属于习惯性错误。我按照建议修改后，代码健壮性和安全性都得到了提升。这种针对具体代码模式的审查，比通用的“要检查输入”建议要有用得多。

4.2 安全审查实战

场景：在一个Express.js中间件中，我实现了基于用户角色的权限控制。

原始代码片段：

// middleware/auth.js function isAdmin(req, res, next) { // 问题1: 从Cookie中直接读取未签名的用户ID const userId = req.cookies.userId; const user = getUserFromDatabase(userId); // 假设的函数 // 问题2: 角色检查逻辑过于简单且可能被绕过 if (user && user.role === 'admin') { req.user = user; return next(); } else { return res.status(403).json({ error: 'Forbidden' }); } }

AI审查输出摘要（使用review-type: security-auth）：

🔒 Authentication & Authorization Review

• 身份验证绕过 (Critical): 第4行直接从Cookie中读取userId。Cookie客户端可任意修改，攻击者可将其改为其他用户的ID，从而实现垂直越权。身份验证必须基于无法篡改的令牌（如签名的JWT）并在服务端验证。
• 脆弱的授权机制 (High Priority): 第7行的角色检查依赖于从数据库查出的user对象。如果getUserFromDatabase函数因任何原因（如缓存污染）返回了错误的用户对象，授权将失效。建议采用基于声明的授权，并在令牌中嵌入角色信息。
• 建议:
  1. 实现基于JWT的认证。从Authorization: Bearer <token>头中获取令牌，并用密钥验证其签名和有效性。
  2. 将用户角色（如admin）作为声明（claim）嵌入JWT载荷中。在中间件中解码令牌后直接验证角色，避免再次查询数据库（除非角色可能实时变更）。
  3. 记录授权失败日志，用于监控可疑行为。

我的分析与改进： 这个审查暴露了我最初设计中的一个严重安全漏洞。我混淆了“身份识别”（谁）和“身份验证”（真的是谁）。“信任客户端传过来的ID”是一个低级但容易在快速开发中犯的错误。AI不仅指出了问题，还给出了具体的实现方向（JWT）。我随后重构了该中间件，使用jsonwebtoken库来验证签名，并从令牌声明中读取角色，彻底消除了这个漏洞。

4.3 性能审查实战

场景：在一个React组件中，我渲染了一个用户列表，每个列表项都是一个复杂的子组件。

原始代码片段：

// UserList.jsx function UserList({ users, onUserClick }) { console.log('UserList renders'); return ( <div> {users.map(user => ( <UserListItem key={user.id} user={user} onClick={() => onUserClick(user)} // 问题所在 /> ))} </div> ); } // UserListItem.jsx const UserListItem = React.memo(({ user, onClick }) => { console.log(`ListItem ${user.id} renders`); return <div onClick={onClick}>{user.name}</div>; });

AI审查输出摘要（使用review-type: performance-react）：

⚡ React Performance Review

• 不必要的重渲染 (High Impact): 在UserList组件的第9行，为每个UserListItem传递了一个内联箭头函数() => onUserClick(user)。每次UserList渲染时，即使users数组和onUserClick引用未变，每个列表项的onClickprop都会得到一个新的函数引用，导致所有React.memo包裹的UserListItem全部失效并重新渲染。
• 内存与计算浪费: 频繁创建新函数会增加GC压力，并使得React.memo的优化目的落空。
• 解决方案:
  1. 推荐: 使用useCallback包裹onUserClick处理函数（如果定义在父组件），并让列表项通过user.id来识别自身。
  2. 或: 将UserListItem重构为接受userId和onClick（附带userId参数），在列表项内部从上下文或Store获取用户详情。这样onClick引用可以稳定。
  3. 临时方案: 如果user对象稳定，可使用useMemo为每个列表项缓存函数，但复杂度较高。

我的分析与改进： 这是一个经典的React性能陷阱。我使用了React.memo试图优化子组件，却因为内联函数prop而使其完全失效。AI审查直接指出了问题根源和最优解。我采纳了第一个建议，修改了父组件的函数定义，并通过user.id来识别点击项，成功消除了不必要的重渲染，在长列表场景下性能提升显著。

5. 集成策略、局限性与最佳实践

5.1 将AI审查融入团队工作流

引入AI工具不是为了取代人工审查，而是为了增强它。以下是我总结的几种集成模式：

1. 第一道过滤器模式：将AI审查配置为PR的必通过检查（通过状态检查）。只有当AI审查通过（或至少没有提出高优先级问题）时，才允许团队成员进行人工审查。这可以过滤掉明显的低级错误，让人工审查者能更专注于业务逻辑和架构设计。
2. 并行顾问模式：AI审查与人工审查同时进行。团队成员在收到PR通知后，可以同时看到AI的评论和同事的评论。AI的评论常常能提供不同的视角，启发人工审查者发现更深层次的问题。
3. 新人导师模式：对于团队新人，AI审查是一个绝佳的学习工具。它不仅能指出代码中的问题，还能解释原因并提供改进方案，相当于一个随时在线的、耐心的代码教练。
4. 专项审计模式：定期（如每周）对所有合并的PR用security或performance类型重新跑一次审查，作为一种持续性的代码质量审计，发现那些可能在合并时被遗漏的潜在风险。

5.2 当前局限性客观看待

尽管强大，但必须清醒认识到AI审查的局限性：

• 并非全知全能：LLM是基于模式识别的，它可能无法理解极其复杂的业务逻辑或特定领域的深层约束。它提出的“最佳实践”建议有时在特定上下文中并不适用。
• 存在“幻觉”可能：在极少数情况下，AI可能会误解代码意图，或提出一个看似合理但完全错误的修改建议（例如，建议使用一个不存在的API）。对于AI的建议，尤其是涉及重大逻辑变更的，必须由开发者进行最终判断和验证。
• 无法运行测试：它只能静态分析代码Diff，无法实际执行你的单元测试或集成测试来验证修改是否正确。
• 成本与延迟：对于大型PR，API调用会产生费用，并且审查过程会有几秒到几十秒的延迟，不适合对即时性要求极高的场景。
• 上下文有限：它主要分析本次PR的Diff，对项目整体的架构、历史决策和团队约定的了解有限。

5.3 避坑指南与实操心得

1. API密钥与成本管理：

   • 分环境设置：在个人或测试仓库先用免费的API额度（如OpenAI的免费额度）进行充分测试。
   • 设置预算警报：所有主流AI API提供商都支持设置月度预算和警报，务必开启。
   • 利用max-diff-size：对于大型重构PR，Diff可能非常大。合理设置此参数（如降低）可以防止意外的高额账单。更好的做法是，鼓励开发者将大型功能拆分成多个小的、聚焦的PR。

2. 审查噪音处理：

   • AI有时会提出过于严格或与团队风格不符的建议（如对某个缩写变量名的命名建议）。团队可以共同决定哪些类型的建议可以忽略，并将其总结成规则。Action本身不支持忽略规则，但你可以引导团队成员理性看待AI评论，将其视为“建议”而非“命令”。
   • 对于反复出现的、团队认为不必要的警告，可以考虑在代码中添加相应的注释来“教育”AI，但这并非百分百有效。

3. 模型选择策略：

   • 日常审查：使用性价比高的“快速”模型，如gpt-4o-mini,claude-3-haiku。它们对大多数代码风格和常见问题已经足够。
   • 关键审查：对于安全、核心架构或复杂算法的修改，切换到更强大的“智能”模型，如gpt-4o,claude-3-5-sonnet。它们推理能力更强，能发现更隐蔽的问题。
   • 定期实验：AI模型更新很快，定期测试新模型在你们代码库上的表现，可能会有意外收获。

4. 与现有工具链结合：

   • 不要取代Linter/Formatter：AI审查应作为ESLint、Prettier、SonarQube等静态分析工具的补充，而非替代。这些工具能更快、更确定地处理格式和基础语法问题。
   • 在CI/CD中的顺序：通常工作流应为：1. 代码格式化与Lint检查（快速失败）；2. 单元测试；3. AI代码审查；4. 人工审查。这样可以确保交给AI和人工审查的代码已经是格式整洁、通过基础测试的。

5. 培养团队的正确预期： 在引入工具前，务必和团队沟通清楚：AI审查是一个辅助工具，目标是提升效率和代码质量，而不是监视或评判开发者水平。鼓励大家以开放的心态对待AI的评论，将其视为一次学习和改进的机会。

在我个人的使用体验中，最大的收获不是它帮我找到了多少个Bug（虽然确实不少），而是它促使我在写代码时更加“自律”。因为知道有一个不知疲倦的审查员在盯着，我会下意识地避免那些我知道AI会指出的坏味道（比如使用any、写内联函数）。长期来看，这对个人编码习惯和团队代码基的整洁度都有潜移默化的提升作用。它就像一位严格的结对编程伙伴，虽然不说话，但每次提交都能给你带来新的启发。