第一次提交
This commit is contained in:
269
app-instance/frontend/README.md
Normal file
269
app-instance/frontend/README.md
Normal file
@ -0,0 +1,269 @@
|
||||
# Boardware Genius Frontend
|
||||
|
||||
这是 `Boardware Genius` 的前端项目，基于 Next.js 13 App Router 构建，提供聊天工作台、登录注册、系统状态、定时任务、技能、插件、智能体、MCP、文件管理等页面。
|
||||
|
||||
这个仓库只负责前端界面和浏览器侧交互，不包含后端服务实现。前端通过 HTTP 和 WebSocket 与后端网关通信。
|
||||
|
||||
## 项目定位
|
||||
|
||||
- 面向 `Boardware Genius` 的 Web 控制台
|
||||
- 提供统一的聊天入口和运维入口
|
||||
- 支持多页面管理能力：
|
||||
- 对话与会话管理
|
||||
- 系统状态查看
|
||||
- 定时任务管理
|
||||
- 技能 / 插件 / 智能体 / MCP 管理
|
||||
- 工作区文件浏览与上传下载
|
||||
|
||||
## 主要功能
|
||||
|
||||
### 1. 聊天工作台
|
||||
|
||||
- 左侧会话列表，支持切换、新建、删除会话
|
||||
- 主聊天区支持文本输入、文件上传、命令提示
|
||||
- WebSocket 实时接收消息和过程事件
|
||||
- 展示任务执行过程、结构化事件和执行产物
|
||||
|
||||
### 2. 认证与访问控制
|
||||
|
||||
- 提供登录、注册页面
|
||||
- 业务页与认证页使用不同 layout
|
||||
- 通过 `AuthGuard` 保护业务页访问
|
||||
- Access Token / Refresh Token 存在浏览器本地存储
|
||||
|
||||
### 3. 平台管理页面
|
||||
|
||||
- `状态`：查看后端配置、模型、Provider、通道、调度器状态
|
||||
- `定时任务`：新增、启停、执行、删除 Cron 任务
|
||||
- `技能`：查看、上传、下载、删除技能包
|
||||
- `插件`：查看已安装插件及其命令、技能、智能体
|
||||
- `智能体`：新增和管理工作区智能体
|
||||
- `MCP`：配置 MCP 服务、测试连接、查看发现的工具
|
||||
- `市场`：浏览和安装市场中的插件
|
||||
- `文件`：浏览工作区目录，上传、下载、删除文件/目录
|
||||
- `帮助`：查看使用说明
|
||||
|
||||
## 页面路由
|
||||
|
||||
| 路由 | 说明 |
|
||||
| --- | --- |
|
||||
| `/` | 聊天工作台 |
|
||||
| `/login` | 登录页 |
|
||||
| `/register` | 注册页 |
|
||||
| `/status` | 系统状态 |
|
||||
| `/cron` | 定时任务 |
|
||||
| `/skills` | 技能管理 |
|
||||
| `/plugins` | 插件管理 |
|
||||
| `/agents` | 智能体管理 |
|
||||
| `/mcp` | MCP 服务管理 |
|
||||
| `/marketplace` | 插件市场 |
|
||||
| `/files` | 工作区文件管理 |
|
||||
| `/help` | 帮助说明 |
|
||||
|
||||
## 技术栈
|
||||
|
||||
- Next.js 13.5
|
||||
- React 18
|
||||
- TypeScript
|
||||
- Tailwind CSS
|
||||
- Radix UI
|
||||
- Zustand
|
||||
- Lucide React
|
||||
|
||||
补充说明：
|
||||
|
||||
- 生产构建输出为 `standalone`
|
||||
- 首页做了按需加载和请求链路优化
|
||||
- 登录/注册与业务页已拆为不同 route group layout
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
app/
|
||||
(app)/ 业务页面与业务布局
|
||||
(auth)/ 登录/注册页面与认证布局
|
||||
globals.css 全局样式
|
||||
layout.tsx 根布局
|
||||
|
||||
components/
|
||||
chat-workbench/ 聊天工作台组件
|
||||
ui/ 通用 UI 组件
|
||||
AuthGuard.tsx 认证守卫
|
||||
Header.tsx 顶部导航
|
||||
|
||||
lib/
|
||||
api.ts 前端 API / WebSocket 客户端
|
||||
store.ts Zustand 状态管理
|
||||
|
||||
types/
|
||||
index.ts 全局类型定义
|
||||
```
|
||||
|
||||
## 本地开发
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Node.js 20
|
||||
- npm
|
||||
- 可访问的后端服务
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 配置环境变量
|
||||
|
||||
可以参考 `env_template`：
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_API_URL=http://127.0.0.1:10000
|
||||
NEXT_PUBLIC_WS_URL=wss://127.0.0.1:10000
|
||||
NEXT_PUBLIC_AUTH_PORTAL_URL=http://127.0.0.1:3081
|
||||
```
|
||||
|
||||
当前前端的地址策略是：
|
||||
|
||||
- 如果配置了 `NEXT_PUBLIC_API_URL` / `NEXT_PUBLIC_WS_URL`，优先使用显式配置
|
||||
- 如果配置了 `NEXT_PUBLIC_AUTH_PORTAL_URL`，未登录跳转会优先去独立 auth portal
|
||||
- 如果未配置，浏览器端会优先使用当前站点同源地址
|
||||
|
||||
### 启动开发环境
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
默认监听：
|
||||
|
||||
- `http://0.0.0.0:3080`
|
||||
|
||||
## 构建与运行
|
||||
|
||||
### 本地生产构建
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm run start
|
||||
```
|
||||
|
||||
### 常用脚本
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
npm run build
|
||||
npm run start
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
## Docker 运行
|
||||
|
||||
项目内已提供 `Dockerfile`，生产镜像基于 Next.js standalone 输出运行。
|
||||
|
||||
注意：
|
||||
|
||||
- 当前 `Dockerfile` 里包含 `npm run -s verify:modules` 校验步骤，但 `package.json` 里暂时没有这个脚本
|
||||
- 如果你直接执行镜像构建，需要先补上该脚本，或者移除这一步校验
|
||||
|
||||
在修正上述校验步骤后，可按下面方式构建：
|
||||
|
||||
```bash
|
||||
docker build -t boardware-genius-frontend .
|
||||
docker run --rm -p 3000:3000 boardware-genius-frontend
|
||||
```
|
||||
|
||||
如果你需要在构建时显式注入后端地址：
|
||||
|
||||
```bash
|
||||
docker build \
|
||||
--build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
|
||||
--build-arg NEXT_PUBLIC_WS_URL=wss://api.example.com \
|
||||
-t boardware-genius-frontend .
|
||||
```
|
||||
|
||||
## 部署建议
|
||||
|
||||
### 推荐：前后端同域部署
|
||||
|
||||
生产环境建议让前端页面与后端 API / WebSocket 走同一域名，例如：
|
||||
|
||||
- 前端页面：`https://boardware.example.com`
|
||||
- API：`https://boardware.example.com/api/...`
|
||||
- WebSocket：`wss://boardware.example.com/ws/...`
|
||||
|
||||
这样可以避免：
|
||||
|
||||
- 跨域预检
|
||||
- 混合内容问题
|
||||
- 证书域名不匹配
|
||||
- 额外的浏览器安全限制
|
||||
|
||||
### 反向代理建议
|
||||
|
||||
推荐在 Nginx / Caddy / 网关层代理：
|
||||
|
||||
- `/api` -> 后端 HTTP 服务
|
||||
- `/ws` -> 后端 WebSocket 服务
|
||||
|
||||
如果已经做了同域代理，前端可以不显式配置 `NEXT_PUBLIC_API_URL` 和 `NEXT_PUBLIC_WS_URL`。
|
||||
|
||||
## 前端交互约定
|
||||
|
||||
### 认证
|
||||
|
||||
- 登录成功后，前端把 token 存在本地
|
||||
- 业务页通过 `AuthGuard` 做访问控制
|
||||
- 认证页与业务页已拆分布局，避免登录页加载业务导航
|
||||
|
||||
### 聊天
|
||||
|
||||
- 聊天页优先使用 WebSocket 实时通信
|
||||
- 非关键数据采用延迟加载或空闲检查
|
||||
- Markdown 渲染做了拆包，减少首页首包体积
|
||||
|
||||
### 状态管理
|
||||
|
||||
- 全局状态使用 Zustand
|
||||
- 聊天消息、会话、连接状态、过程事件等都在 `lib/store.ts` 中维护
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. 这是前端仓库
|
||||
|
||||
如果页面能打开但功能不可用，优先检查后端是否已启动并暴露：
|
||||
|
||||
- 认证接口
|
||||
- 聊天接口
|
||||
- 会话接口
|
||||
- 状态接口
|
||||
- WebSocket 连接
|
||||
|
||||
### 2. 命令名和目录名未做品牌迁移
|
||||
|
||||
当前仓库的部分技术标识仍沿用旧命名，例如：
|
||||
|
||||
- `nanobot web`
|
||||
- `~/.nanobot/plugins/`
|
||||
- 本地存储中的旧 token key
|
||||
|
||||
这些属于兼容性和后端约定的一部分，前端展示品牌已替换为 `Boardware Genius`，但技术标识没有在这个仓库里强制迁移。
|
||||
|
||||
### 3. 动态内容可能仍包含英文
|
||||
|
||||
来自后端、插件、技能包或外部市场的数据描述，可能仍然带有英文内容。当前仓库已经把前端固定文案尽量中文化，但动态数据仍以实际返回为准。
|
||||
|
||||
## 维护建议
|
||||
|
||||
- 新增页面时优先放进合适的 route group：`(app)` 或 `(auth)`
|
||||
- 新增接口统一走 `lib/api.ts`
|
||||
- 新增全局状态统一放到 `lib/store.ts`
|
||||
- 新增用户可见文案优先使用中文，避免再次出现中英混杂
|
||||
|
||||
## 当前状态
|
||||
|
||||
- 页面品牌：`Boardware Genius`
|
||||
- 中文化：已覆盖主要固定文案
|
||||
- 布局拆分：已完成
|
||||
- 生产构建：可通过 `npm run build`
|
||||
Reference in New Issue
Block a user