gmail-skill

📧 Gmail智能收件箱自动化管家

Gmail自动化管理工具,支持后台清理、标签归档与批量整理,配备双重确认机制,显著提升收件箱管理效率。

收藏
14.5k
安装
3.3k
版本
v1.2.0
CLS 安全性认证2026-05-02
点击查看完整报告 >

使用说明

核心用法

Gmail Skill 提供七项核心能力构建完整的邮件自动化工作流。收件箱摘要支持默认收件箱或全量未读查询,以TSV格式返回邮件元数据并智能分组展示;标签结构分析通过后台任务生成树状视图,展示层级关系与未读统计;垃圾与废纸篓清理采用后台守护进程执行,结合WhatsApp每30秒推送进度直至完成;邮件归档严格遵循"仅操作收件箱"原则,通过四步交互流程(搜索标签→列出邮件→确认移动→提供撤销)确保精准归档;标签删除旧邮件清理作为破坏性操作,强制要求用户输入DELETE确认,并区分"移至垃圾箱"与"永久删除"两种模式;全范围授权为可选步骤,一次性配置后即可启用永久删除能力。

显著优点

该技能采用后台任务架构,利用nohupdisown实现守护进程化,彻底规避AI助手超时中断风险,特别适合处理大批量邮件清理;渐进式权限设计体现安全最佳实践,默认仅申请gmail.modify范围(读取、修改、删除至垃圾箱),永久删除需额外运行授权脚本获取https://mail.google.com/权限,降低误操作不可逆风险;交互安全机制极为严格,所有批量移动、标签删除、日期筛选删除均需用户明确选择对象并输入确认指令,且支持撤销操作;可视化反馈通过WhatsApp推送实时进度,解决后台任务"黑盒"焦虑;参数验证覆盖日期格式、消息ID、标签存在性等边界条件,杜绝无效操作。

潜在缺点与局限性

依赖栈复杂,需预装gog CLI工具(npm)、Python 3、jq及Google API客户端库,增加了部署门槛;来源可信度限制,作为T3级个人开发者作品,虽通过A级安全认证,但仍需用户自行审查代码,不适合对供应链安全有极致要求的企业环境;交互模式局限,后台任务虽解决超时问题,但导致用户无法实时干预或查看中间结果,仅能通过WhatsApp接收异步通知;日期格式僵化,仅支持MM/DD/YYYY美式日期格式,对国际用户不够友好;平台锁定,仅支持Gmail,不兼容Outlook等其他邮件服务。

适合的目标群体

适用于Gmail重度依赖者(日均接收50+邮件的商务人士)、合规归档需求者(需定期清理历史邮件以满足GDPR或公司政策)、运营与客服团队(管理大量通知类邮件与工单标签)、个人数字整理爱好者(追求Inbox Zero效率方法论)。尤其适合需要定期执行重复性清理任务(如每周清理促销邮件、每月归档项目文件)的用户,通过后台自动化显著降低手动管理的时间成本。

使用风险

授权范围风险:全范围OAuth令牌存储于本地~/.gmail-skill/,虽采用标准文件权限保护,但仍需防范本地权限提升攻击;误操作残余风险:尽管有双重确认,用户仍可能在疲劳状态下确认删除重要邮件,且永久删除模式下无回收站恢复可能;依赖项失效风险gog工具为第三方npm包,若维护者停止更新或API变更,可能导致技能部分功能失效;后台任务隐蔽故障:若gmail-background-task.sh因系统资源不足崩溃,可能留下僵尸进程或状态不一致,需定期使用gmail-bg-status.sh检查;隐私侧信道:WhatsApp通知功能需配置WHATSAPP_NOTIFY_TARGET,若误配置可能导致邮件统计信息泄露至错误接收者。

安全解读

核心功能

Gmail Skill 是一套面向自动化邮件管理的工具集,通过 gog CLI 调用 Google Gmail API,提供七大核心能力:

1. 收件箱摘要(Capability 1):实时拉取收件箱或未读邮件列表,支持 TSV 格式输出与单条消息详情获取
2. 文件夹结构分析(Capability 2):后台任务生成标签层级树,展示各标签邮件总量与未读数

3. 垃圾/废纸篓清理(Capability 3):后台批量清空 spam 和 trash 文件夹,自动推送 WhatsApp 进度通知

4. 标签归档(Capability 4):交互式多步骤工作流,仅处理收件箱内邮件,需用户逐条确认后移动

5. 标签删除(Capability 5):支持仅删标签或连带删除邮件(转入垃圾箱),需用户键入 DELETE 确认

6. 按日期删除旧邮件(Capability 6):指定标签与截止日期批量清理,支持永久删除(需完整 OAuth 授权)

7. 完整权限授权(Capability 7):一次性配置 https://mail.google.com/ 范围,启用永久删除能力

显著优点

  • 后台任务守护:Capability 2/3/5/6 强制使用 gmail-background-task.sh 包装器,任务 daemon 化脱离终端超时限制,支持 30 秒间隔的 WhatsApp 进度推送
  • 多重确认机制:所有删除操作(标签、邮件)均需显式确认,标签删除要求输入 DELETE 全大写,降低误触风险
  • 最小权限原则:默认使用只读/标签管理范围,永久删除需用户主动授权完整范围,OAuth 令牌本地存储
  • 零第三方依赖:除 gog 工具外无外部依赖包,供应链攻击面极小,11 个文件全部为 Shell 脚本与文档
  • 严格模式编码:所有脚本启用 set -euo pipefail,包含完整输入验证与错误处理

潜在局限

  • 外部工具依赖:核心功能依赖未随包分发的 gog CLI 工具,用户需自行安装并配置 OAuth,工具本身的安全性无法由本 skill 保证(RISK-001)
  • 令牌文件风险:完整权限令牌存储于 ~/.gmail-skill/full-scope-token.json,若文件权限不当或被恶意程序读取,可导致 Gmail 账户完全失守(RISK-002)
  • 日期验证盲点:Capability 6 的 MM/DD/YYYY 格式依赖 Python 脚本验证,复杂日期边界(闰年、无效日期)可能存在验证盲点(RISK-003)
  • 日志脱敏不足:当前脚本出错时可能输出包含 GMAIL_ACCOUNT 的详细命令参数,存在敏感信息泄露至日志的风险

适合人群

  • 收件箱邮件量庞大、需要定期自动化清理的 Gmail 重度用户
  • 依赖标签系统进行邮件分类管理,需批量归档或整理标签结构的效率型用户
  • 能接受命令行交互、具备基础 OAuth 配置能力的进阶用户
  • 对后台异步任务有需求,希望大操作不被终端超时中断的场景

常规风险

  • OAuth 令牌泄露风险:本地存储的令牌文件若被窃取,攻击者可获得完整 Gmail 访问权限;建议定期检查 ~/.gmail-skill/ 目录权限(推荐 700),并每 90 天重新授权轮换令牌
  • 误删除风险:虽然有多重确认,但批量删除旧邮件(Capability 6)和标签删除(Capability 5)操作不可逆(永久删除模式下);建议在首次使用前验证备份策略
  • API 配额限制:高频自动化操作可能触发 Google API 速率限制,后台任务虽能缓解超时问题,但无法突破配额硬限制
  • 工具链完整性gog 工具的来源安全性直接影响本 skill 整体安全,建议从可信渠道获取并校验 SHA256 哈希

gmail-skill 内容

bins文件夹
手动下载zip · 18.6 kB
gmail-auth-full-scope.shtext/x-shellscript
请选择文件