bingo-email — 统一邮件管理#

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

特性一览#

特性说明多邮箱支持腾讯企业邮箱、QQ邮箱、126/163、Gmail、Outlook + 自定义126/163 兼容自动处理 IMAP ID (RFC 2971) 要求中文无乱码草稿箱使用 base64 编码（非 quoted-printable）零外部依赖仅需 imapclient（pip install 即可），无需编译配置外置TOML 配置文件，不含硬编码凭据，可安全共享文件权限 600save_config 后自动 chmod 600，仅本人可读回复引用自动附带原始邮件 inline quote（ > 格式）Reply-All--all 标志一键回复所有人，智能排除自己线程归并自动设置 In-Reply-To / References 头自动诊断check 命令非交互式检测依赖和配置状态

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

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

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

bash

python3 <skill_path>/scripts/bingo_email.py check

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

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

bash

pip3 install imapclient

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

bash

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

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

编号服务商说明1腾讯企业邮箱imap.exmail.qq.com (默认 TLS)2QQ 邮箱imap.qq.com3163 网易邮箱imap.163.com — 自动启用 IMAP ID4126 网易邮箱imap.126.com — 自动启用 IMAP ID5Gmailimap.gmail.com（需应用专用密码）6Outlookoutlook.office365.com（支持 STARTTLS）7+自定义手动输入服务器地址

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

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

第 3 步：验证连接#

bash

python3 <skill_path>/scripts/bingo_email.py test

输出示例：

text

正在测试连接...
  邮箱: 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 给他人时，只分享代码，不分享此文件
• 如果不小心上传了， 立即轮换授权码

toml

# 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"

字段说明#

字段必填说明account.email✅你的邮箱地址account.display_name❌发件显示名称imap.host✅IMAP 服务器地址imap.port❌IMAP 端口（默认 993）imap.encryption❌加密方式： tls(SSL), starttls, none``imap.login❌IMAP 登录名（默认同 email）imap.password✅授权码或密码imap.require_imap_id❌是否发送 IMAP ID 命令（126/163 必须=true）smtp.host✅SMTP 服务器地址smtp.port❌SMTP 端口（默认 465）smtp.encryption❌加密方式（同 imap）smtp.login❌SMTP 登录名（默认同 email）smtp.password✅授权码或密码（可与 imap 共用）

---

⚠️ 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 握手流程： text

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

配置方法#

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

toml

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

技术细节#

IMAP ID 命令格式（RFC 2971）：

text

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

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

---

使用方式#

bash

python3 <skill_path>/scripts/bingo_email.py <command> [args...]

支持的全部命令#

初始化 & 测试 & 环境检查

bash

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）

读取类

bash

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

发送类

bash

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

回复功能说明：

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

草稿类

bash

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

管理类

bash

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

正文输入方式#

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

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

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

2. 管道传入： bash

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

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

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

---

输出格式#

操作输出格式说明list / unread表格ID / 标记(*=未读) / 主题(截断40字) / 发件人 / 日期read结构化文本From, To, Cc, Subject, Date, Message-ID + 正文folders列表文件夹名称 + flagssend/reply/forward/draft状态行✓ 操作结果错误以 错误: 开头后跟具体原因

---

与 himalaya 对比#

维度himalayabingo-email语言Rust CLIPython 脚本中文草稿quoted-printable → 乱码 ✗base64 → 正常 ✓126/163需编译自定义版本配置项一键切换配置TOML 文件TOML 文件（兼容格式）依赖单二进制imapclient (~1MB pip 包)可定制性需改源码重编译直接改 Python

---

安装 & 分享给他人#

方法一：作为 WorkBuddy Skill 安装#

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

bash

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

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

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

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

bash

# 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 即可一键诊断所有前置条件。

---

🔒 安全 & 开源分享#

已内置的安全措施#

措施实现方式文件权限 600save_config() 写入后自动 chmod 0o600，仅文件所有者可读写密码输入无回显init 命令使用 getpass.getpass() 终端不显示明文Git 防泄露.gitignore 已排除 config.toml 和 __pycache__/无硬编码凭据源代码中不含任何真实密码或 token

开源到 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： bash

   # 使用 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 特性）