名称： imap-email
描述： 通过 IMAP 协议读取和管理邮件（支持 ProtonMail Bridge、Gmail 等）。检查新邮件/未读邮件、获取邮件内容、搜索邮箱以及标记已读/未读。适用于任何 IMAP 服务器，包括 ProtonMail Bridge。

IMAP 邮件阅读器

通过 IMAP 协议读取、搜索和管理邮件。支持 ProtonMail Bridge、Gmail IMAP 以及任何标准 IMAP 服务器。

快速开始

检查新邮件：

node skills/imap-email/scripts/imap.js check

获取特定邮件：

node skills/imap-email/scripts/imap.js fetch <uid>

标记为已读：

node skills/imap-email/scripts/imap.js mark-read <uid>

搜索邮箱：

node skills/imap-email/scripts/imap.js search --from "sender@example.com" --unseen

配置

快速设置（ProtonMail Bridge）：

cd skills/imap-email
./setup.sh

设置助手将提示输入 Bridge 凭据并测试连接。

手动设置：
1. 在技能文件夹中，将 .env.example 复制为 .env
2. 填写你的 IMAP 凭据
3. .env 文件已自动被 git 忽略

环境变量：

IMAP_HOST=127.0.0.1          # 服务器主机名
IMAP_PORT=1143               # 服务器端口
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=false               # 使用 TLS/SSL 连接
IMAP_REJECT_UNAUTHORIZED=false  # 对于自签名证书设置为 false（可选）
IMAP_MAILBOX=INBOX           # 默认邮箱

⚠️ 安全提示： 切勿提交你的 .env 文件！它已在 .gitignore 中以防止意外提交。

ProtonMail Bridge 设置：
- 安装并运行 ProtonMail Bridge
- 使用 127.0.0.1:1143 作为 IMAP 地址
- 密码由 Bridge 生成（不是你的 ProtonMail 账户密码）
- TLS：使用 false（Bridge 使用 STARTTLS）
- REJECT_UNAUTHORIZED：设置为 false（Bridge 使用自签名证书）

Gmail IMAP 设置：
- 主机：imap.gmail.com
- 端口：993
- TLS：true
- 启用“安全性较低的应用访问权限”或使用应用专用密码
- REJECT_UNAUTHORIZED：省略或设置为 true（默认值）

命令

check

检查邮箱中的未读/新邮件。

node scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h]

选项：
- --limit <n>：最大结果数（默认：10）
- --mailbox <name>：要检查的邮箱（默认：INBOX）
- --recent <time>：仅显示最近 X 时间内的邮件（例如：30m, 2h, 7d）

返回包含以下信息的 JSON 数组：
- uid、发件人、主题、日期、摘要、标记

fetch

通过 UID 获取完整的邮件内容。

node scripts/imap.js fetch <uid> [--mailbox INBOX]

返回包含完整正文（文本 + HTML）的 JSON。

search

使用过滤器搜索邮件。

node scripts/imap.js search [options]

选项：
  --unseen           仅未读邮件
  --seen             仅已读邮件
  --from <email>     发件人地址包含
  --subject <text>   主题包含
  --recent <time>    最近 X 时间内的邮件（例如：30m, 2h, 7d）
  --since <date>     指定日期之后（YYYY-MM-DD）
  --before <date>    指定日期之前（YYYY-MM-DD）
  --limit <n>        最大结果数（默认：20）
  --mailbox <name>   要搜索的邮箱（默认：INBOX）

时间格式示例：
- 30m = 最近 30 分钟
- 2h = 最近 2 小时
- 7d = 最近 7 天

mark-read / mark-unread

将一条或多条邮件标记为已读或未读。

node scripts/imap.js mark-read <uid> [uid2 uid3...]
node scripts/imap.js mark-unread <uid> [uid2 uid3...]

list-mailboxes

列出所有可用的邮箱/文件夹。

node scripts/imap.js list-mailboxes

Cron 集成

使用 Clawdbot cron 设置定期邮件检查：

# 每 15 分钟检查一次邮件，并发送到 iMessage
clawdbot cron add \
  --name "email-check" \
  --cron "*/15 * * * *" \
  --session isolated \
  --message "检查新的 ProtonMail 邮件并总结" \
  --deliver \
  --channel imessage \
  --to "+15085600825"

在隔离会话中，代理可以运行：

node /Users/mike/clawd/skills/imap-email/scripts/imap.js check --limit 5

工作流示例

早晨邮件摘要：
1. 运行 check --limit 10 --recent 12h
2. 总结夜间未读邮件
3. 将摘要发送到首选渠道

检查特定发件人的近期邮件：
1. 运行 search --from "important@company.com" --recent 24h
2. 如有需要，获取完整内容
3. 处理后将邮件标记为已读

每小时紧急邮件检查：
1. 运行 search --recent 1h --unseen
2. 筛选重要关键词
3. 提取待办事项
4. 如有紧急情况，发送通知

每周摘要：
1. 运行 search --recent 7d --limit 20
2. 总结活动情况
3. 生成每周报告

依赖项

必需包： imap-simple, mailparser, dotenv

安装：

cd skills/imap-email
npm install

这将安装 package.json 中列出的所有依赖项。

安全注意事项

• 将凭据存储在 .env 中（并确保已添加到 .gitignore）
• ProtonMail Bridge 密码不是你的账户密码
• 访问 ProtonMail IMAP 时，Bridge 必须正在运行
• 对于 Gmail，考虑使用应用专用密码

故障排除

连接超时：
- 确认 IMAP 服务器正在运行且可访问
- 检查主机/端口配置
- 使用 telnet <主机> <端口> 测试

认证失败：
- 确认用户名正确（通常是完整的电子邮件地址）
- 检查密码是否正确
- 对于 ProtonMail Bridge：使用 Bridge 生成的密码，而非账户密码
- 对于 Gmail：如果启用了双重验证，请使用应用专用密码

TLS/SSL 错误：
- 确保 IMAP_TLS 设置与服务器要求匹配（SSL 用 true，STARTTLS 用 false）
- 对于自签名证书（例如 ProtonMail Bridge）：设置 IMAP_REJECT_UNAUTHORIZED=false
- 检查端口是否与 TLS 设置匹配（SSL 用 993，STARTTLS 用 143）

结果为空：
- 确认邮箱名称正确（区分大小写）
- 检查搜索条件
- 使用 list-mailboxes 命令列出所有邮箱