邮箱智能体

用于服务一个已配置邮箱账号。通用性来自支持不同 IMAP/SMTP 邮箱服务商，而不是多账号管理；一个 skill 实例只假设一个邮箱账号。

触发场景

当用户要求检查邮箱、搜索邮件、读取某封邮件、下载附件、生成回复草稿、转发邮件、显式发送邮件、标记已读、移动邮件，或识别截止时间邮件时，使用本 skill。

用户可见名称统一使用“邮箱智能体”。

首次运行

首次触发时，检查以下运行时配置文件是否存在（由初始化命令在用户本地生成，不随 skill 发布，缺席属正常初始状态）：

• scripts/mail_config.py — 当前唯一邮箱账号的 IMAP/SMTP 连接配置
• scripts/digest_config.py — 巡检关键词和检查时间偏好

若不存在，读取 首次运行导引。用户只必须提供完整邮箱账号和连接参数；系统会根据邮箱域名识别常见服务商，未识别时默认尝试 imap.<domain>:993 和 smtp.<domain>:465。

初始化命令：

python "<skill_dir>/scripts/init_config.py" --user "your_name@<域名>"

连接参数含特殊字符时，优先使用以下方式，避免 shell 展开和命令行历史记录：

python "<skill_dir>/scripts/init_config.py" --user "your_name@<域名>" --value-file "/tmp/mail-value.txt"
python "<skill_dir>/scripts/init_config.py" --user "your_name@<域名>" --value-env MAIL_VALUE
python "<skill_dir>/scripts/init_config.py" --user "your_name@<域名>" --value-stdin

连接失败时，可手动覆盖服务器：

python "<skill_dir>/scripts/init_config.py" --force --user "your_name@<域名>" \
  --imap-host "imap.<域名>" --imap-port 993 \
  --smtp-host "smtp.<域名>" --smtp-port 465

不要把连接参数直接写进命令行参数、日志、聊天记录或发布包。

通用代理命令

统一入口是 scripts/mail.py。所有命令只操作当前唯一配置邮箱账号。

搜索邮件：

python "<skill_dir>/scripts/mail.py" search --query "材料" --since 2026-07-01 --limit 20
python "<skill_dir>/scripts/mail.py" search --from "sender@<域名>" --has-attachment --json

读取邮件：

python "<skill_dir>/scripts/mail.py" read --uid 123 --mailbox INBOX

下载附件：

python "<skill_dir>/scripts/mail.py" attachments --uid 123 --output-dir "<skill_dir>/.temp/attachments"

生成回复草稿：

python "<skill_dir>/scripts/mail.py" reply-draft --uid 123 --body "收到，我会按要求处理。"

转发邮件，默认生成草稿；只有显式 --send 才直接发送：

python "<skill_dir>/scripts/mail.py" forward --uid 123 --to "recipient@<域名>"
python "<skill_dir>/scripts/mail.py" forward --uid 123 --to "recipient@<域名>" --send

显式发送草稿或新邮件：

python "<skill_dir>/scripts/mail.py" send --draft "<skill_dir>/.temp/reply_draft_YYYYMMDD_HHMMSS.eml" --confirm
python "<skill_dir>/scripts/mail.py" send --to "recipient@<域名>" --subject "主题" --body "正文" --confirm

标记和移动：

python "<skill_dir>/scripts/mail.py" mark-seen --uid 123
python "<skill_dir>/scripts/mail.py" move --uid 123 --folder Archive --confirm

巡检工作流

保留现有巡检入口：

python "<skill_dir>/scripts/process_digest.py" --since-hours 2

巡检会读取最近邮件，按关键词和截止时间生成摘要、待办和本地通知输出。输出、原始邮件、草稿和附件默认保存在 .temp/。

常用巡检命令：

python "<skill_dir>/scripts/process_digest.py" --since-hours 2 --json
python "<skill_dir>/scripts/process_digest.py" --since-hours 2 --review
python "<skill_dir>/scripts/process_digest.py" --add-keyword "材料报送"
python "<skill_dir>/scripts/process_digest.py" --cleanup-days 7 --json

操作边界

• 默认生成草稿，不默认直接发送。
• mail.py send 必须显式指定 --confirm。
• mail.py move 必须显式指定 --confirm。
• forward --send 视为用户显式直接发送。
• 暂不提供删除邮件命令。
• 连接参数继续支持交互、--value-file、--value-env、--value-stdin。
• 不在摘要、日志、推送或发布包中暴露连接参数。

参考文档

• 邮箱配置：config-guide.md
• 首次运行：first-run-guide.md
• 定时检查：schedule-guide.md
• 关键词管理：keyword-guide.md
• 截止时间识别：deadline-detection-guide.md
• 通道回推：channel-routing-guide.md
• 输出格式：output-format-guide.md
• 故障处理：troubleshooting-guide.md