一、引言

邮件是办公协同中最基础也最关键的通信通道之一。AI Agent 若能直接操控用户的个人邮箱，即可将"生成内容"升级为"发送邮件"，从而消除从对话框到收件人之间的最后一道人工环节。2026 年 4 月上线的 QClaw V2（V0.2.5）将邮箱能力纳入连接器体系，形成了由统一入口、路由分发层和底层引擎组成的三级架构。该架构首期覆盖 IMAP/SMTP 个人邮箱收发和平台公邮推送两条路径，支持 163、QQ、Gmail、Outlook 等十八种邮箱服务商，并可结合定时任务实现周期性邮件推送。本文基于 QClaw 安装目录中的邮箱相关源码（email-skill、imap-smtp-email、public-skill、qclaw-cron-skill 共四个 Skill，以及 resolve-account.cjs、smtp.js、imap.js、email_gateway.sh 共四个核心脚本），深入剖析其邮箱系统的架构设计与技术实现，并阐述如何通过对话引导 WPS 灵犀 Claw 从零构建等价的邮箱技能。

二、统一入口与路由分发

QClaw 邮箱系统的第一层是 email-skill，它是一个纯路由层，不执行任何脚本，不调用任何接口，仅负责识别用户意图并分发至下游 Skill。该 Skill 的触发关键词涵盖"发邮件""收邮件""搜索邮件""下载附件""绑定邮箱""邮件推送"等 22 个邮件相关词条，并配有排除规则过滤与邮件无关的指令（如日历、文件管理、站内信等）。

email-skill 的路由遵循"先理解场景，再选路径"的核心原则，将用户需求分为两条路径。第一条路径指向 public-skill（平台公邮通道），触发条件为：发送对象是用户自己、内容为纯文本、不需要附件或抄送密送、不需要收件检索、场景属于"结果推送或消息留存"类（如天气推送、日报留存、报告备份）。第二条路径指向 imap-smtp-email（个人邮箱通道），触发条件为：需要发给第三方收件人、需要抄送或密送、需要附件或 HTML 邮件、需要收件箱查询或附件下载、需要标记已读未读、或用户明确提及"发给别人""带附件""查收件箱""正式邮件"等信号词。两条路径存在清晰的能力边界：公邮支持零配置推送到自己邮箱但仅限纯文本，个人邮箱需配置授权码但支持完整的 IMAP/SMTP 收发。

路由还设计了自动回退策略：当公邮因日发送上限、通道不可用、请求超时或登录过期等原因失败时，自动回退至个人邮箱通道执行；但参数校验错误、频率限制和邮箱未绑定等场景则直接报错，不做回退。这一机制确保了邮件发送的最终送达率，同时在失败路径上为用户提供明确的错误诊断。

三、个人邮箱引擎的底层实现

imap-smtp-email 是邮箱系统的核心引擎，采用三层脚本架构。

第一层是 email_gateway.sh（Unix 平台）或 email_gateway.cmd（Windows 平台），它是整个引擎的入口脚本，仅做两件事：检查 Node.js 运行时是否可用，若可用则将所有参数透传给第二层的 resolve-account.cjs 执行。

第二层是 resolve-account.cjs（11820 字），承担账号解析与凭证管理职责。其执行流程分为四步：首先，通过本地 Auth Gateway 代理（默认端口 19000）调用 4230 接口（authorized-email-platforms）拉取用户全部已绑定的个人邮箱列表，接口经远程地址（现网为 jprx.m.qq.com）转发，白名单限定 163_mail、qq_mail、gmail、outlook、sina_mail、sohu_mail 六个平台；其次，根据用户命令中的 account-email 参数或自动选择逻辑决定使用哪个邮箱，支持按邮箱地址精确匹配绑定列表或按域名反查 platform 标识，当存在多个绑定邮箱时由前端拦截器弹出选择卡片让用户指定后传入参数；再次，比较当前 .env 配置的邮箱与选中邮箱是否一致，若不一致则调用 get-token.sh 刷新凭证写入 .env，get-token.sh 同样通过 4164 接口从凭证网关获取授权码，并按目标域名自动推算 IMAP 和 SMTP 服务器地址后写入环境文件，整个过程超时阈值设为 15 秒；最后，根据命令类型（SMTP_COMMANDS 或 IMAP_COMMANDS）派发至 smtp.js 或 imap.js 执行并继承标准输入输出。

第三层是 smtp.js（13010 字）和 imap.js（24203 字），分别基于 nodemailer v7 和 imap v0.8（配合 imap-simple v5、mailparser v3）实现邮件发送与收件功能。引擎内置 18 种邮箱 Provider 预设（涵盖网易系、QQ/Foxmail、Gmail、Outlook、Yahoo、新浪、搜狐、139、腾讯企业邮和阿里云，以及自定义选项），支持 SSL（465 端口）和 STARTTLS（587 端口）两种加密模式。imap.js 支持 IMAP ID 扩展（RFC 2971），可正确处理 163 等服务器的兼容性要求，并内置连接超时、认证超时和 Socket 超时的分层超时控制机制。安全方面，引擎通过 ALLOWED_READ_DIRS 和 ALLOWED_WRITE_DIRS 两个环境变量限制附件读写的目录范围，防止文件越界访问。

四、平台公邮通道与定时邮件

public-skill 是 QClaw 的平台公邮通道，用于将内容推送到用户自己的邮箱。它通过 4227 接口查询用户已绑定的平台公邮邮箱，返回绑定状态后直接发信。未绑定时提供 bind-check、bind-send-code、bind-verify 三步绑定流程，通过发送和校验验证码完成邮箱绑定。该通道的能力边界严格限定：仅支持纯文本推送到用户自己的邮箱，明确不支持第三方收件人、抄送密送、附件、HTML 邮件和自定义发件人。传入不支持的参数时，通道会直接报错并提示用户改走个人邮箱通道。

在定时邮件方面，qclaw-cron-skill 提供了两种任务创建方式：内置 cron 工具（JSON 参数）和 CLI 命令行，具体选择取决于消息来源渠道（本地 UI 和钉钉用内置工具，企业微信和飞书用 CLI）。时间参数支持一次性定时（ISO 时间戳加时区）和周期任务（cron 表达式），任务投递配置支持本地 announce 模式和外部渠道推送模式。任务管理支持列表查看、暂停恢复和删除操作。该机制使得"每天早上 9 点将日报推送至邮箱"这类定时邮件场景可通过对话直接创建和管理。

五、向 WPS 灵犀 Claw 的迁移实践

WPS 灵犀 Claw 本身不具备邮箱能力，需要用户通过对话引导灵犀从零构建邮箱技能。以下是一个完整的对话式迁移路径。

第一步，提供 QClaw 源码作为参考。用户输入"这是 QClaw 的邮箱技能源码，目录在 D:\QClaw\resources\openclaw\config\skills，请你分析它的邮件系统架构，然后参考它的设计为灵犀创建一个 email 技能"。灵犀会读取该目录下的 email-skill、imap-smtp-email、public-skill 三个 Skill 的 SKILL.md 文件，以及 resolve-account.cjs、smtp.js、imap.js、email_gateway.sh、package.json 等核心脚本，形成对 QClaw 邮箱系统三级架构（路由层、公邮通道、个人邮箱引擎）的完整理解，然后按照灵犀的 skill-creator 规范在 skills/email 目录下创建 email 技能。

第二步，引导灵犀确定迁移策略并创建入口脚本。用户输入"请参考 QClaw 的 imap-smtp-email 引擎，但不要用它的腾讯凭证网关（4230/4164 接口），改为本地 .env 文件直接配置。创建一个 Python 入口脚本 email.py 替代 resolve-account.cjs，通过 subprocess 调用 Node.js 引擎"。灵犀据此创建 email.py 作为统一调度入口，内置 18 种邮箱的域名到服务器地址映射表（覆盖 QQ、163、Gmail、Outlook 等），支持通过 configure 命令一步完成邮箱配置（用户只需提供邮箱地址和授权码），并直接复用 QClaw 的 smtp.js 和 imap.js 作为底层 Node.js 引擎。最终在 skills/email 目录下生成完整的技能结构，包含主 SKILL.md、email-skill 子路由层 SKILL.md、imap-smtp-email 子引擎 SKILL.md、email.py 调度脚本、复用的 smtp.js 和 imap.js，以及 node_modules 依赖目录。

第三步，配置邮箱凭证并测试连通性。用户输入"配置我的 QQ 邮箱，授权码是 xxx"。灵犀调用 email.py 的 configure 命令，根据 qq.com 域名自动匹配 imap.qq.com（IMAP 993 端口 SSL）和 smtp.qq.com（SMTP 465 端口 SSL），同时生成附件读写目录白名单，将完整的连接参数写入 .env 文件。随后用户输入"测试邮箱连通性"，灵犀调用 test 命令通过 smtp.js 发起 SMTP 连接验证，返回连接成功或失败信息。若返回 535 错误码，灵犀会提示用户检查授权码是否正确以及 IMAP/SMTP 服务是否已在邮箱网页端开启；若返回 SSL 证书校验失败，灵犀将建议用户检查网络环境是否安装了代理软件。

第四步，验证邮件收发能力。用户输入"用我的邮箱给 partner@example.com 发一封主题为项目同步的邮件"，灵犀调用 send 命令，由 smtp.js 通过 nodemailer v7 完成实际发送。用户输入"查看最近两小时收到的邮件"，灵犀调用 check 命令并传入 recent 参数限定搜索范围以避免全量扫描收件箱，由 imap.js 返回邮件列表。用户输入"搜索最近一周带有发票关键词的邮件并下载附件"，灵犀依次调用 search 和 download 命令。用户输入"把这封邮件标记为已读"，灵犀调用 mark-read 命令。通过这组提示词，用户可逐一验证邮箱技能的发送、收件、搜索、附件下载和状态管理功能。

第五步，利用灵犀的本地优势扩展邮件场景。用户输入"把这封邮件的附件下载后用 WPS 表格打开分析"，灵犀在获取附件后直接调用 xlsx 技能对数据进行透视分析。用户输入"把邮件里的发票数据汇总做成金山文档在线表格"，灵犀通过 search 提取邮件中的发票信息后调用金山文档技能创建多维表格。用户输入"通过企业微信把这份周报邮件发给项目组"，灵犀在企业微信会话中接收指令后完成邮件发送并将结果推送到群聊。这种邮件与文档处理及 IM 渠道的端到端的全流程联动，是灵犀作为本地 AI 助手的差异化优势。

六、结语

QClaw 邮箱系统的架构价值在于将邮件能力拆解为路由层、公邮通道和个人邮箱引擎三个职责清晰的模块，各模块通过 SKILL.md 定义的契约协作，新增邮箱能力只需实现工具定义即可接入。向 WPS 灵犀 Claw 迁移的核心原则是引擎复用加入口重构：底层 Node.js 邮件引擎可直接复用，入口层用 Python 重写以跳过腾讯凭证网关，凭证管理从远程网关切换为本地 .env 手动配置。上述迁移路径已通过对话式引导验证可行，灵犀在邮件与 WPS 文档生态及 IM 渠道的联动方面具备天然优势，值得在此基础上进一步构建邮件智能驱动的自动化工作流，例如邮件附件定时归档和邮件触发文档生成等场景。