Python 构建基于 Claude 3.5 的全栈代码审计 Agent

为了演示，我们将使用支持 OpenAI 兼容协议的第三方 API 服务。它完美支持 Claude 3.5 Sonnet 和 Gemini 1.5 Pro，且接口格式与 OpenAI 完全一致。

注意：请自行注册并获取对应的 API Key。

四、核心代码实战：编写 Code-Auditor

我们将代码分为三个模块：scanner.py（文件处理）、client.py（模型交互）、main.py（主程序）。

4.1 模块一：智能文件扫描器 (scanner.py)

这个模块的难点在于：如何像 Git 一样聪明地忽略文件？

import os
import pathspec

class ProjectScanner:
    def __init__(self, root_dir):
        self.root_dir = root_dir
        self.gitignore = self._load_gitignore()

    def _load_gitignore(self):
        """加载.gitignore 规则"""
        gitignore_path = os.path.join(self.root_dir, ".gitignore")
        if os.path.exists(gitignore_path):
            with open(gitignore_path, "r", encoding="utf-8") as f:
                return pathspec.PathSpec.from_lines("gitwildmatch", f)
        return pathspec.PathSpec.from_lines("gitwildmatch", [])

    def scan(self):
        """遍历项目，返回所有代码文件的内容"""
        file_count = 0
        code_context = ""  # 初始化变量
        default_ignore = {".git", "__pycache__", "node_modules", "venv", ".idea", ".vscode"}
        for root, dirs, files in os.walk(self.root_dir):
            # 修改 dirs 列表以跳过忽略目录
            dirs[:] = [d for d in dirs if d not in default_ignore]
            for file in files:
                file_path = os.path.join(root, file)
                rel_path = os.path.relpath(file_path, self.root_dir)
                # 检查是否被 gitignore 忽略
                if self.gitignore.match_file(rel_path):
                    continue
                # 只处理代码文件（可根据需求扩展）
                if not file.endswith(('.py', '.js', '.ts', '.java', '.go', '.cpp')):
                    continue
                try:
                    with open(file_path, "r", encoding="utf-8") as f:
                        content = f.read()
                        # 拼接上下文格式：文件名 + 代码内容
                        code_context += f"\n\n--- FILE: {rel_path} ---\n{content}"
                    file_count += 1
                except Exception:
                    pass  # 跳过二进制文件或编码错误的文件
        return code_context, file_count

4.2 模块二：Claude 模型客户端 (client.py)

这里是魔法发生的地方。注意 base_url 的配置，这是我们能够在一个 SDK 里调用不同模型的关键。

from openai import OpenAI
import os

class AIClient:
    def __init__(self, api_key):
        # 配置 OpenAI 兼容协议的 API 地址
        self.client = OpenAI(
            api_key=api_key,
            base_url="https://your-api-gateway.com/v1"  # 替换为实际网关地址
        )

    def analyze_code(self, code_context, prompt):
        """
        发送请求给 Claude-3.5-Sonnet
        """
        system_prompt = """你是一名拥有 20 年经验的资深架构师，精通 Clean Code 原则。
        你的任务是分析用户提供的项目代码，找出潜在的 Bug、性能瓶颈，并给出重构建议。
        请直接输出 Markdown 格式的报告，不要废话。"""
        try:
            stream = self.client.chat.completions.create(
                # 这里指定模型名称，具体名称请参考平台文档
                model="claude-3-5-sonnet",
                messages=[
                    {"role": "system", "content": system_prompt},
                    {"role": "user", "content": f"项目代码如下:\n{code_context}\n\n用户需求:{prompt}"}
                ],
                stream=True,
                temperature=0.2  # 代码任务需要低创造性，高准确性
            )
            return stream
        except Exception as e:
            print(f"API 调用错误:{e}")
            return None

4.3 模块三：主程序入口 (main.py)

结合 rich 库，打造极客风的终端界面。

import os
from scanner import ProjectScanner
from client import AIClient
from rich.console import Console
from rich.markdown import Markdown

console = Console()

def main():
    # 1. 配置 API Key
    api_key = os.getenv("VECTOR_API_KEY")
    if not api_key:
        console.print("[red] 错误：请设置环境变量 VECTOR_API_KEY[/red]")
        return

    # 2. 获取目标路径
    target_dir = input("请输入要分析的项目路径 (默认当前目录): ").strip() or "."

    # 3. 扫描代码
    with console.status("[bold green] 正在扫描项目文件...[/bold green]"):
        scanner = ProjectScanner(target_dir)
        context, count = scanner.scan()
        console.print(f"[blue] 扫描完成！共发现 {count} 个代码文件，字符数:{len(context)}[/blue]")
        if len(context) > 200000:
            console.print("[yellow] 警告：项目过大，建议切换至 gemini-1.5-pro 模型以支持超长上下文[/yellow]")

    # 4. 用户交互
    while True:
        user_query = input("\n请输入你的指令 (例如:'找出代码中的安全漏洞' 或 'q'退出): ")
        if user_query.lower() == 'q':
            break
        ai = AIClient(api_key)
        stream = ai.analyze_code(context, user_query)
        if stream:
            console.print("\n[bold cyan]--- Claude 3.5 Sonnet 分析报告 ---[/bold cyan]\n")
            # 流式打印结果
            for chunk in stream:
                if chunk.choices[0].delta.content:
                    content = chunk.choices[0].delta.content
                    print(content, end='', flush=True)
            print("\n")

if __name__ == "__main__":
    main()

五、深度解析：为什么 Claude 3.5 更适合写代码？

在运行上述代码时，你会发现 Claude 3.5 Sonnet 与 GPT-4o 的一个显著区别：它更懂'人话'。

1. Artifacts 思维：Claude 倾向于一次性生成完整的、可运行的代码块，而不是像挤牙膏一样一段段崩。
2. 指令遵循（Instruction Following）：在复杂的 Prompt 下（比如要求它同时遵循 PEP8 规范、添加类型注解、并编写单元测试），Claude 3.5 的遗漏率远低于其他模型。
3. 视觉多模态辅助：虽然本文主要演示文本代码，但 Claude 3.5 的视觉能力极强。你可以截图 IDE 的报错弹窗发给它，它能精准定位 UI 层面的 Bug。

进阶技巧：利用 Gemini 1.5 Pro 处理超大项目

如果你的项目是一个几十万行的老旧 Java 工程，Token 数量轻松突破 10 万。这时候 Claude 的 200k 上下文可能捉襟见肘。

在 client.py 中，你只需要将 model 参数修改为 gemini-1.5-pro。网关会自动将请求路由到对应模型服务商。Gemini 1.5 Pro 支持高达 100 万甚至 200 万 Token 的上下文。这意味着你可以把整个框架的源码一次性喂给它，问它：'请画出这个项目的 UML 类图'。这种能力在以前是无法想象的。

六、避坑指南与性能优化

在开发这个 Agent 的过程中，有几个技术细节需要注意：

6.1 Token 截断与成本控制

虽然是按量付费，但把整个 node_modules 发过去绝对是灾难。

• 优化方案：务必完善 ProjectScanner 中的过滤逻辑。对于 Python 项目，排除 venv；对于前端，排除 dist 和 build。
• 估算：1 个中文字符约等于 0.7 个 Token，1 行代码约等于 5-10 个 Token。

6.2 提示词工程（Prompt Engineering）

针对代码重构，推荐使用 CO-STAR 框架编写 Prompt：

• C (Context): "你是一个资深 Python 后端工程师..."
• O (Objective): "重构这段代码，使其符合解耦原则..."
• S (Style): "使用 Google 代码风格，强制类型提示..."
• T (Tone): "专业、严谨..."
• A (Audience): "面向初级开发者，代码要有详细注释..."
• R (Response): "输出 Markdown 格式..."

6.3 API 超时处理

分析大项目时，模型思考时间可能长达 30 秒。确保你的 HTTP Client 设置了足够的 timeout 时间，或者使用流式（Stream）接收，这样可以避免连接被中间网关切断。

七、结语

AI 不会取代程序员，但'会用 AI 的程序员'一定会取代'不会用 AI 的程序员'。

从 Copilot 的自动补全，到我们今天构建的全局代码审计 Agent，AI 介入开发的深度正在不断加深。掌握 API 聚合技术，灵活调用 Claude、Gemini 等不同特性的模型，将成为未来全栈开发者的必备技能。