一、问题背景在 CodeGuard AI 项目早期系统已经可以把 PR 变更交给 AI 分析但很快遇到一个工程问题如果模型只返回一段自然语言文本系统后续很难继续处理。自然语言回答可以阅读但不能稳定落库也不方便前端按文件、严重程度和状态展示更无法支撑质量门禁、评论草稿和审计追踪。一个真正的审查平台不能只把 AI 回答贴出来而要让 AI 输出成为后端可以治理的数据。二、我的思路我把 AI 审查结果抽象成结构化 Finding。每个问题都必须包含文件路径、行号、标题、严重程度、问题分类、描述、修复建议、证据、证据来源和置信度。这样 AI 输出就从“能看的一段话”变成了“能被系统继续处理的数据对象”。三、关键代码与实现讲解最核心的是先定义 AI 输出的结构。class GeneratedFinding(BaseModel): path: str title: str severity: str category: str description: str suggestion: str | None None line: int | None None end_line: int | None None source: str llm rule_id: str | None None skill_id: str | None None evidence: str | None None evidence_source: str | None None evidence_line: int | None None confidence: float | None None这段结构的重点不是字段多而是每个字段都对应后续链路中的一个动作。path和line用来决定评论能否定位到具体文件和行severity和category用来支撑前端分组和质量门禁风险计算rule_id和skill_id用来追溯问题来源evidence、evidence_source、evidence_line和confidence则为后续 verifier 做二次校验提供依据。一次审查还需要整体总结所以我又把 summary 和 findings 组合成统一输出。class GeneratedSummary(BaseModel): overview: str strengths: list[str] Field(default_factorylist) concerns: list[str] Field(default_factorylist) next_steps: list[str] Field(default_factorylist) class LLMReviewOutput(BaseModel): findings: list[GeneratedFinding] summary: GeneratedSummary这样前端进入审查任务详情页时不需要直接面对一堆零散评论而是可以先看到整体结论再展开具体问题。四、为什么这样做结构化 Finding 是后续所有能力的基础。如果没有统一结构系统只能展示 AI 文本不能做治理。有了结构化 Finding 以后后端可以落库前端可以筛选和分组质量门禁可以计算风险评论中心可以生成草稿规则引擎可以继续调整严重程度和建议内容审计日志也能追踪问题来源。五、实际效果这一阶段完成后CodeGuard AI 不再是简单的 AI 问答页面而是开始具备审查平台的数据基础。AI 生成的问题可以被保存、过滤、去重、排序、确认和发布。后续的技能执行、上下文分析、候选校验、规则治理和评论草稿都是基于这套结构继续往下做的。六、小结这一阶段让我意识到AI 审查系统的关键不是让模型说得更多而是让模型说出的内容能被系统稳定处理。结构化 Finding 把 AI 输出从“能看”变成了“能管”这是整个审查链路能够继续扩展的前提。
