steven_li
3b0af173cc
移除了所有Hermes相关的命名引用，包括： - 从.gitignore中清理相关构建缓存文件 - 将README中的beaver-home路径配置更新 - 完善backend/README.md文档说明Beaver后端主线实现 - 移除Hermes风格的相关注释和兼容性代码 - 清理nanobot环境变量兼容性处理 - 删除技能迁移和服务迁移相关功能代码 - 更新测试用例中相关命名和函数名 BREAKING CHANGE: 移除了Hermes迁移相关API和CLI命令，不再支持nanobot环境变量兼容性
263 lines
6.6 KiB
Markdown
263 lines
6.6 KiB
Markdown
# 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` | 技能管理 |
|
||
| `/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. 技术标识
|
||
|
||
当前前端使用 Beaver 技术命名，本地 token、语言和 handoff 状态都使用 `beaver_*` key。
|
||
|
||
### 3. 动态内容可能仍包含英文
|
||
|
||
来自后端、插件、技能包或外部市场的数据描述，可能仍然带有英文内容。当前仓库已经把前端固定文案尽量中文化，但动态数据仍以实际返回为准。
|
||
|
||
## 维护建议
|
||
|
||
- 新增页面时优先放进合适的 route group：`(app)` 或 `(auth)`
|
||
- 新增接口统一走 `lib/api.ts`
|
||
- 新增全局状态统一放到 `lib/store.ts`
|
||
- 新增用户可见文案优先使用中文，避免再次出现中英混杂
|
||
|
||
## 当前状态
|
||
|
||
- 页面品牌：`Boardware Genius`
|
||
- 中文化：已覆盖主要固定文案
|
||
- 布局拆分：已完成
|
||
- 生产构建：可通过 `npm run build`
|