1. 项目概述让AI智能体拥有“收邮件”的能力如果你正在开发或使用AI智能体比如Claude Code、OpenClaw、Cursor肯定遇到过这个经典难题你想让AI帮你注册一个新服务它填表、提交一气呵成然后页面弹出一个验证码输入框AI就卡住了。它没有邮箱收不到验证邮件整个自动化流程就此中断。mails-skills这个项目就是为了彻底解决这个问题而生的。它本质上是一套“邮箱技能包”通过一个部署在Cloudflare Workers上的邮件处理服务为任何AI智能体赋予了接收、解析邮件特别是自动提取验证码的能力。这样一来你的AI助手就能像真人一样完成需要邮箱验证的完整注册流程实现真正的端到端自动化。简单来说mails-skills包含两个核心部分一个是后端服务mailsWorker负责收发、存储、解析邮件另一个是前端的“技能文件”Skill Files这些文件定义了AI智能体如何与这个后端服务进行对话的指令集。你只需要部署好服务然后把对应的技能文件“教”给你的AI它立刻就学会了查收邮件、找验证码这个新技能。无论是个人想自动化一些繁琐的注册任务还是开发者想构建更强大的AI工作流这个工具都能显著扩展智能体的能力边界。2. 核心架构与工作原理拆解要理解mails-skills我们需要把它拆解成几个核心组件来看这能帮你更好地判断它是否适合你的场景以及在出问题时如何排查。2.1 三层架构智能体、技能与后端服务整个系统遵循一个清晰的三层架构每一层各司其职AI智能体层这是用户直接交互的对象可以是Claude Code、OpenClaw、Cursor等任何支持外部技能或API调用的LLM应用。它本身不具备邮件处理能力。技能层这是连接智能体和后端服务的“翻译官”或“说明书”。它通常是一个Markdown或特定格式的文件里面用自然语言和结构化指令告诉AI“如果你想查邮件应该调用这个HTTP接口如果你想取验证码应该用那个带超时参数的GET请求。”安装过程其实就是把这个技能文件放到智能体能读取的特定目录下。后端服务层这是系统的核心引擎即mailsWorker。它是一个部署在Cloudflare Workers上的无服务器应用集成了多个云服务Cloudflare Email Routing负责接收发送到指定域名的所有邮件并将其转发路由到我们的Worker进行处理。Cloudflare D1一个SQLite数据库用于存储邮件元数据发件人、主题、时间等、邮件正文以及分类标签。Cloudflare R2对象存储服务用于保存邮件中的附件如PDF、图片并通过API提供下载链接。Resend一个电子邮件API服务Worker通过它来发送外发邮件。它提供了可靠的发信能力和必要的发件人域名认证SPF/DKIM。当AI智能体需要执行邮件相关操作时流程是这样的智能体根据技能文件中的指引构造一个HTTP请求例如GET https://your-worker.workers.dev/api/code?timeout60并发送出去。这个请求到达mailsWorkerWorker验证身份后查询数据库或监听新邮件找到验证码或邮件内容再以JSON格式返回给智能体。智能体收到响应后就能提取出验证码并填入网页或者读取邮件内容并总结给你听。2.2 验证码提取的“黑科技”与局限性自动提取验证码是mails-skills最吸引人的功能。它的实现原理并不复杂但非常实用。Worker在收到邮件后会使用一套预定义的规则对邮件正文包括HTML和纯文本部分进行扫描。这些规则通常用于匹配4到12位之间的数字组合并且会结合一些上下文关键词比如“verification code”、“您的验证码是”、“code:”等来提高匹配的准确性。匹配到的候选数字串会被进一步筛选剔除明显不符合验证码格式的内容比如日期、电话号码。然而这里有一个至关重要的注意事项提取的成功率高度依赖于邮件本身的格式。如果验证码被做成了图片图片验证码或者嵌在极其复杂的HTML表格中纯文本解析就可能失败。因此在技能的设计中除了/api/code这个专为验证码优化的接口通常还会提供一个更通用的/api/email接口让AI可以读取完整的邮件原文以备不时之需。在实际使用中如果/api/code返回空让AI去读取完整邮件内容再由LLM自己从文本中找出验证码是一个可靠的备用方案。2.3 为什么选择Cloudflare Workers Resend这个技术栈这个选型背后有清晰的逻辑考量理解了这些你才能明白项目的设计哲学甚至在未来考虑自建类似服务时做出合理的技术选型。Cloudflare Workers这是整个架构的基石。它提供了全球边缘网络、极快的冷启动速度尤其是对AI这种需要低延迟交互的场景至关重要以及一个非常慷慨的免费额度。对于个人或中等规模的使用免费套餐基本够用。更重要的是它与Cloudflare生态的其他服务Email Routing, D1, R2集成是天衣无缝的配置和管理都在同一个面板大大降低了运维复杂度。Cloudflare D1选择D1而非更传统的PostgreSQL是因为邮件数据模型相对简单但需要快速的全文搜索FTS。D1基于SQLite原生支持FTS5扩展非常适合邮件搜索这种场景。同时它作为Cloudflare原生服务与Worker的通信延迟极低且同样有免费层级。Resend发送邮件比接收要复杂得多涉及到发件人信誉、反垃圾邮件策略SPF, DKIM, DMARC等。自己搭建SMTP服务器门槛高、易进垃圾箱。Resend这类专业邮件发送API类似SendGrid, Mailgun封装了所有复杂性提供简单的API和清晰的仪表盘能极大提高邮件的送达率。项目选择Resend也是因为其开发者体验友好并且提供免费额度。提示这种架构是典型的“Serverless优先”思维核心追求是免运维、按需付费甚至免费、快速集成。如果你的应用场景对数据主权、定制化有极高要求可能需要考虑基于更传统的VPS和邮件服务器来构建但那会引入显著的运维负担。3. 两种部署模式详解与实操指南mails-skills提供了两种部署方式托管模式和自托管模式。选择哪种取决于你的需求、技术偏好和对控制权的渴望程度。3.1 托管模式五分钟快速上手指南这是最快捷的入门方式适合想立即体验、不想操心服务器和域名的用户。你使用的将是项目方提供的共享域名服务如xxxmails0.com。操作步骤如下安装全局CLI工具打开你的终端Terminal运行npm install -g mails-agent。这会在你的电脑上安装一个名为mails的命令行工具。确保你的系统已安装Node.js版本16或以上。申领一个邮箱地址运行mails claim your-agent-name。这里的your-agent-name可以是你任意起的名字比如mybot。命令执行成功后你会获得一个专属的邮箱地址格式类似your-agent-namemails0.com。这个地址和对应的认证令牌Token会自动保存到你的本地配置文件~/.mails/config.json中。为你的AI智能体安装技能克隆技能库并运行安装脚本。git clone https://github.com/Digidai/mails-skills cd mails-skills ./install.sh这个安装脚本非常智能它会自动检测你系统中安装的AI智能体如Claude Code、OpenClaw并读取上一步生成的配置文件将正确的Worker URL、Auth Token和邮箱地址填入对应的技能文件中然后拷贝到智能体的技能目录。你几乎不需要任何手动配置。实操心得在运行./install.sh时建议你打开脚本看一眼用cat install.sh了解一下它做了什么。它本质上是一个bash脚本会检查特定目录如~/.claude/skills/是否存在然后将skills/目录下对应的模板文件复制过去并用sed等工具替换里面的占位符变量。如果安装后AI智能体仍不识别邮件技能第一件事就是去检查这些技能文件是否存在于正确的位置以及文件内的API地址和Token是否已被正确替换。3.2 自托管模式完全掌控的进阶部署如果你需要自定义域名比如aiyourcompany.com有更高的安全性和数据隐私要求或者预计有非常大的使用量那么自托管是唯一的选择。这个过程涉及更多步骤但能给你完全的控制权。准备工作清单一个你拥有管理权限的域名例如yourdomain.com。一个Cloudflare账户并将你的域名添加到Cloudflare托管使用其Nameserver。一个Resend账户用于发送邮件。详细部署步骤部署Worker代码git clone https://github.com/Digidai/mails cd mails/worker bun install # 或 npm install项目推荐使用bun这里使用了bun作为包管理器它比npm安装更快。如果你没有安装bun可以用npm install替代。创建并配置数据库# 在Cloudflare上创建一个D1数据库实例 npx wrangler d1 create mails执行成功后命令行会输出一个database_id。你需要复制这个ID然后打开项目根目录下的wrangler.toml配置文件找到[[d1_databases]]部分将database_id和database_name填写正确。 接着初始化数据库表结构npx wrangler d1 execute mails --fileschema.sql配置敏感信息Worker需要Resend的API Key来发信还可以设置一个Webhook密钥用于安全回调。npx wrangler secret put RESEND_API_KEY # 按提示输入你在Resend后台获取的API Key npx wrangler secret put WEBHOOK_SECRET # 可选用于签名验证部署Workernpx wrangler deploy部署成功后你会获得一个Worker的访问URL格式如https://mails-worker.你的子域名.workers.dev。记下这个URL后续配置会用到。配置Cloudflare邮件路由这是最关键的一步让发送到你域名的邮件能流入Worker。登录Cloudflare仪表板进入你的域名。侧边栏找到EmailEmail Routing点击Enable。在Routing rules标签页点击Create address选择Catch-all address捕获所有地址。这意味着任何发送到*yourdomain.com的邮件都会被处理。在目标Destination选择中选择Send to a Worker然后选择你刚刚部署的mailsWorker。在Resend中验证域名并配置DNS为了让从你域名发出的邮件不被标记为垃圾邮件必须配置SPF和DKIM记录。登录Resend控制台进入Domains添加你的域名如yourdomain.com。Resend会生成一组DNS记录包括TXT类型的SPF记录和CNAME类型的DKIM记录。你需要回到Cloudflare的DNS管理页面将这些记录逐一添加进去。生成认证令牌最后你需要为你的AI智能体创建一个访问令牌。npx wrangler d1 execute mails --command \ INSERT INTO auth_tokens (token, mailbox) VALUES ($(openssl rand -hex 24), agentyourdomain.com)这个命令会生成一个随机的24位十六进制字符串作为Token并将其与邮箱地址agentyourdomain.com绑定。请安全地保存这个Token。注意事项自托管模式最大的坑通常在DNS配置和邮件路由环节。Cloudflare邮件路由的生效可能需要几分钟到几小时。Resend的域名验证DNS记录生效同样需要时间。部署完成后强烈建议你先手动发送一封测试邮件到testyourdomain.com然后通过Worker的API如GET /api/emails需带上Auth Token查询是否成功收到以此验证整个接收链路是否通畅。4. 为不同AI智能体安装技能的具体操作不同的AI开发环境对“技能”的加载方式各不相同。mails-skills项目贴心地为主流平台提供了预制的技能文件。4.1 Claude CodeClaude Code通过读取~/.claude/skills/目录下的.md文件来加载技能。安装脚本install.sh会自动完成以下工作将skills/claude-code/email.md拷贝到~/.claude/skills/email.md。用你的实际配置Worker URL, Auth Token, Mailbox替换文件中的占位符YOUR_WORKER_URL,YOUR_AUTH_TOKEN,YOUR_MAILBOX。手动安装检查如果自动安装失败你可以手动检查。首先确保目录存在ls ~/.claude/skills/然后查看email.md文件内容确认里面的API端点地址和Token是否正确。Claude Code会在启动时加载这些技能你可以在对话中尝试使用“check my inbox”之类的指令来测试。4.2 OpenClawOpenClaw使用一种名为AgentSkills的格式通常技能放在~/.openclaw/skills/目录下并且可能需要环境变量来传递配置。安装脚本会将skills/openclaw/整个目录拷贝到~/.openclaw/skills/email/。尝试在你的Shell配置文件如~/.zshrc或~/.bashrc中追加以下环境变量export MAILS_API_URLhttps://your-worker.workers.dev export MAILS_AUTH_TOKENyour-token export MAILS_MAILBOXagentyourdomain.com你需要执行source ~/.zshrc或重新打开终端使环境变量生效。4.3 Cursor / WindsurfCursor和Windsurf这类AI驱动的编辑器通常通过项目根目录或用户目录下的规则文件如.cursorrules或.windsurfrules来扩展AI的能力。对于它们你需要的是通用的API参考文档。 安装脚本会将skills/universal/email-api.md这个文件的内容整合或提示你添加到你的规则文件中。这个email-api.md文件不包含具体配置而是用清晰的格式描述了每个API端点的功能、请求方法和示例相当于一份给AI看的API文档。你需要手动将这份文档的核心部分结合你的具体配置URL和Token添加到你的.cursorrules文件中。4.4 通用集成任何基于HTTP API的智能体如果你使用的智能体平台允许你自定义系统提示词System Prompt或工具Tools列表那么集成方式最为灵活。你只需要做两件事将skills/universal/email-api.md文件的内容作为“如何使用邮件API”的说明书插入到你的系统提示词里。确保你的智能体具备发起HTTP请求的能力例如通过函数调用或内置工具并在请求头中正确带上认证令牌Authorization: Bearer YOUR_AUTH_TOKEN。实操心得与AI智能体集成的关键在于让AI“理解”它拥有这个工具。技能文件的质量至关重要。一份好的技能文件不仅要列出API参数更要用AI能理解的、自然的方式描述功能场景例如“当你需要获取一个刚刚发送到我们邮箱的验证码时你可以调用这个GET接口并等待最多60秒。如果收到邮件它会返回一个6位数字的代码。” 这种描述比干巴巴的API文档更有效。5. 核心API使用场景与代码示例技能文件的核心是驱动AI去调用一系列HTTP API。我们来深入看看几个最关键的使用场景和背后的细节。5.1 自动化注册获取验证码的完整流程这是最核心的场景。假设我们想让AI注册一个名为“ExampleSaaS”的服务。AI导航与填表你给AI的指令是“请使用邮箱agentyourdomain.com在 example.com 上注册一个账户。” AI会打开注册页面填写用户名、邮箱等信息。触发验证邮件AI点击提交后ExampleSaaS的服务端会向agentyourdomain.com发送一封包含验证码的邮件。AI调用取码API此时AI根据技能文件的指引调用GET /api/code?timeout60。这里的timeout60参数非常关键它告诉Worker“我最多等待60秒请在这段时间内监听新邮件一旦发现包含验证码的邮件就立即返回。” Worker会持续查询数据库匹配新邮件中的验证码。接收并应用验证码Worker在收到邮件并成功提取验证码后返回JSON{“code”: “483920”}。AI收到响应将这个6位数字填入网页的验证码输入框完成注册。注意事项timeout参数需要根据目标网站发送邮件的速度合理设置。对于国内服务可能3-5秒就够了对于某些海外服务可能需要30秒以上。设置太短可能导致取码失败设置太长则会让AI无谓等待。一个经验是首次使用某个服务时可以设长一点如60秒根据实际响应时间再调整。5.2 邮件管理收、发、搜、下附件除了验证码完整的邮件管理能力能让AI成为更得力的助手。接收与搜索邮件AI可以调用GET /api/emails?querygithub来搜索收件箱中所有来自GitHub或内容包含“github”的邮件。返回的结果是结构化的列表包含邮件ID、发件人、主题、时间戳和摘要。AI可以据此向你汇报“你收到了3封GitHub的邮件分别是关于Issue回复、PR合并和仓库动态。”发送邮件通过POST /api/sendAI可以帮你发送邮件。你需要让AI在请求体中构造好收件人、主题和正文。这个功能可以用于自动发送报告、通知或者作为工作流的一部分。{ “to”: “colleaguecompany.com”, “subject”: “项目周报”, “html”: “p本周进展如下.../p” }下载附件邮件中的附件如图片、PDF被存储在Cloudflare R2中。当AI发现一封带有附件的邮件邮件元数据中会标明它可以调用GET /api/attachments/{attachment_id}来获取附件的直接下载链接甚至可以尝试读取其中内容如果是文本格式并总结给你。5.3 结构化数据提取从邮件中抓取关键信息这是一个高阶功能展示了LLM与自动化流程结合的价值。Worker可以对已知格式的邮件如电商订单确认、航班行程单、酒店预订收据进行预处理尝试提取结构化数据。例如当收到一封亚马逊的订单确认邮件时除了存储原始邮件Worker可以尝试运行一个提取器输出类似下面的JSON{ “type”: “order”, “data”: { “order_number”: “123-4567890-1234567”, “total_amount”: “$99.99”, “items”: [“商品A”, “商品B”], “estimated_delivery”: “2023-10-27” } }这样当你让AI“查一下我最近买了什么”它就不需要去阅读理解整封邮件而是直接查询结构化的“订单”数据快速给出答案。这个功能需要预先定义好不同邮件类型的提取规则或模型目前看来是项目的一个发展方向。6. 常见问题排查与实战经验分享在实际部署和使用过程中你肯定会遇到一些问题。下面是我在多次搭建和调试中总结出的常见“坑点”和解决方案。6.1 部署与连接问题问题现象可能原因与排查步骤mails claim命令卡住或无响应1.网络问题检查你的网络连接特别是能否访问相关服务域名。2.服务端状态托管服务mails0.com可能暂时不可用。可以尝试等待片刻或去项目GitHub仓库的Issues页面查看是否有宕机公告。3.本地配置检查~/.mails/config.json文件是否已存在且内容正确。有时可以删除该文件后重试。安装脚本./install.sh报错1.依赖缺失脚本可能需要python3、curl、jq等工具。根据错误提示安装对应工具如brew install python3 jq。2.权限不足确保你对~/.claude/skills/等目录有写入权限。3.自动检测失败脚本可能没检测到你的AI环境。尝试使用非交互模式手动指定参数./install.sh --url YOUR_URL --token YOUR_TOKEN --mailbox YOUR_MAILBOX。AI智能体无法识别邮件技能1.技能文件位置错误确认技能文件是否被复制到了正确的目录如~/.claude/skills/email.md。2.技能文件内容错误打开技能文件检查里面的YOUR_WORKER_URL、YOUR_AUTH_TOKEN等占位符是否已被替换成你的真实配置。3.AI环境重启某些AI工具如Claude Code需要在安装新技能后重启才能加载。API调用返回401 Unauthorized1.Token错误确认你使用的Auth Token与数据库中auth_tokens表里记录的一致且对应的邮箱地址正确。2.Token未传递检查AI发出的HTTP请求头是否包含Authorization: Bearer your-token。3.Token格式确保Token字符串没有多余的空格或换行符。6.2 邮件接收与验证码提取问题问题现象可能原因与排查步骤收不到任何邮件1.Cloudflare邮件路由未生效这是最常见的原因。去Cloudflare仪表板检查Email Routing是否显示“Active”规则是否配置正确。可以尝试给自己发一封邮件然后在Email Routing的日志中查看是否有投递记录。2.DNS问题确保你的域名MX记录等指向Cloudflare。可以尝试在Cloudflare的“网络”-“诊断中心”测试邮件路由。3.Worker部署失败检查Worker的部署状态和日志看是否有运行时错误。能收到邮件但/api/code返回空1.邮件格式问题验证码可能以图片形式存在或隐藏在复杂的HTML标签里。让AI调用GET /api/emails?limit1获取最新一封邮件的完整内容然后让LLM自己从邮件原文中找出验证码。2.超时时间太短邮件服务有延迟。尝试增加timeout参数到90或120秒。3.邮件分类错误Worker可能未将邮件正确识别为“验证码”类。检查邮件是否被标记为label: ‘code’。附件无法下载或损坏1.R2存储配置确保Worker的wrangler.toml中正确配置了R2绑定且部署成功。2.权限问题附件下载API同样需要有效的Auth Token。3.文件类型某些二进制文件在通过API传输时可能需要特殊处理。检查返回的下载链接是否能直接在浏览器中打开。6.3 关于验证码Captcha的终极挑战必须清醒认识到mails-skills解决的是“邮箱验证码”Email OTP的问题但对于现代网站广泛使用的图形验证码CAPTCHA它无能为力。当你的AI在注册流程中遇到Google reCAPTCHA或hCaptcha时流程依然会中断。目前的解决方案主要有以下几类各有优劣使用带验证码求解服务的无头浏览器例如 Browserbase 或 Steel 。这些服务提供了一个云浏览器环境并且集成了第三方验证码求解服务如2Captcha, Anti-Captcha。你的AI通过API控制这个远程浏览器进行操作遇到验证码时服务商会自动尝试求解。优点是自动化程度高缺点是成本较高且依赖于第三方求解服务的成功率。单独集成验证码求解API例如 CapSolver 。你可以在你的AI工作流中当检测到验证码图片时截取图片并调用CapSolver的API进行识别再将结果填入。这需要更多的开发工作并且需要处理图片截取和坐标点击等交互。等待新的协议标准项目中提到的 Web Bot Auth 是一个正在制定的IETF标准旨在为自动化机器人提供一种合法的身份验证方式从而可能免去验证码。但这依赖于网站方的支持短期内难以普及。实操建议对于个人项目或内部工具如果目标网站没有验证码mails-skills是完美的。如果必须处理带验证码的网站现阶段最现实的方案是结合方案1无头浏览器服务但这会引入额外的复杂性和成本。在规划自动化流程时第一步应该是手动测试目标网站的注册流程确认其使用的验证机制类型。7. 安全、成本与扩展性考量在将这样一个系统投入生产环境或处理敏感信息前必须考虑以下几点。7.1 安全最佳实践令牌Token管理Auth Token是访问你邮箱数据的唯一凭证。务必像保管密码一样保管它。不要将Token硬编码在客户端代码或技能文件中。建议在自托管模式下通过环境变量传递给AI智能体。在托管模式下依赖本地的~/.mails/config.json配置文件并确保该文件权限为600。最小权限原则自托管时可以考虑在数据库中为不同的AI智能体或用途创建不同的Token并绑定到特定的邮箱前缀如marketing-botdev-bot。这样即使一个Token泄露影响范围也有限。Webhook安全如果你配置了Webhook用于邮件到达时实时通知外部服务务必使用WEBHOOK_SECRET对请求进行签名验证防止伪造请求。域名与发信信誉使用自定义域名时务必正确配置Resend要求的SPF和DKIM的DNS记录。错误的配置会导致你发出的邮件被标记为垃圾邮件甚至影响域名信誉。7.2 成本估算托管模式目前项目方提供的mails0.com服务是免费的但通常会有使用限制如每日发送/接收量限制。对于轻度使用完全足够但需要注意服务条款。自托管模式Cloudflare Workers免费套餐提供每天10万次请求和一定量的CPU时间对于个人使用绰绰有余。Cloudflare D1免费套餐有读取行数、写入行数和存储空间限制但邮件数据除非海量一般不会超限。Cloudflare R2免费额度包括一定量的存储和操作次数。Resend提供每月100封的免费额度超出后按量计费。总结对于个人或小团队自托管模式在免费额度内基本可以实现零成本运行。但需要监控用量特别是邮件发送量。7.3 性能与扩展性性能基于Cloudflare全球边缘网络API响应延迟极低这对AI交互体验很重要。D1数据库虽然不如专业OLTP数据库但对于邮件元数据查询和FTS搜索性能完全可接受。扩展性瓶颈D1的写入性能如果遇到极高并发的邮件接收例如被用作公开的临时邮箱服务D1的写入可能成为瓶颈。这时可能需要考虑引入队列或换用更强大的数据库。Resend发送限额免费和低阶套餐有发送频率限制。如果需要大规模发送邮件需要升级Resend套餐。Worker内存与CPU时间复杂的邮件解析尤其是HTML解析和结构化提取可能消耗较多CPU时间。需要监控Worker的运行时错误和超时情况。扩展方向这个项目是一个优秀的起点。你可以基于它的代码进行扩展例如增加更强大的邮件解析引擎如mailparser、集成更复杂的分类AI模型、添加自动回复规则、或者将其作为更大自动化工作流中的一个微服务。最后这个项目的魅力在于它用一个相对简洁的架构解决了一个非常具体的痛点。它可能不是功能最全的邮件服务器但绝对是让AI智能体“学会”处理邮件最快、最轻量的方式之一。在实际使用中从简单的自动注册到复杂的邮件工作流自动化它的边界只取决于你的想象力。