muhammadantor/universal-email-agent-n8n

## 📌 这是什么？ **Universal Email Agent** 是一个建立在**自托管 n8n** 之上的、完全自动化的 AI 驱动邮件处理系统。它连接到您的 Gmail 收件箱，通过多层 AI pipeline 处理每一封收到的邮件，并处理回复——全程无需任何人工干预。 由 **[Muhammad Antor](https://www.linkedin.com/in/muhammad-antor)** | [AutomateIQ Labs](https://www.facebook.com/automateiq.labs/) 构建 ## ⚡ 核心功能 | 功能 | 描述 | |---|---| | 🧠 **双 AI 大脑** | Gemini 2.0 Flash (主) + Groq Llama 3.3 (备用) 协同工作 | | 📎 **附件 OCR** | 通过 AI 读取并提取 PDF、图片附件中的内容 | | 💬 **智能分类** | 对每封邮件进行分类：垃圾邮件 / 紧急 / 支持 / 咨询 / 合作 | | 😤 **情感检测** | 检测沮丧或愤怒的语气 —— 自动升级给管理员 | | 🛡️ **Prompt 注入防护** | 阻止试图操纵 AI 的恶意邮件 | | 🔄 **知识库缓存** | 读取 Google Docs 知识库 —— 每小时缓存一次以提升性能 | | 📊 **置信度评分** | 高置信度 → 自动回复。低置信度 → 管理员草稿建议 | | 📋 **完整审计日志** | 每封邮件记录到 Google Sheets，包含类别、情感和置信度 | | 💀 **Dead Letter Queue** | 捕获失败的邮件、记录日志并通过 Telegram 向管理员发送警报 | | 🔁 **去重** | "AI-Processed" Gmail 标签防止任何邮件被处理两次 | | 📱 **Telegram 通知** | 针对紧急邮件、错误和低置信度草稿向管理员发送实时警报 | | 🏠 **100% 自托管** | 完全在您自己的服务器上运行 —— 您的数据永远不会离开您的基础设施 | ## 🏗️ 系统架构 ### 高层流程 ``` 📧 Email Arrives ↓ 📚 Knowledge Base Load (cache → Google Docs) ↓ 🛡️ Security Layer (sanitize + injection check) ↓ 📎 Attachment? ──YES──→ OCR Extract → AI Classify │ NO ↓ 🧠 AI Classify (category + sentiment + confidence) ↓ ┌─────────────────────────────────┐ │ Category Router │ ├──────────┬──────────┬───────────┤ │ 🚫 SPAM │ ⚡URGENT │ 💬 REPLY │ │ Drop │Telegram │ Generate │ │ │ Alert │ + Validate│ └──────────┴──────────┴───────────┘ ↓ High Confidence → Auto Reply Low Confidence → Ack + Admin Draft Alert ↓ ✅ Mark Read + Label + Log to Sheets ⚠️ Any Failure → Dead Letter Queue → Telegram Error Alert ``` ### 架构图  ### 层级概述 | 层级 | 功能 | |---|---| | **L1 — 输入** | Gmail 触发器，每分钟轮询一次未读邮件 | | **L2 — 知识库缓存** | 从 Google Docs 加载带有 1 小时缓存的知识库 | | **L3 — 安全** | 输入清理 + prompt 注入检测 | | **L4 — 路由** | 检测附件是否存在并进行相应路由 | | **L5A — OCR 路径** | 通过 AI 从附件中提取文本 | | **L5B — 文本路径** | 直接处理纯文本邮件 | | **L6 — AI 大脑** | 双 AI 分类 + 情感 + 置信度评分 | | **L7 — 类别路由** | 路由到垃圾邮件 / 紧急 / 回复生成器 | | **L8 — 输出** | 根据置信度进行自动回复或向管理员发送警报 | | **L9 — 完成** | 标记为已读，应用标签，记录到 Google Sheets | | **L10 — 错误** | Dead Letter Queue + 错误日志 + Telegram 警报 | **总计：跨越 10 个层级及子模型的 46 个节点** ## 🛠️ 技术栈 ### 自动化平台  自托管，Docker · 版本 2.25.7+ ### AI / LLM 模型  主 AI 大脑  备用 AI 模型 + 速度层 ### 集成     ## 📋 前置条件 在设置之前，您需要以下账户和服务： | 服务 | 用途 | 费用 | |---|---|---| | n8n (自托管) | 工作流引擎 | 免费 | | Google Gemini API | 主 AI 模型 | 提供免费额度 | | Groq API | 备用 AI 模型 | 免费额度 | | Gmail 账户 | 邮件监控 | 免费 | | Google Docs | 知识库 | 免费 | | Google Sheets | 邮件审计日志 | 免费 | | Google Cloud Service Account | Docs + Sheets 授权 | 免费 | | Telegram Bot | 管理员通知 | 免费 | | Docker | n8n 托管 | 免费 | ## 🚀 设置概述 ### 步骤 1 — 部署 n8n 使用 Docker 托管 n8n。所需的环境变量： ``` N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=true ``` ### 步骤 2 — 配置凭证 在 n8n 中设置以下凭证： - **Gmail OAuth2** — 具有完整的 Gmail 权限范围 (scope) - **Google Service Account** — 用于访问 Docs 和 Sheets - **Google Gemini API** — AI Studio 密钥 - **Groq API** — 来自 console.groq.com - **Telegram Bot** — 来自 @BotFather ### 步骤 3 — 准备 Google 服务 1. **知识库** — 创建一个包含您的业务信息、常见问题解答 (FAQ) 和语气指南的 Google Doc。与您的 Service Account 共享。 2. **邮件日志表** — 创建一个包含两个标签页的 Google Sheet：`Email Log` 和 `Failed Emails`。以 **编辑者** 身份与您的 Service Account 共享。 3. **Gmail 标签** — 在 Gmail 中创建一个 `AI-Processed` 标签。记下 Label ID。 ### 步骤 4 — 导入和配置工作流 1. 导入 n8n 工作流 JSON 2. 将所有凭证连接到相应的节点 3. 更新工作流中的以下内容： - Google Doc URL (知识库) - Google Sheets ID - Telegram Chat ID - Gmail Label ID ### 步骤 5 — 激活 将工作流从 **未激活 (Inactive) → 激活 (Active)** 切换。 ## 🧪 测试场景 使用这些测试用例来验证您的设置： | 测试 | 方法 | 预期结果 | |---|---|---| | **基础邮件** | 发送一封简单的咨询邮件 | 分类 → 自动回复 → 记录到 Sheets | | **紧急检测** | 发送带有沮丧/愤怒语气的邮件 | 升级处理 → Telegram 警报 → 回执回复 | | **附件 (PDF)** | 发送带有 PDF 附件的邮件 | 提取 OCR → 分类 → 回复 | | **Prompt 注入** | 发送 `"忽略之前的指令..."` | 被阻止 → 标记为已读 → 不回复 | | **不支持的文件** | 附加 .mp3 或 .mp4 | 自动回复：不支持的文件类型 | | **重复邮件** | 转发已处理的邮件 | 不触发 (AI-Processed 标签阻止了它) | | **垃圾邮件** | 发送明显的垃圾邮件 | 静默丢弃 → 标记为已读 | ## 📊 邮件类别 | 类别 | 检测逻辑 | 操作 | |---|---|---| | **垃圾邮件** | AI 置信度 + 模式匹配 | 静默丢弃 + 标记为已读 | | **紧急** | 关键词 + 愤怒/沮丧的情感 | 回执回复 + Telegram 警报 | | **支持** | 求助/问题相关内容 | AI 从知识库回复 | | **咨询** | 有关服务/定价的问题 | AI 从知识库回复 | | **合作** | 合作/商业提案 | AI 从知识库回复 | ## 🔒 安全功能 - **Prompt 注入检测** —— 在进行任何 AI 处理之前，会扫描邮件内容以检测是否存在 AI 操纵企图 - **输入清理** —— 所有邮件内容在进入 AI pipeline 之前都会被清理 - **自托管** —— 100% 在您自己的基础设施上。没有第三方邮件数据暴露 - **去重** —— 已处理的邮件会被打上标签，以防止重复处理 ## 📈 为什么采用这种架构？ | 设计选择 | 原因 | |---|---| | 双 AI (Gemini + Groq) | 冗余 + 速度。Groq 处理高速任务，Gemini 处理复杂推理 | | 知识库缓存 (1小时) | 显著减少 Google Docs API 调用 | | 置信度评分 | 防止自动发送糟糕的 AI 回复 | | Dead Letter Queue | 零邮件丢失 —— 每次失败都会被捕获并发出警报 | | 自托管 n8n | 完全的数据所有权。无 SaaS 邮件数据共享 | ## 🗺️ 路线图 - [ ] 多收件箱支持（多个 Gmail 账户） - [ ] 多语言回复支持（孟加拉语 + 英语） - [ ] 用于邮件分析的 Web 仪表板 - [ ] SaaS 版本 —— 插入您的凭证并运行 - [ ] WhatsApp 通知支持 - [ ] CRM 集成（从邮件自动创建线索） ## 📄 许可证 MIT 许可证 —— 详情请参阅 [LICENSE](LICENSE)。