cf_ai_mail_续
基于Cloudflare边缘计算平台构建的人工智能电子邮件处理系统。此应用程序使用Cloudflare AI代理和Durable Objects来分析客户电子邮件，生成智能回复，并通过MCP（模型上下文协议）与Google Calendar等外部服务集成。
项目来源
这个项目是建立在 FailSafeMail，我在自由职业项目中使用的生产电子邮件工作人员。FailSafeMail提供基本的电子邮件路由、转发、R2备份和Discord警报基础架构。
cf_ai_mail_续 通过添加以下内容扩展FailSafeMail：
- 基于人工智能的电子邮件分析和自动回复生成
- 与Cloudflare的代理框架和持久对象集成
- 谷歌日历MCP服务器集成，用于安排咨询
- 用于智能客户支持的产品目录工具
- 跨电子邮件线程的有状态的对话上下文
FailSafeMail的核心电子邮件处理、路由、错误处理和故障转移机制保持不变，在增加智能自动化功能的同时确保了可靠性。
架构与技术栈
此应用程序演示了使用Cloudflare平台的完整AI驱动系统：
核心组件
- LLM（大型语言模型）
- 通过以下方式使用OpenAI GPT-4o @ai-sdk/openai 用于电子邮件分析和回复生成 - 使用Zod模式进行结构化输出，以获得可靠的JSON响应 - 用于产品目录查找和日历操作的工具调用
- 工作流程与协调
- Cloudflare员工：主电子邮件处理员处理收到的电子邮件 - 耐用物品: RetailEmailAgent 类提供有状态的、针对每个客户的对话上下文 - 代理框架：使用Cloudflare的 agents MCP服务器集成和工具编排包
- 用户输入
- Cloudflare电子邮件路由：接收收到的电子邮件并将其发送给员工 - 基于电子邮件的界面（没有传统的聊天UI，但电子邮件作为输入机制）
- 内存和状态
- 耐用物品：维护每个客户电子邮件地址的对话上下文 - 每个客户都会获得一个唯一的Durable Object实例(email-{customer-email}) - 状态在电子邮件线程中保持不变，以便进行上下文感知回复
其他Cloudflare服务
- Cloudflare R2存储：使用完整元数据自动备份失败的电子邮件
- Cloudflare AI：AI绑定可用于未来Workers AI集成
- Cloudflare页面：提供面向公众的HTML界面
外部集成
- Mailgun：发送出站电子邮件（回复客户）
- 谷歌日历MCP服务器：通过MCP协议提供独立的Cloudflare Worker日历工具
- 存储库： 谷歌日历mcp - 提供工具： getAvailability, createConsultation, rescheduleConsultation, cancelConsultation
- Discord Webhooks：交付失败的实时警报
特性
- ✅ 使用GPT-4o进行AI驱动的电子邮件分析，具有结构化输出
- ✅ 智能回复生成与产品目录集成
- ✅ 通过MCP服务器集成谷歌日历，用于安排咨询
- ✅ 使用持久对象的有状态的对话上下文
- ✅ 基于收件人模式的智能电子邮件路由
- ✅ 交付失败时自动备份到R2存储桶
- ✅ 失败交付的Discord webhook警报
- ✅ 带有适当In Reply To标题的电子邮件线程
- ✅ 全面的错误处理和记录
运作原理
电子邮件处理流程
- 电子邮件接收：Cloudflare电子邮件路由接收传入的电子邮件并将其路由到Cloudflare Worker
- 代理分析：AI代理（由GPT-4o提供支持）分析电子邮件内容：
- 提取电子邮件正文和元数据 - 确定自动回复是否合适 - 如果需要，使用产品目录工具查找信息 - 使用Google日历MCP工具安排请求
- 回复生成：如果合适，代理将使用结构化输出生成有用的回复
- 电子邮件投递:
- 通过Mailgun向客户发送回复（带有适当的线程头） - 将原始电子邮件链转发到配置的目标地址
- 错误处理：如果任何步骤失败：
- 电子邮件已保存到R2存储桶中，其中包含完整的元数据 - 发送带有错误详细信息的不一致警报
代理体系结构
这 RetailEmailAgent 类扩展了Cloudflare的 Agent 基类，并提供：
- 有状态的上下文：每个客户电子邮件地址都会获得一个唯一的Durable Object实例
- 工具集成:
- 产品目录工具（本地功能） - 谷歌日历工具（通过MCP服务器）
- MCP服务器连接：通过SSE端点自动连接到Google日历MCP服务器
- 结构化输出：使用Zod模式确保来自LLM的可靠JSON响应
工具系统
代理可以访问两种类型的工具：
- 产品目录工具 （定义见
src/tools.js):
- getProductInfo：获取特定产品的详细信息 - searchProducts：按关键字搜索产品 - getPricing：获取特定产品的定价 - getAllProducts：列出所有可用产品
- 谷歌日历工具 （通过MCP服务器）：
- getAvailability：检查可用的时间安排 - createConsultation：创建新的日历事件 - rescheduleConsultation：更新现有事件的时间 - cancelConsultation：删除日历事件
设置和运行说明
先决条件
- Node.js 18+和npm
- 启用Workers、R2和电子邮件路由的Cloudflare帐户
- 牧马人CLI：
npm install -g wrangler - OpenAI API密钥（适用于GPT-4o）
- Mailgun帐户和API凭据
- Discord webhook URL（可选但推荐）
- 已部署Google日历MCP服务器（可选，用于日历功能）
- 请参阅： 谷歌日历mcp
安装
# Clone the repository
git clone https://github.com/TanujKS/cf_ai_mail_sentinel.git
cd cf_ai_mail_sentinel
# Install dependencies
npm install配置
- 创建R2 Bucket:
wrangler r2 bucket create fail-safe-mail-storage- 配置电子邮件路由 在
wrangler.jsonc:
"vars": {
"EMAIL_ROUTING": {
"user1@yourdomain.com": "user1@personal.com",
"@yourdomain.com": "catchall@personal.com",
"@default": "fallback@personal.com"
}
}- 设置秘密:
# OpenAI API key (required for GPT-4o)
wrangler secret put OPENAI_API_KEY
# Mailgun credentials
wrangler secret put MAILGUN_API_KEY
wrangler secret put MAILGUN_DOMAIN
# Discord webhook (optional)
wrangler secret put DISCORD_WEBHOOK_URL
# Google Calendar MCP server URL (optional)
wrangler secret put MCP_SERVER_URL- 配置环境变量 在
wrangler.jsonc:
"vars": {
"INTERNAL_FROM_EMAIL": "agent@yourdomain.com",
"MAILGUN_TAG": "ai-support"
}本地开发
# Start local development server
npm run dev工人将在 http://localhost:8787为了地方发展，创建一个 .dev.vars 文件：
OPENAI_API_KEY=your-openai-key
MAILGUN_API_KEY=your-mailgun-key
MAILGUN_DOMAIN=your-mailgun-domain
INTERNAL_FROM_EMAIL=agent@yourdomain.com
MCP_SERVER_URL=https://your-mcp-server.workers.dev
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...部署到Cloudflare
npm run deploy配置电子邮件路由
- 转到Cloudflare仪表板→ 电子邮件路由
- 添加您的域名
- 配置worker以处理传入的电子邮件
- 设置电子邮件转发规则
关键实施细节
AI代理实现
代理使用Vercel AI SDK generateText 功能包括：
- 模型：OpenAI GPT-4o(
gpt-4o-2024-11-20) - 结构化输出：Zod模式确保可靠的JSON响应
- 工具调用：LLM可以直接调用工具进行产品查找和日历操作
- 步骤限制：最多5个步骤（工具调用+最终响应）来控制成本
国家耐用物品
每个客户电子邮件地址都会获得一个唯一的持久对象：
- ID格式:
email-{customer-email-address} - 目的：跨电子邮件线程维护对话上下文
- 状态：存储在Durable Object的SQLite数据库中
- 隔离：每个客户的上下文都是完全隔离的
MCP服务器集成
代理连接到单独的Google日历MCP服务器：
- 运输：服务器发送事件（SSE）终结点
- 连接：自动连接管理，清除过时的连接
- 工具：动态发现并提供给LLM
- 仓库: 谷歌日历mcp
电子邮件线程
使用以下方法维护正确的电子邮件线程：
In-Reply-Toheader：引用原始邮件IDReferencesheader：维护线程历史记录- 引用邮件格式：在回复中包含原始电子邮件
项目结构
cf_ai_mail_sentinel/
├── src/
│ ├── index.js # Main worker entry point, email handler
│ ├── agent.js # RetailEmailAgent Durable Object class
│ ├── tools.js # Product catalog tools
│ └── mailgun.js # Mailgun email sending utility
├── public/
│ └── index.html # Public-facing landing page
├── test/
│ ├── index.spec.js # Test suite
│ └── sample.eml # Sample email for testing
├── wrangler.jsonc # Cloudflare Workers configuration
├── package.json # Dependencies and scripts
├── PROMPTS.md # AI prompts used in development
└── README.md # This file相关项目
- FailSafeMail:
- 此项目扩展的基础电子邮件工作器 - 生产就绪的电子邮件路由、转发、R2备份和Discord警报 - 用于自由职业项目的生产
- 谷歌日历MCP服务器:
- 单独的Cloudflare Worker通过MCP协议提供日历集成 - 日历日程安排功能所需
监控与调试
- Cloudflare工作日志：在Cloudflare Dashboard中查看实时日志
- 牧马人尾巴:
wrangler tail用于实时日志流 - R2存储：检查
fail-safe-mail-storage用于失败电子邮件备份的bucket - 不和谐警报：交付失败的实时通知
许可证
该项目是Cloudflare实习申请任务的一部分。
故障排除
常见问题
- 未处理的电子邮件
- 验证Cloudflare电子邮件路由配置是否正确 - 检查worker是否已部署并处于活动状态 - 在Cloudflare Dashboard中查看工作人员日志
- AI代理没有响应
- 验证 OPENAI_API_KEY 密码设置正确 - 检查中的持久对象绑定 wrangler.jsonc - 检查代理日志中的错误
- 日历工具不可用
- 验证 MCP_SERVER_URL 设置为您的MCP服务器基本URL - 检查是否已部署Google日历MCP服务器： 谷歌日历mcp - 确保MCP服务器 /sse 端点可访问 - 查看代理日志中的MCP连接错误
- R2备份不工作
- 验证R2桶是否存在： wrangler r2 bucket list - 检查铲斗是否卡滞 wrangler.jsonc - 查看工作日志中的R2错误
- 不和谐警报未发送
- 验证 DISCORD_WEBHOOK_URL 秘密已经设定 - 检查Discord webhook URL是否有效 - 查看工作日志中的获取错误
调试命令
# View live logs
wrangler tail
# List R2 buckets
wrangler r2 bucket list
# Check deployed worker
wrangler deployments list