gogcli 的 gog gmail history 命令:利用 Gmail History API 增量追踪邮件变更的完整指南
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)的执行顺序:
validateGmailMaxResults(c.Max):校验--max > 0。requireAccount(flags):解析账户参数,选择对应认证凭据。- 校验
--since非空并parseHistoryID解析为 uint64。 gmailService(ctx, account)构建 Gmail API 客户端。- 分页 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 供输出。
-
收集消息 ID:
collectHistoryMessageIDs(resp)委托给 internal/gmailwatch/history.go 的gmailwatch.CollectHistoryMessageIDs,它对所有 history 记录做去重与"新增/删除抵消"处理:同一消息 ID 若先被加入FetchIDs后被标记删除,则从抓取列表移除并归入DeletedIDs;不同记录类型的 ID 统一合并后紧凑化输出。 -
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 三种路径给出了可复现的验证样例。
延伸阅读: