第2课：技术全景图 —— 认识所有零件
本课目标
在动手之前，先把整个系统的零件认全。就像拼乐高之前先把所有零件倒出来看一遍。
项目文件结构
email-agent/
│
├── 📄 .env ← 你的邮箱密码和 API Key
├── 📄 package.json ← 依赖配置（相当于 Python 的 requirements.txt）
│
├── 📂 client/ ← 🖥️ 前端（浏览器里看到的界面）
│ ├── App.tsx ← 应用入口
│ ├── components/ ← UI 组件
│ │ ├── ChatInterface.tsx ← 聊天界面
│ │ ├── InboxView.tsx ← 收件箱
│ │ ├── EmailDisplay.tsx ← 邮件展示
│ │ └── custom/ ← 自定义看板组件
│ │ ├── TaskBoard.tsx
│ │ └── FinancialDashboard.tsx
│ └── hooks/ ← 前端逻辑钩子
│ ├── useWebSocket.ts ← WebSocket 连接
│ └── useUIState.ts ← 数据状态订阅
│
├── 📂 server/ ← 🖧 后端服务器
│ ├── server.ts ← 主服务入口
│ └── endpoints/ ← HTTP 接口
│ ├── emails.ts ← 邮件增删改查
│ ├── listeners.ts ← 监听器管理
│ ├── sync.ts ← 邮件同步
│ └── ui-states.ts ← 数据状态
│
├── 📂 database/ ← 💾 数据库层
│ ├── email-db.ts ← 数据库建表和操作
│ ├── email-sync.ts ← 从邮箱同步邮件到数据库
│ ├── email-search.ts ← 搜索功能
│ └── imap-manager.ts ← IMAP 连接管理
│
├── 📂 ccsdk/ ← 🧠 AI 核心层
│ ├── session.ts ← 会话管理
│ ├── ai-client.ts ← 调用 Claude API
│ ├── websocket-handler.ts ← WebSocket 服务
│ ├── custom-tools.ts ← 给 AI 的自定义工具
│ ├── email-agent-prompt.ts ← AI 的系统提示词
│ ├── actions-manager.ts ← Actions 管理器
│ ├── listeners-manager.ts ← Listeners 管理器
│ ├── ui-state-manager.ts ← UI State 管理器
│ └── component-manager.ts ← 组件管理器
│
└── 📂 agent/ ← 🤖 Agent 配置
├── .claude/agents/
│ └── inbox-searcher.md ← 搜索子Agent的提示词
└── custom_scripts/ ← 用户自定义脚本
├── actions/ ← 一键操作模板
├── listeners/ ← 自动化监听器
└── ui-states/ ← 数据看板定义
六大模块一览
模块1：前端 (client/)
干嘛的： 你在浏览器里看到的一切——聊天框、收件箱、看板。
技术栈： React + TypeScript + Tailwind CSS
打个比方： 餐厅的"前台大厅"，客人（你）在这里看菜单、点菜、看菜上桌。
┌────────────────────────────────────────────┐
│ 标签栏: 收件箱 | 聊天 | 财务看板 | 任务看板 │
├────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌───────────────────┐ │
│ │ 邮件列表 │ │ 邮件详情 / 聊天 │ │
│ │ 或 看板内容 │ │ 或 看板图表 │ │
│ └──────────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ 活跃监听器面板 │ │
│ └──────────────────────────────────────┘ │
└────────────────────────────────────────────┘
模块2：后端服务器 (server/)
干嘛的： 处理前端发来的请求，协调各个子系统。
技术栈： Bun (一个超快的 JavaScript 运行时)
打个比方： 餐厅的"服务员"，跑来跑去传话——前台说要什么，它去厨房（AI）、仓库（数据库）、供应商（IMAP）拿。
模块3：数据库 (database/)
干嘛的： 把邮件存到本地，这样搜索和查询更快；也存看板数据。
技术栈： SQLite（一个轻量级本地数据库）
打个比方： 餐厅的"冷库"，所有食材（邮件数据）都先存这里，用的时候取。
模块4：IMAP 邮件系统 (database/imap-manager.ts)
干嘛的： 连接你的 Gmail，拉取真实邮件。
技术栈： node-imap + mailparser
打个比方： 餐厅的"供应商"，从农场（Gmail）把新鲜食材（邮件）送进来。
模块5：AI 核心 (ccsdk/)
干嘛的： 这是大脑。处理对话、理解用户意图、调用工具、做智能决策。
技术栈： Claude Agent SDK + Anthropic API
打个比方： 餐厅的"大厨"，根据客人的要求（你的聊天消息）决定做什么菜（执行什么操作）。
模块6：自定义脚本 (agent/custom_scripts/)
干嘛的： 你自己写的自动化规则和操作模板。
打个比方： 大厨的"菜谱本"，里面是各种预设的菜品（操作），需要时翻出来做。
数据是怎么流动的？
场景1：你问"找一下上周的发票"
graph TD
A["你在浏览器打字: 找一下上周的发票"]
A -->|"WebSocket"| B["后端服务器收到消息"]
B -->|"传给 AI"| C["Claude Agent 理解意图: 需要搜索邮件"]
C -->|"调用工具"| D["数据库搜索: SELECT * FROM emails<br>WHERE subject LIKE '%发票%' AND date > ..."]
D -->|"返回结果"| E["AI 整理搜索结果: 找到了 3 封发票邮件..."]
E -->|"WebSocket"| F["浏览器显示 AI 回复 + 邮件列表"]
场景2：新邮件自动处理
graph TD
A["Gmail 收到新邮件"]
A -->|"IMAP IDLE（实时推送）"| B["IMAP Manager 检测到新邮件"]
B --> C["Email Sync 拉取邮件 -> 存入 SQLite"]
C -->|"触发事件"| D["Listeners Manager: 有新邮件！检查所有监听器"]
D --> E["财务监听器: 这是发票吗？ -> 调 AI 分析 -> 是! -> 记账 + 贴标签"]
D --> F["任务监听器: 有待办事项吗？ -> 调 AI 分析 -> 有! -> 创建任务"]
D --> G["紧急监听器: 是紧急邮件吗？ -> 不是 -> 跳过"]
E -->|"WebSocket 推送"| H["浏览器实时更新: 收件箱 + 看板 + 通知"]
F -->|"WebSocket 推送"| H
G -->|"WebSocket 推送"| H
核心概念速查表
后面的课程会深入讲每一个，这里先过一遍：
| 概念 | 一句话解释 | 对应课程 |
|---|---|---|
| IMAP | 连邮箱的协议，能收邮件、搜邮件 | 第4课 |
| SQLite | 轻量级本地数据库，一个文件就是一个数据库 | 第5课 |
| WebSocket | 浏览器和服务器之间的"实时电话线" | 第6课 |
| Session | 一次完整的对话会话 | 第7课 |
| Action | 一键操作按钮（如"归档旧邮件""转发Bug"） | 第8课 |
| Listener | 后台自动化规则（如"新邮件来了就分析"） | 第9课 |
| UI State | 持久化数据（如财务记录、任务列表） | 第10课 |
| Component | 自定义 React 组件（如看板、图表） | 第10课 |
| callAgent | 在代码里调用 AI 做判断（递归 AI 模式） | 第9课 |
这个 Demo 最精妙的设计
"递归 AI" 模式
这是整个 demo 最有意思的设计理念：
普通程序: 代码写死逻辑 → 执行
if (邮件包含 "invoice") → 记账
递归AI: 代码控制流程 → 中间请AI帮忙判断 → 根据AI结果继续执行
收到新邮件
→ 调 callAgent("这封邮件是什么类型？", schema)
→ AI 返回: { type: "invoice", amount: 500, vendor: "Acme" }
→ 代码根据返回结果自动记账
代码管"做什么"，AI 管"判断什么"。两者结合，既有代码的确定性，又有 AI 的智能。