构建 AI 智能体的经验分享

原文：Learnings from building AI agents

我们如何让 AI 代码审查助手变得更安静、更精准？

作者：Paul Sangle-Ferriere

我是 Paul，cubic 的联合创始人，cubic 是一个以 AI 为核心的“智能版 GitHub”。其中最重要的功能之一，就是一款 AI 代码审查智能体。它能自动审阅代码提交，帮助发现代码中的错误、不良设计模式、重复代码等问题。

今年 4 月首次发布时，我们最常听到的用户反馈特别简单：AI 提出的反馈太多太吵了！

即便是很小的代码改动（PR），也常常被 AI 评论淹没，充斥着大量低价值的意见、过度挑剔甚至是误报。这不仅没有帮助开发者，反而干扰了真正重要的代码讨论。

一个典型的鸡蛋里挑骨头的例子

于是，我们决定认真反思和深入研究问题的根源。

经过三次重大的架构改进，以及大量线下测试，我们最终成功地将误报率降低了 51%，而且没有牺牲召回率（recall）。

在这个过程中，我们得到了很多重要的教训。这些教训不仅适用于代码审查，也对设计其他高效 AI 智能体有极大帮助。

1. “拍脑袋”阶段：一个包打天下的智能体行不通

我们最初设计的架构看起来简单明了：

[代码差异]

↓

[单个大提示词，包含代码库的全部上下文]

↓

[输出评论列表]

这种设计看起来很干净，实际却很快暴露了严重问题：

  • 误报太多：AI 智能体经常把代码风格的小问题误判为严重 bug，还重复提一些已经修复或被代码格式工具处理过的建议。

  • 用户失去信任：开发者很快开始忽略这些评论，当一半以上都是无关紧要的内容时，真正重要的信息自然也会被漏掉。

  • 推理不透明：AI 为什么要提出特定建议，几乎无法解释。即使明确告诉它“忽略代码风格的小问题”，效果也很差。

我们尝试了标准方案——例如延长提示词、调整模型温度（temperature）和采样方式等，但效果都不明显。

2. 我们最终有效的方案

经过大量尝试，我们找到了一套在实际项目中真正有效的架构。这些方案使得我们现在能减少 51% 的误报率。

2.1 强制要求 AI 给出明确的推理日志

我们要求 AI 智能体在提出任何反馈之前，必须明确地记录自己的推理过程：

{
  "reasoning": "第 42 行 `cfg` 可能是空指针，但在第 47 行却直接引用了它。",
  "finding": "可能存在空指针解引用问题",
  "confidence": 0.81
}

这种方式带来了巨大好处：

  • 能够清楚地了解 AI 为什么提出某个问题。如果推理本身有误，我们可以快速定位并修正。

  • 促使 AI 进行结构化思考，先说明理由再做判断，极大减少了随意的错误结论。

  • 提供了诊断并彻底解决问题根源的有效依据。

2.2 减少工具数量，聚焦于核心功能

一开始，我们给 AI 配备了大量工具，例如语言服务器协议（LSP）、静态分析、测试工具等。但推理日志显示，其实大部分任务只需要几个核心工具，多余的工具反而让 AI 混乱。

我们最终简化工具链，仅保留最基本的语言服务器（LSP）和终端功能。

这样，AI 可以将精力专注在确认真正有意义的问题上，精准度大幅提高。

2.3 使用“专职”微型智能体代替“大而全”规则集

刚开始，我们本能地想用一个超大提示词，添加越来越多规则来处理各种细节：

  • “忽略 .test.ts 文件中的未使用变量”

  • “在 Python 的 __init__.py 文件中跳过导入检查”

  • “不对 Markdown 文件进行代码审查”

结果却发现这种做法既不可持续，也效率低下，AI 常常忽略掉大量规则。

我们最终取得突破性进展的方案，是使用多个专门的微型智能体（micro-agents），每个只专注于非常明确的任务：

  • 规划智能体（Planner）：快速评估代码变化并确定需要进行的检查。

  • 安全智能体（Security Agent）：专门检测安全漏洞，例如代码注入或认证安全问题。

  • 重复代码智能体（Duplication Agent）：负责检查代码是否存在重复或拷贝的情况。

  • 编辑智能体（Editorial Agent）：处理拼写错误和文档一致性。

微型智能体的专职分工，让每个智能体都能保持精细而专注的上下文，从而提高精准度。尽管整体的 token 使用量有所增加，我们通过有效的缓存策略成功控制了成本。

3. 实际效果

这些架构和提示词的改进，在数百个活跃的开源和私有项目中获得了显著成果。在过去六周的实践中，我们具体收获包括：

  • 误报数量减少 51%，显著提升了开发者的信任和用户体验。

  • 每个代码提交（PR）评论的中位数减少一半，让团队能够专注于真正重要的问题。

  • 团队反馈称审查流程明显更流畅，节约了大量管理无效评论的时间，更高效地推动代码合并。

同时，AI 的精准性提高，让开发者更加信任和愿意与 AI 智能体互动，审查效率大大提升。

4. 关键经验总结

  1. 明确推理是关键。要求 AI 首先说明理由，这不仅能提升准确度，也能极大简化后续的调试过程。

  2. 精简工具集。定期检查智能体所用的工具，果断移除使用率低于 10% 的工具。

  3. 专职微型智能体胜过大而全规则。每个智能体聚焦于一个明确的任务，减少认知负担，大幅提高准确性。

See all posts