核心用法
Gmail Skill 是一套基于 gog CLI 工具的本地自动化方案，覆盖邮件管理的六大场景：
1. 收件箱摘要 — 实时拉取未读邮件，输出 TSV 格式（ID/THREAD/DATE/FROM/SUBJECT/LABELS），支持按发件人分组
2. 标签结构分析 — 生成层级化标签树，展示各标签的邮件总量与未读数
3. 垃圾/废纸篓清理 — 后台任务模式运行，通过 WhatsApp 每 30 秒推送进度，完成后报告实际清理数量
4. 邮件归档 — 严格限定从 INBOX 移出，多步骤交互式确认（搜索标签→列出邮件→用户勾选→执行移动→提供撤销）
5. 标签删除 — 区分「仅删标签」或「连带邮件」，需用户输入 DELETE 确认，后台执行
6. 按日期批量删除 — 需同时指定标签与日期，支持永久删除（需前置全范围 OAuth 授权）或移入废纸篓
7. 全范围授权 — 一次性配置 https://mail.google.com/ 权限，启用永久删除能力
显著优点
- 本地执行：依赖
gog二进制与 shell 脚本，无云端服务介入，数据不经过第三方服务器 - 后台任务保障：长时间操作（标签分析、批量清理）通过
gmail-background-task.sh守护进程化，避免代理超时，实时 WhatsApp 通知 - 操作可逆：归档操作内置
--undo支持，删除操作分阶段确认 - 精确权限控制：永久删除需单独 OAuth 授权，默认仅移入废纸篓，降低误操作风险
潜在缺点与局限性
- OAuth 依赖：所有功能需 Gmail API 授权，用户需完成浏览器 OAuth 流程
- 令牌持久化风险：全范围令牌存储于
~/.gmail-skill/full-scope-token.json，本地文件泄露可导致邮件永久删除 - 功能边界严格：归档操作强制限制在 INBOX，无法直接处理其他标签内的邮件
- 无图形界面：纯 CLI 交互，对非技术用户门槛较高
- WhatsApp 通知依赖：后台任务进度推送依赖外部通知渠道配置
适合人群
- 高频 Gmail 用户，收件箱邮件量 >1000，需自动化归档与清理
- 技术背景用户，习惯命令行工具与 OAuth 配置
- 对数据隐私敏感，希望邮件处理完全本地化
- 已配置 WhatsApp Bot 或类似通知渠道的用户
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 误删除 | 批量删除/标签操作不可逆 | 强制 DELETE 关键词确认、分步交互、默认移入废纸篓而非永久删除 |
| 令牌泄露 | `full-scope-token.json` 包含邮件完全控制权限 | 文件权限限制、存储于用户主目录、避免同步到云盘 |
| API 限流 | Gmail API 有每日配额限制 | 后台任务带指数退避，大操作建议分批执行 |
| 后台任务失败 | 守护进程异常退出导致状态丢失 | `gmail-bg-status.sh` 提供 `--failed` 与 `--running` 状态查询 |
安全等级说明
该 skill 执行本地脚本操作真实 Gmail 账户，具备读取、修改、删除邮件的能力。虽然设计有多重确认机制，但 OAuth 令牌本地存储与永久删除功能带来了实质性的账户风险。建议仅在受信任的单用户环境中运行。