Yasin

Yasin

AgentVerse重写方案

Next.js 重写：重点与难点全面梳理

一、整体架构对照

当前 AgentVerse                      →    Next.js 版本
─────────────────────────────────         ─────────────────────────
Vite + React + React Router              Next.js App Router
Cloudflare Functions (后端)              Next.js API Routes
Cloudflare D1 (数据库)                  Prisma + PostgreSQL (Supabase)
localStorage (数据持久化)               服务端数据库
HashRouter (客户端路由)                 文件系统路由
Extension 动态注册                      静态页面 + 条件渲染
OpenAI SDK (浏览器直调)                 API Route 代理调用
Zustand + RxJS (状态管理)              Zustand (保留) + Server State (React Query)

二、需要重写的模块（按优先级排序）

P0：必须重写（核心骨架）

模块 当前实现 Next.js 实现 工作量
路由系统 HashRouter + Extension 动态注册 + PluginRouter app/ 文件系统路由 2-3 天
后端 API functions/api/auth/*（8 个 Cloudflare Functions） app/api/auth/*（Next.js API Routes） 2 天
数据库 Cloudflare D1 + 原始 SQL Prisma ORM + PostgreSQL 1-2 天
数据持久化 LocalStorageProvider（agents/discussions/messages） 数据库 CRUD API + 前端 React Query 3-4 天
AI 调用 浏览器直调 OpenAI（暴露 API Key） app/api/ai/chat/route.ts 服务端代理 2 天

P1：需要适配（中等改动）

模块 改动点 工作量
认证系统 Session Cookie → NextAuth.js 或保留自实现 1-2 天
Provider 嵌套（main.tsx） 移到 app/layout.tsx 半天
响应式分端 isMobile ? <MobileApp/> : <DesktopApp/> → 保留但用 'use client' 半天
主题系统 ThemeProvider → 保留，标记 'use client' 半天
i18n i18next → 可保留，或换 next-intl 1 天

P2：可平移（少量改动）

模块 说明
UI 组件（common/components/ui/） Radix UI + Tailwind，直接复制
Zustand Stores 保留，加 'use client'
Presenter + Manager 层 纯 TS 逻辑，直接复制
MCP 客户端 标记 'use client'，不变

三、六大技术难点详解

难点 1：路由架构重设计 ⭐⭐⭐⭐⭐

当前的 Extension 动态路由是这个项目最精巧的设计，也是最难迁移的部分：

当前：Extension.activate() → addRoute('/chat', ChatPage) → 运行时生效
Next.js：app/chat/page.tsx → 编译时确定

建议方案：

app/
  layout.tsx              ← 全局 Provider（Theme/Breakpoint/Presenter）
  page.tsx                ← 首页 / 重定向
  (desktop)/              ← Route Group（桌面端布局）
    layout.tsx            ← 桌面端 Layout（ActivityBar + 侧边栏）
    chat/
      [id]/page.tsx       ← 聊天页
    agents/
      page.tsx            ← Agent 列表
      create/page.tsx     ← 创建 Agent
  (mobile)/               ← Route Group（移动端布局）
    layout.tsx
    chat/
      [id]/page.tsx

难点在于：功能开关不能再通过"注释 Extension"实现，需要改成环境变量或 Feature Flag：

// 之前
extensions: [
  desktopChatExtension,
  // desktopFileManagerExtension, ← 注释掉就禁用
];

// 之后
// app/(desktop)/file-manager/page.tsx
if (!featureFlags.fileManager) redirect("/chat");

难点 2：数据层从客户端迁移到服务端 ⭐⭐⭐⭐

当前所有业务数据在 localStorage，迁移到服务端涉及整条数据流改造：

当前：
  Component → useMessages() → Manager → Repository → LocalStorageProvider
                                                          ↓
                                                     localStorage

改造后：
  Server Component 直接获取数据（无需 Hook）
  或
  Client Component → React Query → fetch('/api/messages') → API Route → Prisma → DB

关键决策：哪些页面用 Server Component，哪些用 Client Component？

页面 推荐渲染方式 原因
Agent 列表 Server Component 数据简单，无交互状态
聊天页面 Client Component 大量实时交互、流式消息、WebSocket
首页/引导页 Server Component 静态内容为主
设置页 Client Component 表单交互

难在聊天页：消息流式推送 + 实时交互 + 多 Agent 对话编排，这些必须在客户端，无法利用 Server Component 优势。

难点 3：AI 流式调用链路重构 ⭐⭐⭐⭐

当前是浏览器直接调 OpenAI API（API Key 在前端，不安全）：

浏览器 → OpenAI API（流式 SSE）→ StreamDeltaNormalizer → UI 渲染

Next.js 中应该通过 API Route 代理：

浏览器 → /api/ai/chat（Next.js API Route）→ OpenAI API
                ↓ 流式转发 SSE
         浏览器接收 → UI 渲染

难在流式转发：

// app/api/ai/chat/route.ts
export async function POST(req: Request) {
  const { messages, model } = await req.json();

  const stream = await openai.chat.completions.create({
    model,
    messages,
    stream: true,
  });

  // 需要把 OpenAI 的流式响应转发给浏览器
  return new Response(stream.toReadableStream(), {
    headers: { "Content-Type": "text/event-stream" },
  });
}

同时项目里的 StreamDeltaNormalizer（处理 full/delta 两种模式）和 ToolCallCollector（合并工具调用增量）需要决定放在服务端还是客户端。

难点 4：Presenter/Manager 架构与 Server Component 的融合 ⭐⭐⭐

当前 Presenter 是客户端单例，在 Next.js 中：

Server Component：不能用 Presenter（Presenter 依赖浏览器 API）
Client Component：可以继续用 Presenter

建议分两层：

Server Component 层：
  直接用 Prisma 查数据库 → 传 props 给 Client Component

Client Component 层：
  保留 Presenter/Manager 用于实时交互状态
  （聊天消息流、ActivityBar 展开/收起等）

难点 5：认证系统迁移 ⭐⭐⭐

当前自实现了完整的认证流程（注册/登录/密码重置/邮箱验证/Session Cookie）。

两种选择：

方案 说明 推荐度
NextAuth.js (Auth.js) 成熟方案，支持多种登录方式，自动管理 Session ⭐⭐⭐⭐⭐
自实现迁移 把 Functions 里的逻辑搬到 API Routes ⭐⭐⭐

推荐 NextAuth.js，可以少写很多代码，而且自带 Credentials Provider（邮箱密码登录）。

难点 6：MCP + service-bus-portal 跨上下文通信 ⭐⭐

这部分完全是浏览器端逻辑（iframe/Worker/PostMessage），在 Next.js 中：

全部标记 'use client'
把 public/iframe-portal.html 和 worker-portal.js 放到 public/ 目录
其他不变

改动量小，但要注意 Next.js 的 SSR 预渲染阶段不能访问 window/Worker，需要用 dynamic import 或 useEffect 延迟加载。

四、推荐的重写路线图

第 1 周：基础骨架
  ├── 创建 Next.js 项目 + Tailwind + Radix UI
  ├── 搭建 app/ 文件路由结构
  ├── 迁移 UI 组件（components/ui/ 直接复制）
  └── 配置 Prisma + Supabase 数据库

第 2 周：认证 + 数据层
  ├── NextAuth.js 实现登录/注册
  ├── 设计数据库 Schema（users/agents/discussions/messages）
  ├── 实现 CRUD API Routes
  └── 前端用 React Query 接入

第 3 周：核心功能
  ├── 聊天页面（Client Component）
  ├── AI 流式调用（API Route 代理 + SSE 转发）
  ├── 多 Agent 对话编排逻辑
  └── Agent 管理页面

第 4 周：完善 + 特色功能
  ├── MCP 工具集成（'use client'）
  ├── 响应式适配（桌面/移动端）
  ├── 主题系统 + i18n
  └── 部署到 Vercel

五、学习收获最大化的建议

顺序 学到什么
搭骨架阶段 App Router、文件路由、layout 嵌套、Server vs Client Component
数据层阶段 Prisma ORM、API Routes、React Query、数据库设计
聊天功能阶段 流式 SSE、AI SDK、实时交互、状态管理
完善阶段 中间件、认证、部署、性能优化

这个项目用 Next.js 重写的过程，本身就是一个完整的全栈 + AI 应用开发教程。重点享受过程，不必追求和原项目 100% 功能对齐。

← 返回首页