zhangyonghao/ai-chat

Fork 0

Files

ZhangYonghao af9d343f93 first commit

2026-03-26 12:38:19 +08:00

4.5 KiB

Raw Blame History

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

本地启动

npm install
npm run dev

生产构建：

npm run build

预览构建结果：

npm run preview

当前已完成

贴边式聊天主界面
左侧可折叠侧边栏
会话记录列表
固定底部输入框
聊天消息流展示
聊天 / 复习 两个页面路由
柔和 / 简洁 两套主题一键切换
主题切换结果持久化到 localStorage

当前未完成

真实聊天 API 接入
流式输出
会话创建、切换、删除的真实数据逻辑
用户鉴权
消息持久化
复习页面实际业务功能

目录结构

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. 样式修改优先级

建议按这个顺序处理：

先看是否能通过 CSS 变量解决
再决定是否需要新增主题类
最后才在组件里写临时颜色类

4. 组件复用建议

通用样式放 src/components/ui
页面组合逻辑放 src/components/chat 或 src/components/layout
路由页面只做页面级组合，不堆太多视觉细节

后续建议任务

推荐下一步按这个顺序推进：

接入真实聊天 API
支持流式回复
接会话列表真实数据
增加会话创建与切换逻辑
补复习页的业务模块
增加异常状态、空状态、加载态

说明

如果团队继续迭代这个项目，建议先统一以下内容再开发：

API 返回格式
会话与消息的数据结构
主题变量命名规范
页面级组件与业务逻辑的拆分边界

这样可以避免后面出现样式、状态、接口三套逻辑交叉污染的问题。

4.5 KiB Raw Blame History Unescape Escape