1332 lines
28 KiB
Markdown
1332 lines
28 KiB
Markdown
# AI Chatbot 开发文档
|
||
|
||
## 目录
|
||
|
||
- [项目概述](#项目概述)
|
||
- [技术栈](#技术栈)
|
||
- [项目结构](#项目结构)
|
||
- [环境配置](#环境配置)
|
||
- [核心功能模块](#核心功能模块)
|
||
- [数据库设计](#数据库设计)
|
||
- [API 路由](#api-路由)
|
||
- [认证系统](#认证系统)
|
||
- [AI 集成](#ai-集成)
|
||
- [Artifact 系统](#artifact-系统)
|
||
- [开发指南](#开发指南)
|
||
- [部署指南](#部署指南)
|
||
- [系统设置和管理员功能](#系统设置和管理员功能)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于 Next.js 16 和 AI SDK 构建的现代化 AI 聊天机器人应用。项目提供了完整的聊天功能、用户认证、消息持久化、以及多种 AI 工具集成（文档创建、代码编辑、表格处理等）。
|
||
|
||
### 主要特性
|
||
|
||
- ✅ Next.js App Router 架构
|
||
- ✅ React Server Components (RSCs) 和 Server Actions
|
||
- ✅ AI SDK 统一 API，支持多种模型提供商
|
||
- ✅ 完整的用户认证系统（支持注册用户和访客模式）
|
||
- ✅ 消息历史持久化
|
||
- ✅ 多种 Artifact 类型（文本、代码、表格、图片）
|
||
- ✅ 实时流式响应
|
||
- ✅ 可恢复的流式传输（需要 Redis）
|
||
- ✅ 消息投票功能
|
||
- ✅ 文档建议系统
|
||
- ✅ 响应式 UI（基于 shadcn/ui）
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
### 核心框架
|
||
|
||
- **Next.js 16.0.5** - React 框架，使用 App Router
|
||
- **React 19.0.0-rc** - UI 库
|
||
- **TypeScript 5.6.3** - 类型安全
|
||
|
||
### AI 相关
|
||
|
||
- **AI SDK 5.0.26** - Vercel AI SDK，统一 AI 模型接口
|
||
- **@ai-sdk/gateway** - Vercel AI Gateway，统一访问多个 AI 模型
|
||
- **@ai-sdk/react** - React hooks for AI
|
||
- **tokenlens** - Token 使用量统计和分析
|
||
|
||
### 数据库
|
||
|
||
- **Drizzle ORM 0.34.0** - 类型安全的 ORM
|
||
- **PostgreSQL** - 主数据库（通过 Neon Serverless Postgres）
|
||
- **Redis 5.0.0** - 可恢复流式传输（可选）
|
||
|
||
### 认证
|
||
|
||
- **NextAuth 5.0.0-beta.25** - 认证框架
|
||
- **bcrypt-ts** - 密码加密
|
||
|
||
### UI 组件
|
||
|
||
- **shadcn/ui** - UI 组件库
|
||
- **Radix UI** - 无障碍组件原语
|
||
- **Tailwind CSS 4.1.13** - 样式框架
|
||
- **Framer Motion** - 动画库
|
||
|
||
### 编辑器
|
||
|
||
- **CodeMirror 6** - 代码编辑器
|
||
- **ProseMirror** - 富文本编辑器
|
||
- **react-data-grid** - 表格编辑器
|
||
|
||
### 工具库
|
||
|
||
- **Zod** - 模式验证
|
||
- **date-fns** - 日期处理
|
||
- **SWR** - 数据获取和缓存
|
||
- **nanoid** - ID 生成
|
||
|
||
### 开发工具
|
||
|
||
- **Biome** - 代码格式化和 linting
|
||
- **Playwright** - E2E 测试
|
||
- **Drizzle Kit** - 数据库迁移工具
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ai-chatbot-main/
|
||
├── app/ # Next.js App Router 目录
|
||
│ ├── (auth)/ # 认证相关路由组
|
||
│ │ ├── actions.ts # Server Actions
|
||
│ │ ├── auth.ts # NextAuth 配置
|
||
│ │ ├── auth.config.ts # 认证配置
|
||
│ │ ├── login/ # 登录页面
|
||
│ │ └── register/ # 注册页面
|
||
│ ├── (chat)/ # 聊天相关路由组
|
||
│ │ ├── actions.ts # Server Actions
|
||
│ │ ├── api/ # API 路由
|
||
│ │ │ ├── chat/ # 聊天 API
|
||
│ │ │ ├── document/ # 文档 API
|
||
│ │ │ ├── files/ # 文件 API
|
||
│ │ │ ├── history/ # 历史记录 API
|
||
│ │ │ ├── suggestions/ # 建议 API
|
||
│ │ │ └── vote/ # 投票 API
|
||
│ │ ├── chat/[id]/ # 聊天详情页
|
||
│ │ ├── layout.tsx # 聊天布局
|
||
│ │ └── page.tsx # 聊天首页
|
||
│ ├── layout.tsx # 根布局
|
||
│ └── globals.css # 全局样式
|
||
├── artifacts/ # Artifact 实现
|
||
│ ├── code/ # 代码 Artifact
|
||
│ ├── image/ # 图片 Artifact
|
||
│ ├── sheet/ # 表格 Artifact
|
||
│ └── text/ # 文本 Artifact
|
||
├── components/ # React 组件
|
||
│ ├── elements/ # 消息元素组件
|
||
│ ├── ui/ # shadcn/ui 组件
|
||
│ ├── artifact.tsx # Artifact 容器
|
||
│ ├── chat.tsx # 聊天主组件
|
||
│ ├── messages.tsx # 消息列表
|
||
│ └── ...
|
||
├── hooks/ # React Hooks
|
||
│ ├── use-artifact.ts # Artifact 管理
|
||
│ ├── use-chat-visibility.ts # 聊天可见性
|
||
│ ├── use-messages.tsx # 消息管理
|
||
│ └── ...
|
||
├── lib/ # 工具库
|
||
│ ├── ai/ # AI 相关
|
||
│ │ ├── models.ts # 模型定义
|
||
│ │ ├── providers.ts # 模型提供商
|
||
│ │ ├── prompts.ts # 提示词模板
|
||
│ │ ├── entitlements.ts # 用户权限
|
||
│ │ └── tools/ # AI 工具
|
||
│ ├── db/ # 数据库
|
||
│ │ ├── schema.ts # 数据库模式
|
||
│ │ ├── queries.ts # 数据库查询
|
||
│ │ ├── migrations/ # 数据库迁移
|
||
│ │ └── utils.ts # 数据库工具
|
||
│ ├── artifacts/ # Artifact 服务端逻辑
|
||
│ ├── editor/ # 编辑器配置
|
||
│ ├── errors.ts # 错误处理
|
||
│ ├── types.ts # 类型定义
|
||
│ └── utils.ts # 工具函数
|
||
├── tests/ # 测试文件
|
||
│ ├── e2e/ # E2E 测试
|
||
│ ├── pages/ # 页面对象模型
|
||
│ └── routes/ # API 路由测试
|
||
├── public/ # 静态资源
|
||
├── biome.jsonc # Biome 配置
|
||
├── drizzle.config.ts # Drizzle 配置
|
||
├── next.config.ts # Next.js 配置
|
||
├── package.json # 依赖配置
|
||
└── tsconfig.json # TypeScript 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 环境配置
|
||
|
||
### 必需的环境变量
|
||
|
||
创建 `.env.local` 文件并配置以下变量：
|
||
|
||
```bash
|
||
# 数据库
|
||
POSTGRES_URL=postgresql://user:password@host:port/database
|
||
|
||
# NextAuth
|
||
AUTH_SECRET=your-secret-key-here
|
||
AUTH_URL=http://localhost:3000
|
||
|
||
# AI Gateway (非 Vercel 部署时需要)
|
||
AI_GATEWAY_API_KEY=your-gateway-api-key
|
||
|
||
# Redis (可选，用于可恢复流式传输)
|
||
REDIS_URL=redis://localhost:6379
|
||
|
||
# Vercel Blob (文件存储，可选)
|
||
BLOB_READ_WRITE_TOKEN=your-blob-token
|
||
```
|
||
|
||
### 环境变量说明
|
||
|
||
- **POSTGRES_URL**: PostgreSQL 数据库连接字符串（必需）
|
||
- **AUTH_SECRET**: NextAuth 加密密钥，使用 `openssl rand -base64 32` 生成（必需）
|
||
- **AUTH_URL**: 应用的基础 URL（必需）
|
||
- **AI_GATEWAY_API_KEY**: Vercel AI Gateway API 密钥（非 Vercel 部署时必需）
|
||
- **REDIS_URL**: Redis 连接字符串（可选，用于可恢复流式传输）
|
||
- **BLOB_READ_WRITE_TOKEN**: Vercel Blob 存储令牌（可选）
|
||
|
||
### 安装和运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 运行数据库迁移
|
||
pnpm db:migrate
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
```
|
||
|
||
应用将在 `http://localhost:3000` 运行。
|
||
|
||
---
|
||
|
||
## 核心功能模块
|
||
|
||
### 1. 聊天系统
|
||
|
||
聊天系统是应用的核心，位于 `app/(chat)/` 目录。
|
||
|
||
#### 主要组件
|
||
|
||
- **`components/chat.tsx`**: 聊天主组件，管理消息状态和 UI
|
||
- **`components/messages.tsx`**: 消息列表组件
|
||
- **`components/message.tsx`**: 单条消息组件
|
||
- **`components/multimodal-input.tsx`**: 多模态输入组件（支持文本、文件等）
|
||
|
||
#### 关键功能
|
||
|
||
- 实时流式响应
|
||
- 消息历史持久化
|
||
- 消息投票（点赞/点踩）
|
||
- 消息重新生成
|
||
- 消息编辑
|
||
- 自动滚动到底部
|
||
|
||
### 2. 用户认证
|
||
|
||
认证系统使用 NextAuth 5，支持两种用户类型：
|
||
|
||
- **注册用户**: 通过邮箱和密码注册
|
||
- **访客用户**: 临时用户，无需注册
|
||
|
||
**注意**: 当前版本**没有管理员功能**，所有用户都是普通用户。如需添加管理员功能，需要扩展用户表和认证系统。
|
||
|
||
#### 认证流程
|
||
|
||
1. 用户访问应用
|
||
2. 未登录用户自动创建访客账户
|
||
3. 注册用户通过登录页面登录
|
||
4. 会话信息存储在 JWT 中
|
||
|
||
#### 相关文件
|
||
|
||
- `app/(auth)/auth.ts`: NextAuth 配置
|
||
- `app/(auth)/auth.config.ts`: 认证配置
|
||
- `app/(auth)/login/page.tsx`: 登录页面
|
||
- `app/(auth)/register/page.tsx`: 注册页面
|
||
|
||
### 3. 消息系统
|
||
|
||
消息系统使用新的 `parts` 架构，支持多种内容类型。
|
||
|
||
#### 消息结构
|
||
|
||
```typescript
|
||
type DBMessage = {
|
||
id: string;
|
||
chatId: string;
|
||
role: "user" | "assistant";
|
||
parts: MessagePart[]; // 消息部分数组
|
||
attachments: Attachment[];
|
||
createdAt: Date;
|
||
};
|
||
```
|
||
|
||
#### 消息部分类型
|
||
|
||
- `text`: 文本内容
|
||
- `tool-call`: 工具调用
|
||
- `tool-result`: 工具结果
|
||
- `data`: 自定义数据
|
||
|
||
### 4. Artifact 系统
|
||
|
||
Artifact 是 AI 生成的可编辑文档，支持四种类型：
|
||
|
||
- **text**: 富文本文档
|
||
- **code**: 代码文件
|
||
- **sheet**: 表格数据
|
||
- **image**: 图片生成
|
||
|
||
#### Artifact 架构
|
||
|
||
每个 Artifact 类型包含：
|
||
|
||
1. **客户端组件** (`artifacts/{kind}/client.tsx`): UI 渲染和交互
|
||
2. **服务端处理器** (`artifacts/{kind}/server.ts`): 创建和更新逻辑
|
||
|
||
#### 创建 Artifact
|
||
|
||
```typescript
|
||
// AI 工具调用
|
||
createDocument({
|
||
title: "示例代码",
|
||
kind: "code"
|
||
})
|
||
```
|
||
|
||
#### 更新 Artifact
|
||
|
||
```typescript
|
||
// AI 工具调用
|
||
updateDocument({
|
||
documentId: "...",
|
||
description: "添加错误处理"
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### 表结构
|
||
|
||
#### User 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
email: varchar(64) (唯一)
|
||
password: varchar(64) (可空，访客用户无密码)
|
||
}
|
||
```
|
||
|
||
#### Chat 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
createdAt: timestamp
|
||
title: text
|
||
userId: uuid (外键 -> User.id)
|
||
visibility: "public" | "private"
|
||
lastContext: jsonb (最后的使用统计)
|
||
}
|
||
```
|
||
|
||
#### Message_v2 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
chatId: uuid (外键 -> Chat.id)
|
||
role: "user" | "assistant"
|
||
parts: json (消息部分数组)
|
||
attachments: json (附件数组)
|
||
createdAt: timestamp
|
||
}
|
||
```
|
||
|
||
#### Document 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
createdAt: timestamp (主键的一部分)
|
||
title: text
|
||
content: text (可空)
|
||
kind: "text" | "code" | "image" | "sheet"
|
||
userId: uuid (外键 -> User.id)
|
||
}
|
||
```
|
||
|
||
#### Vote_v2 表
|
||
|
||
```typescript
|
||
{
|
||
chatId: uuid (主键的一部分)
|
||
messageId: uuid (主键的一部分)
|
||
isUpvoted: boolean
|
||
}
|
||
```
|
||
|
||
#### Suggestion 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
documentId: uuid
|
||
documentCreatedAt: timestamp
|
||
originalText: text
|
||
suggestedText: text
|
||
description: text (可空)
|
||
isResolved: boolean
|
||
userId: uuid (外键 -> User.id)
|
||
createdAt: timestamp
|
||
}
|
||
```
|
||
|
||
#### Stream 表
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
chatId: uuid (外键 -> Chat.id)
|
||
createdAt: timestamp
|
||
}
|
||
```
|
||
|
||
### 数据库查询
|
||
|
||
所有数据库查询函数位于 `lib/db/queries.ts`，包括：
|
||
|
||
- `getUser()`: 获取用户
|
||
- `createUser()`: 创建用户
|
||
- `createGuestUser()`: 创建访客用户
|
||
- `saveChat()`: 保存聊天
|
||
- `getChatById()`: 获取聊天
|
||
- `getMessagesByChatId()`: 获取消息列表
|
||
- `saveMessages()`: 保存消息
|
||
- `saveDocument()`: 保存文档
|
||
- `getDocumentById()`: 获取文档
|
||
- 等等...
|
||
|
||
### 数据库迁移
|
||
|
||
使用 Drizzle Kit 管理数据库迁移：
|
||
|
||
```bash
|
||
# 生成迁移文件
|
||
pnpm db:generate
|
||
|
||
# 应用迁移
|
||
pnpm db:migrate
|
||
|
||
# 推送更改（开发环境）
|
||
pnpm db:push
|
||
|
||
# 打开 Drizzle Studio
|
||
pnpm db:studio
|
||
```
|
||
|
||
---
|
||
|
||
## API 路由
|
||
|
||
### 聊天 API
|
||
|
||
**路径**: `/api/chat`
|
||
|
||
#### POST - 发送消息
|
||
|
||
创建新聊天或继续现有聊天。
|
||
|
||
**请求体**:
|
||
```typescript
|
||
{
|
||
id: string; // 聊天 ID
|
||
message: ChatMessage; // 用户消息
|
||
selectedChatModel: string; // 选择的模型 ID
|
||
selectedVisibilityType: "public" | "private";
|
||
}
|
||
```
|
||
|
||
**响应**: Server-Sent Events (SSE) 流
|
||
|
||
**功能**:
|
||
- 验证用户身份
|
||
- 检查速率限制
|
||
- 创建或获取聊天
|
||
- 流式生成 AI 响应
|
||
- 保存消息到数据库
|
||
|
||
#### DELETE - 删除聊天
|
||
|
||
**查询参数**:
|
||
- `id`: 聊天 ID
|
||
|
||
**响应**: 删除的聊天对象
|
||
|
||
### 文档 API
|
||
|
||
**路径**: `/api/document/[id]`
|
||
|
||
#### GET - 获取文档
|
||
|
||
获取指定 ID 的文档。
|
||
|
||
#### POST - 更新文档
|
||
|
||
更新文档内容。
|
||
|
||
### 文件 API
|
||
|
||
**路径**: `/api/files`
|
||
|
||
处理文件上传和存储。
|
||
|
||
### 历史记录 API
|
||
|
||
**路径**: `/api/history`
|
||
|
||
获取用户的聊天历史记录（分页）。
|
||
|
||
### 建议 API
|
||
|
||
**路径**: `/api/suggestions`
|
||
|
||
获取文档的建议列表。
|
||
|
||
### 投票 API
|
||
|
||
**路径**: `/api/vote`
|
||
|
||
对消息进行投票（点赞/点踩）。
|
||
|
||
---
|
||
|
||
## 认证系统
|
||
|
||
### NextAuth 配置
|
||
|
||
认证系统使用 NextAuth 5，配置在 `app/(auth)/auth.ts`。
|
||
|
||
#### 认证提供者
|
||
|
||
1. **Credentials Provider**: 邮箱密码登录
|
||
2. **Guest Provider**: 访客模式（自动创建临时用户）
|
||
|
||
#### 会话结构
|
||
|
||
```typescript
|
||
{
|
||
user: {
|
||
id: string;
|
||
email: string | null;
|
||
type: "guest" | "regular";
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 认证中间件
|
||
|
||
使用 `auth()` 函数获取当前会话：
|
||
|
||
```typescript
|
||
import { auth } from "@/app/(auth)/auth";
|
||
|
||
const session = await auth();
|
||
if (!session?.user) {
|
||
// 未登录
|
||
}
|
||
```
|
||
|
||
### 用户权限
|
||
|
||
用户权限定义在 `lib/ai/entitlements.ts`：
|
||
|
||
```typescript
|
||
export const entitlementsByUserType = {
|
||
guest: {
|
||
maxMessagesPerDay: 10,
|
||
},
|
||
regular: {
|
||
maxMessagesPerDay: 100,
|
||
},
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## AI 集成
|
||
|
||
### 模型提供商
|
||
|
||
项目使用 Vercel AI Gateway 统一访问多个 AI 模型，配置在 `lib/ai/providers.ts`。
|
||
|
||
#### 可用模型
|
||
|
||
- **chat-model**: Grok Vision (xai/grok-2-vision-1212)
|
||
- **chat-model-reasoning**: Grok Reasoning (xai/grok-3-mini)
|
||
- **title-model**: Grok 2 (xai/grok-2-1212)
|
||
- **artifact-model**: Grok 2 (xai/grok-2-1212)
|
||
|
||
#### 切换模型提供商
|
||
|
||
要切换到其他提供商（如 OpenAI），修改 `lib/ai/providers.ts`：
|
||
|
||
```typescript
|
||
import { openai } from "@ai-sdk/openai";
|
||
|
||
export const myProvider = customProvider({
|
||
languageModels: {
|
||
"chat-model": openai("gpt-4"),
|
||
// ...
|
||
},
|
||
});
|
||
```
|
||
|
||
### AI 工具
|
||
|
||
AI 可以调用以下工具：
|
||
|
||
1. **getWeather**: 获取天气信息
|
||
2. **createDocument**: 创建文档（text/code/sheet/image）
|
||
3. **updateDocument**: 更新文档
|
||
4. **requestSuggestions**: 请求文档建议
|
||
|
||
#### 添加新工具
|
||
|
||
1. 在 `lib/ai/tools/` 创建工具文件
|
||
2. 在 `app/(chat)/api/chat/route.ts` 注册工具：
|
||
|
||
```typescript
|
||
tools: {
|
||
// ... 现有工具
|
||
myNewTool: myNewTool({ session, dataStream }),
|
||
}
|
||
```
|
||
|
||
3. 在 `experimental_activeTools` 数组中添加工具名称
|
||
|
||
### 提示词系统
|
||
|
||
系统提示词定义在 `lib/ai/prompts.ts`，包括：
|
||
|
||
- `systemPrompt()`: 主聊天提示词
|
||
- `titlePrompt`: 标题生成提示词
|
||
- `codePrompt`: 代码生成提示词
|
||
- `textPrompt`: 文本生成提示词
|
||
- `sheetPrompt`: 表格生成提示词
|
||
- `updateDocumentPrompt()`: 文档更新提示词
|
||
|
||
### 流式响应
|
||
|
||
使用 AI SDK 的 `streamText()` 和 `createUIMessageStream()` 实现流式响应：
|
||
|
||
```typescript
|
||
const stream = createUIMessageStream({
|
||
execute: ({ writer: dataStream }) => {
|
||
const result = streamText({
|
||
model: myProvider.languageModel(selectedChatModel),
|
||
messages: convertToModelMessages(uiMessages),
|
||
tools: { /* ... */ },
|
||
});
|
||
|
||
dataStream.merge(result.toUIMessageStream());
|
||
},
|
||
onFinish: async ({ messages }) => {
|
||
// 保存消息到数据库
|
||
},
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## Artifact 系统
|
||
|
||
### Artifact 类型
|
||
|
||
#### 1. Text Artifact
|
||
|
||
富文本文档，使用 ProseMirror 编辑器。
|
||
|
||
**文件**:
|
||
- `artifacts/text/client.tsx`: 客户端组件
|
||
- `artifacts/text/server.ts`: 服务端处理器
|
||
|
||
**功能**:
|
||
- Markdown 支持
|
||
- 实时编辑
|
||
- 版本历史
|
||
|
||
#### 2. Code Artifact
|
||
|
||
代码文件，使用 CodeMirror 编辑器。
|
||
|
||
**文件**:
|
||
- `artifacts/code/client.tsx`: 客户端组件
|
||
- `artifacts/code/server.ts`: 服务端处理器
|
||
|
||
**功能**:
|
||
- 语法高亮
|
||
- 代码补全
|
||
- 多语言支持（JavaScript、Python 等）
|
||
- 代码执行（通过 Pyodide）
|
||
|
||
#### 3. Sheet Artifact
|
||
|
||
表格数据，使用 react-data-grid。
|
||
|
||
**文件**:
|
||
- `artifacts/sheet/client.tsx`: 客户端组件
|
||
- `artifacts/sheet/server.ts`: 服务端处理器
|
||
|
||
**功能**:
|
||
- CSV 导入/导出
|
||
- 数据格式化
|
||
- 数据清理工具
|
||
|
||
#### 4. Image Artifact
|
||
|
||
图片生成和编辑。
|
||
|
||
**文件**:
|
||
- `artifacts/image/client.tsx`: 客户端组件
|
||
|
||
**功能**:
|
||
- 图片生成
|
||
- 图片编辑
|
||
- 版本历史
|
||
|
||
### 创建自定义 Artifact
|
||
|
||
1. **定义 Artifact 类型**
|
||
|
||
在 `components/artifact.tsx` 中添加类型：
|
||
|
||
```typescript
|
||
export const artifactDefinitions = [
|
||
// ... 现有 Artifact
|
||
myCustomArtifact,
|
||
];
|
||
```
|
||
|
||
2. **创建客户端组件**
|
||
|
||
`artifacts/my-custom/client.tsx`:
|
||
|
||
```typescript
|
||
import { Artifact } from "@/components/create-artifact";
|
||
|
||
export const myCustomArtifact = new Artifact({
|
||
kind: "my-custom",
|
||
description: "我的自定义 Artifact",
|
||
initialize: () => null,
|
||
onStreamPart: ({ setArtifact, streamPart }) => {
|
||
if (streamPart.type === "data-myCustomDelta") {
|
||
setArtifact((draft) => ({
|
||
...draft,
|
||
content: streamPart.data,
|
||
isVisible: true,
|
||
status: "streaming",
|
||
}));
|
||
}
|
||
},
|
||
content: ({ content }) => {
|
||
return <MyCustomEditor content={content} />;
|
||
},
|
||
});
|
||
```
|
||
|
||
3. **创建服务端处理器**
|
||
|
||
`artifacts/my-custom/server.ts`:
|
||
|
||
```typescript
|
||
import { createDocumentHandler } from "@/lib/artifacts/server";
|
||
|
||
export const myCustomDocumentHandler = createDocumentHandler({
|
||
kind: "my-custom",
|
||
onCreateDocument: async ({ title, dataStream }) => {
|
||
// 生成内容逻辑
|
||
// 使用 dataStream.write() 发送增量更新
|
||
return finalContent;
|
||
},
|
||
onUpdateDocument: async ({ document, description, dataStream }) => {
|
||
// 更新内容逻辑
|
||
return updatedContent;
|
||
},
|
||
});
|
||
```
|
||
|
||
4. **注册处理器**
|
||
|
||
在 `lib/artifacts/server.ts` 中注册：
|
||
|
||
```typescript
|
||
export const documentHandlersByArtifactKind = [
|
||
// ... 现有处理器
|
||
myCustomDocumentHandler,
|
||
];
|
||
```
|
||
|
||
5. **更新数据库模式**
|
||
|
||
在 `lib/db/schema.ts` 中更新 `Document.kind` 类型：
|
||
|
||
```typescript
|
||
kind: varchar("text", {
|
||
enum: ["text", "code", "image", "sheet", "my-custom"]
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 代码规范
|
||
|
||
项目使用 Biome 进行代码格式化和 linting，配置继承自 Ultracite。
|
||
|
||
#### 运行检查
|
||
|
||
```bash
|
||
# 检查代码
|
||
pnpm lint
|
||
|
||
# 自动修复
|
||
pnpm format
|
||
```
|
||
|
||
#### 主要规则
|
||
|
||
- 使用 TypeScript 严格模式
|
||
- 遵循 React Hooks 规则
|
||
- 使用函数式组件和 Hooks
|
||
- 避免使用 `any` 类型
|
||
- 使用 Zod 进行数据验证
|
||
- 遵循无障碍性 (a11y) 标准
|
||
|
||
### 添加新功能
|
||
|
||
#### 1. 添加新的 API 路由
|
||
|
||
在 `app/(chat)/api/` 下创建新目录和 `route.ts` 文件：
|
||
|
||
```typescript
|
||
import { auth } from "@/app/(auth)/auth";
|
||
|
||
export async function GET(request: Request) {
|
||
const session = await auth();
|
||
if (!session?.user) {
|
||
return new Response("Unauthorized", { status: 401 });
|
||
}
|
||
|
||
// 处理逻辑
|
||
return Response.json({ data: "..." });
|
||
}
|
||
```
|
||
|
||
#### 2. 添加新的 Server Action
|
||
|
||
在 `app/(chat)/actions.ts` 中添加：
|
||
|
||
```typescript
|
||
"use server";
|
||
|
||
export async function myAction() {
|
||
// 服务端逻辑
|
||
}
|
||
```
|
||
|
||
#### 3. 添加新的 UI 组件
|
||
|
||
在 `components/` 目录下创建组件：
|
||
|
||
```typescript
|
||
"use client";
|
||
|
||
export function MyComponent() {
|
||
return <div>...</div>;
|
||
}
|
||
```
|
||
|
||
### 测试
|
||
|
||
项目使用 Playwright 进行 E2E 测试。
|
||
|
||
#### 运行测试
|
||
|
||
```bash
|
||
pnpm test
|
||
```
|
||
|
||
#### 测试文件结构
|
||
|
||
- `tests/e2e/`: E2E 测试用例
|
||
- `tests/pages/`: 页面对象模型
|
||
- `tests/routes/`: API 路由测试
|
||
|
||
### 调试
|
||
|
||
#### 开发模式
|
||
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
|
||
#### 数据库调试
|
||
|
||
使用 Drizzle Studio：
|
||
|
||
```bash
|
||
pnpm db:studio
|
||
```
|
||
|
||
#### 查看日志
|
||
|
||
- 服务端日志：控制台输出
|
||
- 客户端日志：浏览器控制台
|
||
|
||
---
|
||
|
||
## 部署指南
|
||
|
||
### Vercel 部署
|
||
|
||
1. **连接 GitHub 仓库**
|
||
|
||
在 Vercel 控制台连接你的 GitHub 仓库。
|
||
|
||
2. **配置环境变量**
|
||
|
||
在 Vercel 项目设置中添加环境变量：
|
||
- `POSTGRES_URL`
|
||
- `AUTH_SECRET`
|
||
- `AUTH_URL`
|
||
- `REDIS_URL` (可选)
|
||
- `BLOB_READ_WRITE_TOKEN` (可选)
|
||
|
||
3. **部署**
|
||
|
||
推送代码到 GitHub，Vercel 会自动部署。
|
||
|
||
### 数据库迁移
|
||
|
||
在部署前或部署后运行迁移：
|
||
|
||
```bash
|
||
pnpm db:migrate
|
||
```
|
||
|
||
或在 Vercel 的构建命令中：
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"build": "tsx lib/db/migrate && next build"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 环境检查清单
|
||
|
||
- [ ] PostgreSQL 数据库已配置
|
||
- [ ] 环境变量已设置
|
||
- [ ] 数据库迁移已运行
|
||
- [ ] AI Gateway API 密钥已配置（如需要）
|
||
- [ ] Redis 已配置（如需要可恢复流式传输）
|
||
|
||
---
|
||
|
||
## 系统设置和管理员功能
|
||
|
||
### 功能概述
|
||
|
||
项目已实现完整的管理员系统设置功能，包括：
|
||
|
||
- ✅ 用户管理（激活/删除/编辑用户）
|
||
- ✅ 网站设置（LOGO、网站名、浏览器图标、主题模式LOGO）
|
||
- ✅ 工具库管理（启用/禁用 AI 工具）
|
||
|
||
### 数据库 Schema
|
||
|
||
#### User 表扩展
|
||
|
||
已为 User 表添加以下字段：
|
||
|
||
```typescript
|
||
{
|
||
role: "guest" | "regular" | "admin" (默认: "regular")
|
||
isActive: boolean (默认: true)
|
||
createdAt: timestamp
|
||
updatedAt: timestamp
|
||
}
|
||
```
|
||
|
||
#### SystemSettings 表
|
||
|
||
用于存储系统配置：
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
key: string (唯一键)
|
||
value: jsonb (配置值)
|
||
updatedAt: timestamp
|
||
updatedBy: uuid (外键 -> User.id)
|
||
}
|
||
```
|
||
|
||
支持的配置键：
|
||
- `siteName`: 网站名称
|
||
- `siteLogo`: 网站 LOGO URL
|
||
- `favicon`: 浏览器图标 URL
|
||
- `logoLight`: 白天模式 LOGO URL
|
||
- `logoDark`: 黑夜模式 LOGO URL
|
||
|
||
#### ToolConfig 表
|
||
|
||
用于管理 AI 工具配置：
|
||
|
||
```typescript
|
||
{
|
||
id: uuid (主键)
|
||
toolName: string (唯一键)
|
||
isEnabled: boolean (是否启用)
|
||
description: string (工具描述)
|
||
config: jsonb (工具配置)
|
||
updatedAt: timestamp
|
||
updatedBy: uuid (外键 -> User.id)
|
||
}
|
||
```
|
||
|
||
### 认证系统
|
||
|
||
#### 用户类型
|
||
|
||
系统支持三种用户类型：
|
||
|
||
- **guest**: 访客用户（临时账户）
|
||
- **regular**: 普通注册用户
|
||
- **admin**: 管理员用户
|
||
|
||
#### 管理员权限
|
||
|
||
管理员拥有以下权限：
|
||
|
||
- 无限消息数量（`maxMessagesPerDay: Infinity`）
|
||
- 访问所有 AI 模型
|
||
- 访问系统设置页面
|
||
- 管理用户账户
|
||
- 配置系统设置
|
||
- 管理 AI 工具
|
||
|
||
### 管理员中间件
|
||
|
||
使用 `lib/middleware/admin.ts` 中的 `requireAdmin()` 函数保护管理员路由：
|
||
|
||
```typescript
|
||
import { requireAdmin } from "@/lib/middleware/admin";
|
||
|
||
export async function GET(request: Request) {
|
||
const session = await requireAdmin();
|
||
// 只有管理员可以访问
|
||
}
|
||
```
|
||
|
||
### API 路由
|
||
|
||
#### 用户管理 API
|
||
|
||
**路径**: `/api/admin/users`
|
||
|
||
- **GET**: 获取用户列表（支持分页）
|
||
- 查询参数: `limit`, `offset`
|
||
- **PATCH**: 更新用户信息
|
||
- 请求体: `{ id, email?, role?, isActive? }`
|
||
- **DELETE**: 删除用户
|
||
- 查询参数: `id`
|
||
|
||
#### 系统设置 API
|
||
|
||
**路径**: `/api/admin/settings`
|
||
|
||
- **GET**: 获取系统设置
|
||
- 查询参数: `key` (可选，获取特定设置)
|
||
- **POST**: 更新系统设置
|
||
- 请求体: `{ key, value }`
|
||
|
||
#### 工具管理 API
|
||
|
||
**路径**: `/api/admin/tools`
|
||
|
||
- **GET**: 获取工具配置列表
|
||
- 查询参数: `toolName` (可选，获取特定工具)
|
||
- **POST**: 更新工具配置
|
||
- 请求体: `{ toolName, isEnabled, description?, config? }`
|
||
|
||
### 系统设置页面
|
||
|
||
**路径**: `/admin/settings`
|
||
|
||
管理员可以通过此页面管理：
|
||
|
||
#### 1. 用户管理
|
||
|
||
- 查看所有用户列表
|
||
- 修改用户角色（guest/regular/admin）
|
||
- 激活/禁用用户账户
|
||
- 删除用户账户
|
||
|
||
#### 2. 网站设置
|
||
|
||
- 设置网站名称
|
||
- 配置网站 LOGO URL
|
||
- 配置浏览器图标（Favicon）URL
|
||
- 配置白天模式 LOGO URL
|
||
- 配置黑夜模式 LOGO URL
|
||
|
||
#### 3. 工具库管理
|
||
|
||
- 查看所有可用 AI 工具
|
||
- 启用/禁用工具
|
||
- 工具状态实时更新
|
||
|
||
### 工具注册系统
|
||
|
||
系统使用 `lib/ai/tools-registry.ts` 管理工具启用状态：
|
||
|
||
```typescript
|
||
import { getEnabledTools } from "@/lib/ai/tools-registry";
|
||
|
||
// 获取启用的工具列表
|
||
const enabledTools = await getEnabledTools();
|
||
// 返回: ["getWeather", "createDocument", ...]
|
||
```
|
||
|
||
聊天 API 会自动根据工具配置决定哪些工具可用。
|
||
|
||
### 数据库迁移
|
||
|
||
运行以下命令创建数据库迁移：
|
||
|
||
```bash
|
||
# 生成迁移文件
|
||
pnpm db:generate
|
||
|
||
# 应用迁移
|
||
pnpm db:migrate
|
||
```
|
||
|
||
### 创建管理员账户
|
||
|
||
要创建管理员账户，可以通过以下方式：
|
||
|
||
1. **通过数据库直接更新**：
|
||
|
||
```sql
|
||
UPDATE "User" SET role = 'admin' WHERE email = 'admin@example.com';
|
||
```
|
||
|
||
2. **通过系统设置页面**：
|
||
|
||
- 以管理员身份登录
|
||
- 访问 `/admin/settings`
|
||
- 在"用户管理"标签页中找到目标用户
|
||
- 将角色修改为"管理员"
|
||
|
||
### 使用示例
|
||
|
||
#### 访问系统设置页面
|
||
|
||
1. 以管理员身份登录
|
||
2. 访问 `http://localhost:3000/admin/settings`
|
||
3. 使用三个标签页管理不同功能
|
||
|
||
#### 更新网站设置
|
||
|
||
```typescript
|
||
// 通过 API
|
||
await fetch("/api/admin/settings", {
|
||
method: "POST",
|
||
headers: { "Content-Type": "application/json" },
|
||
body: JSON.stringify({
|
||
key: "siteName",
|
||
value: "我的 AI 聊天机器人",
|
||
}),
|
||
});
|
||
```
|
||
|
||
#### 禁用工具
|
||
|
||
```typescript
|
||
// 通过 API
|
||
await fetch("/api/admin/tools", {
|
||
method: "POST",
|
||
headers: { "Content-Type": "application/json" },
|
||
body: JSON.stringify({
|
||
toolName: "getWeather",
|
||
isEnabled: false,
|
||
description: "获取天气信息",
|
||
}),
|
||
});
|
||
```
|
||
|
||
### 安全注意事项
|
||
|
||
- 所有管理员 API 都使用 `requireAdmin()` 中间件保护
|
||
- 只有管理员角色的用户才能访问系统设置页面
|
||
- 用户删除操作需要确认，防止误操作
|
||
- 系统设置更改会记录更新者信息
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1. 数据库连接失败
|
||
|
||
**问题**: 无法连接到 PostgreSQL 数据库
|
||
|
||
**解决方案**:
|
||
- 检查 `POSTGRES_URL` 环境变量是否正确
|
||
- 确认数据库服务正在运行
|
||
- 检查网络连接和防火墙设置
|
||
|
||
### 2. 认证失败
|
||
|
||
**问题**: 用户无法登录
|
||
|
||
**解决方案**:
|
||
- 检查 `AUTH_SECRET` 是否设置
|
||
- 确认 `AUTH_URL` 与部署 URL 匹配
|
||
- 检查数据库中的用户数据
|
||
|
||
### 3. AI 模型无响应
|
||
|
||
**问题**: AI 模型不返回响应
|
||
|
||
**解决方案**:
|
||
- 检查 AI Gateway API 密钥（非 Vercel 部署）
|
||
- 确认模型 ID 正确
|
||
- 检查网络连接
|
||
- 查看控制台错误日志
|
||
|
||
### 4. 流式传输中断
|
||
|
||
**问题**: 流式响应中途断开
|
||
|
||
**解决方案**:
|
||
- 配置 Redis 以启用可恢复流式传输
|
||
- 检查网络稳定性
|
||
- 增加超时时间设置
|
||
|
||
### 5. Artifact 不显示
|
||
|
||
**问题**: Artifact 创建后不显示
|
||
|
||
**解决方案**:
|
||
- 检查 `dataStream.write()` 调用是否正确
|
||
- 确认 Artifact 类型已注册
|
||
- 查看浏览器控制台错误
|
||
- 检查数据库中的文档记录
|
||
|
||
### 6. 消息不保存
|
||
|
||
**问题**: 消息发送后未保存到数据库
|
||
|
||
**解决方案**:
|
||
- 检查数据库连接
|
||
- 确认 `saveMessages()` 函数被调用
|
||
- 查看服务端日志
|
||
- 检查数据库表结构
|
||
|
||
### 7. 如何添加管理员功能
|
||
|
||
**问题**: 项目没有管理员功能，如何添加？
|
||
|
||
**解决方案**:
|
||
- 参考文档中的"系统设置和管理员功能"章节
|
||
- 扩展数据库 schema 添加角色字段
|
||
- 更新认证系统支持管理员类型
|
||
- 创建管理员中间件和页面
|
||
- 实现管理员专用的 API 路由
|
||
|
||
---
|
||
|
||
## 扩展资源
|
||
|
||
### 官方文档
|
||
|
||
- [Next.js 文档](https://nextjs.org/docs)
|
||
- [AI SDK 文档](https://ai-sdk.dev)
|
||
- [Drizzle ORM 文档](https://orm.drizzle.team)
|
||
- [NextAuth 文档](https://authjs.dev)
|
||
- [shadcn/ui 文档](https://ui.shadcn.com)
|
||
|
||
### 相关链接
|
||
|
||
- [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)
|
||
- [Neon Serverless Postgres](https://neon.tech)
|
||
- [Vercel Blob](https://vercel.com/storage/blob)
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
### 代码提交
|
||
|
||
1. 创建功能分支
|
||
2. 编写代码并添加测试
|
||
3. 运行 `pnpm lint` 和 `pnpm format`
|
||
4. 提交 Pull Request
|
||
|
||
### 代码审查
|
||
|
||
- 确保所有测试通过
|
||
- 遵循代码规范
|
||
- 添加必要的文档
|
||
- 更新 CHANGELOG（如适用）
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
查看 `LICENSE` 文件了解许可证信息。
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
### v3.1.0
|
||
|
||
- 支持多种 Artifact 类型
|
||
- 改进的消息系统（parts 架构）
|
||
- 可恢复流式传输支持
|
||
- 用户权限系统
|
||
- 消息投票功能
|
||
|
||
---
|
||
|
||
**最后更新**: 2024年
|
||
|
||
**维护者**: 项目团队
|
||
|