分工方向：平台接入与后端架构
总结范围：结合前期技术手记与当前仓库实际进展

一、项目背景与总体进度

       CodeGuard AI 做的是一件很具体的事：面向 GitHub 的 Pull Request，做一个真正意义上的代码审查助手——在 PR 从开到合的过程里，把事件接进来、把审查任务编排好，再走静态分析、上下文提取和大模型辅助，最后落到结构化结论、评论草稿和人工确认发布上。它产出的东西应该是有据、可追踪、能和人一起决策的，而不是提供一些废话。

        就我目前的内容来说，项目早就不是搭个能跑的demo了。最早那一版更像首版可跑通的 MVP：Webhook 进来能建任务，异步流水线能转起来，管理后台以读为主，先把闭环讲圆。往后的代码和 CHANGELOG 又在往平台化走：身份登录、GitHub 真实接入、团队和仓库怎么绑、规则和技能怎么治、运维和统计怎么摆上台面。我自己的感受是：审查那条主心骨已经通了，接下来需要完成的，是怎么从能演示挪到能接真环境、能一起协作治理、最后还能验收和观测。

---

二、本人分工与已完成工作概述

       我负责的是平台接入与后端架构。把它和代码审查助手这条主线放在一起想，其实很直白：我得先把 GitHub 上的 PR 事件安全、稳定地变成系统里能执行的一条审查任务，再把重活从 HTTP 里剥离出去，后面无论是静态分析、模型还是评论回写，才有一条统一的跑道可走。

      对于我完成的工作，大概能够总结出以下方面的内容：

      工程骨架和 API 形态
      我用的是 FastAPI + SQLAlchemy + Pydantic + Celery 这一套，把收事件和跑审查拆开；再用 GitProvider 这类抽象把 GitHub 和 Mock 隔开，没有凭据也能把整条链路跑完。因为对于AI助手首先要明确一个点：助手得先可靠进单，再谈智能——进单不稳，后面全是虚的。

      GitHub 侧接入和联调环境
      Webhook 到底打哪个路径，要看 API_V1_PREFIX；.env 里 GITHUB_*、GIT_PROVIDER_MODE 这些键我也来回对过很多遍。本地为了能让 GitHub 真推到笔记本上，穿透、端口、HTTPS 一类的事也没少折腾。体会很深的一点是：卡人的往往是网络、配置和事件 JSON ，这些内容往往不太符合真实情况。

      可信入口：签名、头字段和幂等
      我从直接把 JSON 绑进模型慢慢挪到先拿 raw_body，再对 X-Hub-Signature-256；再往后又不得不认真看待 X-GitHub-Delivery、X-GitHub-Event、重放时间窗这些东西。服务层里配合 GitHubWebhookDelivery、payload 指纹去做重复投递跳过，审计里会出现 webhook.duplicate_skipped 一类记录。我的想法很简单：要是分不清真假 GitHub、分不清是不是同一条投递在重试，后面的 findings 和评论就全是错误，指标根本没法完成。

      异步执行和资源调度
      开发时我长期开着 CELERY_TASK_ALWAYS_EAGER，图省事；真要模拟线上，就得切回 Redis Worker。切过去之后，prefetch、软超时、硬超时、compose 里的并发环境变量、fair 调度，全都会从纸面配置变成队列为什么不动这种现场问题。我的结论是：对于助手类任务，HTTP 必须短，队列必须可控；演示能跑和多来几次 PR 推送还能扛完全不是一回事。

---

三、工作对项目整体方向的意义和作用

从功能演示往能接入的产品挪一小步
      平台接入和后端架构，本质上决定的是：GitHub 那边的流程，能不能无损地嵌进我们内部的审查流程。入口收紧一点、异步稳一点，项目才有机会从单机脚本走向团队可用；否则后面做得再花，也只是停留在表面的玩具项目。

关于项目的集成和协作
      审查流水线、规则技能、草稿评论、发布动作，全都得靠统一的任务对象和能翻得出来的审计。我这边把接入和建任务这条链兜住，等于给做 AI、做分析、做前端的发了一套同一个订单号和同一份现场记录，联调时少很多对接时的问题。

和产品想讲的故事对齐
      助手最怕三件事：误报、重复、说不清为什么。幂等和审计让同一次 PR 事件在系统里说得清、对得上账；异步和超时即使会让输出变慢，但也不会使得平台出问题。

---

四、对于项目技术思想与理解

安全和对齐，得优先于堆功能
      签名没收口、重复投递没想清楚就往里加业务，数据层迟早堆出一堆幽灵任务和重复评论，后面返工只会更痛，不如在入口一次性把该收紧的收紧。

字节级契约和框架顺手，有时候会打架
      FastAPI 可以直接绑定模型，但 Webhook 签名吃的就是原始 body。这时候只能承认：平台协议偶尔要压框架默认一头，不能图省事。

异步系统不可观测，就不算做完
      Celery 不只是 delay 一下完事；得靠超时、并发、队列表现，再加上审计，才能回答系统变慢的原因到底是什么。

Mock 和真实必须同时落实
      Mock 让教学和验收能重复；真实模式让东西能落地。架构里留着切换点，是课程项目和真环境之间很现实的折中，我越来越觉得这不是妥协，而是正经工程判断。

---

五、真实实操体会

      联调花掉的时间，经常比写接口还多：穿透、环境变量、事件类型、GitHub 重试和重复投递，出现的问题使人焦头烂额
      日志和审计在我眼里差不多是第二套源代码——没有 duplicate_skipped 这类记录时，很难和 GitHub delivery 对时间线。
      从 eager 换到 broker，会把一堆以前藏住的假设全抖出来：prefetch、长任务占满 worker、并发默认值太小，都是真跑队列才看得见。
      对照新旧两份仓库时，我能很直观地看到项目在长高：入口从薄变厚，模型从单条业务线扩到多实体和权限依赖。

---

六、后期工作目标

6.1 我还需要完成的事

项目和仓库治理的接口别留半截
Webhook 自动建项很好，但管理端该有的一整套——CRUD、绑定状态、webhook 状态——该补的还得补，为多项目接入打好基础。

PR 拉取和评论回写保证稳定性
真令牌、真权限边界下面，重试、降级、错误分类都得处理；如果最后真要交发布成功率一类指标，口径和最小能看的面板得提前想。

测试和回归别拖成尾巴
补链路型的集成测试：带签名的 Webhook、重复 delivery、入队、worker 跑关键路径，最好还能和前端、VS Code 扩展那条演示脚本对齐。

6.2 项目集成

跟做AI / Prompt / Finding 的同学对齐：任务载荷和快照字段别老变，不然他们下游很难收。
跟做静态分析和解析的对齐：worker 超时和重试策略得盖得住最坏耗时
跟前端和插件的对齐：鉴权头、错误码、连接状态展示，得和后端状态机是同一套显示，不能出现看似绿了实际上没有跑通的问题

6.3 测试和质量

单测：配置分支、签名开关、幂等分支，纯逻辑先钉住。
集成测：模拟 GitHub 的头和 body，成功、缺签、错签、重复 delivery 都跑一遍。
端到端：真仓库或沙盒 + 真 worker，从 PR 进来到草稿能看见，全程留痕。
性能和稳定性：在可控并发下看看队列深度和耗时分布，再决定要不要加 worker、调超时。

---

七、结语

       前期我在平台接入与后端架构上花的时间，说到底是在抠代码审查助手的第一条外线：让 GitHub 上的 PR 事件，能稳、可信、可重复地变成内部的审查任务；又让异步执行在资源和超时的约束下还能继续跑下去。没有这条线，后面再谈智能和平台化都不可能。

      后半程我会继续注重真实接入、治理和观测、测试和联调，使得助手在日常项目中真实可用