打造企业级 AI 知识问答与代码评审助手：从需求到落地的完整实践

在企业级软件研发中，知识分散、代码评审效率低、业务逻辑缺陷难发现，一直是困扰团队的痛点。我们决定用 AI 来解决这些问题。

一、为什么需要这样一个助手？

在日常研发工作中，我们遇到了太多让人头疼的场景：

新人入职，面对一堆分散在 Wiki、文档、代码注释中的规范和设计，光是找资料就要花上好几天。

代码评审，依赖人工经验，质量参差不齐。现有的工具只能检查代码缺陷和风格，却对业务逻辑是否正确实现束手无策。

更让人头疼的是，新设计文档是否与已有设计兼容？需求方案是否合理？编码实现是否偏离了原始设计？这些问题往往要到上线后才会暴露。

我们需要的，是一个能理解业务、懂设计规范、能持续守护代码质量的 AI 助手。

二、产品定位

这不是一个简单的代码检查工具，而是一个完整的 AI 知识问答与代码评审助手。

它的核心能力可以概括为三个关键词：

知识 — 基于多模块知识库，让规范、设计、业务逻辑都能被快速检索和问答

评审 — 不仅检查代码缺陷和风格，更能评审业务逻辑实现是否正确

持续 — 从设计文档到需求方案，从代码提交到 Spec 验收，全程守护质量

三、核心功能模块

3.1 多模块知识库管理

知识库不是一个大杂烩，而是按知识类型划分的独立模块：

▎ 设计规范库：架构设计、接口规范、数据模型规范

▎ 代码规范库：编码规范、命名规范、最佳实践

▎ 业务逻辑库：业务规则、状态流转、业务流程

▎ 架构文档库：系统架构、模块划分、依赖关系

▎ Spec 库：需求规格说明、功能点、验收标准

每个知识库模块都有独立的审批流程，确保入库内容的准确性和权威性。

文档上传后需经过审批，审批通过后才会向量化入库，未审批的文档不会被检索到。

3.2 知识问答服务

支持自然语言问答，回答基于知识库内容，并提供引用溯源。

开发者可以直接提问："我们的订单状态流转规则是什么？" 系统会从业务逻辑库中检索并给出准确回答，同时标注来源文档。

3.3 IDEA 插件集成

在 IDEA 中右键选中代码或文件，即可触发 AI 代码评审。

评审结果直接在侧边栏展示，每个问题都可以点击跳转到对应代码行，查看修改建议。

3.4 Gerrit 自动评审

当开发者提交代码到 Gerrit 时，系统自动触发 AI 评审，并将评审报告以 Comment 形式回写到 Gerrit。

评审员在 Gerrit 中可以直接查看 AI 评审报告，辅助人工评审决策。

3.5 AI 代码评审引擎

这是整个系统的核心引擎，支持多维度评审：

▎ 代码缺陷评审：空指针、资源泄漏、并发问题等

▎ 代码风格评审：命名规范、代码格式、注释规范等

▎ 业务逻辑评审：基于业务逻辑知识库，检查代码是否正确实现业务逻辑

▎ 设计规范评审：基于设计规范知识库，检查代码是否符合架构设计

3.6 评审报告服务

评审报告支持三种格式：

▎ JSON 格式：方便 Agent 消费和自动修改代码

▎ Markdown 格式：方便人类阅读

▎ HTML 格式：方便可视化展示

每个问题都包含：问题描述、严重程度、文件路径、行号、代码片段、修改建议。

修改建议以 Unified Diff 格式输出，Agent 可以直接应用修改。

3.7 设计文档评审

上传新设计文档后，系统会自动：

▎ 从设计规范知识库检索已有设计文档

▎ 评审新设计与已有设计的兼容性

▎ 检测架构、接口、数据模型等方面的冲突

▎ 检查是否符合企业设计规范

3.8 需求方案评审

上传需求文档后，系统会评审：

▎ 技术方案的合理性和可行性

▎ 与已有设计是否存在冲突

▎ 与现有编码实现是否存在冲突

▎ 变更对现有系统的影响范围

3.9 Spec 驱动持续 Review

这是最有特色的功能之一。

当需求规格说明（Spec）细化到功能点、验收标准、业务规则层级时，系统可以：

▎ 解析 Spec，提取结构化信息

▎ 建立 Spec 功能点与代码文件的映射关系

▎ 监听代码变更，持续评审代码是否符合 Spec

▎ 检查 Spec 覆盖度：是否有功能点未实现

▎ 当代码实现偏离 Spec 时，生成告警并通知相关人员

Spec 至少需要细化到业务规则和验收标准层级，才能有效驱动代码业务逻辑评审。

四、典型使用场景

场景一：开发者本地评审

小张在 IDEA 中写完一段订单取消的代码，右键触发 AI 评审。

30 秒后，评审报告显示：

▎ 一个 Critical 问题：未校验订单状态，已发货订单不应允许取消

▎ 一个 Major 问题：退款逻辑未处理原路返回

小张根据修改建议快速修复，避免了业务逻辑缺陷。

场景二：Gerrit 自动评审

小李提交了一个 Patch Set 到 Gerrit。

5 分钟内，AI 评审报告自动回写到 Gerrit，指出代码风格问题和一处设计规范违规。

评审员王工查看 AI 报告后，快速完成了人工评审。

场景三：设计文档评审

架构师小赵上传了一份新的支付系统设计文档。

系统自动评审后发现：

▎ 新设计的接口定义与已有订单系统的接口存在冲突

▎ 数据模型缺少必要的索引设计

小赵根据评审报告修改了设计文档，避免了后续开发中的返工。

场景四：Spec 驱动持续 Review

产品经理小孙上传了一份细化的需求 Spec，包含 10 个功能点和详细的验收标准。

开发过程中，每次代码提交都会触发 Spec 评审：

▎ 第一次提交：实现了 3/10 功能点，系统提示还有 7 个未实现

▎ 第二次提交：实现了 7/10 功能点，但有一个功能点的业务逻辑偏离了 Spec

▎ 第三次提交：10/10 功能点全部实现，业务逻辑一致，评审通过

五、技术架构要点

5.1 知识库向量化

文档上传审批通过后，自动进行分块和向量化处理，存入向量数据库。

检索时支持语义检索和关键词检索，确保回答的准确性。

5.2 多 Agent 协作

复杂评审任务会分解给多个智能体协作完成：

▎ Architect 智能体：负责架构和设计规范评审

▎ Plan 智能体：负责业务逻辑和 Spec 评审

▎ Zulu 智能体：负责代码缺陷和风格评审

5.3 Agent 友好格式

评审报告采用 JSON Schema 定义，包含完整的代码 Diff、文件路径、行号范围。

Agent 可以解析报告并自动应用修改建议，大幅提升修复效率。

六、验收标准

项目的验收标准覆盖了所有核心功能：

▎ 知识问答准确率 ≥ 80%

▎ 代码缺陷检出率 ≥ 80%

▎ 业务逻辑评审检出率 ≥ 70%

▎ 误报率 ≤ 5%

▎ 知识问答 P95 响应时间 < 10 秒

▎ 代码评审 P95 响应时间 < 5 分钟

▎ 设计文档评审 P95 响应时间 < 3 分钟

七、项目进展

目前需求分析阶段已经完成，产出了完整的需求分析文档，包含：

▎ 9 个核心功能模块的详细定义

▎ 8 个主流程和 14 个异常流程

▎ 54 项验收标准

▎ 26 个待确认问题

接下来将进入技术设计阶段，输出架构设计文档。

好的工具不是替代人，而是让人做得更好。

这个 AI 知识问答与代码评审助手，就是朝着这个方向迈出的一步。