first commit

README.md

@@ -0,0 +1,202 @@
+# 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 返回格式
+- 会话与消息的数据结构
+- 主题变量命名规范
+- 页面级组件与业务逻辑的拆分边界
+
+这样可以避免后面出现样式、状态、接口三套逻辑交叉污染的问题。