从零构建AI代码审查智能体：基于Coze平台与VSCode集成实践

在实际项目开发中，很多开发者对AI大模型的应用还停留在“问个问题，拿个答案”的初级阶段。这种用法不仅效率低下，无法发挥AI的真正潜力，还常常因为提示词不精准、流程设计不合理，导致结果反复修改，浪费大量时间。真正有价值的AI应用，是将大模型作为智能体（AI Agent），嵌入到具体的开发、测试、文档、运维等环节，形成自动化或半自动化的解决方案。这需要开发者理解如何通过API调用、如何设计工作流、如何编写有效的提示词，以及如何将AI能力与现有工具链（如VSCode）集成。

本文将以一个具体的工程实践为例，带你从零开始，构建一个能够辅助代码审查的AI智能体。我们将使用扣子（Coze）平台作为智能体的开发和部署平台，并探讨如何将其能力通过API或插件形式，与开发环境（如VSCode）或团队协作工具（如飞书、钉钉）打通。通过这个案例，你将掌握AI智能体从设计、开发到集成的完整流程，理解如何将零散的AI能力转化为稳定、可控的生产力工具，从而在代码质量、开发效率等方面获得实质提升。

1. 理解AI智能体与工作流：从单次问答到自动化流程

在深入实践之前，必须厘清几个核心概念。很多人混淆了“大模型”、“AI应用”和“AI智能体”，导致工具选型和设计思路出现偏差。

1.1 大模型、AI应用与AI智能体的区别

大模型（如豆包的模型、千问的模型）是底层的能力提供者，它们接收文本输入，生成文本输出。其本身不具备记忆、工具调用或复杂决策能力。

AI应用是指基于大模型能力构建的、面向特定场景的软件或服务。例如，一个基于千问API开发的代码补全插件，就是一个AI应用。它的逻辑相对简单：用户输入代码片段，应用调用API，返回补全建议。

AI智能体（AI Agent）则是一个更高级的概念。它通常包含以下几个核心组件：

1. 规划能力：能够将复杂目标分解为可执行的子任务序列。
2. 记忆能力：拥有短期记忆（对话上下文）和长期记忆（知识库、向量数据库），能记住历史交互。
3. 工具使用能力：可以调用外部工具，如执行代码、查询数据库、调用API、操作文件系统等。
4. 行动与反思能力：执行动作后，能评估结果，并根据需要进行调整。

简单来说，AI应用是“你问，它答”；而AI智能体是“你给目标，它自己规划、调用工具、执行并给你最终结果”。扣子平台、即梦AI等，都提供了低代码构建这类智能体的能力。

1.2 为什么选择扣子（Coze）平台进行实践

在众多AI智能体开发平台中，扣子平台因其与豆包生态的深度集成、直观的工作流编排界面和灵活的发布方式，成为快速原型验证和轻量级生产部署的优选。它解决了几个关键问题：

• 降低开发门槛：无需从零编写Agent框架，通过拖拽即可编排复杂的工作流。
• 内置丰富插件：直接使用联网搜索、知识库、代码解释器、文本处理等插件，无需自行开发对接。
• 多端部署便捷：构建的智能体可以一键发布为豆包App、独立网页，或通过API集成到第三方系统。

对于希望将AI能力快速工程化的团队和个人开发者，扣子是一个高效的起点。理解了智能体的概念和平台价值后，我们就可以开始设计一个具体的智能体了。

2. 环境准备与依赖配置：搭建智能体开发基础

在开始构建代码审查智能体之前，我们需要准备好开发环境，并明确技术选型。虽然扣子平台是云端服务，但本地环境的准备对于后续的API调试、代码集成至关重要。

2.1 核心工具与平台账号准备

你需要注册并准备好以下账号和工具：

1. 扣子平台账号：访问扣子官网（通常为coze.cn或相关域名）进行注册。这是我们构建智能体的主战场。
2. 豆包开发者账号：由于扣子与豆包生态紧密关联，拥有豆包开发者账号（可访问豆包开放平台）有助于理解API调用和权限体系。豆包官网为www.doubao.com。
3. 代码编辑器：Visual Studio Code (VSCode) 是首选，因为它有丰富的插件生态，也是我们后期集成AI能力的目标之一。
4. API测试工具：Postman 或 Insomnia，用于测试扣子智能体发布后的API接口。
5. 命令行终端：用于执行一些简单的脚本命令。

2.2 明确智能体的技术边界与依赖

我们的目标是构建一个“代码审查智能体”，它需要具备以下能力，并对应相应的技术实现：

• 能力：理解代码语义和上下文。
  • 实现：依赖底层大模型（如豆包Pro、千问等）。在扣子平台，创建机器人时会让你选择默认的模型。
• 能力：知晓常见的代码坏味道、安全漏洞和最佳实践。
  • 实现：通过精心设计的提示词（Prompt）和知识库来注入这部分知识。我们可以将《阿里巴巴Java开发手册》、OWASP Top 10安全指南等文档上传为知识库文件。
• 能力：针对特定代码片段给出结构化、可操作的审查意见。
  • 实现：通过工作流和插件来标准化输出。例如，使用“文本处理”插件确保输出格式为Markdown，使用“条件判断”插件对不同严重级别的问题进行归类。
• 能力：与开发环境（如VSCode）或CI/CD流程集成。
  • 实现：将智能体发布为API，然后在VSCode中通过插件调用该API，或在GitLab CI的.gitlab-ci.yml中通过curl命令调用。

下表总结了本实践案例的主要技术栈：

环境就绪后，我们就可以进入扣子平台，开始核心的智能体创建工作。

3. 构建代码审查智能体：从设计到实现

本节是核心实操部分。我们将一步步在扣子平台上创建一个名为“CodeReviewer”的智能体。

3.1 创建机器人并配置基础信息

1. 登录扣子平台，点击“创建机器人”。
2. 机器人名称：填写CodeReviewer。
3. 机器人描述：清晰说明其功能，例如：“一个专注于Java/Python代码质量与安全审查的AI助手，可识别潜在bug、性能问题、安全漏洞和代码坏味道。”
4. 模型选择：在“模型与插件”配置中，选择能力较强的模型，如“豆包Pro”。对于代码理解场景，优先选择代码能力被验证过的模型。
5. 人设与回复逻辑：在“提示词”区域，填写核心人设指令。这是智能体的“灵魂”。

初始提示词示例：

你是一个资深且严格的代码审查专家，专注于Java和Python语言。你的核心职责是分析用户提供的代码片段，找出其中的问题并提供改进建议。 审查维度必须包括： 1. **功能性**：逻辑错误、边界条件处理、异常处理。 2. **性能**：时间复杂度、空间复杂度、重复计算、资源泄漏（如数据库连接、文件流未关闭）。 3. **安全性**：SQL注入、XSS、命令注入、不安全的反序列化、硬编码密钥。 4. **代码风格与可维护性**：命名规范、代码重复、过长的函数/类、复杂的条件判断。 5. **最佳实践**：是否符合语言社区的主流实践（如Java的Effective Java， Python的PEP 8）。 输出格式要求： - 使用Markdown格式。 - 首先对代码整体可读性和结构做简要评价。 - 然后以表格形式列出发现的问题，表格列包括：`行号`、`问题类型`、`严重级别(高/中/低)`、`问题描述`、`修改建议`。 - 最后，给出一个整体的优化总结和重构建议（如果有的话）。 如果用户提供的不是代码，或者你无法理解，请直接告知用户并提供正确的使用方式。

注意：提示词是引导模型行为的关键。务必具体、结构化，并明确输出格式要求。模糊的提示词会导致输出结果不稳定。

3.2 创建并关联知识库

仅靠模型的通用知识还不够，我们需要注入我们团队或项目的特定规范。

1. 在扣子平台侧边栏找到“知识库”，点击“创建知识库”，命名为Team-Coding-Standards。
2. 上传你的代码规范文档（如.md或.pdf文件）。例如，可以上传简化版的《阿里巴巴Java开发手册》和《Google Python风格指南》摘要。
3. 回到CodeReviewer机器人的编辑页面，在“知识库”配置区域，添加刚刚创建的Team-Coding-Standards知识库。
4. 调整“引用方式”，通常选择“自动引用”，让机器人在回复时自动检索相关知识片段。

3.3 设计并编排工作流

工作流是实现复杂、稳定审查逻辑的关键。单靠提示词，模型可能会忽略某些审查维度。工作流可以强制按步骤执行。

我们设计一个简单的工作流：“代码审查流水线”。

1. 在机器人编辑页点击“工作流”标签，创建新工作流，命名为standard_code_review。
2. 使用拖拽方式编排节点。一个基础的工作流可以包含：
   • 开始节点：接收用户输入的代码和语言类型。
   • 条件判断节点：判断输入代码是否为空或非代码文本。
   • 插件节点（代码解释器）：如果平台支持，可以尝试让模型执行代码以发现运行时错误（需谨慎，在沙盒中运行）。
   • LLM节点（核心审查）：调用大模型，使用我们编写好的提示词进行审查。这里的提示词可以更精细，例如分步骤审查。
   • 插件节点（文本处理）：对LLM输出的审查结果进行格式化，确保是标准的Markdown表格。
   • 结束节点：输出最终结果。

工作流配置示例（以LLM节点为例）：

• 节点名称：Detailed_Code_Analysis
• 提示词：可以复用并细化机器人的初始提示词，或者针对不同语言（Java/Python）设置不同的审查重点。
• 连接知识库：勾选关联的Team-Coding-Standards知识库。

3.4 配置技能与发布设置

1. 技能配置：在“技能”页面，将创建好的standard_code_review工作流添加为机器人的一个技能。可以设置触发词，例如当用户说“审查这段代码”或“review this”时，自动触发该工作流。
2. 发布设置：
   • 豆包App：可以直接发布到豆包，在豆包内搜索使用。
   • API发布：这是与外部系统集成的关键。在“发布”页面，选择“API访问”，创建一个新的API密钥。记录下Bot ID、API Key和接口地址（通常为https://api.coze.cn/v1/chat之类的格式）。
   • 网页版：可以生成一个独立的H5页面链接，分享给团队成员使用。

完成以上步骤后，你的CodeReviewer智能体就已经在扣子平台上构建完毕。你可以在平台的对话窗口直接测试其效果。

4. 通过API集成与验证：让智能体融入开发生命周期

构建好的智能体如果只能在扣子平台内对话，价值有限。我们必须将其能力通过API暴露出来，集成到开发者的日常工作流中。

4.1 获取API配置信息

在扣子平台的机器人“发布”->“API访问”页面，你需要获取以下关键信息：

• Bot ID: 你的机器人的唯一标识。
• API Key: 用于鉴权的密钥。
• Endpoint: API的服务端点地址。

请妥善保管API Key，不要泄露在客户端代码中。

4.2 编写API调用示例代码

以下是一个使用 Pythonrequests库调用扣子智能体API的示例。我们假设智能体已经配置了standard_code_review工作流作为默认或触发技能。

import requests import json def code_review_via_coze(code_snippet, language='java'): """ 调用扣子平台的CodeReviewer智能体进行代码审查。 Args: code_snippet (str): 待审查的代码字符串。 language (str): 代码语言，如 'java', 'python'。 Returns: str: 智能体返回的审查结果Markdown文本。 """ # 从环境变量或配置文件中读取，切勿硬编码 api_key = "your_coze_api_key_here" # 替换为你的API Key bot_id = "your_bot_id_here" # 替换为你的Bot ID api_url = "https://api.coze.cn/v1/chat" # 扣子API地址，以实际为准 headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", # 扣子API可能还需要特定的版本头，请查阅最新文档 # "X-API-Version": "2024-01-01" } # 构造请求体。扣子API的格式可能变化，以下为示例格式。 # 核心是向指定的bot发送一条消息，消息内容触发审查工作流。 payload = { "bot_id": bot_id, "user_id": "unique_user_identifier_123", # 用于区分用户，可自定义 "stream": False, # 非流式响应 "additional_messages": [ { "role": "user", "content": f"请以{language}语言专家身份，严格审查以下代码：\n```{language}\n{code_snippet}\n```", # 可以尝试使用工作流的触发词，例如： # "content": f"/standard_code_review 语言：{language} 代码：{code_snippet}" } ] } try: response = requests.post(api_url, headers=headers, data=json.dumps(payload)) response.raise_for_status() # 检查HTTP错误 result = response.json() # 解析响应，获取AI回复的内容。实际路径需根据扣子API响应结构调整。 # 通常内容在 result['messages'][-1]['content'] 或类似位置 if 'messages' in result and len(result['messages']) > 0: # 假设最后一条消息是assistant的回复 last_message = result['messages'][-1] if last_message.get('role') == 'assistant': return last_message.get('content', '审查结果为空。') return "未能从API响应中解析出审查结果。" except requests.exceptions.RequestException as e: return f"API请求失败: {e}" except json.JSONDecodeError as e: return f"响应解析失败: {e}" # 测试调用 if __name__ == "__main__": test_code = """ public class Example { public static void main(String[] args) { String sql = "SELECT * FROM users WHERE id = " + args[0]; // 执行查询... } } """ review_result = code_review_via_coze(test_code, language='java') print("代码审查结果：") print(review_result)

关键点解释：

1. 鉴权：Authorization头使用 Bearer Token 方式，Token 就是你的API Key。
2. 请求结构：扣子API的具体格式请务必查阅其官方最新文档。示例中的additional_messages是一种常见方式，用于模拟用户与机器人的对话历史，其中最后一条user消息是本次查询。
3. 触发工作流：可以通过在content中包含特定指令（如/standard_code_review）来触发对应的工作流，这取决于你在扣子平台中如何配置技能的触发方式。
4. 错误处理：网络请求和JSON解析都可能出错，必须进行异常捕获，避免程序因API调用失败而崩溃。
5. 安全：API Key必须从环境变量或安全的配置中心读取，绝不能写在源代码里提交到版本库。

4.3 验证API调用结果

运行上述测试代码，你应该能收到一段Markdown格式的审查结果。例如，对于上面那个存在SQL注入漏洞的测试代码，返回结果可能包含：

## 代码审查报告 **整体评价**：代码结构简单，但存在严重的安全漏洞。 | 行号 | 问题类型 | 严重级别 | 问题描述 | 修改建议 | | :--- | :--- | :--- | :--- | :--- | | 3 | 安全性 | 高 | 存在SQL注入风险。直接拼接用户输入(`args[0]`)到SQL语句中。 | 应使用预编译语句(PreparedStatement)来传递参数。 | | 2, 3 | 代码风格 | 低 | 类名`Example`过于泛化，未能体现其职责。 | 建议根据实际功能重命名类，如`UserQueryService`。 |

这表明我们的智能体已经成功通过API被调用，并返回了结构化的审查意见。

5. 集成到VSCode与CI流程：实现自动化审查

让API跑通只是第一步，接下来我们要把它嵌入到开发者最常用的工具和流程中，实现“无处不在”的代码审查。

5.1 创建简易VSCode插件（概念示例）

在VSCode中，我们可以创建一个命令，将选中的代码发送给我们的智能体进行审查。这里给出一个概念性的extension.js主要逻辑：

// 这是一个简化的VSCode插件示例，展示核心逻辑 const vscode = require('vscode'); const axios = require('axios'); // 需要安装axios function activate(context) { // 注册一个命令，例如 `codeReviewer.reviewSelection` let disposable = vscode.commands.registerCommand('codeReviewer.reviewSelection', async function () { const editor = vscode.window.activeTextEditor; if (!editor) { vscode.window.showErrorMessage('没有活动的编辑器！'); return; } const selection = editor.selection; const codeSnippet = editor.document.getText(selection); if (!codeSnippet.trim()) { vscode.window.showWarningMessage('请先选择一段代码。'); return; } const languageId = editor.document.languageId; // 获取文档语言 // 从插件配置中读取API信息 const config = vscode.workspace.getConfiguration('codeReviewer'); const apiKey = config.get('apiKey'); const botId = config.get('botId'); const apiUrl = config.get('apiUrl'); if (!apiKey || !botId) { vscode.window.showErrorMessage('请先在设置中配置CodeReviewer的API Key和Bot ID。'); return; } // 调用扣子API vscode.window.withProgress({ location: vscode.ProgressLocation.Notification, title: "AI代码审查中...", cancellable: false }, async (progress) => { try { const response = await axios.post(apiUrl, { bot_id: botId, user_id: `vscode_${Date.now()}`, stream: false, additional_messages: [{ role: 'user', content: `请以${languageId}语言专家身份，严格审查以下代码：\n\`\`\`${languageId}\n${codeSnippet}\n\`\`\`` }] }, { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }); const reviewResult = response.data.messages?.[-1]?.content || '无结果'; // 在一个新的侧边栏或输出面板展示Markdown结果 const panel = vscode.window.createWebviewPanel( 'codeReview', 'AI代码审查结果', vscode.ViewColumn.Two, { enableScripts: true } ); panel.webview.html = `<!DOCTYPE html><html><body>${marked.parse(reviewResult)}</body></html>`; // 使用marked解析markdown } catch (error) { vscode.window.showErrorMessage(`审查请求失败: ${error.message}`); } }); }); context.subscriptions.push(disposable); } exports.activate = activate;

开发者安装此插件后，只需在设置中配置好apiKey、botId和apiUrl，然后选中代码，右键选择“AI代码审查”，即可在编辑器旁看到详细的审查报告。

5.2 集成到GitLab CI/CD流水线

在团队协作中，将自动化代码审查作为CI/CD的一个环节，可以在代码合并前发现问题。以下是一个.gitlab-ci.yml的示例阶段：

stages: - test - code-review - deploy ai-code-review: stage: code-review script: - | # 假设我们审查本次提交中变更的Java/Python文件 CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD | grep -E '\.(java|py)$' | head -5) # 限制数量，避免API调用过多 for FILE in $CHANGED_FILES; do if [ -f "$FILE" ]; then echo "正在审查文件: $FILE" # 提取变更的代码块（简化示例，实际可用git diff获取具体行） # 这里简单审查整个文件的最新版本 CODE_CONTENT=$(cat "$FILE") # 调用封装好的Python脚本，该脚本内部调用扣子API REVIEW_OUTPUT=$(python3 /scripts/coze_reviewer.py --file "$FILE" --code "$CODE_CONTENT") # 将结果输出到CI日志，也可以解析结果并判断是否失败 echo "$REVIEW_OUTPUT" # 可选：如果发现“严重级别: 高”的问题，可以标记本次流水线为失败 if echo "$REVIEW_OUTPUT" | grep -q "严重级别.*高"; then echo "发现严重级别问题，请修复后再提交。" # exit 1 # 严格模式下，直接失败 fi fi done only: - merge_requests # 仅在合并请求时触发 rules: - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "main" # 例如，仅对合并到主分支的请求进行审查

这个CI任务会在每次向主分支提交合并请求时，自动分析变更的代码文件，并调用我们的智能体API进行审查，将结果输出到日志。团队可以根据审查结果决定是否合并代码。

6. 常见问题排查与性能优化

将AI智能体投入实际使用，必然会遇到各种问题。以下是基于此方案的常见故障点及排查路径。

6.1 API调用失败排查清单

6.2 审查效果优化建议

1. 提示词工程：

   • 分步骤审查：在提示词中要求模型按“安全性 -> 功能性 -> 性能 -> 代码风格”的顺序逐一审查，避免遗漏。
   • 提供示例：在提示词中给出一个“好审查”和“坏审查”的示例，引导模型输出格式和深度。
   • 限制输出：明确要求“最多列出5个最严重的问题”，避免生成过于冗长的报告。

2. 知识库优化：

   • 文档切片：将大型规范文档拆分成小块（如按章节），并添加清晰的标题，有助于向量检索更精准。
   • 添加元数据：在知识库中为不同片段打上标签，如language:java、category:security，在提示词中要求模型优先检索特定标签的知识。

3. 性能与成本考量：

   • 缓存结果：对于重复的、未修改的代码片段，可以在本地或中间件（如Redis）中缓存审查结果，避免重复调用API产生不必要的费用和延迟。
   • 异步处理：在CI/CD流水线中，如果审查耗时较长，可以考虑将审查任务提交到消息队列异步执行，不阻塞CI流程。
   • 采样审查：在大型项目中，不要审查所有文件。可以针对变更行数最多的文件、特定目录（如src/main/java）或修改频率高的作者进行重点审查。

6.3 安全与合规注意事项

注意：将代码发送给第三方AI服务进行审查，必须经过严格的安全评估。

1. 代码脱敏：在调用API前，必须移除代码中的敏感信息，如密码、密钥、IP地址、内部域名、个人信息等。可以编写预处理脚本进行自动过滤。
2. 合规审批：在企业环境中，使用外部AI服务处理公司源代码，需要经过安全、法务部门的审批，并评估数据出境等风险。
3. 私有化部署：对于高安全要求的场景，应关注扣子等平台是否提供私有化部署方案，或将方案迁移到支持本地部署的开源模型（如通过Spring AI集成本地模型）。
4. 权限控制：API Key必须具备最小权限原则，仅能访问指定的Bot，并设置调用频率限制。

7. 扩展方向与最佳实践

构建一个可用的智能体只是起点。要让它真正成为团队的生产力，还需要考虑更多。

7.1 扩展智能体能力

• 多语言支持：扩展知识库和提示词，支持Go、JavaScript、Rust等更多语言。
• 架构审查：不仅审查单文件代码，还能接受项目结构描述（如tree命令输出），对模块划分、依赖关系提出建议。
• 自动化修复：结合代码解释器插件，让智能体在给出建议的同时，直接生成修复后的代码补丁（Diff格式）。
• 与Jira/飞书集成：审查出严重问题后，自动在项目管理工具中创建任务，或发送通知到群聊。

7.2 工程化最佳实践清单

1. 配置外置：API Key、Bot ID、端点地址等所有配置信息必须通过环境变量或配置中心管理，绝对禁止硬编码。
2. 日志与监控：记录每一次API调用的请求、响应时间、Token用量和审查结果摘要。设置告警，当API失败率或延迟超过阈值时通知负责人。
3. 版本管理：将扣子平台上的智能体提示词、工作流配置、知识库文件通过导出功能进行版本化管理（如保存为JSON/YAML文件，存入Git），便于回滚和审计。
4. 渐进式采用：先在非核心项目或个人项目中试用，收集反馈，逐步优化提示词和工作流，再推广到核心业务。
5. 人机结合：AI审查不应完全取代人工审查。最佳模式是AI作为“第一道过滤器”，发现明显问题并标准化常见建议，人类审查员则专注于更复杂的逻辑、业务一致性和架构设计。

通过以上步骤，你不仅学会了一个AI智能体的构建，更掌握了一套将AI能力工程化、产品化的方法论。其核心在于：明确场景、设计流程、利用平台、打通集成、持续优化。避免“瞎用AI”的关键，就是不再把大模型当作一个聊天玩具，而是将其视为一个需要精心设计接口、输入、输出和边界的软件组件。从这个项目出发，你可以将这套模式复制到文档生成、测试用例生成、日志分析、运维问答等无数个具体场景中，让AI真正成为你开发工作中的“副驾驶”。