核心功能
gws-gmail-watch 是 gws 工具集中专门用于实时监控 Gmail 收件箱的命令行技能。它通过 Google Cloud Pub/Sub 建立持久化推送通道，将新邮件以 NDJSON（Newline Delimited JSON）格式实时流式输出，便于与数据处理管道、自动化工作流或监控告警系统集成。
显著优点
- 实时推送机制：基于 GCP Pub/Sub 而非轮询，延迟低、可靠性高
- 灵活过滤：支持通过 Gmail 标签 ID（如 INBOX、UNREAD）精准筛选关注邮件
- 多种输出模式：支持 STDOUT 流式输出、批量拉取（--once）、文件持久化（--output-dir）
- 资源管理友好：--cleanup 自动清理临时 Pub/Sub 资源，避免遗留费用
- 可配置消息格式：full/metadata/minimal/raw 四种格式适配不同场景
潜在局限
- 基础设施依赖：必须拥有 GCP 项目并正确配置 Pub/Sub 权限，门槛较高
- 有效期限制：Gmail 推送授权 7 天过期，需定期重新运行续期
- 云端成本：Pub/Sub 资源持续运行可能产生少量 GCP 费用
- 权限复杂度：需同时配置 Gmail API 和 GCP IAM 权限，调试链路较长
适合人群
- 运维工程师构建邮件驱动的自动化流水线
- 安全团队搭建邮件告警实时分析系统
- 开发者集成 Gmail 数据到 ETL/数据仓库流程
- 需要替代 IMAP 轮询的高可靠性场景
常规风险
- 资源泄露风险：未使用 --cleanup 时，Pub/Sub topic/subscription 会持续计费
- 授权过期导致漏报：7 天有效期若未续期，新邮件无法推送
- 数据暴露风险：--output-dir 写入的 JSON 文件需确保目录权限受控
- API 配额限制：高频拉取可能触及 Gmail API 或 Pub/Sub 配额