一、问题背景
在 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_factory=list) concerns: list[str] = Field(default_factory=list) next_steps: list[str] = Field(default_factory=list) class LLMReviewOutput(BaseModel): findings: list[GeneratedFinding] summary: GeneratedSummary这样前端进入审查任务详情页时，不需要直接面对一堆零散评论，而是可以先看到整体结论，再展开具体问题。
四、为什么这样做
结构化 Finding 是后续所有能力的基础。如果没有统一结构，系统只能展示 AI 文本，不能做治理。
有了结构化 Finding 以后，后端可以落库，前端可以筛选和分组，质量门禁可以计算风险，评论中心可以生成草稿，规则引擎可以继续调整严重程度和建议内容，审计日志也能追踪问题来源。
五、实际效果
这一阶段完成后，CodeGuard AI 不再是简单的 AI 问答页面，而是开始具备审查平台的数据基础。
AI 生成的问题可以被保存、过滤、去重、排序、确认和发布。后续的技能执行、上下文分析、候选校验、规则治理和评论草稿，都是基于这套结构继续往下做的。
六、小结
这一阶段让我意识到，AI 审查系统的关键不是让模型说得更多，而是让模型说出的内容能被系统稳定处理。
结构化 Finding 把 AI 输出从“能看”变成了“能管”，这是整个审查链路能够继续扩展的前提。
