在上一章中我们完成了技术选型与架构设计。从本章开始我们将正式进入工程落地阶段。万丈高楼平地起一个优秀的企业级项目往往取决于最初的项目骨架是否扎实。本章的目标是搭建整个项目的核心骨架配置好所有核心依赖并建立一套清晰、可扩展的目录结构。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-applatest ai-agent-enterprise--typescript--tailwind--app--src-dir--eslint# 进入项目cdai-agent-enterprise3. 安装核心依赖根据第二章的技术选型我们需要安装以下核心包# AI 核心npminstallai ai-sdk/openai# 数据库 ORMnpminstallprisma prisma/client# UI 组件库 (HeroUI)npminstallheroui/react framer-motion# Markdown 渲染 (用于 AI 回复)npminstallreact-markdown remark-gfm4. 目录结构设计一个清晰的目录结构是项目可维护性的基石。我们在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/apiAI 对话接口必须放在这里利用 Next.js Route Handlers 处理流式响应。lib/ai将 AI 相关的配置、Prompt 模板、Tool Calling 定义集中管理避免业务逻辑与 AI 逻辑耦合。lib/dbPrisma Client 在开发环境下会创建大量连接必须封装为单例Singleton以防止连接池耗尽。5. 核心配置实现5.1 Prisma 数据库初始化npx prisma init这会生成prisma/schema.prisma和.env文件。为什么需要 PrismaPrisma 提供了类型安全的数据库访问。当我们在 AI Agent 中定义工具时可以直接将 Prisma 的查询结果作为 Tool 的返回值TypeScript 会自动推导类型极大减少运行时错误。5.2 AI SDK 配置在src/lib/ai/config.ts中import{createOpenAI}fromai-sdk/openai;exportconstopenaicreateOpenAI({apiKey:process.env.OPENAI_API_KEY,baseURL:process.env.OPENAI_BASE_URL,// 支持 DeepSeek 等兼容接口});5.3 HeroUI 配置HeroUI 需要包裹HeroUIProvider。在src/app/layout.tsx中import{HeroUIProvider}fromheroui/react;exportdefaultfunctionRootLayout({children}:{children:React.ReactNode}){return(html langzh-CNbodyHeroUIProvider{children}/HeroUIProvider/body/html);}6. 项目架构流转图初始化完成后我们的项目数据流如下7. 测试验证运行开发服务器npmrun dev访问http://localhost:3000如果看到 Next.js 默认页面且没有报错说明项目骨架搭建成功。验证清单项目能正常启动HeroUI 组件能正常渲染Prisma 能正常连接数据库检查控制台无报错环境变量能正常读取8. 常见问题与踩坑分析问题 1Prisma 在 Next.js 中导致连接池耗尽原因Next.js 的 HMR热更新会在每次代码修改时重新执行模块导致 Prisma Client 被反复实例化。解决在src/lib/db/index.ts中使用全局单例模式import{PrismaClient}fromprisma/client;constglobalForPrismaglobalThisasunknownas{prisma:PrismaClient};exportconstprismaglobalForPrisma.prisma||newPrismaClient();if(process.env.NODE_ENV!production)globalForPrisma.prismaprisma;问题 2HeroUI 样式不生效原因HeroUI 依赖 Tailwind CSS 的插件配置。解决确保在 tailwind.config.ts 中正确配置了 heroui/theme 插件。本章总结我们创建了基于 App Router 的 Next.js 项目选择了 src/ 目录结构。安装了 AI SDK、Prisma、HeroUI、react-markdown 等核心依赖。建立了符合 AI Agent 开发范式的目录结构将 UI、AI 逻辑、数据库配置分离。完成了 Prisma 初始化与 AI SDK 基础配置。解决了 Prisma 连接池、HeroUI 样式等常见踩坑问题。项目骨架已经搭建完毕并且可以正常运行。从下一章开始我们将正式接入大模型实现第一个流式对话功能。
在上一章中我们完成了技术选型与架构设计。从本章开始我们将正式进入工程落地阶段。万丈高楼平地起一个优秀的企业级项目往往取决于最初的项目骨架是否扎实。本章的目标是搭建整个项目的核心骨架配置好所有核心依赖并建立一套清晰、可扩展的目录结构。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-applatest ai-agent-enterprise--typescript--tailwind--app--src-dir--eslint# 进入项目cdai-agent-enterprise3. 安装核心依赖根据第二章的技术选型我们需要安装以下核心包# AI 核心npminstallai ai-sdk/openai# 数据库 ORMnpminstallprisma prisma/client# UI 组件库 (HeroUI)npminstallheroui/react framer-motion# Markdown 渲染 (用于 AI 回复)npminstallreact-markdown remark-gfm4. 目录结构设计一个清晰的目录结构是项目可维护性的基石。我们在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/apiAI 对话接口必须放在这里利用 Next.js Route Handlers 处理流式响应。lib/ai将 AI 相关的配置、Prompt 模板、Tool Calling 定义集中管理避免业务逻辑与 AI 逻辑耦合。lib/dbPrisma Client 在开发环境下会创建大量连接必须封装为单例Singleton以防止连接池耗尽。5. 核心配置实现5.1 Prisma 数据库初始化npx prisma init这会生成prisma/schema.prisma和.env文件。为什么需要 PrismaPrisma 提供了类型安全的数据库访问。当我们在 AI Agent 中定义工具时可以直接将 Prisma 的查询结果作为 Tool 的返回值TypeScript 会自动推导类型极大减少运行时错误。5.2 AI SDK 配置在src/lib/ai/config.ts中import{createOpenAI}fromai-sdk/openai;exportconstopenaicreateOpenAI({apiKey:process.env.OPENAI_API_KEY,baseURL:process.env.OPENAI_BASE_URL,// 支持 DeepSeek 等兼容接口});5.3 HeroUI 配置HeroUI 需要包裹HeroUIProvider。在src/app/layout.tsx中import{HeroUIProvider}fromheroui/react;exportdefaultfunctionRootLayout({children}:{children:React.ReactNode}){return(html langzh-CNbodyHeroUIProvider{children}/HeroUIProvider/body/html);}6. 项目架构流转图初始化完成后我们的项目数据流如下7. 测试验证运行开发服务器npmrun dev访问http://localhost:3000如果看到 Next.js 默认页面且没有报错说明项目骨架搭建成功。验证清单项目能正常启动HeroUI 组件能正常渲染Prisma 能正常连接数据库检查控制台无报错环境变量能正常读取8. 常见问题与踩坑分析问题 1Prisma 在 Next.js 中导致连接池耗尽原因Next.js 的 HMR热更新会在每次代码修改时重新执行模块导致 Prisma Client 被反复实例化。解决在src/lib/db/index.ts中使用全局单例模式import{PrismaClient}fromprisma/client;constglobalForPrismaglobalThisasunknownas{prisma:PrismaClient};exportconstprismaglobalForPrisma.prisma||newPrismaClient();if(process.env.NODE_ENV!production)globalForPrisma.prismaprisma;问题 2HeroUI 样式不生效原因HeroUI 依赖 Tailwind CSS 的插件配置。解决确保在 tailwind.config.ts 中正确配置了 heroui/theme 插件。本章总结我们创建了基于 App Router 的 Next.js 项目选择了 src/ 目录结构。安装了 AI SDK、Prisma、HeroUI、react-markdown 等核心依赖。建立了符合 AI Agent 开发范式的目录结构将 UI、AI 逻辑、数据库配置分离。完成了 Prisma 初始化与 AI SDK 基础配置。解决了 Prisma 连接池、HeroUI 样式等常见踩坑问题。项目骨架已经搭建完毕并且可以正常运行。从下一章开始我们将正式接入大模型实现第一个流式对话功能。
