dodo-agent 前端技术文档

面向读者：HTML/CSS/JS 有基础、React 新手的前端小白
目标：从「能看懂项目代码」到「能动手修改/添加功能」
项目代号：豆豆 — 一个多 Agent AI 聊天界面

🆕 项目最新特性（重要！先看这里）

1. 6 套主题系统（暗色 3 + 亮色 3）

通过侧边栏底部「主题设置」按钮切换，状态持久化到 localStorage：

ID	名称	风格	背景	主色
`ink`	墨韵东方	暗	`#0e0d0b` 浓墨	`#c9a36b` 古铜金
`minimal`	极简留白	暗	`#0a0a0a` 纯黑	`#c8553d` 朱砂
`forest`	森绿雅静	暗	`#0f1611` 深林	`#8ba67b` 苔藓
`paper`	素雅米黄	亮	`#f5f0e6` 宣纸	`#a07a3e` 古铜金
`cream`	乳白简约	亮	`#fafaf7` 乳白	`#3a4a6b` 靛蓝
`matcha`	抹茶清新	亮	`#e8e6d8` 抹茶绿	`#5a6b3e` 抹茶深绿

主题切换原理：document.documentElement.setAttribute('data-theme', '...')，CSS 用 [data-theme='ink'] 选择器分组覆盖 token。

2. 移动端完整适配

真实视口绑定：position: fixed; inset: 0 替代 100vh（修复 Chrome 移动端 100vh 含地址栏高度的 bug）
抽屉式侧边栏：移动端默认隐藏，点击 hamburger 滑出
iOS 安全区适配：env(safe-area-inset-*) 用于底部输入区
文字防缩放：iOS input 字号 ≥ 16px（防止 focus 时自动缩放）
横向滚动 Agent 选择器：移动端 Agent 多时左右滑动而不是溢出

3. 跨组件通信模式

不再用 prop drilling，使用 CustomEvent 让兄弟组件直接通信：

dodo:sidebar-toggle — Topbar ↔ Sidebar 同步展开状态
dodo:open-theme-switcher — Topbar → ThemeSwitcher 打开主题面板

4. UI 改造重点

顶栏模式（替代原嵌套卡片）：豆豆 logo（永远在屏幕最左上）+ 当前聊天主题 + 主题切换标签
透明磨砂胶囊按钮（color-mix + backdrop-filter: blur）
AI 消息带金色左竖线（书页批注感）
空状态用渐变大书法「豆豆」+ 古风分隔线
输入区卡片式（案台式）

学习路径（按顺序阅读）

🌱 第一阶段：前置基础回顾（10 分钟/篇）

你说你有 HTML/CSS/JS 基础，但项目用了 TypeScript 和一些较新的语法。
这一阶段的目的不是教基础，而是对齐语法，避免后面的 React 示例看不懂。

#	文档	重点
02	HTML 基础回顾	表单元素、`<input type="file">`、data-* 属性、`<svg>`
03	CSS 基础回顾	变量 (var)、calc、媒体查询、transform/animation
04	JavaScript 基础回顾	解构、展开运算符、可选链 `?.`、模板字符串、async/await、Promise
05	TypeScript 快速入门	基础类型、接口、泛型、联合类型 — React 项目必备
06	前端工具链：npm 与 Vite	什么是 node_modules、import 怎么解析、为什么需要构建

⚛️ 第二阶段：React 核心（重点，逐篇读）

#	文档	重点
07	React 是什么与 JSX	React 解决什么问题、JSX 不是 HTML、createElement
08	组件与 Props	函数组件、Props 传参、children、组合
09	State 与 useState	为什么需要 state、不可变更新、对象/数组更新
10	副作用 useEffect 与 useRef	副作用、依赖数组、清理、ref 是什么
11	事件处理与条件/列表渲染	onClick、map、key、条件渲染的所有写法
12	React 代码完整阅读训练	把 App.tsx 完整拆解一遍，把前面所有概念串起来

🎨 第三阶段：项目专用技术

#	文档	重点
13	CSS Modules 与项目样式	项目如何写样式、变量系统、动画
14	Zustand 状态管理	为什么不用 useState、Store 是什么、Immer 中间件
15	SSE 流式通信	流式数据是什么、Fetch + ReadableStream、AbortController
16	主题系统与 ThemeSwitcher	新增：6 主题实现、CSS 变量切换原理、跨组件通信
17	移动端适配实战	新增：100vh 坑、fixed 定位、安全区、响应式断点

📦 第四阶段：项目结构与实战

#	文档	重点
18	项目组件详解	每个组件的功能、Props、读代码指南（含新增 Topbar/ThemeSwitcher）
19	API 与后端交互	接口清单、类型定义、错误处理
20	开发者指南	安装、启动、调试、部署

🚀 最快上手路线

如果你只想尽快看懂项目代码并动手改：

1 小时路径：02 → 07 → 08 → 09 → 11 → 12 → 13 → 14 → 18

半天路径：完整按上面第一~第四阶段顺序阅读

🗂 项目结构速览（最新版）

dodo-agent-frontend/
├── index.html                ← 入口 HTML（viewport-fit=cover, 字体预加载）
├── package.json              ← 依赖配置
├── vite.config.ts            ← 构建配置
└── src/
    ├── main.tsx              ← 应用挂载点
    ├── App.tsx               ← 根组件（协调 Topbar / Sidebar / ThemeSwitcher）
    ├── App.module.css        ← 根布局（position: fixed + safe-area）
    │
    ├── styles/
    │   ├── tokens.css        ← 设计令牌（6 主题分组，data-theme 切换）
    │   └── global.css        ← 全局 reset + 背景水墨装饰
    │
    ├── types/api.ts          ← 后端 API 类型定义
    ├── constants/            ← agents / streamTypes
    │
    ├── api/                  ← 后端 API 封装
    │   ├── client.ts
    │   ├── session.ts
    │   ├── file.ts
    │   └── stream.ts
    │
    ├── store/
    │   ├── chatStore.ts      ← 全局状态（聊天）⭐
    │   └── themeStore.ts     ← 全局状态（主题）⭐ NEW
    │
    ├── hooks/                ← 自定义 Hook
    ├── utils/                ← 工具函数
    │
    └── components/
        ├── Sidebar/          ← 侧边栏（桌面 flex 子项 / 移动端 fixed 抽屉）
        ├── MessageList/      ← 消息列表 + 空状态
        ├── Message/          ← 单条消息 + Markdown / Timeline / Reference / Recommend
        ├── InputArea/        ← 输入区 + AgentSelector + FilePreview
        ├── Topbar/           ← 顶栏 NEW（豆豆 logo + 标题 + 主题）
        ├── ThemeSwitcher/    ← 主题切换面板 NEW
        ├── ConfirmDialog/    ← 确认弹窗
        └── ConnectionError/  ← 连接错误

🆕 与原版相比的关键变化

原版	现版
1 个固定暗色主题（青绿）	6 主题可切换（暗 3 + 亮 3）
嵌套卡片布局	顶栏 + 抽屉布局
玻璃拟态	透明磨砂胶囊（color-mix + blur）
100vh 布局	position: fixed; inset: 0
移动端单列	抽屉式侧边栏 + 顶栏
Props 层层传 sidebar 状态	CustomEvent 跨组件通信
12 篇文档	19 篇文档