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

建议按这个顺序处理：

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

4. 组件复用建议

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

后续建议任务

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

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

说明

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

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

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