第十章：副作用 useEffect 与 useRef
10 — 副作用 useEffect 与 useRef 这一章讲 React 中处理「和外部世界打交道」的两个 Hook：useEffect 和 useRef。 useEffect：发请求、操作 DOM、定时器、订阅事件 useRef：拿到 DOM 元素、存可变值（不触发渲染） 1. 什么是「副作用」？1.1 渲染 = 纯计算React 组件的渲染过程应该是纯的： 12345// ✅ 纯渲染：只根据 state 和 props 计算 UIfunction Counter({ count }) { return <p>{count}</p>;}// 同样的输入，永远得到同样的输出 1.2 副作用 = 渲染之外的事123456// ❌ 渲染里不该做的事：// - 改 DOM（React 自己会改）// - 发 API 请求// - 设置定时器// - 打印日志（其实可以）// - 订阅/取消订阅事件 这些东西叫「副作用」(side effects)，因为它们： 会影...
第十二章：React 代码完整阅读训练
12 — React 代码完整阅读训练 这一章是最重要的一章。我会拿项目里的真实组件逐行拆解，把前面学的所有概念串起来。读完后，你应该能独立读懂 90% 的项目代码。 训练方式我会拿几个典型的、有代表性的组件来拆解： InputArea.tsx — 简单但完整（表单、事件、ref） ChatItem.tsx — 中等（条件渲染、Props、事件回调） MessageList.tsx — 较复杂（map、条件、Hooks 综合） Message.tsx — 最复杂（多种条件组合、嵌套子组件） 阅读方法：先看拆解的「摘要」，再看「逐行注释」，最后试着自己读一遍。 训练 1：InputArea.tsx（简单）1.1 完整代码（项目原始）123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990im...
第十三章：CSS Modules 与项目样式
13 — CSS Modules 与项目样式 10 分钟理解项目里所有 CSS 的写法。包括：CSS Modules 工作机制、设计令牌系统、6 主题切换原理、常用模式。 1. CSS Modules 是什么？CSS Modules 是一种文件命名约定，文件名包含 .module.css 就会被 Vite 处理。 123/* 任何 *.module.css 文件：类名会被 Vite 自动哈希 */.item { ... } /* 编译为 .Message_item_a1b2c3 */.active { ... } /* 编译为 .Message_active_x7y8z9 */ 核心价值： ✅ 类名永远不会冲突 ✅ 每个组件样式独立管理 ✅ 不需要 BEM 等命名规范 ✅ 不需要额外构建配置 详见 03-CSS基础回顾.md 第 9 节。 2. 项目里所有 CSS 文件清单（最新）123456789101112131415161718192021222324252627282930313233src/...
第十四章：Zustand 状态管理
14 — Zustand 状态管理 本章讲解本项目最重要的部分：Zustand Store。整个应用 80% 的业务逻辑都在这里。读懂它 = 读懂应用。项目有两个 Store：chatStore.ts（聊天业务）和 themeStore.ts（主题）。 1. 为什么需要状态管理？1.1 跨组件共享数据的问题123456789// 问题场景：InputArea 显示输入文字，EmptyState 也想显示输入的文字function App() { return ( <> <EmptyState /> {/* 想显示输入框的文字 */} <InputArea /> {/* 输入框组件 */} </> );} 没有状态管理的解法：层层传 Props（痛苦）。 有状态管理的解法：全局 Store，组件按需订阅。 1.2 状态管理的解法把共享数据放到一个全局仓库（Store）里： 12345function Em...
第十五章：SSE 流式通信
15 — SSE 流式通信 本章讲解 AI 「打字机效果」是怎么实现的。这是项目中最技术性的部分。 1. 什么是 SSE？Server-Sent Events = 服务器单向推送数据给浏览器的协议。 对比其他技术： 方式 方向 用途 HTTP 请求 客户端 → 服务器 普通 API 调用 SSE (Server-Sent Events) 服务器 → 客户端（单向） AI 回复、实时通知 WebSocket 双向 聊天（双向）、实时游戏 长轮询 客户端反复请求 旧方案，已不推荐 SSE 特点： 基于 HTTP（简单） 服务器主动推送 数据格式简单（data: ...\n\n） 自动重连 浏览器原生 API：EventSource（但本项目用 fetch + ReadableStream，更灵活） 2. AI 流式回复的工作流程1234567891011121314151617181920用户点发送 ↓前端发 GET 请求到 /api/chat/stream ↓服务器开始返回数据（不是一次性，是持续的） ↓data: ...
第十六章：主题系统与 ThemeSwitcher
16 — 主题系统与 ThemeSwitcher 本章讲解本项目6 套主题系统的完整实现。涵盖：主题切换原理、CSS 变量分组、CSS-only 主题应用、ThemeSwitcher 组件。 1. 主题列表6 套主题（3 暗 + 3 亮）： ID 名称 风格 背景 主色 ink 墨韵东方 暗 #0e0d0b 浓墨 #c9a36b 古铜金 minimal 极简留白 暗 #0a0a0a 纯黑 #c8553d 朱砂 forest 森绿雅静 暗 #0f1611 深林 #8ba67b 苔藓 paper 素雅米黄 亮 #f5f0e6 宣纸 #a07a3e 古铜金 cream 乳白简约 亮 #fafaf7 乳白 #3a4a6b 靛蓝 matcha 抹茶清新 亮 #e8e6d8 抹茶绿 #5a6b3e 抹茶深绿 主题元数据（src/store/themeStore.ts）： 123456789101112export interface ThemeMeta { id: ThemeId; name: string; description: ...
第十七章：移动端适配实战
17 — 移动端适配实战 本章讲解本项目的移动端适配。重点：Chrome 100vh 坑、iOS 安全区、抽屉式侧边栏、跨组件通信。 1. 适配策略总览 断点 行为 > 768px 桌面布局：Sidebar 作为 flex 子项永久参与布局 ≤ 768px 移动布局：Sidebar 变 fixed 抽屉，点击 hamburger 滑出 项目里所有响应式 CSS 用 @media (max-width: 768px) 切分。 2. 核心问题：Chrome 100vh 坑2.1 问题Chrome 移动端的 100vh 包含地址栏高度（约 56px），而地址栏在滚动时会收起/展开。所以用 100vh 确定的底部边界在 Chrome 里比实际可见区域高出地址栏的高度，输入框被推到屏幕之外。 夸克浏览器正确处理了动态视口高度（用了 dvh 或动态计算），所以显示正常。 2.2 修复：用 position: fixed; inset: 0 绑定真实视口文件：src/styles/global.css 1234567html,body,#root ...
第十八章：项目组件详解
18 — 项目组件详解 本章按”用途”对项目所有组件做汇总介绍。前 12 章你应该已经能读懂代码了，本章给你一个速查表。 1. 组件总览按功能分类： 1.1 布局组件 组件 文件 作用 App App.tsx 根组件，协调所有面板，启动初始化 Topbar Topbar/Topbar.tsx 🆕 顶部栏（豆豆 logo + 标题 + 主题按钮） Sidebar Sidebar/Sidebar.tsx 侧边栏（桌面 flex 子项 / 移动 fixed 抽屉） ChatItem Sidebar/ChatItem.tsx 侧边栏中单个会话项 1.2 消息相关 组件 文件 作用 MessageList MessageList/MessageList.tsx 消息列表容器 EmptyState MessageList/EmptyState.tsx 空状态欢迎页（渐变大书法「豆豆」） Message Message/Message.tsx 单条消息（金色左竖线） Markdown Message/Markdown.tsx Ma...
第十九章：API 与后端交互
19 — API 与后端交互 本文档讲解前端如何与后端通信。涉及：HTTP 请求封装、错误处理、Vite 代理、接口定义、SSE 流式 URL。 1. 通信方式概览 方式 用途 文件 HTTP JSON 会话管理、文件上传 api/client.ts SSE AI 回复流式推送 api/stream.ts + useSseStream.ts Vite 代理 解决开发时跨域 vite.config.ts 2. HTTP 请求封装文件：src/api/client.ts 2.1 API 基础路径1const API_BASE = import.meta.env.VITE_API_BASE || '/api'; 开发时通过 Vite 代理，/api 自动转发到后端 生产环境通过环境变量配置：VITE_API_BASE=https://api.example.com/api 2.2 三个封装函数1234567891011121314151617181920212223// GET 请求export async function htt...
第二十章：开发者指南
20 — 开发者指南 从零开始运行、开发、调试、部署 dodo-agent 前端。包含：环境搭建、开发流程、移动端调试、主题开发、生产部署。 1. 环境要求 工具 版本 验证 Node.js >= 18 node -v npm >= 9 npm -v Node.js 安装： 官网下载安装：https://nodejs.org 推荐 LTS 版本 macOS 也可以用 Homebrew：brew install node@18 2. 快速开始2.1 启动开发服务器12345678# 1. 进入前端目录cd agent/dodo-agent-frontend# 2. 安装依赖（首次运行或依赖变更时）npm install# 3. 启动开发服务器npm run dev 启动后你会看到： 12345VITE v5.4.10 ready in 500 ms➜ Local: http://localhost:5173/➜ Network: http://192.168.x.x:5173/➜ press h + ente...
