Chat Assistant 页面技术文档

1. 背景与目标

搭建一个支持多大语言模型（OpenAI GPT-4o、Anthropic Claude、Google Gemini 等）的对话页面，具备流式输出与多会话管理能力，为后续接入检索增强生成（RAG）与插件式工具链奠定基础。

2. MVP 功能范围

模型切换：在会话栏可选择目标模型与参数（温度、最大 tokens 等）。
消息发送：输入框支持快捷键发送、换行、代码块粘贴。
流式输出：前端逐 token 渲染，提供停止、重新生成、复制等操作。
会话管理：列表侧栏新增、重命名、删除会话，本地持久化。
错误处理：明确返回额度不足、网络异常等状态。

3. 系统架构

flowchart TD
  UI[Next.js/React UI]
  API[Next.js API Routes / Edge Functions]
  Models[LLM Providers]
  Store[(Supabase / SQLite)]
  UI -->|HTTP / SSE| API
  API -- Stream --> UI
  API -->|REST / WebSocket| Models
  API --> Store

3.1 前端

Next.js 14 App Router + React Server Components。
状态管理：Zustand / React Context。
UI 库：Tailwind CSS + shadcn/ui。
流式解析：使用 fetch(EventSource) 或 ReadableStream 处理 SSE。

3.2 后端

统一封装模型调用：/api/chat/completions 接收 model, messages, stream 参数。
根据模型路由到不同 SDK：
- OpenAI (openai-node)
- Anthropic (anthropic-sdk)
- Google (@google/generative-ai)
返回 Content-Type: text/event-stream 实现流式响应。

3.3 数据持久化

会话元数据与历史：Supabase Postgres / SQLite（可本地开发）。
Schema

CREATE TABLE conversations (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  title text,
  model text,
  created_at timestamptz DEFAULT now()
);

CREATE TABLE messages (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  conversation_id uuid REFERENCES conversations(id),
  role text CHECK (role IN ('user','assistant')),
  content text,
  created_at timestamptz DEFAULT now()
);

4. 关键技术点

流式打字机效果：前端利用 TextDecoderStream 将字节流转为 token 并增量渲染，自动滚动到底部。
中断控制：前端发送 AbortController，后端在各 SDK 请求中监听并取消。
Token 统计：后端记录请求与响应 token 数，用于费用展示。
安全：后端仅从服务器端环境变量读取 API Key，前端绝不暴露。

5. API 设计

方法	路径	描述
POST	/api/chat/completions	流式返回模型回答
GET	/api/conversations	拉取会话列表
POST	/api/conversations	新建会话
DELETE	/api/conversations/:id	删除会话

请求示例：

POST /api/chat/completions
{
  "conversationId": "uuid",
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "stream": true
}

流式响应示例：

id: 0
data: {"delta":"H"}

id: 1
data: {"delta":"i"}

id: [DONE]

6. 环境变量

# OpenAI
OPENAI_API_KEY=
# Anthropic
ANTHROPIC_API_KEY=
# Google
GEMINI_API_KEY=
# DB
DATABASE_URL=

7. 部署

Vercel：使用 Edge Runtime 实现低延迟流式输出。
本地开发：npm run dev，依赖 .env.local。
导出 Supabase URL 与匿名密钥到云端环境变量。

8. 迭代计划

阶段	里程碑
v0.1	MVP 完成：多模型对话 + 流式输出
v0.2	向量数据库接入，实现 RAG
v0.3	插件系统：Web 搜索、文件摘要
v1.0	团队多用户、角色模板、权限管理

9. 风险与对策

请求限速：设置服务器端速率限制中间件。
成本失控：前端显示 token 消耗；后端阈值告警。
数据泄漏：所有请求经过服务端代理，前端无密钥。

完成后即可进入开发阶段：

初始化 Next.js 项目与数据库。
实现 /api/chat/completions 代理。
搭建前端 UI 并接通流式接口。
编写单元与集成测试，确保稳定性。