Gmail 新邮件实时监控技能 — googleworkspace-gws-gmail-watch

技能简介

googleworkspace-gws-gmail-watch 是 Google Workspace 官方 CLI 仓库（googleworkspace/cli）出品的邮箱监控技能，面向 Claude、Codex、Claude Code 等 AI 编程代理。它解决的问题很具体：想让工作流"来一封新邮件就处理一封"，靠人手动刷邮箱既慢又漏。这个技能通过 Gmail watch + Google Cloud Pub/Sub 的组合，把新到邮件以 NDJSON 流的形式持续推送出来，让 AI 代理或脚本能像消费消息队列一样消费邮箱。它是 Google Workspace 官方技能族的一员（同族的表格命令助手已在站内收录），Skillstore 质量评分 80 分（silver 档），riskLevel 为 safe，MIT 许可，已完成安全审计，页面浏览 85 次、安装 8 次；版本 0.23.0，持续维护中。

核心能力

• 新邮件流式监听：启动 Gmail watch 后，把新到达的邮件以 NDJSON 格式逐条流出，天然适配管道处理。
• 双接入模式：既可以用指定的 Google Cloud 项目从零创建 Pub/Sub 资源，也可以复用已存在的订阅，适配不同团队的资源管理策略。
• 标签级过滤：按一个或多个 Gmail 标签 ID 过滤监听范围，只让关心的邮件进入流水线。
• 流量精细控制：拉取批次大小、轮询间隔、邮件格式（metadata / full 等）均可配置，避免把配额或带宽打满。
• 单次拉取模式：支持只拉一批就停，方便定时任务与集成测试，不必常驻监听进程。
• 落盘与清理：可以把每封邮件写成独立文件供归档审查，退出时可选择自动清理本次创建的 Pub/Sub 资源。

安装配置

1. 环境前置：安装 gws 命令行工具（Node.js 环境），并完成 Google 账号认证，确保 Gmail 与 Pub/Sub 权限可用。
2. 安装技能：执行 npx skillstore add googleworkspace/gws-gmail-watch，把技能写入本地 Agent 技能目录。
3. 云项目准备：准备一个 Google Cloud 项目用于创建 Pub/Sub 主题与订阅；若团队已有订阅，可直接记录订阅名待用。
4. 安全基线：为监听分配权限最小的服务账号，明确邮件输出目录并限制访问权限——完整邮件往往含敏感信息。

使用步骤

1. 发起监听：用"Watch New Gmail Messages"模板让 AI 基于已认证的 gws 环境启动监听，结果以 NDJSON 流返回。
2. 限定标签与批次：指定如 INBOX 等标签 ID、云项目 ID，设置批次大小与轮询间隔，先拉一批验证链路。
3. 接入处理流程：把流出的邮件交给下游工作流——AI 摘要、工单创建、自动归档等均可，技能本身只负责可靠地把邮件送出来。
4. 持久化归档（可选）：要求把每封邮件写入指定输出目录，形成可审查的留档。
5. 收尾清理：任务结束时启用清理选项，删除本次会话创建的 Pub/Sub 资源；若资源被其他流程共用则不要清理。
6. 定期续期：记住 Gmail watch 七天自动过期，长期监听任务需要按周期重新发起。

适用场景

• 运营收件箱自动化：把客服、销售共享邮箱的新邮件实时送入事件处理流水线。
• Gmail 自动化测试：单次拉取一批带标签的邮件，验证集成逻辑而不必常驻监听。
• 邮件归档留档：按标签把 incoming 邮件逐封落盘，满足审查与留存要求。
• AI 邮件助理后端：为"新邮件自动分类 / 起草回复"类 Agent 提供稳定的消息触发源。
• 告警邮件联动：让监控系统发出的告警邮件进入自动化处理链，缩短响应时间。

适用人群

• 后端与平台工程师：为团队构建基于邮件触发的自动化系统。
• 运维 / SRE：把告警邮箱接入值班处理流程。
• AI 工程师：为邮件类 Agent 应用寻找可靠的新邮件事件源。
• 无代码自动化团队的开发者：用官方技能替代脆弱的轮询脚本。
• Google Workspace 管理员：评估邮箱自动化的合规实现方式。

工作原理

技能围绕 Gmail API 的 watch 机制与 Google Cloud Pub/Sub 消息队列展开：启动 watch 后，Gmail 服务端会在新邮件到达时向 Pub/Sub 主题推送通知，技能负责配置这条链路并持续拉取消息，再把每条消息以 NDJSON（每行一个 JSON 对象）的形式输出给 AI 代理或脚本消费。NDJSON 流式设计让下游可以边接收边处理，无需等待批量结束。需要注意三条边界：Gmail watch 七天过期需续期；技能只搬运邮件、不理解也不回复邮件内容；Pub/Sub 资源默认在退出后保留，只有显式开启清理才会删除。这些限制都写进了技能的最佳实践与反模式清单，帮助使用者在自动化收益与资源安全之间做正确取舍。

官方链接

• Skillstore 详情页：
• GitHub 仓库：
• 一键安装：npx skillstore add googleworkspace/gws-gmail-watch
• Manifest：