29-模块四-AI代码审核实战 第29讲-Git 工作流集成 - Webhook 触发 PR 评论 审核状态管理

本讲目标：把 CodeSentinel 从「本地脚本」接入 GitHub/GitLab 的真实事件流；掌握 Webhook 验签、PR/MR diff 拉取、行内评论与摘要评论、提交状态（commit status/check）更新；实现平台适配层GitPlatformAdapter与ReviewStatusManager状态机；交付 FastAPI Webhook 端点与可测试的 httpx 客户端示例。本讲强调安全默认值：先验签，再执行业务。建议准备一枚测试仓库与 Personal Access Token 做联调。开场：没有托管平台集成，审核只是「自言自语」自动代码审核的最终用户不是机器，而是正在协作的人类工程师。工程师最常停留的工作界面，通常是 Pull Request 或 Merge Request 页面：他们在这里阅读 diff、回复评论、查看检查项是否通过、决定是否合并。若你的 CodeSentinel 只会在终端打印 findings，它就很难进入团队的「默认工作流」，最终会被边缘化为少数爱好者的玩具。本讲解决的是平台化接入问题：当有人打开或更新 PR，托管平台向你推送事件；你验证这是平台发来的真实请求而不是伪造攻击；你用平台 API 拉回可审核的变更内容；你把审核结果以评论与状态的形式写回 PR，让合并门槛可以依赖这些信号。你会同时看到 GitHub 与 GitLab 在概念上高度相似、在细节上处处不同：事件名不同、鉴权不同、评论 API 不同、状态检查字段不同。CodeSentinel 用适配器隔离差异，用状态机管理审核生命周期，避免把 if/else 平台分支写满业务核心。完成本讲后，你应能向团队说明：Webhook 为什么是推送模型、为什么必须验签、以及如何把「pending → running → success/failure」映射到研发可理解的合并策略。下面先给出端到端事件流，再展开安全、API 与完整 Python 实现。在工程组织层面，本讲还回答一个关键问题：平台集成要不要做在审核核心逻辑里？答案是不要。集成层负责「外部世界如何进来、结果如何出去」，审核核心负责「给定变更内容如何判定」。边界清晰后，你可以把同一套审核核心接到 GitHub、GitLab、Gerrit，甚至接到内部代码托管；也可以把 webhook 暂时替换为「CLI 手动触发」而不改规则引擎。很多团队失败的原因是把这些层搅在一起，最后任何平台字段变更都会牵动规则代码，维护成本指数上升。此外，你要建立对「失败模式」的共同语言：验签失败、API 429、权限不足、评论定位非法、以及任务重试导致的重复评论，分别对应不同的运维动作。把失败分桶后，On-call 才不会每次靠猜。下面先给出端到端事件流，再展开安全、API 与完整 Python 实现。全局视角：Webhook → 审核 → 回写（Mermaid）平台 REST APIReviewPipeline\n(下一讲串联)GitPlatformAdapterCodeSentinel\nFastAPI公网入口\n(API Gateway)GitHub/GitLab平台 REST APIReviewPipeline\n(下一讲串联)GitPlatformAdapterCodeSentinel\nFastAPI公网入口\n(API Gateway)GitHub/GitLabPOST /hooks/github转发原始 body + headers验签/令牌校验parse_event(pr_meta)GET pull/files / diffdiff + refsenqueue_review(job)ReviewReportPOST review commentsPOST check/statusUI 展示评论/检查项PR 审核生命周期：状态机（Mermaid）