Gmail 收件箱清零分类处理

借助 AI 驱动的邮件分类能力，轻松实现收件箱清零！通过 OAuth（无需密码）交互式处理 Gmail 收件箱中的全部邮件，并自动生成摘要、支持批量操作。

功能特性

✅ 基于 OAuth 认证 — 无需密码，通过 gog 安全完成身份验证
✅ AI 摘要 — 每封邮件生成一行简明摘要
✅ 批量处理 — 立即排队操作，最后统一执行
✅ Telegram 按钮操作 — 支持归档、创建过滤器、退订、查看原文
✅ 聚焦收件箱清零 — 处理所有收件箱邮件（已读 + 未读）
✅ 高效工作流 — 各操作之间无需等待

工作流程

1. 用户触发指令：“Triage my emails” 或 “Process my inbox”
2. 从 Gmail 获取全部收件箱邮件（每次最多 20 封）
3. 一次性展示所有邮件，每封邮件包含：
   • 主题与发件人
   • AI 生成的一行摘要
   • Telegram 内联按钮（用于执行各类操作）
4. 用户为每封邮件点击操作按钮（操作立即入队，暂不调用 API）
5. 用户点击 “Done” 按钮，批量执行所有已排队的操作
6. 重复上述流程，直至达成收件箱清零！ 🎯

前置条件

必需依赖： 已安装并完成认证的 gog CLI（需绑定 Gmail 账户）。

检查是否已配置：

gog auth list

若尚未配置，用户需运行 gog auth add（详见 gog skill 中关于 OAuth 的配置说明）。

设置密钥环（keyring）密码环境变量：

export GOG_KEYRING_PASSWORD="your-password"

Telegram 按钮布局

每封邮件下方显示 4 个操作按钮：

[📥 Archive] [🔍 Filter]
[🚫 Unsub]   [📧 View]

• 📥 Archive — 从收件箱移除，同时标记为已读
• 🔍 Filter — 为该发件人创建过滤器，自动归档后续来信
• 🚫 Unsubscribe — 查找并打开退订链接
• 📧 View — 展示邮件完整正文内容
• 不点击任何按钮 = 跳过（保留在收件箱中）

页面底部提供执行按钮：

[✅ Done - Execute All Actions]

操作队列系统

为规避 Telegram 64 字符回调数据长度限制，采用简短回调码表示操作：

• q:a:0 = 归档操作，对应消息索引 0
• q:f:0 = 创建过滤器操作，对应消息索引 0
• q:u:0 = 退订操作，对应消息索引 0
• q:v:0 = 查看全文操作，对应消息索引 0（立即执行）
• q:done = 批量执行所有已排队操作

队列由 scripts/queue_manager.py 管理，持久化存储于 action_queue.json 文件中。

脚本说明

gog_processor.py

主程序，通过 gog CLI 执行 Gmail 相关操作。

列出收件箱邮件：

python3 scripts/gog_processor.py list  [limit]

归档某封邮件：

python3 scripts/gog_processor.py archive  

查找退订链接：

python3 scripts/gog_processor.py unsubscribe  

创建过滤器：

python3 scripts/gog_processor.py filter  ""

获取邮件正文：

python3 scripts/gog_processor.py body  

queue_manager.py

管理操作队列，供批量执行使用。

向队列添加操作：

python3 scripts/queue_manager.py add   [from_header]

获取当前队列内容：

python3 scripts/queue_manager.py get

清空队列：

python3 scripts/queue_manager.py clear

execute_queue.py

批量执行所有已排队操作。

python3 scripts/execute_queue.py 

返回包含所有已执行操作结果的 JSON 数据。

实现步骤

1. 加载当前批次： 获取收件箱邮件并保存至 current_batch.json
2. 展示全部邮件： 逐封显示摘要及操作按钮
3. 处理按钮回调：
   • 归档 / 创建过滤器 / 退订：调用 queue_manager.py 加入队列
   • 查看：立即调用接口获取并展示完整邮件内容
   • 完成：调用 execute_queue.py 执行队列中全部操作
4. 展示执行结果： 报告本次归档数量与剩余收件箱邮件数
5. 按需继续处理： 获取下一批邮件，或庆祝收件箱清零成功

AI 摘要编写规范

生成简洁、准确的一行摘要：

• 账单 / 发票类： “$X 支付凭证。财务记录。”
• 安全提醒类： “[操作] 相关安全通知。[重要 / 常规] 提醒。”
• 新闻简报类： “关于 [主题] 的简报。无需操作。”
• 日历事件类： “日历 [事件类型]，时间：[日期/时间]。”
• 法律文书类： “[文件类型] 法律文件。[简要上下文]。”

保持语言简洁、事实准确、侧重可操作性。

安全说明

• OAuth 认证机制 — 不涉及密码，仅使用 gog 的 OAuth token
• Token 安全存储 — gog CLI 将 token 存储于系统密钥环（system keychain）中
• 最小权限原则 — gog 仅获得用户显式授权的读取与修改权限
• 本地临时队列 — 操作队列仅在本地临时存储，执行后即清除

错误处理

常见问题及解决方案：

• gog 未完成认证： 运行 gog auth add
• 账户不存在： 使用 gog auth list 查看已注册账户列表
• 收件箱无新邮件： 正常状态 — 收件箱清零已达成！
• 权限被拒绝： 用户可能需要重新通过 gog 完成认证
• 密钥环密码未设置： 请设置环境变量 GOG_KEYRING_PASSWORD

依赖项

• gog CLI — 必须已安装并完成认证（参见 gog skill 文档）
• Python 3 — 仅依赖标准库（subprocess、json、re、pathlib）

无需额外安装 pip 包。

最佳实践建议

• 定期处理： 每日进行一次分类，持续维持收件箱清零状态
• 善用过滤器： 对重复出现的简报和通知类邮件积极启用自动归档
• 激进归档： 若当前无需处理，即刻归档（仍可在“All Mail”中搜索）
• 批量模式高效： 10–20 封邮件可在一分钟内完成处理
• 信任 AI 摘要： 摘要内容准确，适用于快速决策