gogcli 的gog calendar calendars命令详解日历列表、分页机制与面向 Agent 的脚本化输出【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog calendar calendars是 gogcliGoogle Workspace 命令行工具中用于列出当前账户全部 Google Calendar 日历的命令。本篇以官方命令参考页 gog-calendar-calendars.md 为主体完整继承其命令用法与全部参数说明并结合 internal/cmd/calendar_list_cmds.go 等源码深入讲解该命令的分页实现、JSON/表格双模式输出、空结果退出码以及它与--readonly、--fail-empty等安全参数配合用于 CI 与 LLM Agent 场景的实战方式。命令定位与基本用法gog calendar calendars别名gog cal calendars的功能是List calendars——列出当前 Google 账户可见的所有日历主日历、二级日历、订阅的他人共享日历等。该命令在命令树中的注册位置见 internal/cmd/calendar.goCalendars CalendarCalendarsCmd cmd: name:calendars help:List calendars它隶属于gog calendar命令组完整命令组文档见 gog-calendar.md。基本用法gog calendar (cal) calendars [flags]典型调用示例# 默认列出最多 100 个日历表格形式 gog calendar calendars # JSON 输出适合脚本与 LLM 消费 gog calendar calendars --json # 拉取全部分页 gog calendar calendars --all # 无结果时以退出码 3 失败CI 断言 gog calendar calendars --fail-empty命令实现入口为CalendarCalendarsCmd.Runinternal/cmd/calendar_list_cmds.go执行流程为校验--max→ 解析账户requireAccount→ 构建 calendar API 服务calendarService→ 分页拉取CalendarListEntry→ 按输出模式写 JSON 或表格。命令专属 Flags 详解以下参数在CalendarCalendarsCmd结构体中定义internal/cmd/calendar_list_cmds.go是本文档参考页 Flags 表格中与本命令直接相关的部分FlagTypeDefaultHelp--max--limitint64100Max results--page--cursorstringPage token--all--all-pages--allpagesboolFetch all pages--fail-empty--non-empty--require-resultsboolExit with code 3 if no results逐项说明--max/--limit默认 100单次请求的最大条目数直接映射到 Google Calendar API 的maxResults。源码中先做合法性校验Max 0会直接返回usage(max must be 0)错误。测试用例 internal/cmd/calendar_max_validation_test.go 明确验证了Max: 0和Max: -1两种非法输入都会被拒绝。--page/--cursor传入上一页返回的nextPageToken从指定位置继续拉取。源码中先做strings.TrimSpace空串则不附加PageTokeninternal/cmd/calendar_list_cmds.go。--all/--all-pages/--allpages自动循环翻页直到nextPageToken为空返回全部日历。--fail-empty/--non-empty/--require-results结果为空时以退出码 3 退出。实现见 internal/cmd/paging.go定义了emptyResultsExitCode 3failEmptyExit在启用该标志且无结果时返回ExitError{Code: 3}未启用时正常返回nil。全局RootFlags 完整参考参考页中的完整 Flags 表还包含作用于所有 gog 命令的全局参数这里完整保留便于在脚本中直接复用FlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-y--force--assume-yes--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers其中与 Agent/CI 场景关系最密切的几个--readonly运行时阻断一切写操作本命令本身只读加上它可形成双重保险、--no-input禁止任何交互提示直接失败适合无人值守、--json与--results-only稳定机器可读输出、--wrap-untrusted把拉取到的文本字段包裹在“外部不可信内容”标记中降低提示注入风险。源码级实现剖析API 调用与分页闭环Run方法内部定义了一个fetch闭包封装单页请求internal/cmd/calendar_list_cmds.gofetch : func(pageToken string) ([]*calendar.CalendarListEntry, string, error) { call : svc.CalendarList.List().MaxResults(c.Max) if strings.TrimSpace(pageToken) ! { call call.PageToken(pageToken) } r, callErr : call.Do() if callErr ! nil { return nil, , callErr } return r.Items, r.NextPageToken, nil }可见--max逐字透传为MaxResults--page仅在非空时才附加PageToken。随后调用通用分页辅助函数loadPagedItems(c.Page, c.All, fetch)internal/cmd/paged_list_helpers.go未指定--all只执行一次fetch(page)返回当页数据与nextPageToken指定--all走collectAllPages循环调用 fetch 直到 token 为空。collectAllPages底层是带安全护栏的collectPagesinternal/cmd/paging.go以10000 页作为上限maxPages防止分页死循环超过上限返回pagination exceeded max pages错误通过pageTokenGuard追踪已见 page token对重复 token 提前报错避免 API 异常返回相同 token 导致的无限翻页每轮next均做TrimSpace空 token 即终止。这种“上限 已见 token 集合”的双重防护是 gogcli 所有分页列表命令共享的通用模式。双模式输出JSON 与表格输出逻辑internal/cmd/calendar_list_cmds.go分两支JSON 模式--jsonoutfmt.WriteJSON(ctx, stdoutWriter(ctx), map[string]any{ calendars: items, nextPageToken: nextPageToken, })稳定输出{calendars: [...], nextPageToken: ...}信封结构calendars为CalendarListEntry数组含id、summary、accessRole等字段nextPageToken供下一页续拉。配合--results-only可丢弃信封字段配合--select id,summary可按点路径挑选字段best-effort。表格模式默认outfmt.WriteTable(ctx, stdoutWriter(ctx), compactCalendarRows(items), calendarListColumns(), ) printNextPageHintWithAll(u, nextPageToken, --all/--all-pages)表格列定义在calendarListColumnsinternal/cmd/calendar_presentation.go中固定为三列Header来源字段IDentry.Id日历 ID如邮箱地址或长 IDNAMEentry.Summary显示名称ROLEentry.AccessRoleowner/reader 等访问角色compactCalendarRows会把空值行紧凑化减少表格视觉噪声。若仍存在下一页且未加--allprintNextPageHintWithAll会在输出末尾提示使用--all/--all-pages获取全量。空结果与退出码两种输出模式下items为空时行为一致JSON 模式正常写完 JSONcalendars为空数组后再判断表格模式向 stderr 打印No calendars若启用--fail-empty统一通过failEmptyExit(c.FailEmpty)以退出码 3失败internal/cmd/paging.go。这个设计让gog calendar calendars --json --fail-empty可以直接作为“该账户是否还有日历”的布尔断言用在 CI 或自动化脚本中。与其他 calendar 子命令的协作calendars列出的 ID 是其他gog calendar子命令的输入。从 internal/cmd/calendar.go 的命令注册可以看出典型协作链gog calendar calendars拿到 ID用该 ID 调用gog calendar acl calendarId查看共享权限、gog calendar events calendarId列事件、gog calendar freebusy查忙闲等管理类命令create-calendar/delete-calendar/subscribe/unsubscribe用于增删二级日历——例如subscribe命令的参数定义internal/cmd/calendar_list_cmds.go支持--color-id1-24、--hidden、--selected并带有-n/--dry-run预演保护。此外gog calendar alias子命令可以为长日历 ID 建立短别名便于在后续命令中直接以别名引用相关实现与测试见 internal/cmd/calendar_alias_resolution_test.go。Agent 与 CI 场景实战综合上述参数面向自动化与 LLM Agent 的推荐组合如下# 1. 全量列出日历的 ID 与角色JSON供程序解析 gog calendar calendars --all --json # 2. 只挑 ID 与名称字段级裁剪减少上下文体积 gog calendar calendars --json --select id,summary # 3. CI 中做断言无日历则失败退出码 3 gog calendar calendars --json --fail-empty # 4. 安全沙箱显式账号 只读 禁止交互 包裹不可信内容 gog calendar calendars -a myalias --readonly --no-input --wrap-untrusted --json要点回顾--all与--page二选一思路前者自动翻全量带 10000 页护栏后者手动续拉--max必须为正整数默认 100非法值0 或负数会被命令直接拒绝--fail-empty的退出码 3 与普通错误区分开方便脚本精确判断“结果为空”这一语义全局安全参数--readonly、--no-input、--wrap-untrusted使该命令可以被谨慎地纳入受限 Agent 的执行面结合仓库中--enable-commands/--disable-commands的点路径前缀机制见 safety-profiles/agent-safe.yaml 等安全档案还可以进一步收窄 CLI 可用命令集。参考索引资源路径命令参考页本文主体docs/commands/gog-calendar-calendars.mdcalendar 命令组文档docs/commands/gog-calendar.md命令总索引docs/commands/README.md命令结构与注册internal/cmd/calendar.go命令实现Calendars/Subscribe/ACLinternal/cmd/calendar_list_cmds.go表格列定义与行紧凑化internal/cmd/calendar_presentation.go分页与空结果退出码internal/cmd/paging.go分页辅助loadPagedItemsinternal/cmd/paged_list_helpers.gomax 参数校验测试internal/cmd/calendar_max_validation_test.goAgent 安全档案示例safety-profiles/agent-safe.yaml注意该参考页由gog schema --json自动生成页首注明 “Do not edit this page by hand; runmake docs-commands”因此其 Flags 表格与源码中的 kong 标签始终保持一致如命令行行为有出入以 internal/cmd/calendar_list_cmds.go 的实际实现为准。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考