gogcli 文档评论轮询指南用gog docs comments poll持久化监听 Google Docs 评论变化【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog docs comments poll是 gogcli 提供的持久化轮询命令用于持续监听 Google Docs 文档中新增或被修改的评论并把已处理进度watermark写入本地 JSON 状态文件从而做到断点续传、不重不漏。本文以该命令为主线完整讲解其用法、状态文件机制、输出格式、Shell Hook 事件回调与源码级实现原理帮助你在终端、CI 或自动化工作流中可靠地消费 Google Docs 评论流。命令概览与定位gog docs comments poll属于gog docs comments命令族负责Poll new and modified comments with persisted state轮询新增/修改的评论并持久化状态。它的核心价值在于Google Drive Comments API 只提供基于modifiedTime的时间过滤而不是真正的推送通道轮询命令通过本地状态文件记住上次看到哪里让每次轮询只产出真正的新事件即使进程重启也不会重复消费历史评论。gog docs (doc) comments poll --state-fileSTRING docId [flags]其中docId是位置参数接受 Google Doc ID 或完整文档 URL源码中通过normalizeGoogleID归一化见 internal/cmd/docs_comments_poll.go。--state-file为必填参数用于指定存储评论时间水印的 JSON 文件。该命令所属的命令族见 docs/commands/gog-docs-comments.md还包括gog docs comments add— 添加评论gog docs comments get— 按 ID 获取评论gog docs comments list— 列出文档评论gog docs comments locate— 将评论引用解析为 Docs API 索引区间gog docs comments reply— 回复评论gog docs comments resolve— 将评论标记为已解决gog docs comments reopen— 重新打开已解决的评论gog docs comments delete— 删除评论轮询命令与gog drive changes pollDrive 变更轮询共享同一套轮询基础设施两篇文章可对照阅读 docs/polling.md。命令级参数详解命令自身定义了 6 个业务参数源码见 internal/cmd/docs_comments_poll.go其余为 gogcli 全局通用参数。业务专属参数参数类型默认值说明docId位置参数string必填Google Doc ID 或 URL--state-filestring必填存储评论时间水印的 JSON 文件--intervaltime.Duration60s两次轮询之间的延迟--include-resolved别名--resolvedboolfalse是否包含已解决的评论--on-newstring空每条评论触发的本地 Shell 命令事件 JSON 通过 stdin 传入--max-iterationsint0轮询 N 次后停止0 表示持续运行直到被中断--max别名--limitint64100每页 API 最多获取的评论数参数校验规则源码约束从 internal/cmd/docs_comments_poll.go 可以看出以下硬性校验docId为空直接报错empty docId--interval必须大于 0否则报--interval must be greater than zero--max-iterations必须 0--max必须大于 0。此外--state-file缺失时会报missing --state-file路径会经过config.ExpandPath展开支持~等见 internal/cmd/poll_helpers.go。全局通用参数以下参数对所有 gogcli 命令生效轮询场景中尤其常用FlagTypeDefaultHelp--access-tokenstring直接使用提供的访问令牌绕过存储的刷新令牌令牌约 1 小时过期-a--account--acctstring认证 Google API 命令使用的账户邮箱、别名或 auto--clientstringOAuth 客户端名选择存储的凭证和令牌桶--colorstringauto颜色输出auto|always|never-n--dry-run--dryrun--noop--previewbool不做任何更改打印预期操作并成功退出-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-input--non-interactive--noninteractivebool永不提示失败即报错适合 CI-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的 TSV 文本--quota-projectstring用于结算 API 用量的 Google Cloud 项目作为 X-Goog-User-Project 发送--readonlyboolfalse运行时阻止变更类 API 请求auth add 也请求只读 OAuth 范围--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段支持点路径-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将获取的文本字段包裹在外部不可信内容标记中快速上手最小可用示例先进行一次最简单的轮询把评论事件以 JSON 形式输出gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --json命令启动后会立即轮询一次然后按--interval默认 60 秒周期性重复。首次运行时状态文件不存在命令会以当前 UTC 时间为初始 watermark 创建状态文件因此不会重放历史评论见 docs/polling.md。其他高频场景# 每 30 秒轮询一次 gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --interval 30s \ --json # 有界运行只轮询 3 次后退出适合 CI 与测试 gog docs comments poll docId \ --state-file comments.json \ --max-iterations 3 \ --json # 同时包含已解决的评论 gog docs comments poll docId \ --state-file comments.json \ --include-resolved \ --json终止方式SIGINTCtrlC与SIGTERM都会优雅停止轮询器已完成迭代的状态已经持久化重启后可无缝续跑源码通过signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)实现见 internal/cmd/poll_helpers.go。状态文件机制水印 已见 ID这是本命令最核心的机制。状态文件是一个本地 JSON 文件其结构定义在源码中见 internal/cmd/docs_comments_poll.go{ version: 1, doc_id: 1abc..., watermark: 2026-06-11T10:00:01Z, seen_ids: [c1, c2], include_resolved: false, updated_at: 2026-06-11T10:00:01Z }字段含义字段说明version状态文件格式版本当前为 1常量pollStateVersiondoc_id绑定的文档 ID防止状态文件被错误复用到其他文档watermark已处理到的评论modifiedTime时间戳RFC3339Nanoseen_ids在水印时间戳上已交付过的评论 ID 列表include_resolved生成状态时使用的--include-resolved设置updated_at状态文件最近更新时间为什么需要 seen_idsDrive Comments API 的时间过滤是闭区间inclusive语义startModifiedTime会包含该时间点上修改的评论。如果多条评论共享同一个modifiedTime仅靠单一 watermark 无法区分已交付与未交付。因此状态同时记录最新时间戳watermark在该时间戳上已经交付过的评论 IDseen_ids。这样同一时间点的新同伴仍会交付一次而不会把 watermark 推进过尚未见到的评论见 docs/polling.md 的 State 一节。状态文件的持久化约束从 internal/cmd/poll_helpers.go 可以看到状态写入的关键行为写入使用原子写config.WriteFileAtomic避免半写状态文件权限为0600只允许所有者读写测试TestDriveChangesPollPersistsFilteredBatch中对 0600 权限有明确断言目录不存在时自动以0700创建状态文件为空或不存在时视为全新开始不重放历史只有所有输出与 Hook 都成功之后才推进状态输出或 Hook 失败会返回错误并保留上一轮游标下一轮会重试该事件——因此消费者必须容忍重复交付见 docs/polling.md。状态文件绑定与冲突防护状态文件绑定到文档 ID若状态中的doc_id与命令行传入的docId不匹配命令直接报错poll state doc_id ... does not match docId ...状态文件也绑定--include-resolved设置两者不一致时报错Drive 评论轮询的状态按文档与--include-resolved设置隔离同一个状态文件只允许一个轮询器使用并发写入会互相覆盖游标想重新开始一个新的评论流删除状态文件或换一个新路径即可。输出格式TSV 与 NDJSON轮询器的输出行为由全局输出参数控制。默认/TSV 模式--plain/--tsv每条新评论输出一行制表符分隔文本格式见 internal/cmd/docs_comments_poll.gocomment commentId 作者显示名 评论内容 修改时间RFC3339Nano 是否已解决:true/false字段依次为comment固定标记、评论 ID、作者显示名、评论内容、修改时间RFC3339Nano、是否已解决。JSON 模式--json/--machinestdout 输出换行分隔的 JSONNDJSON每条评论一个对象结构为{kind:docs_comment,docId:1abc...,comment:{ ...drive.Comment 完整对象... }}字段定义见源码中的docsCommentPollEventinternal/cmd/docs_comments_poll.gokind固定为docs_commentdocId文档 IDcommentGoogle Drive API 的完整Comment对象包含 id、content、author、createdTime、modifiedTime、resolved、quotedFileContent、anchor 等字段。空轮询不产生任何 stdout。没有新评论时命令只是静默等待下一个周期。测试TestDocsCommentsPollPersistsWatermarkAndSeenIDs对 NDJSON 输出的每行都做了json.Valid校验见 internal/cmd/poll_test.go。Shell Hook用--on-new对接自动化--on-new是本命令的自动化核心为每一条新评论运行一个本地 Shell 命令事件 JSON 通过标准输入stdin传入。gog docs comments poll docId \ --state-file comments.json \ --on-new ./handle-commentHook 的安全模型Hook 是显式信任的本地命令Google 提供的内容绝不会被插值进命令字符串——事件 JSON 只通过 stdin 传递因此即使评论内容包含恶意 Shell 片段也无法注入命令Hook 通过平台 Shell 执行Linux/macOS 为/bin/sh -cWindows 为cmd.exe /D /S /C没有沙箱只应使用固定的、操作者控制的命令绝不能根据 Google 内容动态拼接命令见 docs/polling.md 与 internal/cmd/poll_helpers.goHook 的 stdout 与 stderr 都重定向到 gog 的 stderr保证事件 stdout 始终可解析。事件顺序与失败语义Docs 命令按modified-time 升序 评论 ID 顺序为每条评论调用一次--on-new--on-change是 Drive 命令对应物按批次调用Hook 串行执行状态只在输出与所有 Hook 全部成功之后才推进。任一 Hook 失败即返回错误并保留上一轮游标事件在下次运行时重试源码测试TestDocsCommentsPollHookFailureRetainsWatermark验证了这一点Hook 失败后 watermark 保持不变见 internal/cmd/poll_test.go。一个实用的 Hook 示例——把每条新评论追加到本地日志并推送通知gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --json \ --on-new ./handle-comment其中handle-comment脚本从 stdin 读取 NDJSON 事件并做业务处理如通知、归档、转发到聊天工具等。源码级运行流程结合 internal/cmd/docs_comments_poll.go 与 internal/cmd/poll_helpers.go一次轮询迭代的完整链路如下注册信号上下文pollSignalContext监听SIGINT/SIGTERM支持优雅退出参数归一化与校验normalizeGoogleID归一化 docIdexpandPollStatePath展开状态路径校验--interval、--max-iterations、--max的取值干跑支持--dry-run时打印预期操作文档 ID、状态路径、interval、include_resolved、max_iterations、max、是否配置 Hook后直接退出不产生任何 API 调用建立 Drive 服务requireDriveService获取已认证的 Drive API 客户端加载或初始化状态状态文件不存在时以当前 UTC 时间为初始 watermark 创建状态Version写入pollStateVersion拉取评论调用listDriveComments使用startModifiedTime state.Watermark的时间过滤、max分页、all全页拉取、includeResolved: true模式解决与否在本地二次过滤确保 watermark 也能越过被排除的已解决评论本地过滤与排序filterPolledDriveComments按 watermark seen_ids 去重并按时间、评论 ID 稳定排序已解决过滤未开启--include-resolved时filterPolledCommentsByResolved剔除Resolvedtrue的评论输出与 Hook逐条写出事件TSV 或 NDJSON并调用--on-newHook推进状态advanceDocsCommentsPollState更新 watermark 与 seen_ids原子写回状态文件循环等待--max-iterations 0且达到次数则正常退出否则waitForPollInterval睡眠--interval后进入下一轮可被信号/取消打断。从源码结构看轮询逻辑通过pollRuntimenow/runHook/wait三个可注入函数与底层解耦这也是测试能够用假时钟、假 Hook 完整验证状态推进的原因。测试验证状态机的可靠性保证仓库的 internal/cmd/poll_test.go 为评论轮询提供了系统性的回归测试可以作为理解行为的活文档测试验证点TestDocsCommentsPollPersistsWatermarkAndSeenIDs首轮拉取后 watermark 推进到最新修改时间seen_ids 正确记录NDJSON 每行合法TestDocsCommentsPollSkipsSeenAtInclusiveWatermark闭区间语义下跳过已交付 ID同一时间点的新评论仍交付TestDocsCommentsPollAdvancesPastExcludedResolvedComments被排除的已解决评论不输出、不触发 Hook但 watermark 仍越过它TestDocsCommentsPollHookFailureRetainsWatermarkHook 失败时 watermark 保持不变事件可重试TestWaitForPollIntervalCanceled等待周期可被取消支持优雅退出这些测试全部使用内存 HTTP 测试服务newDriveTestService模拟 Drive API无需真实网络与凭据即可运行。与gog drive changes poll的异同两者共享同一套轮询框架状态持久化、原子写、NDJSON 输出、Hook 机制但关注点不同维度docs comments polldrive changes poll监听对象单个文档的评论Drive 中的文件变更流状态核心watermark时间 seen_idsstart page tokenHook 触发粒度每条评论一次--on-new每个非空过滤批次一次--on-change状态绑定文档 ID --include-resolved--drive两者的通用规则包括状态文件0600权限原子写、空轮询不输出、Hook 失败不推进游标、消费者需容忍重复投递。详细对比见 docs/polling.md。适用场景与最佳实践典型场景评论流式消费把 Google Docs 上的评审意见实时转发到聊天工具、工单系统或日志定时巡检与cron或 systemd timer 配合用--max-iterations 1做单次快照或长时间驻留做连续监听自动化审阅工作流配合gog docs comments resolve、gog docs comments reply实现新评论 → 处理 → 回复/标记解决的闭环。最佳实践每个状态文件只运行一个轮询器避免并发覆盖游标把状态文件放在持久目录如~/.local/state/gog/让重启后无缝续跑如需重新开始监听删除状态文件或换新路径Hook 使用固定命令绝不使用 Google 内容拼接命令字符串业务消费者设计为幂等容忍重复交付批量处理、夜间作业可用--max-iterations N做有界运行避免进程无限驻留。相关命令文档gog docs comments、命令索引通用轮询机制见 docs/polling.md更多用法示例见 docs/examples.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gogcli 文档评论轮询指南：用 `gog docs comments poll` 持久化监听 Google Docs 评论变化
gogcli 文档评论轮询指南用gog docs comments poll持久化监听 Google Docs 评论变化【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog docs comments poll是 gogcli 提供的持久化轮询命令用于持续监听 Google Docs 文档中新增或被修改的评论并把已处理进度watermark写入本地 JSON 状态文件从而做到断点续传、不重不漏。本文以该命令为主线完整讲解其用法、状态文件机制、输出格式、Shell Hook 事件回调与源码级实现原理帮助你在终端、CI 或自动化工作流中可靠地消费 Google Docs 评论流。命令概览与定位gog docs comments poll属于gog docs comments命令族负责Poll new and modified comments with persisted state轮询新增/修改的评论并持久化状态。它的核心价值在于Google Drive Comments API 只提供基于modifiedTime的时间过滤而不是真正的推送通道轮询命令通过本地状态文件记住上次看到哪里让每次轮询只产出真正的新事件即使进程重启也不会重复消费历史评论。gog docs (doc) comments poll --state-fileSTRING docId [flags]其中docId是位置参数接受 Google Doc ID 或完整文档 URL源码中通过normalizeGoogleID归一化见 internal/cmd/docs_comments_poll.go。--state-file为必填参数用于指定存储评论时间水印的 JSON 文件。该命令所属的命令族见 docs/commands/gog-docs-comments.md还包括gog docs comments add— 添加评论gog docs comments get— 按 ID 获取评论gog docs comments list— 列出文档评论gog docs comments locate— 将评论引用解析为 Docs API 索引区间gog docs comments reply— 回复评论gog docs comments resolve— 将评论标记为已解决gog docs comments reopen— 重新打开已解决的评论gog docs comments delete— 删除评论轮询命令与gog drive changes pollDrive 变更轮询共享同一套轮询基础设施两篇文章可对照阅读 docs/polling.md。命令级参数详解命令自身定义了 6 个业务参数源码见 internal/cmd/docs_comments_poll.go其余为 gogcli 全局通用参数。业务专属参数参数类型默认值说明docId位置参数string必填Google Doc ID 或 URL--state-filestring必填存储评论时间水印的 JSON 文件--intervaltime.Duration60s两次轮询之间的延迟--include-resolved别名--resolvedboolfalse是否包含已解决的评论--on-newstring空每条评论触发的本地 Shell 命令事件 JSON 通过 stdin 传入--max-iterationsint0轮询 N 次后停止0 表示持续运行直到被中断--max别名--limitint64100每页 API 最多获取的评论数参数校验规则源码约束从 internal/cmd/docs_comments_poll.go 可以看出以下硬性校验docId为空直接报错empty docId--interval必须大于 0否则报--interval must be greater than zero--max-iterations必须 0--max必须大于 0。此外--state-file缺失时会报missing --state-file路径会经过config.ExpandPath展开支持~等见 internal/cmd/poll_helpers.go。全局通用参数以下参数对所有 gogcli 命令生效轮询场景中尤其常用FlagTypeDefaultHelp--access-tokenstring直接使用提供的访问令牌绕过存储的刷新令牌令牌约 1 小时过期-a--account--acctstring认证 Google API 命令使用的账户邮箱、别名或 auto--clientstringOAuth 客户端名选择存储的凭证和令牌桶--colorstringauto颜色输出auto|always|never-n--dry-run--dryrun--noop--previewbool不做任何更改打印预期操作并成功退出-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-input--non-interactive--noninteractivebool永不提示失败即报错适合 CI-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的 TSV 文本--quota-projectstring用于结算 API 用量的 Google Cloud 项目作为 X-Goog-User-Project 发送--readonlyboolfalse运行时阻止变更类 API 请求auth add 也请求只读 OAuth 范围--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段支持点路径-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将获取的文本字段包裹在外部不可信内容标记中快速上手最小可用示例先进行一次最简单的轮询把评论事件以 JSON 形式输出gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --json命令启动后会立即轮询一次然后按--interval默认 60 秒周期性重复。首次运行时状态文件不存在命令会以当前 UTC 时间为初始 watermark 创建状态文件因此不会重放历史评论见 docs/polling.md。其他高频场景# 每 30 秒轮询一次 gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --interval 30s \ --json # 有界运行只轮询 3 次后退出适合 CI 与测试 gog docs comments poll docId \ --state-file comments.json \ --max-iterations 3 \ --json # 同时包含已解决的评论 gog docs comments poll docId \ --state-file comments.json \ --include-resolved \ --json终止方式SIGINTCtrlC与SIGTERM都会优雅停止轮询器已完成迭代的状态已经持久化重启后可无缝续跑源码通过signal.NotifyContext(ctx, os.Interrupt, syscall.SIGTERM)实现见 internal/cmd/poll_helpers.go。状态文件机制水印 已见 ID这是本命令最核心的机制。状态文件是一个本地 JSON 文件其结构定义在源码中见 internal/cmd/docs_comments_poll.go{ version: 1, doc_id: 1abc..., watermark: 2026-06-11T10:00:01Z, seen_ids: [c1, c2], include_resolved: false, updated_at: 2026-06-11T10:00:01Z }字段含义字段说明version状态文件格式版本当前为 1常量pollStateVersiondoc_id绑定的文档 ID防止状态文件被错误复用到其他文档watermark已处理到的评论modifiedTime时间戳RFC3339Nanoseen_ids在水印时间戳上已交付过的评论 ID 列表include_resolved生成状态时使用的--include-resolved设置updated_at状态文件最近更新时间为什么需要 seen_idsDrive Comments API 的时间过滤是闭区间inclusive语义startModifiedTime会包含该时间点上修改的评论。如果多条评论共享同一个modifiedTime仅靠单一 watermark 无法区分已交付与未交付。因此状态同时记录最新时间戳watermark在该时间戳上已经交付过的评论 IDseen_ids。这样同一时间点的新同伴仍会交付一次而不会把 watermark 推进过尚未见到的评论见 docs/polling.md 的 State 一节。状态文件的持久化约束从 internal/cmd/poll_helpers.go 可以看到状态写入的关键行为写入使用原子写config.WriteFileAtomic避免半写状态文件权限为0600只允许所有者读写测试TestDriveChangesPollPersistsFilteredBatch中对 0600 权限有明确断言目录不存在时自动以0700创建状态文件为空或不存在时视为全新开始不重放历史只有所有输出与 Hook 都成功之后才推进状态输出或 Hook 失败会返回错误并保留上一轮游标下一轮会重试该事件——因此消费者必须容忍重复交付见 docs/polling.md。状态文件绑定与冲突防护状态文件绑定到文档 ID若状态中的doc_id与命令行传入的docId不匹配命令直接报错poll state doc_id ... does not match docId ...状态文件也绑定--include-resolved设置两者不一致时报错Drive 评论轮询的状态按文档与--include-resolved设置隔离同一个状态文件只允许一个轮询器使用并发写入会互相覆盖游标想重新开始一个新的评论流删除状态文件或换一个新路径即可。输出格式TSV 与 NDJSON轮询器的输出行为由全局输出参数控制。默认/TSV 模式--plain/--tsv每条新评论输出一行制表符分隔文本格式见 internal/cmd/docs_comments_poll.gocomment commentId 作者显示名 评论内容 修改时间RFC3339Nano 是否已解决:true/false字段依次为comment固定标记、评论 ID、作者显示名、评论内容、修改时间RFC3339Nano、是否已解决。JSON 模式--json/--machinestdout 输出换行分隔的 JSONNDJSON每条评论一个对象结构为{kind:docs_comment,docId:1abc...,comment:{ ...drive.Comment 完整对象... }}字段定义见源码中的docsCommentPollEventinternal/cmd/docs_comments_poll.gokind固定为docs_commentdocId文档 IDcommentGoogle Drive API 的完整Comment对象包含 id、content、author、createdTime、modifiedTime、resolved、quotedFileContent、anchor 等字段。空轮询不产生任何 stdout。没有新评论时命令只是静默等待下一个周期。测试TestDocsCommentsPollPersistsWatermarkAndSeenIDs对 NDJSON 输出的每行都做了json.Valid校验见 internal/cmd/poll_test.go。Shell Hook用--on-new对接自动化--on-new是本命令的自动化核心为每一条新评论运行一个本地 Shell 命令事件 JSON 通过标准输入stdin传入。gog docs comments poll docId \ --state-file comments.json \ --on-new ./handle-commentHook 的安全模型Hook 是显式信任的本地命令Google 提供的内容绝不会被插值进命令字符串——事件 JSON 只通过 stdin 传递因此即使评论内容包含恶意 Shell 片段也无法注入命令Hook 通过平台 Shell 执行Linux/macOS 为/bin/sh -cWindows 为cmd.exe /D /S /C没有沙箱只应使用固定的、操作者控制的命令绝不能根据 Google 内容动态拼接命令见 docs/polling.md 与 internal/cmd/poll_helpers.goHook 的 stdout 与 stderr 都重定向到 gog 的 stderr保证事件 stdout 始终可解析。事件顺序与失败语义Docs 命令按modified-time 升序 评论 ID 顺序为每条评论调用一次--on-new--on-change是 Drive 命令对应物按批次调用Hook 串行执行状态只在输出与所有 Hook 全部成功之后才推进。任一 Hook 失败即返回错误并保留上一轮游标事件在下次运行时重试源码测试TestDocsCommentsPollHookFailureRetainsWatermark验证了这一点Hook 失败后 watermark 保持不变见 internal/cmd/poll_test.go。一个实用的 Hook 示例——把每条新评论追加到本地日志并推送通知gog docs comments poll docId \ --state-file ~/.local/state/gog/doc-comments.json \ --json \ --on-new ./handle-comment其中handle-comment脚本从 stdin 读取 NDJSON 事件并做业务处理如通知、归档、转发到聊天工具等。源码级运行流程结合 internal/cmd/docs_comments_poll.go 与 internal/cmd/poll_helpers.go一次轮询迭代的完整链路如下注册信号上下文pollSignalContext监听SIGINT/SIGTERM支持优雅退出参数归一化与校验normalizeGoogleID归一化 docIdexpandPollStatePath展开状态路径校验--interval、--max-iterations、--max的取值干跑支持--dry-run时打印预期操作文档 ID、状态路径、interval、include_resolved、max_iterations、max、是否配置 Hook后直接退出不产生任何 API 调用建立 Drive 服务requireDriveService获取已认证的 Drive API 客户端加载或初始化状态状态文件不存在时以当前 UTC 时间为初始 watermark 创建状态Version写入pollStateVersion拉取评论调用listDriveComments使用startModifiedTime state.Watermark的时间过滤、max分页、all全页拉取、includeResolved: true模式解决与否在本地二次过滤确保 watermark 也能越过被排除的已解决评论本地过滤与排序filterPolledDriveComments按 watermark seen_ids 去重并按时间、评论 ID 稳定排序已解决过滤未开启--include-resolved时filterPolledCommentsByResolved剔除Resolvedtrue的评论输出与 Hook逐条写出事件TSV 或 NDJSON并调用--on-newHook推进状态advanceDocsCommentsPollState更新 watermark 与 seen_ids原子写回状态文件循环等待--max-iterations 0且达到次数则正常退出否则waitForPollInterval睡眠--interval后进入下一轮可被信号/取消打断。从源码结构看轮询逻辑通过pollRuntimenow/runHook/wait三个可注入函数与底层解耦这也是测试能够用假时钟、假 Hook 完整验证状态推进的原因。测试验证状态机的可靠性保证仓库的 internal/cmd/poll_test.go 为评论轮询提供了系统性的回归测试可以作为理解行为的活文档测试验证点TestDocsCommentsPollPersistsWatermarkAndSeenIDs首轮拉取后 watermark 推进到最新修改时间seen_ids 正确记录NDJSON 每行合法TestDocsCommentsPollSkipsSeenAtInclusiveWatermark闭区间语义下跳过已交付 ID同一时间点的新评论仍交付TestDocsCommentsPollAdvancesPastExcludedResolvedComments被排除的已解决评论不输出、不触发 Hook但 watermark 仍越过它TestDocsCommentsPollHookFailureRetainsWatermarkHook 失败时 watermark 保持不变事件可重试TestWaitForPollIntervalCanceled等待周期可被取消支持优雅退出这些测试全部使用内存 HTTP 测试服务newDriveTestService模拟 Drive API无需真实网络与凭据即可运行。与gog drive changes poll的异同两者共享同一套轮询框架状态持久化、原子写、NDJSON 输出、Hook 机制但关注点不同维度docs comments polldrive changes poll监听对象单个文档的评论Drive 中的文件变更流状态核心watermark时间 seen_idsstart page tokenHook 触发粒度每条评论一次--on-new每个非空过滤批次一次--on-change状态绑定文档 ID --include-resolved--drive两者的通用规则包括状态文件0600权限原子写、空轮询不输出、Hook 失败不推进游标、消费者需容忍重复投递。详细对比见 docs/polling.md。适用场景与最佳实践典型场景评论流式消费把 Google Docs 上的评审意见实时转发到聊天工具、工单系统或日志定时巡检与cron或 systemd timer 配合用--max-iterations 1做单次快照或长时间驻留做连续监听自动化审阅工作流配合gog docs comments resolve、gog docs comments reply实现新评论 → 处理 → 回复/标记解决的闭环。最佳实践每个状态文件只运行一个轮询器避免并发覆盖游标把状态文件放在持久目录如~/.local/state/gog/让重启后无缝续跑如需重新开始监听删除状态文件或换新路径Hook 使用固定命令绝不使用 Google 内容拼接命令字符串业务消费者设计为幂等容忍重复交付批量处理、夜间作业可用--max-iterations N做有界运行避免进程无限驻留。相关命令文档gog docs comments、命令索引通用轮询机制见 docs/polling.md更多用法示例见 docs/examples.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考