AI导哈

AI邮件处理系统

基于Cloudflare边缘计算平台的AI邮件处理系统，利用AI代理和Durable Objects分析客户邮件、生成智能回复并集成Google Calendar等外部服务。

  • by TanujKS
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 TanujKS/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响应
    • 用于产品目录查找和日历操作的工具调用

  2. 工作流程与协调

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

  3. 用户输入

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

  4. 内存和状态

    • 耐用物品：维护每个客户电子邮件地址的对话上下文
    • 每个客户都会获得一个唯一的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工具安排请求
  3. 回复生成：如果合适，代理将使用结构化输出生成有用的回复
  4. 电子邮件投递:
    • 通过Mailgun向客户发送回复（带有适当的线程头）
    • 将原始电子邮件链转发到配置的目标地址
  5. 错误处理：如果任何步骤失败：
    • 电子邮件已保存到R2存储桶中，其中包含完整的元数据
    • 发送带有错误详细信息的不一致警报

代理体系结构

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

  • 有状态的上下文：每个客户电子邮件地址都会获得一个唯一的Durable Object实例
  • 工具集成:
    • 产品目录工具（本地功能）
    • 谷歌日历工具（通过MCP服务器）
  • MCP服务器连接：通过SSE端点自动连接到Google日历MCP服务器
  • 结构化输出：使用Zod模式确保来自LLM的可靠JSON响应

工具系统

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

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

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

  2. 谷歌日历工具 （通过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服务器（可选，用于日历功能）

安装

# 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: github/TanujKS/FailSafeMail

    • 此项目扩展的基础电子邮件工作器
    • 生产就绪的电子邮件路由、转发、R2备份和Discord警报
    • 用于自由职业项目的生产

  • 谷歌日历MCP服务器: github.com/TanujKS/google-calendar-mcp

    • 单独的Cloudflare Worker通过MCP协议提供日历集成
    • 日历日程安排功能所需

监控与调试

  • Cloudflare工作日志：在Cloudflare Dashboard中查看实时日志
  • 牧马人尾巴: wrangler tail 用于实时日志流
  • R2存储：检查 fail-safe-mail-storage 用于失败电子邮件备份的bucket
  • 不和谐警报：交付失败的实时通知

许可证

该项目是Cloudflare实习申请任务的一部分。

故障排除

常见问题

  1. 未处理的电子邮件

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

  2. AI代理没有响应

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

  3. 日历工具不可用

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

  4. R2备份不工作

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

  5. 不和谐警报未发送

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

调试命令

# View live logs
wrangler tail

# List R2 buckets
wrangler r2 bucket list

# Check deployed worker
wrangler deployments list

相关 MCP