名称： portable-email-manager
版本： 0.2.0
描述： 轻量级邮件管理器，支持 IMAP/SMTP、高级搜索、文件夹管理和附件检测。兼容 Zoho、Gmail、Outlook 及任何 IMAP/SMTP 服务提供商。

Email Manager Lite v0.2

一个为 OpenClaw 设计的完全独立的邮件管理技能。使用标准 IMAP 和 SMTP 协议，无任何外部依赖。

✨ v0.2 新特性

🔍 高级搜索与过滤

• 按发件人搜索 (--from)
• 按主题关键词搜索 (--subject)
• 按日期范围过滤 (--since, --before)
• 按已读/未读状态过滤 (--seen, --unseen)
• 在邮件正文中搜索 (--body，注意：可能较慢)

📁 文件夹管理

• 使用 folders 命令列出所有 IMAP 文件夹
• 使用 move 命令在文件夹间移动邮件
• 自动验证文件夹是否存在

📎 附件信息

• 自动检测附件
• 显示附件详情：
• 文件名
• MIME 类型
• 文件大小 (格式化为 KB/MB)
• 在 read 和 search 结果中均会显示

🔧 安装

cd skills/portable-email-manager
npm install

依赖项已打包在 package.json 中：
- nodemailer - 通过 SMTP 发送邮件
- imap-simple - 执行 IMAP 操作
- mailparser - 解析邮件并检测附件

🔐 凭证设置

设置以下环境变量：

export EMAIL_USER="your.email@domain.com"
export EMAIL_PASS="your-app-password"

建议： 对于 Gmail、Outlook、Zoho，请使用应用专用密码，而非主密码。

服务商设置

Zoho Mail (默认配置)：
- 已预配置为 smtp.zoho.eu 和 imap.zoho.eu
- 生成应用密码：https://accounts.zoho.eu/home#security/apppasswords

Gmail：
- 编辑 scripts/email.js 并修改：
javascript host: 'smtp.gmail.com' // SMTP host: 'imap.gmail.com' // IMAP
- 启用两步验证并创建应用密码：https://myaccount.google.com/apppasswords

Outlook/Hotmail：
- 编辑配置以使用 smtp.office365.com / outlook.office365.com
- SMTP 端口为 587 (TLS)

📖 使用指南

发送邮件

./scripts/email.js send "recipient@example.com" "Subject" "Email body text"

示例：

./scripts/email.js send "boss@company.com" "Weekly Report" "Attached is this week's summary."

读取最近邮件

./scripts/email.js read [limit]

示例：

# 读取最近 5 封邮件 (默认)
./scripts/email.js read

# 读取最近 20 封邮件
./scripts/email.js read 20

输出包含：
- UID (用于移动邮件的唯一标识符)
- 发件人/收件人地址
- 主题和日期
- 附件数量及详情
- 邮件正文预览 (前 500 个字符)

高级搜索

./scripts/email.js search [options]

搜索选项：

示例：

# 查找特定发件人的未读邮件
./scripts/email.js search --from "client@example.com" --unseen

# 按主题搜索
./scripts/email.js search --subject "invoice" --limit 5

# 按日期范围搜索
./scripts/email.js search --since "Jan 15, 2026" --before "Feb 1, 2026"

# 在正文中搜索 (谨慎使用 - 可能较慢)
./scripts/email.js search --body "quarterly review"

# 组合多个过滤器
./scripts/email.js search --from "boss@company.com" --subject "urgent" --unseen --limit 3

列出文件夹

./scripts/email.js folders

显示所有 IMAP 文件夹的层次结构树及其属性。

示例输出：

📁 INBOX
📁 Sent
📁 Archive
📁 Drafts
📁 Spam
📁 Trash

将邮件移至文件夹

./scripts/email.js move <uid> <folder-name>

重要提示：
- 从 read 或 search 的输出中获取 uid
- 文件夹名称区分大小写
- 脚本会在移动前验证文件夹是否存在

示例：

# 首先，查找邮件并记下其 UID
./scripts/email.js search --from "newsletter@example.com"
# 输出显示：UID: 12345

# 移动到 Archive 文件夹
./scripts/email.js move 12345 "Archive"

# 移动到自定义文件夹
./scripts/email.js move 67890 "Projects/Work"

错误处理：
- 如果文件夹不存在，会显示可用文件夹列表
- 在尝试移动前会验证 UID 是否存在

帮助

./scripts/email.js help

显示完整的使用指南，包含所有命令和示例。

🎯 使用场景

每日邮件处理

# 检查未读邮件
./scripts/email.js search --unseen --limit 10

# 将新闻简报移动到文件夹
./scripts/email.js search --from "newsletter@site.com" --limit 1
./scripts/email.js move <uid> "Newsletters"

查找特定邮件

# 按发件人和主题搜索
./scripts/email.js search --from "client@example.com" --subject "proposal"

# 按日期搜索
./scripts/email.js search --since "Jan 20, 2026" --subject "meeting notes"

归档旧邮件

# 查找旧的已读邮件
./scripts/email.js search --before "Dec 1, 2025" --seen --limit 50

# 将每封邮件移至 Archive (使用输出中的 UID)
./scripts/email.js move <uid> "Archive"

检查附件

# 读取最近邮件并查看附件信息
./scripts/email.js read 10

# 搜索输出会自动显示：
# - 附件数量
# - 每个附件的文件名、类型和大小

🔒 安全性

• 凭证从不记录或存储在文件中
• 所有连接均使用 TLS/SSL 加密
• 建议使用应用密码而非账户密码
• 除 IMAP/SMTP 连接外，数据不会离开您的机器

⚙️ 配置

默认配置已针对 Zoho Mail EU 优化。

要使用其他服务商，请编辑 scripts/email.js：

// SMTP 配置
const smtpConfig = {
  host: 'smtp.your-provider.com',
  port: 465,  // 或 587 (TLS)
  secure: true,  // true 对应 SSL (465)，false 对应 TLS (587)
  auth: {
    user: EMAIL_USER,
    pass: EMAIL_PASS
  }
};

// IMAP 配置
const imapConfig = {
  imap: {
    user: EMAIL_USER,
    password: EMAIL_PASS,
    host: 'imap.your-provider.com',
    port: 993,
    tls: true,
    authTimeout: 20000
  }
};

🚀 性能说明

• 正文搜索 (--body) 在大型邮箱上可能较慢 - 请谨慎使用
• 主题/发件人搜索 速度很快 - 使用 IMAP 服务器端过滤
• 日期过滤器 效率高
• 使用 --limit 限制结果数量以获得更快的响应

🐛 故障排除

"Authentication failed" (认证失败)
- 确认 EMAIL_USER 和 EMAIL_PASS 设置正确
- 使用应用密码，而非账户密码
- 检查服务商设置 (两步验证、低安全性应用访问等)

"Folder not found" (文件夹未找到)
- 使用 folders 命令查看确切的文件夹名称
- 文件夹名称区分大小写
- 某些服务商使用不同的名称 (例如 "Sent Items" 与 "Sent")

"Connection timeout" (连接超时)
- 检查防火墙/网络设置
- 确认 IMAP/SMTP 端口可访问
- 尝试在配置中增加 authTimeout 值

"No emails found" (未找到邮件)
- 检查搜索条件
- 确认邮件存在于收件箱 (而非其他文件夹)
- 尝试更宽泛的搜索 (移除部分过滤器)

📝 版本历史

v0.2.0 (当前版本)

• ✨ 支持多种过滤器的高级搜索
• 📁 文件夹管理 (列表、移动)
• 📎 附件检测和信息显示
• 🎨 改进的输出格式
• 📚 全面的文档

v0.1.0

• 基础的发送/读取功能
• Zoho Mail 支持
• IMAP/SMTP 基础框架

🤝 兼容性

已测试：
- ✅ Zoho Mail (EU & US)
- ✅ Gmail
- ✅ Outlook/Hotmail
- ✅ iCloud Mail
- ✅ 自定义 IMAP/SMTP 服务器

💡 使用技巧

1. 利用 UID 实现自动化： 保存搜索结果中的 UID，以便以编程方式移动邮件
2. 组合过滤器： 多个过滤器会形成 AND 条件，实现精确搜索
3. 规划文件夹结构： 先列出文件夹以规划整理策略
4. 日期格式： 使用自然语言日期，如 "Jan 1, 2026" 或 "December 25, 2025"
5. 附件过滤： 在搜索结果中查找 "Attachments: X" 以找到带附件的邮件

📄 许可证

ISC - 可在您的 OpenClaw 设置中自由使用。