第3课：环境搭建 —— 连上 Gmail，跑起来

本课目标

把整个系统跑起来，在浏览器里看到你的真实邮件。

需要准备什么？

东西	说明
Bun	JavaScript 运行时（类似 Node.js 但更快）
Gmail 账号	需要开启 IMAP 和生成应用专用密码
Anthropic API Key	Claude 的"门票"

第一步：安装 Bun

bash
# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# 验证
bun --version

如果你更习惯 Node.js，npm 也能用，但这个 demo 官方推荐 Bun。

第二步：配置 Gmail

2.1 开启 IMAP

打开 Gmail 网页版
点击右上角 ⚙️ 齿轮 → "查看所有设置"
切换到 "转发和 POP/IMAP" 标签
找到 IMAP 访问，选择 "启用 IMAP"
保存更改

2.2 开启两步验证

打开 Google 账号安全设置
找到 "两步验证"，按提示开启
这是生成应用专用密码的前提

2.3 生成应用专用密码

打开 Google 应用专用密码页面
选择应用: 选"其他"，输入名称如 "Email Agent"
点击"生成"
你会得到一个 16位密码（如 abcd efgh ijkl mnop）
复制保存好！这个密码只显示一次

⚠️ 不要用你的 Gmail 登录密码！必须用这个应用专用密码。

第三步：获取 API Key

打开 console.anthropic.com
创建 API Key，复制下来

第四步：克隆项目

code
# 如果你已经有 demos 目录
cd demos/email-agent

# 如果从零开始
git clone https://github.com/anthropics/claude-agent-sdk-demos.git
cd claude-agent-sdk-demos/email-agent

第五步：配置环境变量

复制示例配置文件：

code

cp .env.example .env

编辑 .env 文件：

code
# Gmail IMAP 配置
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
EMAIL_ADDRESS=你的邮箱@gmail.com
EMAIL_APP_PASSWORD=abcdefghijklmnop    # 第二步生成的16位密码（去掉空格）

# Claude API
ANTHROPIC_API_KEY=sk-ant-xxxxx你的key放这里xxxxx

第六步：安装依赖并启动

code
# 安装所有依赖
bun install

# 启动开发服务器
bun run dev

如果一切正常，你会看到：

code

🚀 Server running at http://localhost:3000
📧 Connecting to IMAP server...
✅ IMAP connected, syncing emails...
📬 Synced 50 emails from inbox
🔌 WebSocket server ready

第七步：打开浏览器

访问 http://localhost:3000，你应该看到：

收件箱标签 — 显示你 Gmail 里的真实邮件
聊天标签 — 可以跟 AI 助手对话
看板标签 — 财务看板和任务看板（初始为空）

试试在聊天框输入："帮我看看最新的5封邮件"——AI 应该能返回你的真实邮件内容。

常见问题

Q：IMAP 连接失败

检查几个点： - Gmail 的 IMAP 是否开启了？ - 应用专用密码是否正确？（注意去掉空格） - 网络能否访问 imap.gmail.com:993？

Q：前端白屏

可能是依赖没装好：

code
bun install  # 重新安装
bun run dev  # 重新启动

Q：不是 Gmail 怎么办？

修改 .env 里的 IMAP 配置：

code
# Outlook
IMAP_HOST=outlook.office365.com
IMAP_PORT=993

# QQ邮箱
IMAP_HOST=imap.qq.com
IMAP_PORT=993

不同邮箱的应用密码获取方式不同，搜索"XX邮箱 IMAP 应用密码"即可。

Q：API 调用要花多少钱？

日常聊天搜索很便宜（每次几分钱）。但如果开了很多 Listener 自动处理每一封新邮件，费用会累积。建议开发测试时先少开几个 Listener。

跑起来之后的目录变化

启动后，项目会多出一些运行时文件：

code

email-agent/
├── emails.db        ← SQLite 数据库文件（存着你的邮件）
├── .logs/
│   ├── actions/     ← Action 执行日志
│   └── listeners/   ← Listener 执行日志
└── ...