PR Agent工程实践：自动化代码审查与AI成本控制

过去一年技术圈经常出现一个口径Uber 用 Agent 接管了大量代码 PR 工作同时 AI 账单零增长。这个说法没有公开完整实现细节工程上的价值不在那个“70%”本身而在它背后的约束条件自动化覆盖越高AI 成本越不能失控。这里要解决的真实问题不是“用不用 AI 审查 PR”而是“如何设计一个能稳定接住团队日常 PR 工作流、又能把单 PR 成本压住的 Agent”。我将围绕这个目标写一篇可落地的工程实践长文先拆解 AI 处理 PR 的工作链路再搭建最小可运行的 PR Agent然后重点讲成本计量、路由、缓存、预算降级最后补上 Webhook 接入、排错思路和生产环境建议。读者需要有 Python 基础了解 Git 和 GitHub PR 的基本流程。1. 先拆解“AI 处理代码 PR”到底是什么以及零增长为什么难1.1 拆开 PR 生命周期哪些环节可以交给 Agent一个 PR 从创建到合并并不是单一动作。它至少包括补全描述、识别改动范围、评估影响面、生成测试建议、静态审查、检查合并条件、跟进修复、合并后发布说明。不同环节的风险和自动化程度差异很大。PR 阶段人工操作示例Agent 可以做什么自动化程度风险创建 PR写标题和描述基于 diff 自动生成摘要和测试说明高低识别改动范围判断改动涉及哪些模块按路径分析影响面标注相关模块高低生成测试建议为关键逻辑补测试给出测试用例草案和边界条件中高中代码审查逐文件检查逻辑、安全、性能基于 diff 输出风险提示中中高修改反馈回复评论并补丁给出修复建议甚至生成补丁中中高合并判断人工确认 CI 和审批结果读取 CI 状态和审批输出准备标记低高发布说明汇总变更基于合并后的 commit 生成说明高低从这个表格能看出Agent 更适合先接“描述生成、影响面分析、测试草案、静态审查”这些低风险任务。它可以直接做但结果要可视化让人能回溯。至于是否合并、是否批准必须保留人的决策权。1.2 70% 覆盖率与“零增长”对应的是单 PR 成本下降很多人会把“70% PR 由 Agent 处理”理解成“70% 的 PR 由 AI 合并”这是两码事。更合理的理解是有 70% 的 PR 流程中Agent 自动完成了部分环节例如生成描述、扫描 diff、输出建议、补充测试用例人工只需要看过结果后决定采纳与否。如此定义下覆盖率才可能做到很高因为低风险任务适合自动化。真正的工程难点在于“AI 账单零增长”。如果 Agent 处理 100 个 PR 要花 100 美元那么处理 300 个 PR 花 300 美元不算失控但这也不是零增长。零增长意味着PR 处理量上升时账单保持平稳。这等价于单 PR 平均 AI 成本必须下降。cost_per_pr sum(每次模型调用的 input token 费用 output token 费用)要降低单 PR 成本不能只靠换便宜模型还要控制上下文体积、减少重复调用、引入缓存、限制重试次数。否则 PR 量越大token 消耗越接近“全量 diff 多轮分析 重复重试”成本增长会快于 PR 增速。1.3 Agent 不是自动合并机器人边界要先画清楚接入 Agent 之前团队必须明确边界。默认情况下Agent 的产出应该是评论、建议、补丁草稿、状态标记而不是直接合并代码。Agent 一旦拥有合并权限即使一次误判也会污染主干历史。推荐的分级策略低风险改动Agent 自动生成描述、补充测试建议并打上 “agent: reviewed” 标记。中风险改动Agent 输出审查意见等待至少一名 reviewer 确认。高风险改动Agent 只提供静态分析和影响面描述人工必须逐条确认。这样“接管”的是重复劳动而不是取消人的最终判断。2. 搭一个最小 PR Agent环境、目录和三种触发方式2.1 环境准备和依赖版本检查最小案例可以使用 Python 3.11、GitHub REST API、OpenAI SDK。实现思路基于通用 LLM API不绑定厂商所以代码中会把模型名、API Key、模型价格都放到配置里。组件推荐配置说明Python3.11使用 dataclass、类型注解和最新 requests 兼容性GitHub 访问凭证GitHub App 或 classic token需要 pull requests 和 issues 的读取、评论权限LLM API KeyOpenAI-compatible endpoint示例使用 openai SDK实际可按供应商调整本地调试命令行传入 PR 编号避免一上来就接入 Webhook代码托管GitHub思路同样适配 GitLab接口路径不同先创建虚拟环境并安装依赖。下面示例用于说明思路实际项目要结合自己的包名、路径和版本调整。mkdir pr-agent cd pr-agent python -m venv .venv source .venv/bin/activate pip install requests openai python-dotenv把安装结果导出到 requirements.txt 并锁定具体版本。不同版本的 SDK 接口会有差异例如response_format参数、timeout参数可能不同落地前要确认依赖版本。2.2 项目目录把“任务编排”和“模型调用”分开最小项目不建议把所有逻辑塞进一个文件。目录可以这样拆pr-agent/ ├── main.py # 入口串联 GitHub 和 LLM ├── github_client.py # 读取 PR、发布评论 ├── llm_client.py # 模型调用和 JSON 解析 ├── cost_model.py # token 计量和费用估算 ├── config.py # 环境变量和模型路由配置 ├── prompts/ │ └── review_system.txt # 审查系统提示词 ├── tests/ │ └── fixtures/ │ └── example.diff # 本地测试样例 ├── requirements.txt └── .env.example这里最关键的取舍是“任务编排”和“模型调用”分离。Pr Agent 会随着需求膨胀逐渐加入去重、缓存、预算降级、审计日志。如果模型调用散落在 main 流程里后面很难改路由策略。2.3 三种触发方式本地调试、Webhook、定时拉取触发方式适用场景优点注意点本地命令行开发调试可以传一个 PR 编号直接复现不模拟真实事件时序GitHub Webhook生产环境PR 创建后立即处理需要公网回调、签名校验、幂等去重定时拉取临时方案或受限网络部署简单有延迟不能实时响应最小案例先走本地命令行。Webhook 放到第 5 节讲。export GITHUB_REPOyour-org/your-repo export PR_NUMBER42 python main.py这样可以在不配置回调地址的情况下验证完整链路读取 diff、调用模型、发布评论。3. 写核心链路从 diff 读取到结构化审查结果3.1 用 GitHub API 读取 PR 的 diff先做体积控制先写一个github_client.py负责获取 PR 的 diff 文本。这里直接用 GitHub 的 diff 响应头会得到一个纯文本 diff。生产环境更推荐按文件读取/pulls/{number}/files因为可以按文件分批处理。import os import requests GITHUB_TOKEN os.getenv(GITHUB_TOKEN) GITHUB_API https://api.github.com def fetch_pr_diff(repo: str, pr_number: int, max_chars: int 60_000) - str: 获取一个 PR 的 diff 文本并限制输入体积。 headers { Authorization: fBearer {GITHUB_TOKEN}, Accept: application/vnd.github.v3.diff, X-GitHub-Api-Version: 2022-11-28, } url f{GITHUB_API}/repos/{repo}/pulls/{pr_number} resp requests.get(url, headersheaders, timeout30) resp.raise_for_status() diff_text resp.text if len(diff_text) max_chars: # 生产环境更推荐按文件分批读取而不是直接截断。 # 截断会丢失后半段信息可能漏掉高风险问题。 return diff_text[:max_chars] \n... [diff truncated] return diff_text这里的关键点是max_chars。大多数小改动的 diff 不超过几 KB但一个大型 PR 可能产生几十 KB 甚至几百 KB 文本。直接把完整 diff 塞进 prompt不仅贵还会让模型注意力分散。先限制输入再在后续版本中改为按文件分析。3.2 Prompt 设计让 Agent 先规划再输出 JSONAI 审查 PR 最常见的失败是输出不稳定。所以 prompt 要约束输出结构。系统提示词里明确角色、范围、输出格式并禁止模型写出“看起来合理但无法验证”的结论。你是一个资深代码审查助手。 你只负责审查用户提供的 PR diff不假设仓库外信息。 先列出改动文件再判断高风险问题最后输出 JSON。 JSON 格式必须如下 { summary: PR 整体摘要不超过 200 字, files: [ {path: src/main.py, change_type: modified} ], issues: [ { path: src/main.py, line: null, severity: high, title: 问题标题, suggestion: 修复建议 } ] } 如果某个问题没有精确行号line 使用 null。 不要输出 JSON 之外的文字。为什么要用 JSON 而不是让模型自由发挥因为后续要自动化路由高风险问题可能进入深度审查低风险问题只做提示。结构化的输出能降低解析成本也能减少模型在无关内容上的 token 消耗。3.3 调用模型并解析结构化结果llm_client.py用 OpenAI SDK 完成调用。模型名、temperature、timeout 都要做成配置。import json import os from openai import OpenAI SYSTEM_PROMPT open(prompts/review_system.txt, encodingutf-8).read() client OpenAI(api_keyos.getenv(OPENAI_API_KEY)) def review_diff(diff_text: str) - dict: 调用模型审查 PR diff并解析为 JSON dict。 resp client.chat.completions.create( modelos.getenv(REVIEW_MODEL, gpt-4o-mini), messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: fdiff:\n{diff_text}}, ], temperature0.2, response_format{type: json_object}, timeout60, ) content resp.choices[0].message.content return json.loads(content)需要注意几点temperature调到 0.2 而不是 0是防止模型输出过于死板。代码审查场景需要一定灵活性。response_format不是所有模型都支持。如果你的模型不支持 JSON mode就要在后端增加一个容错解析函数。timeout必须设置。长时间无响应会导致 Webhook 连接耗尽。这里的 API Key 不要硬编码统一从环境变量读取。3.4 把审查意见作为 comment 写回 PR最小闭环可以先使用 issue comment 接口把结果以 Markdown 文本写到 PR 页面。这样做最简单副作用是评论层级不够精致。后续要升级为 review thread让意见关联到具体行。import json import os import requests GITHUB_TOKEN os.getenv(GITHUB_TOKEN) GITHUB_API https://api.github.com GITHUB_REPO os.getenv(GITHUB_REPO) PR_NUMBER int(os.getenv(PR_NUMBER)) def post_pr_comment(repo: str, pr_number: int, body: str) - None: 把 Agent 输出写入 PR 的 issue comment。 headers { Authorization: fBearer {GITHUB_TOKEN}, Accept: application/vnd.githubjson, X-GitHub-Api-Version: 2022-11-28, } url f{GITHUB_API}/repos/{repo}/issues/{pr_number}/comments payload {body: body} resp requests.post(url, headersheaders, jsonpayload, timeout30) resp.raise_for_status() def render_markdown(result: dict) - str: 把结构化审查结果渲染成 Markdown 评论。 lines [ ## AI Review Summary, , result.get(summary, ), , ### Issues, , ] for issue in result.get(issues, []): lines.append(f- **[{issue[severity]}] {issue[path]}**: {issue[title]}) if issue.get(line): lines.append(f - 建议行号{issue[line]}) lines.append(f - {issue[suggestion]}) return \n.join(lines)这一段的意义是形成“输入 diff - 模型分析 - 结果落盘”的最小闭环。先把评论写出去方便人工看到 Agent 的判断再做优化。3.5 把流程串成最小闭环在main.py中串联三部分import os import sys from github_client import fetch_pr_diff, post_pr_comment, render_markdown from llm_client import review_diff def main() - None: repo os.getenv(GITHUB_REPO) pr_number int(sys.argv[1]) if len(sys.argv) 1 else int(os.getenv(PR_NUMBER)) diff_text fetch_pr_diff(repo, pr_number) result review_diff(diff_text) markdown_body render_markdown(result) post_pr_comment(repo, pr_number, markdown_body) print(fPR #{pr_number} review done.) if __name__ __main__: main()运行之后PR 页面会出现一条 AI 审查评论。这条链路还只是“单次调用模型”。真实生产系统中这个流程需要加入成本计量和路由控制否则很容易在几十个 PR 并发时触发高额账单。4. 控制 AI 账单计量、路由、缓存和预算降级4.1 成本不是线性增长token 放大的四个环节单 PR 的 token 消耗往往不是一次调用决定的。它可能被以下四个环节放大diff 过大输入 token 随改动量和上下文裁剪策略一起增长。多轮调用一个 Agent 读完 diff还要分析文件再生成总结每轮都会重复输入部分内容。重试模型返回格式错误、网络超时、业务判断不明确都会触发多次调用。日志污染把完整请求参数、响应内容、甚至 API Key 打日志不仅不安全还会增加存储和观测成本。在代码审查场景中一个 1000 行增删的大 PR如果一次调用塞入完整 diff可能消耗上万 token。如果再用“先生成摘要再逐文件审查再生成总结”的方式每层都重复传入相同上下文token 会快速膨胀。4.2 先给 Agent 装一个计量表预算治理的前提是计量。cost_model.py里维护模型价格并计算每次调用的费用。价格仅为示意实际以供应商公布的计费为准不同模型、不同区域和账号可能有差异。from dataclasses import dataclass # 示意价格每百万 token 的美元价格请按真实账单维护。 MODEL_PRICES { gpt-4o-mini: {input: 0.15, output: 0.60}, gpt-4o: {input: 2.50, output: 10.00}, } dataclass class CostRecord: pr_number: int model: str prompt_tokens: int completion_tokens: int cached_tokens: int 0 def cost_usd(self) - float: 按 token 数估算一次调用的成本。 if self.model not in MODEL_PRICES: raise KeyError(fmissing price for {self.model}) price MODEL_PRICES[self.model] input_tokens self.prompt_tokens - self.cached_tokens return input_tokens / 1_000_000 * price[input] \ self.completion_tokens / 1_000_000 * price[output]实际项目中每次模型响应都会返回usage.prompt_tokens、usage.completion_tokens。把这些字段追加到一个数据库表或日志表就能统计单 PR、单团队、单日成本。4.3 三层降本模型路由、重复代码缓存、重试限制第一层是模型路由。小文件、低风险文件用便宜模型分析只有发现高风险或大型改动时才调用更强模型。def should_deep_review(diff_text: str, cheap_result: dict) - bool: if cheap_result.get(risk_level) high: return True for file_info in cheap_result.get(files, []): if file_info.get(additions, 0) 200: return True return False路由参数可以做成配置{ model_router: { cheap_model: gpt-4o-mini, deep_review_model: gpt-4o, deep_review_threshold_additions: 200, high_risk_keywords: [auth, payment, sql, token] } }第二层是缓存。相同 base 和 head 的 PR 重复分析没有意义。可以用repo:base_sha:head_sha作为分析结果的缓存键。GitHub 在 PR 更新时head_sha会变化所以缓存不会挡住新提交。import hashlib def diff_cache_key(repo: str, base_sha: str, head_sha: str) - str: raw f{repo}:{base_sha}:{head_sha} return hashlib.sha256(raw.encode(utf-8)).hexdigest()第三层是重试限制。模型输出解析失败时可以重试一次但不要无上限重试。建议同一 PR 最多重试 1 到 2 次超过后只评论“Agent 暂时无法解析结果请人工检查”而不是继续烧 token。4.4 预算上限和降级策略预算不能只靠事后统计要在调用前判断。配置一个 JSON 预算规则{ budget_control: { max_cost_per_pr: 0.5, max_daily_agent_cost: 10, fallback_mode: summary_only, alert_webhook: https://example.com/alert } }对应代码逻辑def decide_review_mode(pr_number: int, current_used: float) - str: cfg load_budget_config() if current_used 0.1 cfg[max_cost_per_pr]: return summary_only if get_today_cost() cfg[max_daily_agent_cost]: return summary_only return full_review降级到什么程度要提前约定。可以在预算超限后Agent 只生成摘要不发详细审查也可以“fail closed”直接通知人工。两种选择都有代价前者可能漏掉模型尚未检查的高风险问题后者会让自动化服务中断。推荐先做 summary_only并把预算告警发到监控群让运维尽早介入。5. 接入 Webhook 后的安全护栏鉴权、去重和最小权限5.1 Webhook 事件类型和请求签名校验生产环境中PR Agent 最常用 GitHub Webhook 触发。Webhook 配置项里要关注的三个点事件类型、Payload URL、Secret。事件选择pull_requestaction 选择opened和synchronize。不要监听所有 action否则编辑标题、关闭 PR 也会触发 Agent浪费 token。GitHub 会用 Secret 对请求体做 HMAC-SHA256 签名。收到请求后必须先校验签名防止伪造请求。import hashlib import hmac def verify_signature(payload_body: bytes, signature_header: str, secret: str) - bool: 校验 GitHub Webhook 请求签名。 expected sha256 hmac.new( secret.encode(utf-8), payload_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature_header, expected)如果使用 FastAPI 或 Flask在路由入口调用这个函数。校验失败直接返回 401不进入业务逻辑。5.2 去重、并发锁和状态标记Webhook 不是绝对可靠的。GitHub 可能因为网络问题重发同一事件服务端也可能在重启后重复消费。因此必须做幂等。最简单的幂等方案给每个 PR 的每次 commit SHA 保存一个处理记录。处理前先查记录处理成功后写入。没有数据库时可以先给 PR 打一个 label例如agent:reviewed后续任务检查该 label 是否存在。但 label 方案有并发窗口两个请求同时检查时都可能通过生产环境建议用 Redis 锁或数据库唯一键。lock_key fpr-agent:lock:{repo}:{pr_number} if redis_client.set(lock_key, 1, nxTrue, ex300): try: process_pr(repo, pr_number) finally: redis_client.delete(lock_key) else: print(another worker is processing this PR)nxTrue表示只有 key 不存在时才能写入成功这是最简单的分布式锁。过期时间 300 秒是为了防止进程崩溃后锁永远不释放。5.3 最小权限与人工审批闸门接入生产环境前必须把 Agent 的权限收敛到最小范围。即使 Agent 需要写回评审意见也不需要仓库管理员权限。能力推荐权限说明读取代码和 diffcontents: read必须写 PR 评论pull_requests: write必须写 issue commentissues: write如果使用 issue comment 接口打 labelissues: write / pull_requests: write用于幂等标记合并 PR不授禁止 Agent 自动合并修改分支contents: write仅当需要自动提交补丁时才授予如果 Agent 是通过 GitHub App 接入还要关闭 App 的不必要权限。权限越大被攻击或被误用的风险越高。人工审批闸门不一定要改代码而可以通过分支保护规则实现分支要求至少一个 maintainer 批准Agent 评论只作为辅助。这样即使 Agent 给出“可以合并”的标记也不会突破合并保护。5.4 生产环境上线前的配置检查清单Webhook Secret 已配置在环境变量不写进 Git 仓库。GitHub Token 或 GitHub App 私钥只保存到密钥管理服务。服务能处理 Webhook 超时和重试不重复消费同一事件。日志不打印完整 API Key 和完整 diff。每个 PR 有成本记录预算超限会告警。模型调用有重试上限不会无限循环。分支保护规则未给 Agent 合并权限。6. 常见问题排查现象、根因和修复清单遇到问题先按顺序排查输入是否正常、事件是否到达、权限是否够用、依赖版本是否匹配、配置是否生效、模型返回是否符合预期、日志有没有异常。下面是四个高频问题的经验。问题现象常见原因检查方式处理建议Webhook 没触发Agent 完全没运行GitHub App 未订阅对应事件或回调地址不通查看 GitHub Webhook 的 Recent Deliveries确认监听pull_request修复回调网络模型返回内容无法解析成 JSON模型不支持 JSON mode或 prompt 约束不足打印原始content和报错堆栈增加容错解析重试不超过 2 次同一 PR 被评论多次或同一问题反复出现没有幂等键Webhook 重发或并发消费查看服务日志中处理记录用 PR 的 head SHA 处理状态去重AI 账单增速比 PR 增速更快diff 过大、重试太多、模型路由失效查看单 PR token 和费用统计启用缓存、限制 diff 大小、收紧重试次数6.1 Webhook 没触发Agent 完全没运行现象是 PR 创建后没有任何评论日志里也没有请求记录。先看 GitHub 仓库 Settings - Webhooks - Recent Deliveries确认事件是否到达服务器。如果状态码是 404说明服务地址或路径不对如果是 500需要看服务错误日志如果是 401先检查签名校验。本地调试阶段不要依赖 Webhook直接命令行传入 PR 编号。Webhook 只负责把“事件变成任务”真正的逻辑在任务处理函数里。这样网络问题不会阻塞功能调试。6.2 模型返回内容无法解析成 JSON在接入不支持response_format的模型时模型可能会在 JSON 外面加 Markdown 代码块或输出一段解释文字。解析函数要兼容这些情况。import json import re def parse_json_like(text: str) - dict: if text.startswith(): text re.sub(r^(json)?, , text).strip() text text.rstrip().strip() return json.loads(text)更稳妥的做法是先让模型只输出 JSON不用任何额外解释如果还是失败再尝试抽取最外层花括号。两次失败后进入降级状态不再重试。6.3 同一 PR 被评论多次或同一问题反复出现原因通常是没有幂等设计。Webhook 在请求超时时会重试多个 worker 也可能同时消费任务。处理前先检查是否已经为这个 PR 的 head SHA 生成过结果。可以在数据库里记录pull_request_id head_sha status状态为 done 就不再处理。每次新提交会有新的 head SHA所以不要只用 PR 编号去重。否则新提交触发的分析会被旧状态挡住。6.4 AI 账单增速比 PR 增速更快先看费用统计是按 PR 还是按调用。如果单 PR 成本波动很大重点检查 diff 大小和模型路由是否失效。比如一个大 PR 没有按文件拆分也没有切成多个段落一次调用就把整段 diff 塞进 prompt成本自然高。日志排查重点看三个字段prompt_tokens、completion_tokens、model。如果大部分费用集中在一个模型上而它处理的是简单文件说明路由没有生效。7. 从实验到工程效能平台指标、扩展和落地清单7.1 学习环境和生产环境的差异学习环境可以单脚本运行生产环境要按服务化方式改造。这不仅是代码结构差异也是运维保障差异。维度学习环境生产环境触发方式命令行手动运行Webhook 异步任务队列凭证管理本机 .env密钥管理服务不落磁盘幂等处理可忽略必须实现否则重复评论和费用成本记录控制台打印数据库记录 监控告警容错策略失败后手动重跑有界重试 降级日志打印到终端结构化日志脱敏后存储审计无保留每次调用的请求 ID、PR、模型、token7.2 用四个指标评估一个 PR Agent 是否值得继续投入只看“处理了多少 PR”不够还要看质量、成本和人工负担。PR 平均处理时间Agent 从事件触发到完成第一轮评论的耗时P95 应稳定在 1 分钟内。Agent 自动完成率不需要人工修改摘要、分类和低风险建议的比例。单 PR 平均成本按周统计观察是否随模型路由优化而下降。误报率和回滚率Agent 提出的问题中有多少是误报采纳 Agent 建议的 PR 有没有增加回滚。如果 Agent 自动完成率高