gogcli 的 gog gmail history 命令:利用 Gmail History API 增量追踪邮件变更的完整指南

原创2026-09-16 23:22:051,365 阅读

gogcli 的 gog gmail history 命令:利用 Gmail History API 增量追踪邮件变更的完整指南

gog gmail history 是 gogcli(Google Workspace in your terminal)中面向 Gmail History API 的增量同步命令,它从指定的 historyId 开始拉取邮件变更记录,输出新增/变更的消息 ID 列表。本文基于 docs/commands/gog-gmail-history.md 命令参考,结合仓库源码与测试,完整讲解该命令的用法、全部参数语义、输出格式、分页机制与底层实现,帮助你在终端脚本、Agent 编排和增量备份场景中准确使用它。

命令定位:Gmail History API 的增量视图

Gmail 的 History API 记录的是邮箱在某一个 historyId 之后发生的变更(新邮件到达、标签变化、邮件删除等)。与全量搜索不同,增量 history 是构建"上次同步之后发生了什么"这类任务的基础:

  • 增量拉取新邮件 ID:拿到上轮的 historyId,用本命令得到自那之后新增的消息 ID,再配合 gog gmail get 拉取正文。
  • 轮询/监听:本命令在 internal/cmd/gmail.go 中被注册在 GmailCmd 的 Read 组,位于 gog gmail 根命令之下,命令注册代码为 History GmailHistoryCmd cmd:"" name:"history" group:"Read" help:"Gmail history"。
  • 触发后续动作:本命令解析出的 historyId 与 history 记录同样服务于仓库内的 Gmail watch 机制(见 internal/gmailwatch/history.go 中的 HistoryRecord、HistoryPage 等类型),是邮件变更事件流的基础数据结构。

命令本身只做"读"操作,属于只读命令族,因此在只读安全模式下(--readonly)也可安全使用。

基本用法与命令别名

gog gmail (mail,email) history [flags]

gog gmail 根命令定义了别名 mail 和 email(见 internal/cmd/root.go 中 Gmail GmailCmd cmd:"" aliases:"mail,email" help:"Gmail"),因此以下写法完全等价:

gog gmail history --since 12345
gog mail history --since 12345
gog email history --since 12345

最小可运行示例(必填 --since):

gog gmail history --since 12345

从源码看,GmailHistoryCmd 的结构体定义(internal/cmd/gmail_history.go)直接声明了本命令专属的 5 个参数:

type GmailHistoryCmd struct {
	Since     string `name:"since" help:"Start history ID"`
	Max       int64  `name:"max" aliases:"limit" help:"Max results" default:"100"`
	Page      string `name:"page" aliases:"cursor" help:"Page token"`
	All       bool   `name:"all" aliases:"all-pages,allpages" help:"Fetch all pages"`
	FailEmpty bool   `name:"fail-empty" aliases:"non-empty,require-results" help:"Exit with code 3 if no results"`
}

命令专属参数详解

Flag 类型 默认值 说明
--since string (必填) 起始 history ID,即 Gmail 侧的 StartHistoryId
--max
--limit
int64 100 单页最大结果数
--page
--cursor
string 分页 token,用于获取下一页
--all
--all-pages
--allpages
bool 自动抓取所有页
--fail-empty
--non-empty
--require-results
bool 无结果时以退出码 3 结束

--since:必填的起始 history ID

这是本命令唯一强制参数。执行顺序中会先校验它再发起任何 API 请求(internal/cmd/gmail_history.go):

if strings.TrimSpace(c.Since) == "" {
	return usage("--since is required")
}
startID, err := parseHistoryID(c.Since)
if err != nil {
	return usage(err.Error())
}

parseHistoryID 委托给 internal/gmailwatch/state.go 的 gmailwatch.ParseHistoryID:它先 strings.TrimSpace 去空白,空串直接返回 ErrHistoryIDRequired,随后用 strconv.ParseUint(raw, 10, 64) 解析为 uint64——因此 history ID 必须是纯十进制无符号整数。非法输入(如 nope)会返回 ErrInvalidHistoryID 包装的错误,测试 TestGmailHistoryCmd_InvalidSinceIsUsageError 验证了此时退出码为 2(usage error)且错误信息包含 invalid historyId "nope"。

--max / --limit:单页结果上限

默认 100,取值必须大于 0。运行前先调用 validateGmailMaxResults(internal/cmd/gmail_search_request.go):

func validateGmailMaxResults(maxResults int64) error {
	if maxResults <= 0 {
		return usage("--max must be > 0")
	}
	return nil
}

传入 MaxResults(c.Max) 会直接映射到 Gmail API 的 maxResults 请求参数。

--page / --cursor:手动翻页

当未使用 --all 时,命令只抓取当前页。若响应中存在 nextPageToken,文本输出末尾会打印提示(由 internal/cmd/output_helpers.go 的 printNextPageHintWithAll 生成):

# More results: use --all/--all-pages to fetch every page, or --page <token> for the next page

将提示中的 token 传给 --page 即可继续下一页:

gog gmail history --since 12345 --page "NEXT_PAGE_TOKEN"

--all:自动翻页抓全量

设置后,loadPagedItems 会走 collectAllPages 分支(internal/cmd/paged_list_helpers.go),持续请求直到 nextPageToken 为空。

--fail-empty:空结果时以退出码 3 结束

适合在脚本/CI 中判定"是否有新邮件"。底层实现在 internal/cmd/paging.go:

const emptyResultsExitCode = 3

func failEmptyExit(failEmpty bool) error {
	if !failEmpty {
		return nil
	}
	return &ExitError{Code: emptyResultsExitCode, Err: nil}
}

当 --fail-empty 开启且没有任何消息 ID 时,命令以退出码 3 结束;否则正常退出 0。

全局通用参数

以下为所有 gogcli 命令共有的参数,对本命令同样生效:

Flag 类型 默认值 说明
--access-token string 直接使用提供的 access token(绕过存储的 refresh token;token 约 1 小时过期)
-a
--account
--acct
string 账户邮箱、别名或 auto,用于认证的 Google API 命令
--client string OAuth client 名称(选择对应存储的凭据与 token 桶)
--color string auto 彩色输出:auto|always|never
--disable-commands string 逗号分隔的禁用命令列表,支持点路径
-n
--dry-run
--dryrun
--noop
--preview
bool 不实际变更,仅打印计划动作并成功退出
--enable-commands string 逗号分隔的启用命令前缀列表,支持点路径(限制 CLI)
--enable-commands-exact string 逗号分隔的精确启用命令列表;点路径下父命令不会启用子命令
--gmail-no-send bool false 阻止 Gmail 发送类操作(Agent 安全开关)
-h
--help
kong.helpFlag 显示上下文相关的帮助
--home string 覆盖 gogcli 配置/数据/状态/缓存根目录(等价于 GOG_HOME)
-j
--json
--machine
bool false 以 JSON 输出到 stdout(最适合脚本化处理)
--no-input
--non-interactive
--noninteractive
bool 从不提示,失败直接报错(适合 CI)
-p
--plain
--tsv
bool false 输出稳定、可解析的纯文本(TSV,无颜色)
--quota-project string 用于 API 计费的 Google Cloud 项目(发送 X-Goog-User-Project 头;部分 API 在 --access-token 或 ADC 下必需)
--readonly bool false 运行时阻止变更型 API 请求;auth add 也仅请求只读 OAuth scope
--results-only bool JSON 模式下仅输出主结果(丢弃 nextPageToken 等信封字段)
--select
--pick
--project
string JSON 模式下按逗号分隔选择字段(尽力而为,支持点路径)
-v
--verbose
bool 开启详细日志
--version kong.VersionFlag 打印版本并退出
--wrap-untrusted bool false JSON/raw 输出时,将抓取的文本字段包裹在外部不可信内容标记中

对脚本自动化而言,常用组合是 --json --since <id> --account <email>,配合 --results-only 可只得到消息 ID 数组。

输出格式与结果语义

文本模式(默认 / --plain)

默认输出两行结构:表头 MESSAGE_ID 加每行一个消息 ID;若没有任何结果则向 stderr 打印 No history(见 internal/cmd/gmail_history.go 与测试 TestGmailHistoryCmd_NoHistory):

MESSAGE_ID
m1
m2

--plain/--tsv 下同样稳定输出该表,便于 awk/cut 解析。

JSON 模式(--json)

输出固定信封结构:

{
  "historyId": "200",
  "messages": ["m1", "m2"],
  "nextPageToken": "npt"
}

字段含义:

  • historyId:本次请求响应中 Gmail 返回的最新 history ID(由 formatHistoryID 格式化,见 internal/gmailwatch/state.go,historyId 为 0 时输出空字符串),可用于下一次 --since 形成连续增量游标。
  • messages:收集到的消息 ID 列表。
  • nextPageToken:下一页 token,为空表示没有更多页。

TestGmailHistoryCmd_JSON 用 httptest.Server 模拟 Gmail API(响应含 history[].messagesAdded[].message.id、historyId: "200"、nextPageToken: "npt"),并断言 JSON 输出中的 historyId == "200"、messages == ["m1"]、nextPageToken == "npt",验证了信封结构与字段名的一致性。

底层实现:一次调用完整走查

GmailHistoryCmd.Run(internal/cmd/gmail_history.go)的执行顺序:

  1. validateGmailMaxResults(c.Max):校验 --max > 0。
  2. requireAccount(flags):解析账户参数,选择对应认证凭据。
  3. 校验 --since 非空并 parseHistoryID 解析为 uint64。
  4. gmailService(ctx, account) 构建 Gmail API 客户端。
  5. 分页 fetch 闭包构造 API 调用:
call := svc.Users.History.List("me").StartHistoryId(startID).MaxResults(c.Max)
call.HistoryTypes("messageAdded")
if strings.TrimSpace(pageToken) != "" {
	call = call.PageToken(pageToken)
}
resp, callErr := call.Context(ctx).Do()

注意两点实现细节:

  • 固定使用 HistoryTypes("messageAdded"),即只关心"消息新增"类型;这是与 gog gmail settings watch(其 --history-types 支持 messageAdded、messageDeleted、labelAdded、labelRemoved)的一个差异,历史命令当前专注于新增消息。
  • historyID = formatHistoryID(resp.HistoryId) 记录响应中的最新 historyId 供输出。
  1. 收集消息 ID:collectHistoryMessageIDs(resp) 委托给 internal/gmailwatch/history.go 的 gmailwatch.CollectHistoryMessageIDs,它对所有 history 记录做去重与"新增/删除抵消"处理:同一消息 ID 若先被加入 FetchIDs 后被标记删除,则从抓取列表移除并归入 DeletedIDs;不同记录类型的 ID 统一合并后紧凑化输出。

  2. loadPagedItems(c.Page, c.All, fetch) 处理分页,最后按文本/JSON 分支输出。

分页与防循环保护

loadPagedItems(internal/cmd/paged_list_helpers.go)在 --all 时调用 collectAllPages,进而走 internal/cmd/paging.go 的通用 collectPages:它以 10,000 页为上限防止无限循环,并通过 pageTokenGuard 追踪已见过的 page token,一旦出现重复 token 立即终止,避免 Gmail API 因异常返回同一 token 而导致的死循环。非 --all 时只调用一次 fetch(page) 返回单页。

典型使用场景:脚本化的增量同步

配合 JSON 输出与 shell 循环,可以构造"从上次游标开始增量拉取新邮件 ID"的管线:

# 用 jq 提取 messages 与最新 historyId,落盘为下次游标
gog gmail history --since "$LAST_HISTORY_ID" --json --account me@example.com \
  | tee /tmp/history.json
NEW_IDS=$(jq -r '.messages[]' /tmp/history.json)
echo "$(jq -r '.historyId' /tmp/history.json)" > /tmp/last_history_id

# 逐条拉取新邮件元数据
for id in $NEW_IDS; do
  gog gmail get "$id" --account me@example.com --json
done

在 CI 或定时任务中可用 --fail-empty 快速判断是否有新邮件,无结果即退出码 3:

if gog gmail history --since 12345 --fail-empty; then
  echo "有新增邮件"
else
  echo "无新增邮件(退出码 3)"
fi

边界情况与注意事项

  • --since 必须是十进制 uint64:传非法字符串会以 usage error(退出码 2)失败,且不会创建 Gmail 服务连接(测试 TestGmailHistoryCmd_InvalidSinceIsUsageError 用 t.Fatal("gmail service should not be created") 显式验证了这一点)。
  • historyId 会被 Gmail 侧滚动清理:Gmail 只保留有限窗口内的 history 数据,--since 指向过老的 ID 可能返回空或错误,长期任务建议定期做一次全量基线(如 gog gmail search)再继续增量。
  • --all 有 10,000 页上限保护:超大历史区间会被防循环保护拦截并报错,需要分多段游标推进。
  • 只返回新增消息 ID,不含正文:要获取内容需配合 gog gmail get 或 gog gmail raw 等命令。

总结

gog gmail history 通过 --since 建立增量游标,返回自该 historyId 以来的新增消息 ID 及最新 historyId,并以稳定文本或 JSON 信封输出,天然适合脚本与 Agent 构建"增量同步—拉取正文—推进游标"的邮件处理流水线。其参数校验、分页防循环、去重抵消等细节均在 internal/cmd/gmail_history.go 与 internal/gmailwatch/history.go 中有清晰实现,测试 internal/cmd/gmail_history_cmd_test.go 则对 JSON 输出、空结果与非法 --since 三种路径给出了可复现的验证样例。

延伸阅读:

登录后查看全文
gogcli