【从0开发一个 Agent】第三章：初始化项目-平芜编程栈

在上一章中，我们完成了技术选型与架构设计。从本章开始，我们将正式进入工程落地阶段。

万丈高楼平地起，一个优秀的企业级项目，往往取决于最初的项目骨架是否扎实。本章的目标是搭建整个项目的核心骨架，配置好所有核心依赖，并建立一套清晰、可扩展的目录结构。

1. 为什么需要精心设计的初始化？

很多开发者习惯于使用create-next-app生成默认项目后直接开始写业务代码，这在 AI Agent 项目中是致命的。

AI Agent 项目的特殊性：

多职责分离：我们需要区分 UI 组件、业务逻辑、AI 核心逻辑、工具调用、数据库模型等。
服务端与客户端边界：Next.js App Router 对 Server Component 和 Client Component 有严格区分，AI SDK 的某些 Hook 只能在客户端使用，而数据库操作只能在服务端进行。
配置复杂度：Prisma、pgvector、AI SDK、HeroUI 都需要特定的配置才能协同工作。

本章我们将建立：

标准化的 Next.js 项目骨架。
核心依赖的安装与配置。
符合 AI Agent 开发范式的目录结构。
数据库的初始化与连接。

2. 创建 Next.js 项目

首先，我们使用官方脚手架创建项目。注意，我们选择 src/ 目录结构，这是企业级项目的标准做法，能将应用代码与配置文件彻底隔离。

# 创建项目npx create-next-app@latest ai-agent-enterprise--typescript--tailwind--app--src-dir--eslint# 进入项目cdai-agent-enterprise

3. 安装核心依赖

根据第二章的技术选型，我们需要安装以下核心包：

# AI 核心npminstallai @ai-sdk/openai# 数据库 ORMnpminstallprisma @prisma/client# UI 组件库 (HeroUI)npminstall@heroui/react framer-motion# Markdown 渲染 (用于 AI 回复)npminstallreact-markdown remark-gfm

4. 目录结构设计

一个清晰的目录结构是项目可维护性的基石。我们在src/下建立以下结构：

src/ ├── app/# Next.js App Router 路由与 API│ ├── api/# API 路由 (AI 对话接口等)│ ├── page.tsx# 首页│ └── layout.tsx# 根布局├── components/# UI 组件│ ├── ui/# 基础 UI 组件 (Button, Input 等)│ └── chat/# 聊天业务组件 (ChatWindow, MessageBubble)├── lib/# 核心工具与配置│ ├── ai/# AI SDK 配置、工具定义│ ├── db/# Prisma Client 单例│ └── utils.ts# 通用工具函数├── types/# 全局 TypeScript 类型定义└── styles/# 全局样式

为什么这样设计？

app/api：AI 对话接口必须放在这里，利用 Next.js Route Handlers 处理流式响应。
lib/ai：将 AI 相关的配置、Prompt 模板、Tool Calling 定义集中管理，避免业务逻辑与 AI 逻辑耦合。
lib/db：Prisma Client 在开发环境下会创建大量连接，必须封装为单例（Singleton）以防止连接池耗尽。

5. 核心配置实现

5.1 Prisma 数据库初始化

npx prisma init

这会生成prisma/schema.prisma和.env文件。

为什么需要 Prisma？
Prisma 提供了类型安全的数据库访问。当我们在 AI Agent 中定义工具时，可以直接将 Prisma 的查询结果作为 Tool 的返回值，TypeScript 会自动推导类型，极大减少运行时错误。

5.2 AI SDK 配置

在src/lib/ai/config.ts中：

import{createOpenAI}from'@ai-sdk/openai';exportconstopenai=createOpenAI({apiKey:process.env.OPENAI_API_KEY,baseURL:process.env.OPENAI_BASE_URL,// 支持 DeepSeek 等兼容接口});

5.3 HeroUI 配置

HeroUI 需要包裹HeroUIProvider。在src/app/layout.tsx中：

import{HeroUIProvider}from'@heroui/react';exportdefaultfunctionRootLayout({children}:{children:React.ReactNode}){return(<html lang="zh-CN"><body><HeroUIProvider>{children}</HeroUIProvider></body></html>);}

6. 项目架构流转图

初始化完成后，我们的项目数据流如下：

7. 测试验证

运行开发服务器：

npmrun dev

访问http://localhost:3000，如果看到 Next.js 默认页面且没有报错，说明项目骨架搭建成功。

验证清单：

项目能正常启动
HeroUI 组件能正常渲染
Prisma 能正常连接数据库（检查控制台无报错）
环境变量能正常读取

8. 常见问题与踩坑分析

问题 1：Prisma 在 Next.js 中导致连接池耗尽

原因：Next.js 的 HMR（热更新）会在每次代码修改时重新执行模块，导致 Prisma Client 被反复实例化。
解决：在src/lib/db/index.ts中使用全局单例模式：

import{PrismaClient}from'@prisma/client';constglobalForPrisma=globalThisasunknownas{prisma:PrismaClient};exportconstprisma=globalForPrisma.prisma||newPrismaClient();if(process.env.NODE_ENV!=='production')globalForPrisma.prisma=prisma;