cf AI mail sentinel

cf_ai_mail_续

基于Cloudflare边缘计算平台构建的人工智能电子邮件处理系统。此应用程序使用Cloudflare AI代理和Durable Objects来分析客户电子邮件，生成智能回复，并通过MCP（模型上下文协议）与Google Calendar等外部服务集成。

项目来源

这个项目是建立在 FailSafeMail，我在自由职业项目中使用的生产电子邮件工作人员。FailSafeMail提供基本的电子邮件路由、转发、R2备份和Discord警报基础架构。

cf_ai_mail_续 通过添加以下内容扩展FailSafeMail：

• 基于人工智能的电子邮件分析和自动回复生成
• 与Cloudflare的代理框架和持久对象集成
• 谷歌日历MCP服务器集成，用于安排咨询
• 用于智能客户支持的产品目录工具
• 跨电子邮件线程的有状态的对话上下文

FailSafeMail的核心电子邮件处理、路由、错误处理和故障转移机制保持不变，在增加智能自动化功能的同时确保了可靠性。

架构与技术栈

此应用程序演示了使用Cloudflare平台的完整AI驱动系统：

核心组件

1. LLM（大型语言模型）

- 通过以下方式使用OpenAI GPT-4o @ai-sdk/openai 用于电子邮件分析和回复生成 - 使用Zod模式进行结构化输出，以获得可靠的JSON响应 - 用于产品目录查找和日历操作的工具调用

1. 工作流程与协调

- Cloudflare员工：主电子邮件处理员处理收到的电子邮件 - 耐用物品: RetailEmailAgent 类提供有状态的、针对每个客户的对话上下文 - 代理框架：使用Cloudflare的 agents MCP服务器集成和工具编排包

1. 用户输入

- Cloudflare电子邮件路由：接收收到的电子邮件并将其发送给员工 - 基于电子邮件的界面（没有传统的聊天UI，但电子邮件作为输入机制）

1. 内存和状态

- 耐用物品：维护每个客户电子邮件地址的对话上下文 - 每个客户都会获得一个唯一的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标题的电子邮件线程
• ✅ 全面的错误处理和记录

运作原理

电子邮件处理流程

1. 电子邮件接收：Cloudflare电子邮件路由接收传入的电子邮件并将其路由到Cloudflare Worker
2. 代理分析：AI代理（由GPT-4o提供支持）分析电子邮件内容：

- 提取电子邮件正文和元数据 - 确定自动回复是否合适 - 如果需要，使用产品目录工具查找信息 - 使用Google日历MCP工具安排请求

1. 回复生成：如果合适，代理将使用结构化输出生成有用的回复
2. 电子邮件投递:

- 通过Mailgun向客户发送回复（带有适当的线程头） - 将原始电子邮件链转发到配置的目标地址

1. 错误处理：如果任何步骤失败：

- 电子邮件已保存到R2存储桶中，其中包含完整的元数据 - 发送带有错误详细信息的不一致警报

代理体系结构

这 RetailEmailAgent 类扩展了Cloudflare的 Agent 基类，并提供：

• 有状态的上下文：每个客户电子邮件地址都会获得一个唯一的Durable Object实例
• 工具集成:

- 产品目录工具（本地功能） - 谷歌日历工具（通过MCP服务器）

• MCP服务器连接：通过SSE端点自动连接到Google日历MCP服务器
• 结构化输出：使用Zod模式确保来自LLM的可靠JSON响应

工具系统

代理可以访问两种类型的工具：

1. 产品目录工具 （定义见 src/tools.js):

- getProductInfo：获取特定产品的详细信息 - searchProducts：按关键字搜索产品 - getPricing：获取特定产品的定价 - getAllProducts：列出所有可用产品

1. 谷歌日历工具 （通过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

配置

1. 创建R2 Bucket:

wrangler r2 bucket create fail-safe-mail-storage

1. 配置电子邮件路由 在 wrangler.jsonc:

"vars": {
  "EMAIL_ROUTING": {
    "user1@yourdomain.com": "user1@personal.com",
    "@yourdomain.com": "catchall@personal.com",
    "@default": "fallback@personal.com"
  }
}

1. 设置秘密:

# 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

1. 配置环境变量 在 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

配置电子邮件路由

1. 转到Cloudflare仪表板→ 电子邮件路由
2. 添加您的域名
3. 配置worker以处理传入的电子邮件
4. 设置电子邮件转发规则

关键实施细节

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-To header：引用原始邮件ID
• References header：维护线程历史记录
• 引用邮件格式：在回复中包含原始电子邮件

项目结构

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实习申请任务的一部分。

故障排除

常见问题

1. 未处理的电子邮件

- 验证Cloudflare电子邮件路由配置是否正确 - 检查worker是否已部署并处于活动状态 - 在Cloudflare Dashboard中查看工作人员日志

1. AI代理没有响应

- 验证 OPENAI_API_KEY 密码设置正确 - 检查中的持久对象绑定 wrangler.jsonc - 检查代理日志中的错误

1. 日历工具不可用

- 验证 MCP_SERVER_URL 设置为您的MCP服务器基本URL - 检查是否已部署Google日历MCP服务器： 谷歌日历mcp - 确保MCP服务器 /sse 端点可访问 - 查看代理日志中的MCP连接错误

1. R2备份不工作

- 验证R2桶是否存在： wrangler r2 bucket list - 检查铲斗是否卡滞 wrangler.jsonc - 查看工作日志中的R2错误

1. 不和谐警报未发送

- 验证 DISCORD_WEBHOOK_URL 秘密已经设定 - 检查Discord webhook URL是否有效 - 查看工作日志中的获取错误

调试命令

# View live logs
wrangler tail

# List R2 buckets
wrangler r2 bucket list

# Check deployed worker
wrangler deployments list