# vibe-next-template

Nova Agent 示例模板工程。[Nova](https://nova.betteryeah.com) 是一个创建 Agent 的 SaaS 产品，可以通过 Nova 创建能够操作沙箱、浏览器、文件系统的专业 Agent。本项目基于 Next.js 提供完整的 Agent 聊天前端，包含消息流、事件列表、会话管理与文件上传能力。

项目中 `.nova/config.json` 内置了一个示例 Agent，如需基于本模板开发自己的应用，请在 Nova 平台创建 Agent 并替换配置。

## 技术栈

- Next.js 16（App Router） / React 19 / TypeScript 5
- Tailwind CSS 4 / Radix UI / Lucide React Icons
- Zustand（状态管理）
- 自定义 WebSocket 客户端（实时通信）
- 自定义 HTTPClient（Fetch 封装，支持拦截器）
- Drizzle ORM + PostgreSQL
- Winston（日志，生产环境按天轮转）
- Shiki（代码高亮）/ React Markdown + Remark GFM

## 快速开始

1. 安装依赖：`pnpm install`
2. `.env`环境变量文件已经初始化完成了，所以设计环境变量的需要在这里修改
3. （可选）修改 `.nova/config.json`，替换为你自己的 Agent
4. 启动开发服务器：`pnpm dev`（端口 13000）

## Agent 配置

Agent 配置存放在 `.nova/config.json`：

```json
{
  "agents": [
    {
      "agent_id": "70da765f2d42490ca574d72dce4d24fe",
      "agent_name": "Nova示例Agent",
      "agent_description": "一个Nova的Agent示例，包含Agent具备的通用功能，文件操作、沙箱环境执行、浏览器操作等等。"
    }
  ]
}
```

- `agents` 数组中的第一个 Agent 作为默认使用的 Agent
- 在 Nova 平台创建新 Agent 后，将 `agent_id`、`agent_name`、`agent_description` 替换为新 Agent 的信息
- 配置通过 `app/api/nova-config.ts` 的 `getDefaultAgentId()` 在服务端读取，启动后缓存

## 目录结构

```
.nova/
  config.json             # Agent 配置（agent_id, agent_name, agent_description）

app/
  layout.tsx              # 根布局（Geist Sans/Mono 字体）
  page.tsx                # 主入口，初始化聊天连接
  globals.css             # 全局样式
  api/                    # Next.js API 路由（BFF 层，代理 Nova 平台 API）
    oapi-client.ts        # 共享的 Nova OpenAPI HTTPClient 实例
    nova-config.ts        # 读取 .nova/config.json，提供 getDefaultAgentId()
    info/route.ts         # 返回客户端配置：agentId, conversationId, wssUrl, token
    chat/event/route.ts   # 代理获取聊天事件历史
    chat/stop/route.ts    # 停止当前任务
    conversation/route.ts # 会话列表
    file/upload/route.ts  # 文件上传
    file/sign/route.ts    # 文件签名 URL
    health/route.ts       # 健康检查

components/
  nova-sdk/               # 核心聊天 SDK
    types.ts              # 核心类型定义（ApiEvent, PlatformConfig, TaskArtifact 等）
    websocket.ts          # WebSocket 客户端（自动重连、心跳、离线队列）
    store/
      useNovaStore.ts     # Zustand 全局状态（events, artifacts, ws 状态, loading）
    context/
      context.ts          # NovaContext 定义（HTTPClient + getArtifactUrl）
      Provider.tsx         # Context Provider
      useNova.ts          # useContext hook
    hooks/
      useNovaChatLogic.ts # 主编排 hook，组合所有子 hook
      useNovaEvents.ts    # WebSocket + 历史事件获取
      useNovaService.ts   # 从 platformConfig 创建 HTTPClient
      useMessageSender.ts # 通过 WebSocket 发送消息
      useEventProcessor.ts # ApiEvent → UI 消息转换
      useBuildConversationConnect.ts # 初始化：获取 agentId、conversationId
      useFileUploader.ts  # 文件上传逻辑
      useAttachmentHandlers.ts # 附件点击处理
      useMessageScroll.ts # 消息列表自动滚动
      usePanelState.ts    # 产物面板开关
      useSize.ts          # 响应式尺寸
    nova-chat/            # 聊天主组件
      index.tsx           # NovaChat（包裹 Provider、Header、MessageList、Input、TaskPanel）
      ChatHeader.tsx      # 聊天头部
      ChatInputArea.tsx   # 输入区域
    message-list/         # 消息列表
      index.tsx           # MessageList
      MessageItem.tsx     # 单条消息
      AttachmentItem.tsx  # 文件附件
      ImageAttachmentItem.tsx # 图片附件
      ToolCallAction.tsx  # 工具调用展示
    message-input/        # 消息输入
      index.tsx           # 输入组件
      FilePreviewList.tsx # 文件预览列表
    task-panel/           # 产物预览面板
      index.tsx           # TaskPanel（侧边栏，50% 宽度）
      ArtifactList.tsx    # 产物列表
      ArtifactPreview.tsx # 产物预览
      Preview/            # 各类预览组件（Markdown、代码、PPT、工具调用）
  ui/                     # 基础 UI 组件（Shadcn 风格）
    button.tsx, dialog.tsx, scroll-area.tsx, image.tsx, image-preview.tsx

http/
  index.ts                # HTTPClient 类（Fetch 封装）
  http.ts                 # 底层 fetch 包装，支持 onRequest/onResponse/onError 钩子
  type.ts                 # HTTP 类型定义

db/
  index.ts                # Drizzle ORM 连接（server-only，全局单例）

utils/
  logger.ts               # Winston 日志（开发→终端，生产→按天文件轮转）
  cn.ts                   # clsx + tailwind-merge 工具函数
```

## 数据流

```
app/page.tsx
  │  useBuildConversationConnect() → GET /api/info
  │  获取 agentId（来自 .nova/config.json）, conversationId, platformConfig
  ▼
NovaChat 组件
  │  useNovaChatLogic() 编排所有子 hook
  ├── useNovaEvents()    → WebSocket 连接 + GET /api/chat/event 加载历史
  ├── useMessageSender() → WebSocket 发送消息
  └── useEventProcessor()→ 事件转 UI 消息
  ▼
Zustand Store (useNovaStore)
  │  events[], artifacts[]（从 events 自动提取）, loading, ws 状态
  ▼
MessageList / TaskPanel 渲染
```

## API 路由

| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/info` | GET | 返回客户端配置：agentId, conversationId, wssUrl, token |
| `/api/chat/event` | GET | 代理 Nova `/chat/event_list`，获取事件历史 |
| `/api/chat/stop` | POST | 停止当前任务 |
| `/api/conversation` | GET | 会话列表 |
| `/api/file/upload` | POST | 上传文件 |
| `/api/file/sign` | POST | 获取文件签名 URL |
| `/api/health` | GET | 健康检查 |

所有 API 路由通过 `app/api/oapi-client.ts` 中的共享 HTTPClient 代理到 Nova 平台，请求头自动注入 `Tenant-Id` 和 `Authorization`。Agent ID 从 `.nova/config.json` 读取，不再依赖环境变量。

## WebSocket 消息格式

- 心跳：`{ message_type: 'ping' }`
- 聊天消息：`{ message_type: 'chat', conversation_id, content, ... }`
- 切换会话：`{ message_type: 'switch_conversation', conversation_id }`

WebSocket 客户端内置自动重连（可配置次数/间隔）、心跳检测、网络状态监听、页面可见性恢复。

## 常用命令

```bash
pnpm install          # 安装依赖
pnpm dev              # 启动开发服务器（端口 13000）
pnpm build            # 生产构建
pnpm start            # 生产运行（端口 13000）
pnpm lint             # ESLint 检查并自动修复
pnpm db:generate      # 生成 Drizzle 迁移
pnpm db:migrate       # 执行数据库迁移
pnpm db:studio        # 打开 Drizzle Studio GUI
```

## 环境变量

参考 `.env.example`，在项目根目录创建 `.env.local`：

| 变量名 | 说明 |
|--------|------|
| `DATABASE_URL` | PostgreSQL 连接地址（Drizzle 使用） |
| `LOG_DIR` | 生产环境日志目录（默认 `./logs`，按天切分） |
| `NOVA_BASE_URL` | Nova OpenAPI 服务地址 |
| `NOVA_TENANT_ID` | 租户 ID（请求头 `Tenant-Id`） |
| `NOVA_ACCESS_KEY` | 鉴权密钥（请求头 `Authorization`） |

> Agent ID 已从环境变量迁移至 `.nova/config.json`，无需在 `.env.local` 中配置。

## 代码约定

- **路径别名**：`@/*` → `./*`（tsconfig paths）
- **组件**：PascalCase 文件名，使用 `React.memo()` 优化
- **Hooks**：camelCase，`use*` 前缀
- **工具函数**：camelCase
- **常量枚举**：UPPER_SNAKE_CASE（如 `EventType`, `TaskStatus`）
- **样式**：Tailwind CSS 工具类，通过 `cn()` 函数（`utils/cn.ts`）合并类名
- **回调稳定性**：使用 ahooks 的 `useMemoizedFn()` 或 `useCallback()`
- **异步状态**：`queueMicrotask()` 延迟更新，避免 React 批量更新冲突
- **Store 去重**：Zustand store 按 `event_id` 去重事件
- **日志**：开发环境输出到终端，生产环境按天写入 `${LOG_DIR}/app-YYYY-MM-DD.log`
- **数据库**：所有操作通过 Drizzle ORM，`import { db } from '@/db'`，仅限 server 端
- **UI 错误提示**：使用中文（如 "Chat 不可用，请检查项目 .env 配置"）
- **请求头约定**：`X-Locale=zh`, `X-Region=CN`

## 注意事项

- `next.config.ts` 中 `reactStrictMode: false`
- `.next/` 目录为构建产物，不要手动修改
- 数据库连接使用全局单例模式，`db/index.ts` 标记了 `server-only`
- 聊天初始化流程：先请求 `/api/info` 获取配置 → 再建立 WebSocket → 加载历史事件
- 产物提取来源：`attachments`, `attachment_files`, `files`, `generated_files`，按文件 key 去重
- 文件签名通过 `getArtifactUrl()` 懒加载，POST `/file/sign`，失败时 fallback 到原始路径