gogcli Gmail settings watch：基于 Pub/Sub 的邮箱实时通知与 Webhook 转发完整指南

gogcli Gmail settings watch基于 Pub/Sub 的邮箱实时通知与 Webhook 转发完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog gmail settings watch是 gogcli 中负责 Gmail 邮箱变更实时感知的命令组它把 Gmail 的 Pub/Sub 通知新邮件、删除、标签变化转化为可投递到下游 Webhook 的结构化 payload支持 pushHTTP 服务端与 pull本地消费两种交付模式。本文覆盖该命令组的完整 CLI 面start/status/renew/stop/serve/pull、全部关键参数与默认值、持久化状态文件 schema、payload 结构以及错误处理与重投递语义并结合internal/gmailwatch与internal/cmd中的源码实现说明其底层机制读完即可搭建一条“邮件到达 → 唤醒 Agent”的自动化管道。命令组结构与命令别名该命令组的用法形如mail、email是gmail的别名gog gmail (mail,email) settings watch command它挂载在 gog gmail settings 之下共 6 个子命令源码中的定义见 GmailWatchCmd子命令别名作用gog gmail settings watch startbegin为 Pub/Sub 启动 Gmail watch注册 watch 并保存状态gog gmail settings watch statusls查看持久化的 watch 状态gog gmail settings watch renewupdate使用已保存的配置续期 watchgog gmail settings watch stoprm,delete停止 Gmail watch 并清除持久化状态gog gmail settings watch serve—运行 Pub/Sub push 处理器HTTP 服务端gog gmail settings watch pull—运行 Pub/Sub pull 消费者本地消费订阅子命令参考页分别为watch start、watch status、watch renew、watch stop、watch serve、watch pull。快速开始整体链路是GCP 中的 Pub/Sub topic 接收 Gmail 发出的 watch 通知 →gog进程push 或 pull 模式收到通知 → 回读 Gmail history 得到具体变更 → 按 hook 策略把 payload POST 到--hook-url。Pull 模式本地 Agent 首选Google 不需要能反向访问你的机器# 1) 在 GCP 项目中创建 topic 与 pull 订阅 # 2) 启动 watch gog gmail settings watch start \ --topic projects/project/topics/topic \ --label INBOX # 3) 运行 pull 消费者 gog gmail settings watch pull \ --subscription projects/project/subscriptions/subscription \ --hook-url http://127.0.0.1:18789/hooks/agentPush 模式你主动运维一个可达的 HTTPS 端点时# 1) 创建指向你的 serve 端点的 push 订阅 # 2) 启动 watch gog gmail settings watch start \ --topic projects/project/topics/topic \ --label INBOX # 3) 运行 HTTP 处理器 gog gmail settings watch serve \ --bind 127.0.0.1 \ --port 8788 \ --path /gmail-pubsub \ --token shared \ --hook-url http://127.0.0.1:18789/hooks/agentwatch start注册 watch 与核心参数start是唯一的“写注册”命令。其参数结构定义在 GmailWatchStartCmdFlag类型默认值说明--topicstring必填Pub/Sub topicprojects/.../topics/...--label[]string—要监听的标签 ID 或名称可重复、逗号分隔如INBOX--ttlstring—续期时长秒数或 Go duration如5s、3600--hook-urlstring—Webhook 转发地址--hook-tokenstring—Webhook bearer token--include-bodyboolfalse在 payload 中包含 text/plain 正文--max-bytesint20000包含正文时的最大字节数从 Run 方法 可以看到其执行链校验--topic非空 → 解析 TTL → 从 flags 组装 hook 配置 → 校验--dry-run只打印计划、不落盘→ 解析账号--account/--client选择已存储的 Gmail OAuth 账号→ 创建 Gmail 服务并解析标签名 → 调用 GmailwatchAPIrequestGmailWatch→ 用返回的historyId与过期时间构建状态buildWatchState→ 通过ApplyWatchRegistration原子地更新持久化状态。几个行为要点start会为账号保存{historyId, expirationMs, topic, labels}以及可选 hook 配置Gmail 对新注册的 watch 会立即发一条通知因此 start 之后不需要等待下次邮件变化即可触发一次通知若 watch 已过期renew会报错此时需重新执行start。持久化状态status 命令与状态文件 schema每个账号的 watch 状态保存在~/.config/gogcli/state/gmail-watch/account.json使用--home/GOG_HOME时根目录相应变化。状态结构定义在 Statev1 schema 示例{ account: yougmail.com, topic: projects/…/topics/…, labels: [INBOX], historyId: 12345, expirationMs: 1730000000000, providerExpirationMs: 1730000000000, renewAfterMs: 1730000001000, updatedAtMs: 1730000001000, authRecoveryPending: true, authFailureAtMs: 1730000001000, authFailureReason: reauthentication_required, hook: { url: http://127.0.0.1:18789/hooks/agent, token: ..., includeBody: false, maxBytes: 20000 } }status命令以只读、原子方式读取该状态不会创建状态目录或锁文件它还有一个专属 flag--show-secrets用于以明文显示 hook token 等机密值默认脱敏。status是排查auth_recovery_pending、auth_failure_at、auth_failure_reason等字段的主要入口。watch renew 与 watch stopgog gmail settings watch renew别名update复用已保存的 topic/labels 重新注册 watch可用--ttl调整续期时长。重认证后凭据过期恢复后应执行renew或重新start。gog gmail settings watch stop别名rm、delete调用 Gmail 的 stop watch 接口并清除本地状态。一个重要的恢复语义见 ApplyWatchRegistration如果状态中标记了authRecoveryPending凭据失效导致某次通知未能处理新的 watch 注册会保留上次处理到的 historyId而不是用新注册返回的游标覆盖。这样 Gmail 为新 watch 发出的立即通知就会从保留的游标位置追赶避免丢失恢复期间到达的邮件。成功处理一次 history 后AdvanceHistory 会清除恢复标记。watch servePub/Sub push 处理器serve在本地起一个 HTTP 服务接收 Pub/Sub push 通知。关键参数完整列表见 watch serve 参考页Flag默认值说明--bind127.0.0.1绑定地址--port8788监听端口--path/gmail-pubsubpush 处理器路径--token—共享 token校验x-gog-token头或?token开发用兜底--verify-oidcfalse校验 Pub/Sub 推送的 OIDC JWT--oidc-email—期望的服务账号邮箱--oidc-audience—期望的 OIDC audience--hook-url/--hook-token已存状态Webhook 转发地址与 bearer token--fetch-delay3s收到通知后延迟回读 Gmail history秒数或 duration规避索引竞态--include-bodyfalsepayload 包含 text/plain 正文--max-bytes20000正文字节硬上限--exclude-labelsSPAM,TRASH从 hook payload 中排除的标签 ID区分大小写的精确匹配置空字符串可禁用--history-typesmessageAdded通知类型白名单可重复/逗号分隔messageAdded,messageDeleted,labelAdded,labelRemoved至少一项非空--save-hookfalse把本次 hook 配置持久化到 watch 状态--dry-runfalse校验 flags 并打印不含机密的 listen/auth/hook 计划不创建客户端、不开 socket、不更新状态鉴权上push 模式推荐配置 Pub/Sub 的 OIDC JWT服务账号签名配合--verify-oidc --oidc-email --oidc-audience校验共享 token 头/查询参数仅作为开发环境的兜底。另外serve在处理入站请求时会保留所选 OAuth client 与直接传入的--access-token或GOG_ACCESS_TOKEN——直连 token 模式不依赖已存储的刷新 token但 token 是静态的、会正常过期过期后需重启服务换新 token。watch pullPub/Sub pull 消费者pull模式不暴露任何入站 HTTP 端点本地gog进程主动从订阅中拉取消息是本地 Agent 的推荐形态。专属参数完整列表见 watch pull 参考页Flag默认值说明--subscription必填Pub/Sub pull 订阅projects/.../subscriptions/...--hook-url/--hook-token已存状态Webhook 转发地址与 bearer token--fetch-delay3s收到通知后延迟回读 Gmail history--include-body/--max-bytes/--exclude-labels/--history-types/--save-hook同 serve与 serve 完全相同的下游 hook 投递策略pull 模式的鉴权分两层容易混淆需分别配置Gmail history 读取针对被监听账号使用--account/--client选中的常规已存储 Gmail OAuth 账号Pub/Sub 订阅消费走 Google Cloud 客户端库的凭据链如 Application Default Credentials 或GOOGLE_APPLICATION_CREDENTIALS指定的服务账号而不是已存储的 Gmail OAuth token。最小权限的常见做法是给该订阅授予roles/pubsub.subscriber。下游 hook token 只作用于gog到--hook-url的本地调用与上述两层都无关。Hook payload 结构两种模式共享同一下游 payload 格式{ source: gmail, account: yougmail.com, historyId: ..., deletedMessageIds: [...], messages: [ { id: ..., threadId: ..., from: ..., to: ..., subject: ..., date: ..., snippet: ..., body: ..., bodyTruncated: true, labels: [INBOX] } ] }正文策略默认只含头部 snippet--include-body开启后附带第一个匹配的 text/plain 部分--max-bytes是硬上限默认 20000超限时截断并置bodyTruncatedtrue。错误处理与可靠重投递语义这是该命令组在可靠性上最值得关注的部分行为定义见 docs/watch.md陈旧 historyId回退到messages.list最近 N 条并重置 historyIdwatch 过期watch renew会报错需重新watch start毒消息pull 模式把无法解析的 Pub/Sub 消息记为 poison message——记录日志后 ack而不是无限重投账号不匹配的通知在 push/pull 两种模式下都是终态凭据失效invalid_grant对当前通知是终态但只有先把“恢复待定”标记持久化后才会 ack且不推进存储的 history 游标——避免 Pub/Sub 重投风暴同时保住追赶位置。若标记无法保存通知保持可重试。重新认证后执行gog gmail settings watch renew或重跑start成功注册会保留上次游标Gmail 的立即通知即从该游标追赶。用watch status可检查auth_recovery_pending等字段hook 失败可重试gog记录 hook 失败状态、保留 hook 前的游标并向 Pub/Sub 返回投递失败push 返回非 2xxpull nack 消息使 Pub/Sub 在下游恢复后重投同一通知。这意味着hook 接收方必须幂等——同一 Gmail history 通知可能被调用多次容量边界该重投策略面向常规邮件通知量若需处理很高邮件速率例如每分钟 1000 封应自建监控、告警、积压与死信/背压策略而不是把默认 watcher 当作完整队列平台。通用 Flags作为生成的命令参考页gog gmail settings watch 还列出了该命令组共享的根级 flags常用的包括Flag类型默认说明-a/--account/--acctstring—账号邮箱、别名或 auto--clientstring—OAuth client 名称选择已存储凭据 token 桶--access-tokenstring—直接使用提供的 access token绕过已存 refresh token约 1 小时过期--quota-projectstring—API 计费项目作为 X-Goog-User-Project 发送-n/--dry-runbool—不产生变更仅打印计划-y/--force/--yesbool—破坏性命令跳过确认--readonlyboolfalse运行时阻断变更类 API 请求--gmail-no-sendboolfalse阻断 Gmail 发送操作Agent 安全开关-j/--jsonboolfalseJSON 输出适合脚本-p/--plain/--tsvboolfalse稳定可解析的 TSV 文本输出--results-onlybool—JSON 模式仅输出主结果--select/--pickstring—JSON 模式下按逗号分隔字段挑选支持点路径--homestring—覆盖 gogcli 配置/数据/状态/缓存根目录等价GOG_HOME--no-input/--non-interactivebool—从不交互失败即退出适合 CI-v/--verbosebool—详细日志--colorstringauto颜色输出auto|always|never--enable-commands/--disable-commandsstring—按点路径启停命令子集--wrap-untrustedboolfalseJSON/raw 输出中用不可信内容标记包裹抓取到的文本字段实现入口小结关注点位置6 个子命令的注册与别名internal/cmd/gmail_watch_cmds.go#L29-L36start的执行链解析→注册→落盘internal/cmd/gmail_watch_cmds.go#L48-L111状态 schema 与游标/恢复标记推进逻辑internal/gmailwatch/state.go#L24-L125historyId 陈旧判定与比较internal/gmailwatch/state.go#L66-L98push 处理器、hook 投递等其余实现internal/cmd/gmail_watch_pull.go、internal/gmailwatch/行为与错误处理说明文档docs/watch.md综上gog gmail settings watch用 6 个子命令覆盖了 watch 生命周期start/status/renew/stop与两种交付模式serve/pull并以持久化状态文件作为游标与恢复标记的单一事实来源结合 pull 模式的默认排除标签、fetch-delay、history-types 白名单与幂等 hook 契约可以把它直接用作邮箱事件驱动的本地 Agent 唤醒网关。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考