bingo-email — 统一邮件管理

基于 Python IMAPClient + smtplib 的全功能邮件管理工具，支持任意 IMAP/SMTP 邮箱。

特性一览

快速开始（AI 自动引导流程）

当用户首次触发邮件相关操作时，AI 应按以下流程自动执行：

0. 环境自检（自动，用户无感）

python3 /scripts/bingo_email.py check

• ✅ exit 0 → 直接执行用户请求的邮件操作
• ❌ exit 2 → 提示用户完成缺失步骤后继续

第 1 步：安装依赖（check 发现缺失时提示）

pip3 install imapclient

第 2 步：初始化配置（check 发现缺失时提示）

# 运行交互式向导（推荐）
python3 /scripts/bingo_email.py init

向导会引导你选择邮箱服务商并填写账号密码。支持预设模板：

关于授权码：大部分邮箱不使用登录密码，而是使用「授权码」或「应用专用密码」。

• 腾讯企业邮箱：企业邮箱后台 → 设置 → POP/SMTP 服务
• QQ 邮箱：设置 → 账户 → POP3/SMTP服务 → 开启并获取授权码
• 163/126：设置 → POP3/SMTP/IMAP → 开启并获取授权码
• Gmail：Google Account → Security → App Passwords（需要开启 2FA）

第 3 步：验证连接

python3 /scripts/bingo_email.py test

输出示例：

正在测试连接...
  邮箱: you@example.com
  IMAP: imap.example.com:993
  SMTP: smtp.example.com:465

  ✓ IMAP 连接成功 — 收件箱共 42 封邮件
  ✓ SMTP 连接成功

看到两个 ✓ 就说明配置正确。

配置文件详解

配置保存在 ~/.config/bingo-email/config.toml：

⚠️ 安全警告：此文件包含明文密码/授权码！

• 文件权限已自动设为 600（仅本人可读），请勿修改权限
• 绝对不要将此文件提交到 Git / GitHub（已通过 .gitignore 排除）
• 分享 skill 给他人时，只分享代码，不分享此文件
• 如果不小心上传了，立即轮换授权码

# bingo-email 配置文件
[account]
email = "your@email.com"
display_name = "Your Name"

[imap]
host = "imap.exmail.qq.com"
port = 993
encryption = "tls"           # tls | starttls | none
login = "your@email.com"
password = "your_auth_code"
require_imap_id = false       # ⚠️ 关键字段！126/163 必须设为 true

[smtp]
host = "smtp.exmail.qq.com"
port = 465
encryption = "tls"           # tls | starttls | none
login = "your@email.com"
password = "your_auth_code"

字段说明

⚠️ 126 / 163 网易邮箱特殊说明

问题背景

网易的 126 和 163 邮箱强制要求 RFC 2971 IMAP ID 扩展。客户端必须在 LOGIN 之前或之后立即发送 ID 命令，否则服务器会拒绝登录并返回 "Unsafe Login" 错误。

解决方案

bingo-email 内置了两种连接模式：

1. 标准模式（require_imap_id = false）：使用 imapclient 库正常连接。适用于腾讯企业邮箱、QQ、Gmail、Outlook 等大多数邮箱服务商。

2. IMAP ID 模式（require_imap_id = true）：通过 raw SSL socket 手动实现完整的 IMAP 握手流程：

   TCP Connect → TLS Handshake → CAPABILITY → ID → LOGIN → [Ready]
   

配置方法

选择 126 或 163 预设模板时，require_imap_id 会自动设为 true。手动配置时确保：

[imap]
host = "imap.163.com"        # 或 imap.126.com
require_imap_id = true        # ← 这行是关键

技术细节

IMAP ID 命令格式（RFC 2971）：

A02 ID (("name" "bingo-email") ("version" "1.0"))

这告诉服务器客户端的身份信息，满足网易的安全策略要求。标准 IMAP 客户库（如 imapclient）默认不发送此命令，因此需要对 126/163 做特殊处理。

使用方式

python3 /scripts/bingo_email.py  [args...]

支持的全部命令

初始化 & 测试 & 环境检查

python3 bingo_email.py init              # 交互式初始化配置（首次必做）
python3 bingo_email.py test              # 测试 IMAP/SMTP 连接
python3 bingo_email.py check             # 非交互式环境检查（自动诊断依赖+配置）

🤖 AI Agent 注意：在执行任何邮件操作之前，必须先运行 check 命令确认环境就绪。

• 如果 exit code = 0 → 环境正常，继续执行用户请求的操作
• 如果 exit code ≠ 0 → 根据输出提示用户完成缺失的步骤（安装依赖或运行 init）

读取类

python3 bingo_email.py list [N]          # 列出最近 N 封邮件（默认20封）
python3 bingo_email.py unread [N]        # 列出未读邮件
python3 bingo_email.py read          # 读取指定 ID 的邮件详情
python3 bingo_email.py folders           # 列出所有文件夹

发送类

python3 bingo_email.py send   [--body "正文"]
python3 bingo_email.py reply  [--body "回复正文"] [--all]        # --all = 回复所有人
python3 bingo_email.py forward   [--body "附言"]

回复功能说明：

• reply 默认只回复发件人，自动附带原始邮件 inline quote 引用（标准 > 格式）
• reply ... --all 为 Reply-All 模式，额外 Cc 给原始邮件 To/Cc 中的其他收件人（自动排除自己）
• 回复邮件自动设置 In-Reply-To 和 References 头，确保邮件客户端能正确归并对话线程
• draft-reply 同样支持 --all 参数，保存为回复全部草稿

草稿类

python3 bingo_email.py draft --to  --subject  [--body "正文"]
python3 bingo_email.py draft-reply  [--body "回复正文"] [--all]   # --all = 回复所有人草稿

管理类

python3 bingo_email.py delete         # 删除邮件（移至已删除）
python3 bingo_email.py move   # 移动到其他文件夹

正文输入方式

三种方式传入邮件正文（优先级从高到低）：

1. --body 参数（推荐用于脚本调用）：

   python3 bingo_email.py send a@b.com "主题" --body "这是正文内容"
   

2. 管道传入：

   echo "正文内容" | python3 bingo_email.py send a@b.com "主题"
   

3. 交互输入（不带以上两种时自动进入）：

   python3 bingo_email.py send a@b.com "主题"
   # 请输入邮件正文（输入空行结束）:
   # > 第一行
   # > 第二行
   # > （直接回车结束）
   

输出格式

与 himalaya 对比

安装 & 分享给他人

方法一：作为 WorkBuddy Skill 安装

将整个 bingo-email/ 目录放到 WorkBuddy skills 目录：

# 复制到用户级 skills 目录（所有项目可用）
cp -r bingo-email/ ~/.workbuddy/skills/

# 或复制到项目级 skills 目录（仅当前项目可用）
cp -r bingo-email/ .workbuddy/skills/

然后运行 init 命令配置自己的邮箱即可。

方法二：独立使用（不需要 WorkBuddy）

# 1. 下载脚本
curl -o ~/bin/bingo_email.py https://your-host/scripts/bingo_email.py
chmod +x ~/bin/bingo_email.py

# 2. 安装依赖
pip3 install imapclient

# 3. 初始化配置
~/bin/bingo_email.py init

# 4. 使用
~/bin/bingo_email.py unread

分享检查清单

给其他人使用前，确认对方完成以下步骤：

• Python 3.8+ 已安装
• pip3 install imapclient
• 运行 bingo_email.py init 完成配置
• 运行 bingo_email.py test 验证连接
• 如果是 126/163 邮箱，确认 init 时选择了对应预设（或手动设 require_imap_id = true）

新用户快速验证：直接运行 python3 bingo_email.py check 即可一键诊断所有前置条件。

🔒 安全 & 开源分享

已内置的安全措施

开源到 GitHub 的检查清单

发布前确认以下事项：

• config.toml 不在仓库中：确认 .gitignore 包含 config.toml
• 历史提交无凭据：git log -p -- config.toml 确认从无此文件
• 无敏感信息在示例中：SKILL.md / README 中的配置示例只用 your_auth_code 占位符
• 添加 LICENSE：建议 MIT 或 Apache 2.0
• 添加 SECURITY.md：告知用户如何安全报告漏洞

如果不小心泄露了授权码

1. 立即去邮箱后台轮换（重新生成）授权码
2. 更新本地 config.toml
3. 如果已推送到 GitHub：

   # 使用 BFG 或 git-filter-repo 从历史中彻底删除
   # 然后强制推送（需谨慎！）
   

用户侧安全建议（可写入文档）

最终用户应了解：

1. 保持 config.toml 权限为 600（程序自动设置）
2. 不要在公共场合截图包含此文件内容
3. 定期检查是否有未授权的邮件操作（查看"已发送"文件夹）
4. 多设备使用时各自独立配置，不要复制粘贴配置文件

常见问题

Q: 提示 "未找到配置文件"？

A: 首次使用必须先运行 python3 bingo_email.py init 进行配置。

Q: 登录失败 "Authentication failed"？

A: 检查以下几点：

1. 是否使用了授权码而不是登录密码？（QQ/163/126/腾讯企业邮箱都是授权码）
2. 授权码是否有过期？部分服务的授权码会定期失效
3. Gmail 必须使用应用专用密码（App Password），不是 Google 账号密码

Q: 126/163 报 "Unsafe Login"？

A: 确认配置中 require_imap_id = true。如果用的旧版配置，重新运行 init 选择 126 或 163 模板即可。

Q: 草稿箱中文乱码？

A: 这个问题在 bingo-email 中不会出现——草稿统一使用 MIMEText + base64 编码写入。如果遇到乱码请报 bug。

Q: 如何切换邮箱账号？

A: 编辑 ~/.config/bingo-email/config.toml 修改账号信息，或重新运行 init 覆盖配置。

注意事项

• 企业邮箱已发送文件夹通常名为 Sent Messages（不是 Sent）
• 草稿箱为 Drafts
• 删除操作默认移至"已删除"文件夹，不做物理删除
• Message ID 在列表中显示为整数 UID，每次刷新可能变化（IMAP 特性）