203 lines
4.5 KiB
Markdown
203 lines
4.5 KiB
Markdown
# AI Chat Frontend
|
||
|
||
一个用于智能体比赛的前端主入口原型项目。当前阶段聚焦于聊天首页体验，使用 `React + Vite + TypeScript + Tailwind CSS` 构建，提供两套可切换主题：
|
||
|
||
- `柔和`：更偏 Kawaii Minimal 的浅色柔和风格
|
||
- `简洁`：更接近 `shadcn-admin / ChatGPT` 的中性简洁风格
|
||
|
||
目前未接入真实 API，聊天内容使用本地模拟数据渲染。
|
||
|
||
## 目标
|
||
|
||
- 作为智能体系统的前端主入口
|
||
- 后续承接聊天、多轮对话、知识库、复习流等功能
|
||
- 先把布局、主题、交互骨架稳定下来，再接真实后端能力
|
||
|
||
## 技术栈
|
||
|
||
- React 19
|
||
- Vite 6
|
||
- TypeScript
|
||
- Tailwind CSS
|
||
- React Router
|
||
- `class-variance-authority`
|
||
- `clsx`
|
||
- `tailwind-merge`
|
||
|
||
## 本地启动
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
生产构建：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
预览构建结果：
|
||
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
## 当前已完成
|
||
|
||
- 贴边式聊天主界面
|
||
- 左侧可折叠侧边栏
|
||
- 会话记录列表
|
||
- 固定底部输入框
|
||
- 聊天消息流展示
|
||
- `聊天 / 复习` 两个页面路由
|
||
- `柔和 / 简洁` 两套主题一键切换
|
||
- 主题切换结果持久化到 `localStorage`
|
||
|
||
## 当前未完成
|
||
|
||
- 真实聊天 API 接入
|
||
- 流式输出
|
||
- 会话创建、切换、删除的真实数据逻辑
|
||
- 用户鉴权
|
||
- 消息持久化
|
||
- 复习页面实际业务功能
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/
|
||
App.tsx
|
||
main.tsx
|
||
index.css
|
||
components/
|
||
chat/
|
||
chat-page.tsx
|
||
chat-composer.tsx
|
||
message-bubble.tsx
|
||
mock-data.ts
|
||
types.ts
|
||
layout/
|
||
app-shell.tsx
|
||
sidebar.tsx
|
||
theme-switcher.tsx
|
||
theme.ts
|
||
ui/
|
||
avatar.tsx
|
||
badge.tsx
|
||
button.tsx
|
||
card.tsx
|
||
input.tsx
|
||
icons.tsx
|
||
pages/
|
||
review-page.tsx
|
||
lib/
|
||
utils.ts
|
||
```
|
||
|
||
## 页面说明
|
||
|
||
### 聊天页
|
||
|
||
文件：
|
||
- `src/components/chat/chat-page.tsx`
|
||
- `src/components/chat/chat-composer.tsx`
|
||
- `src/components/chat/message-bubble.tsx`
|
||
|
||
特点：
|
||
- 消息区独立滚动
|
||
- 输入框固定在底部
|
||
- 会话记录放在侧边栏，不单独拆出中栏
|
||
|
||
### 复习页
|
||
|
||
文件：
|
||
- `src/pages/review-page.tsx`
|
||
|
||
当前仅做跳转占位，后续可扩展复习计划、知识卡片、错题归档等模块。
|
||
|
||
## 主题系统
|
||
|
||
主题状态定义：
|
||
- `src/components/layout/theme.ts`
|
||
|
||
主题切换组件：
|
||
- `src/components/layout/theme-switcher.tsx`
|
||
|
||
主题挂载位置：
|
||
- `src/components/layout/app-shell.tsx`
|
||
|
||
主题变量定义：
|
||
- `src/index.css`
|
||
|
||
说明：
|
||
- 主题通过 `data-theme="soft" | "classic"` 挂在最外层容器上
|
||
- 视觉差异主要通过 CSS 变量控制
|
||
- 页面、侧边栏、聊天气泡、输入框、按钮、头像都会跟随主题变化
|
||
|
||
协作时建议：
|
||
- 新增颜色时优先扩展 CSS 变量，不要在组件里继续堆硬编码颜色
|
||
- 如果是主题相关样式，优先落在 `index.css`
|
||
- 如果是单个组件结构调整，再改对应 `tsx`
|
||
|
||
## 数据约定
|
||
|
||
当前聊天内容来自：
|
||
- `src/components/chat/mock-data.ts`
|
||
|
||
后续接真实接口时建议：
|
||
- 把 `mock-data.ts` 替换为独立的 `services/` 或 `api/` 层
|
||
- 页面组件只负责展示，不直接拼接请求逻辑
|
||
- 消息结构沿用 `src/components/chat/types.ts`，避免重复定义
|
||
|
||
## 开发约定
|
||
|
||
### 1. 保持布局原则
|
||
|
||
- 聊天页采用贴边布局
|
||
- 会话记录保留在侧边栏
|
||
- 输入框固定底部
|
||
- 主聊天区尽量保持留白，不堆无关卡片
|
||
|
||
### 2. 保持主题策略
|
||
|
||
- `柔和` 主题：低饱和、轻甜、不杂乱
|
||
- `简洁` 主题：接近 ChatGPT / shadcn-admin 的中性灰白
|
||
- 不要出现带性别暗示的主题命名
|
||
|
||
### 3. 样式修改优先级
|
||
|
||
建议按这个顺序处理：
|
||
|
||
1. 先看是否能通过 CSS 变量解决
|
||
2. 再决定是否需要新增主题类
|
||
3. 最后才在组件里写临时颜色类
|
||
|
||
### 4. 组件复用建议
|
||
|
||
- 通用样式放 `src/components/ui`
|
||
- 页面组合逻辑放 `src/components/chat` 或 `src/components/layout`
|
||
- 路由页面只做页面级组合，不堆太多视觉细节
|
||
|
||
## 后续建议任务
|
||
|
||
推荐下一步按这个顺序推进：
|
||
|
||
1. 接入真实聊天 API
|
||
2. 支持流式回复
|
||
3. 接会话列表真实数据
|
||
4. 增加会话创建与切换逻辑
|
||
5. 补复习页的业务模块
|
||
6. 增加异常状态、空状态、加载态
|
||
|
||
## 说明
|
||
|
||
如果团队继续迭代这个项目，建议先统一以下内容再开发：
|
||
|
||
- API 返回格式
|
||
- 会话与消息的数据结构
|
||
- 主题变量命名规范
|
||
- 页面级组件与业务逻辑的拆分边界
|
||
|
||
这样可以避免后面出现样式、状态、接口三套逻辑交叉污染的问题。
|