PureChatNext 技术架构：Vite SPA、Next.js BFF 与 AI SDK

了解 PureChatNext 如何用 React 19、Vite、React Router、Next.js API、Vercel AI SDK、PostgreSQL 和常驻 Channel Gateway 组成一套多渠道 AI 工作台。

PureChatNext 把业务页面和服务端 API 分开：React 19、Vite 与 React Router 驱动 Web SPA；Next.js 负责 API、认证、BFF 和生产 HTML 壳；聊天生成使用 Vercel AI SDK；微信轮询与 QQ WebSocket 由持久 Node.js 进程中的 Channel Gateway 管理。

请求路径

浏览器 / 微信 / QQ
        │
        ├── Web UI ── Vite SPA（React Router）
        │                  │
        ├── 微信 Gateway ──┤
        └── QQ Webhook / Gateway
                           ▼
                   Next.js API / Auth / BFF
                           │
          Agent / Provider / Search / File loaders
                           │
                  PostgreSQL / 对象存储

Web 页面日常开发走 Vite；请求 /api 由 Vite 代理给本地 Next 服务。生产环境仍由 Next 返回注入服务端配置的 SPA HTML 壳，并提供同域 API 和认证入口。业务页面不应该迁移到 Next 页面路由。

主要模块

模块	职责	源码入口
Vite SPA	认证后的工作台、设置、Community 与聊天界面	`src/spa/entry.web.tsx`、`src/routes/`
Next.js BFF	API、认证、生产 SPA HTML、Webhook 和服务端配置	`src/app/api/`、`src/app/spa/`
Chat API	校验聊天请求、解析附件、创建模型流并处理结果	`src/app/api/chat/route.ts`
模型与工具	Provider、Agent、联网搜索、文件读取和用量能力	`src/server/chat/`
Channel Gateway	在持久 Node 进程中维护微信轮询与 QQ WebSocket；QQ Webhook 也可由无状态 Route 接收	`src/server/channel-gateway/`
共享 workspace packages	数据库、模型目录、文件加载器、类型和工具	`packages/`

一条聊天请求经过什么

React SPA 收集消息、附件、Agent 和模型选择，并请求同域 /api/chat。
Next API 解析身份和聊天上下文，按 Provider 创建 Vercel AI SDK 流。
文件附件由 @pure/file-loaders 提取文本；图片则要求所选模型支持视觉输入。
搜索、文件读取等工具由服务端工具注册表提供；聊天与用量数据按当前数据库模型写入。
Web、微信和 QQ 入口最终复用同一套 Agent、Provider 和服务端聊天能力；渠道只负责接收与回复消息。

为什么 Gateway 不放在 Serverless 函数中

微信 iLink 依赖持续轮询，QQ WebSocket 依赖长连接、心跳和进程状态；这些模式需要常驻 Node.js 运行时。QQ Webhook 是平台调用 HTTPS Route 的方式，适合短生命周期部署，但不能替代长连接。自托管可以使用 Docker；Vercel 备用站仅承接 Web 工作台和 QQ Webhook。

这个取舍增加了自托管部署、数据库状态和健康检查的复杂度。选择 Webhook-only 的部署时，应在产品说明里明确可用范围；需要微信或 QQ 长连接时，必须验证目标主机的持续进程能力。