用途
gws-gmail-watch 是 gws-claude-plugin 提供的一个 Gmail 相关技能，用于监听新邮件，并将邮件以 NDJSON（每行一个 JSON 对象）的形式流式输出。它适合需要持续获取 Gmail 新邮件并进行后续处理的场景。
前置条件
使用前需阅读 ../gws-shared/SKILL.md，了解认证方式、全局参数和安全规则。如果该文件缺失，可运行 gws generate-skills 生成。
主要能力
- 监听新邮件并以 NDJSON 流式输出。
- 通过 Google Cloud Pub/Sub 接收 Gmail 推送：可指定 GCP 项目 ID，也可直接使用已有的 Pub/Sub 订阅或已授予 Gmail 推送权限的 Pub/Sub 主题。
- 按 Gmail 标签 ID 过滤，例如 INBOX、UNREAD，多个标签用逗号分隔。
- 控制拉取行为：设置每批最大消息数（默认 10）、拉取间隔秒数（默认 5）、消息格式（full、metadata、minimal、raw，默认 full）。
- 支持单次拉取后退出（--once）。
- 支持退出时清理所创建的 Pub/Sub 资源（--cleanup）。
- 支持将每封邮件写入指定目录下的独立 JSON 文件（--output-dir）。
使用方式
基本命令：
gws gmail +watch
可用参数：
- --project：用于 Pub/Sub 资源的 GCP 项目 ID。
- --subscription：已有的 Pub/Sub 订阅名称（跳过设置）。
- --topic：已有的、已授予 Gmail 推送权限的 Pub/Sub 主题。
- --label-ids：逗号分隔的 Gmail 标签 ID，用于过滤，例如 INBOX,UNREAD。
- --max-messages：每次拉取批次的最大消息数，默认 10。
- --poll-interval：两次拉取之间的秒数，默认 5。
- --msg-format：Gmail 消息格式，可选 full、metadata、minimal、raw，默认 full。
- --once：拉取一次后退出。
- --cleanup：退出时删除所创建的 Pub/Sub 资源。
- --output-dir：将每封邮件写入该目录下的独立 JSON 文件。
示例：
gws gmail +watch --project my-gcp-project gws gmail +watch --project my-project --label-ids INBOX --once gws gmail +watch --subscription projects/p/subscriptions/my-sub gws gmail +watch --project my-project --cleanup --output-dir ./emails
提示与限制
- Gmail watch 会在 7 天后过期，需要重新运行以续期。
- 如果不使用 --cleanup，Pub/Sub 资源会保留，便于重新连接。
- 按 Ctrl-C 可优雅停止。
相关技能
- gws-shared：全局参数与认证。
- gws-gmail：所有发送、读取和管理邮件的命令。