gogcli gog calendar create-calendar在终端创建 Google Calendar 辅助日历的完整指南与源码解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文基于 gogcliGoogle Workspace in your terminal仓库中 gog-calendar-create-calendar.md 命令参考页展开完整覆盖gog calendar create-calendar的用法、全部命令行参数、输出格式与 dry-run 行为并结合 internal/cmd/calendar_create_calendar.go 源码与测试用例剖析其参数校验、时区校验、账户解析和 Google Calendar API v3 调用链读完后可在脚本、CI 或 Agent 工作流中可靠地创建、预览和验证新的 Google 辅助日历。1. 命令定位与基本用法gog calendar create-calendar用于在当前认证账户下创建一个全新的二级日历secondary calendar对应 Google Calendar API v3 的POST /calendars即Calendars.Insert。它与创建单个日程事件的gog calendar create见 gog-calendar.md 子命令列表不同前者操作日历资源本身后者操作日历内的事件。完整用法如下来自命令参考页 docs/commands/gog-calendar-create-calendar.mdgog calendar (cal) create-calendar (new-calendar) summary [flags]要点说明父命令为gog calendar带别名calcreate-calendar本身带别名new-calendar在源码 internal/cmd/calendar.go 中声明CreateCalendar CalendarCreateCalendarCmd cmd: name:create-calendar aliases:new-calendar help:Create a new secondary calendarsummary是必传的位置参数作为日历显示名称若传入空值含纯空格命令会返回用法错误并以退出码 2 终止见 internal/cmd/usage.gousage()返回ExitError{Code: 2}。2. 参数总览2.1 核心业务参数命令结构体定义于 internal/cmd/calendar_create_calendar.gotype CalendarCreateCalendarCmd struct { Summary string arg: name:summary help:Calendar display name Description string name:description help:Calendar description TimeZone string name:timezone aliases:tz help:IANA timezone (e.g., America/New_York) Location string name:location help:Calendar location }参数类型默认值说明summarystring位置参数必填日历显示名称源码中会先strings.TrimSpace再判空--descriptionstring空日历描述--timezone/--tzstring空交由 Google 端使用账户默认时区IANA 时区名如America/New_York客户端本地先行校验非法值直接报错退出码 2不会发起 API 请求--locationstring空日历位置2.2 全局 Flags继承自 gogcli 根命令命令参考页完整列出的全局参数如下适用于本命令也适用于大多数 gogcli 写操作命令Flag类型默认说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring账户邮箱、别名或auto用于需要认证的 Google API 命令--clientstringOAuth 客户端名选择对应存储的凭据 token 桶--colorstringauto颜色输出auto|always|never--disable-commandsstring禁用命令的逗号分隔列表支持点分路径-n/--dry-run/--dryrun/--noop/--previewbool不执行变更打印计划中的操作并成功退出--enable-commandsstring启用命令前缀的逗号分隔列表支持点分路径用于收窄 CLI 能力--enable-commands-exactstring启用命令的精确匹配列表父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--gmail-no-sendboolfalse阻止 Gmail 发送类操作Agent 安全-h/--helpkong.helpFlag显示上下文帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本消费--no-input/--non-interactive/--noninteractivebool从不提示遇到需要交互时直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 文本无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目以X-Goog-User-Project发送部分 API 在使用--access-token或 ADC 时必填--readonlyboolfalse运行时拦截所有变更类 API 请求auth add也会改为请求只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等包裹字段--select/--pick/--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点分路径-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将拉取的文本字段包裹在外部不可信内容标记内3. 实战示例# 1) 基础用法创建一个名为 Team Calendar 的日历 gog calendar create-calendar Team Calendar # 2) 指定描述、时区与位置 gog calendar create-calendar Sprint Planning \ --description Weekly sprint planning calendar \ --timezone Asia/Shanghai \ --location HQ # 3) dry-run只打印将要发送的请求不接触认证、不发起 API 调用 gog calendar create-calendar Dry Run --timezone UTC --dry-run # 4) JSON 输出便于脚本/Agent 解析 gog calendar create-calendar Team Calendar -j # {calendar:{id:...,summary:Team Calendar,...}} # 5) 多账户场景用别名指定账户或临时使用 access token gog calendar create-calendar Ops Calendar -a my-alias gog calendar create-calendar Ops Calendar --access-token $TOKEN --quota-project my-project # 6) CI 场景不交互 机器可读输出 gog calendar create-calendar CI Calendar --no-input --plaindry-run 模式在 JSON 输出下形如由 internal/cmd/dryrun.go 生成{ dry_run: true, op: calendar.create-calendar, request: { calendar: { summary: Dry Run, timeZone: UTC } } }4. 源码级执行流程剖析Run方法internal/cmd/calendar_create_calendar.go#L21-L77的执行顺序非常清晰可以分为五个阶段4.1 参数清洗与必填校验summary : strings.TrimSpace(c.Summary) if summary { return usage(required: calendar name (positional argument)) }四个字段summary/description/timezone/location在构造calendar.Calendar请求体前都会先做TrimSpace避免把纯空格当作有效值传给 API。4.2 客户端时区预校验if cal.TimeZone ! { if _, tzErr : loadTimezoneLocation(cal.TimeZone); tzErr ! nil { return usagef(invalid timezone %q: %v, cal.TimeZone, tzErr) } }loadTimezoneLocationinternal/cmd/timezone.go#L87-L89内部就是time.LoadLocation即基于系统/嵌入的 tzdata 校验 IANA 时区名。这意味着传入--timezone Nope/Zone这类非法值时命令在本地就失败返回invalid timezone Nope/Zone: ...错误并以退出码 2 退出不会创建 Calendar 服务、更不会发起任何网络请求时区留空时不做校验请求体中timeZone为空串由 Google 端按账户默认时区处理该命令只对显式传入的 flag 值做严格校验。仓库中还存在更完整的时区解析链flag →GOG_TIMEZONE环境变量 → 配置项default_timezone见 internal/cmd/timezone.go#L40-L70但create-calendar走的是显式 flag 校验路径行为更确定、更适合脚本。4.3 dry-run 提前退出if dryRunErr : dryRunExit(ctx, flags, calendar.create-calendar, map[string]any{ calendar: cal, }); dryRunErr ! nil { return dryRunErr }dryRunExitinternal/cmd/dryrun.go#L12-L53在--dry-run时按当前输出模式分三路输出JSON 的{dry_run, op, request}、plain 的 TSV 三行、人类可读文本然后返回退出码 0 的ExitError。其注释明确说明设计意图“在触碰 auth/keyring 或发起 API 调用之前尽早调用”——也就是说 dry-run 连凭据读取都会跳过。测试用例 TestCalendarCreateCalendarCmd_DryRunDoesNotOpenService 用了一个会t.Fatal的 service 工厂来严格证明 dry-run 路径绝不会构造 calendar 服务。4.4 账户解析与服务构造dry-run 之后才进入认证路径account, err : requireAccount(flags) svc, err : calendarService(ctx, account)requireAccountinternal/cmd/account.go#L20-L38 起支持多种认证形态ADC应用默认凭据/服务账号模式下无需用户邮箱常规模式按--account邮箱、别名或auto→ 配置 →--access-token→ 本地已存账户的顺序解析calendarServiceinternal/cmd/runtime_services.go#L217-L223从运行时服务注册表取出按账户惰性构造的calendar.Service测试环境下可被替换为 mock HTTP 服务本命令的单测正是这样做的。4.5 发起 API 调用并格式化输出created, err : svc.Calendars.Insert(cal).Context(ctx).Do()调用即 Google Calendar API v3 的POST /calendar/v3/calendars。单测 TestCalendarCreateCalendarCmd_RunJSON 中的 mock server 精确匹配POST /calendar/v3/calendars并回显请求体验证了四个字段summary/description/timeZone/location都原样进入请求。输出分两种模式JSON 模式-j输出{calendar: 完整 Calendar 资源}由 internal/cmd/calendar_create_calendar.go#L61-L63 决定文本/TSV 模式逐行输出id、summary以及仅当非空时的timezone、description、locationinternal/cmd/calendar_create_calendar.go#L65-L76例如id createdexample.com summary Team Calendar timezone UTC location Remote该行为由 TestCalendarCreateCalendarCmd_RunTextIncludesLocation 断言保证。此外仓库的端到端 dry-run 测试 internal/cmd/dryrun_e2e_test.go#L314-L316 也收录了calendar create-calendar场景确保该命令纳入全仓库统一的 dry-run 契约op 名为calendar.create-calendar退出码 0。5. 安全与 Agent 使用建议从源码结构看create-calendar属于“写操作”因此可叠加多层防护--dry-run/--preview先确认请求内容再执行且完全不触碰凭据--readonly运行时拦截所有变更类 API 请求适合只读审查会话--enable-commands/--enable-commands-exact可为 Agent 会话显式收窄可用命令集--no-inputCI 中避免意外交互挂起--wrap-untrustedJSON 输出中的外部文本字段会被不可信内容标记包裹降低 prompt 注入面。6. 生命周期配套命令create-calendar不是孤立命令它通常与同族日历资源命令配合使用均可在 docs/commands/gog-calendar.md 的子命令列表中查到场景命令参考页创建辅助日历gog calendar create-calendar本页删除自己拥有的辅助日历gog calendar delete-calendargog-calendar-delete-calendar.md列出日历验证创建结果gog calendar calendarsgog-calendar-calendars.md把日历加入/移出日历列表gog calendar subscribe/gog calendar unsubscribegog-calendar-subscribe.md7. 小结与依据索引命令参考页参数表与用法来源docs/commands/gog-calendar-create-calendar.md由gog schema --json生成、make docs-commands维护命令实现internal/cmd/calendar_create_calendar.go字段定义、时区预校验、dry-run、Insert 调用、双格式输出单元与契约测试internal/cmd/calendar_create_calendar_test.goJSON 请求回显、TSV 输出、dry-run 不建服务、非法时区退出码 2与 internal/cmd/dryrun_e2e_test.go通用机制dry-run 输出格式见 internal/cmd/dryrun.go退出码 2 的用法错误见 internal/cmd/usage.go账户解析见 internal/cmd/account.go时区工具见 internal/cmd/timezone.go服务构造见 internal/cmd/runtime_services.go。掌握以上内容后你可以在终端、脚本或 Agent 工作流中安全地创建 Google 辅助日历先用--dry-run预览请求体再用-j拿到calendar.id作为后续create、subscribe、delete-calendar等操作的日历标识。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
gogcli gog calendar create-calendar：在终端创建 Google Calendar 辅助日历的完整指南与源码解析
gogcli gog calendar create-calendar在终端创建 Google Calendar 辅助日历的完整指南与源码解析【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文基于 gogcliGoogle Workspace in your terminal仓库中 gog-calendar-create-calendar.md 命令参考页展开完整覆盖gog calendar create-calendar的用法、全部命令行参数、输出格式与 dry-run 行为并结合 internal/cmd/calendar_create_calendar.go 源码与测试用例剖析其参数校验、时区校验、账户解析和 Google Calendar API v3 调用链读完后可在脚本、CI 或 Agent 工作流中可靠地创建、预览和验证新的 Google 辅助日历。1. 命令定位与基本用法gog calendar create-calendar用于在当前认证账户下创建一个全新的二级日历secondary calendar对应 Google Calendar API v3 的POST /calendars即Calendars.Insert。它与创建单个日程事件的gog calendar create见 gog-calendar.md 子命令列表不同前者操作日历资源本身后者操作日历内的事件。完整用法如下来自命令参考页 docs/commands/gog-calendar-create-calendar.mdgog calendar (cal) create-calendar (new-calendar) summary [flags]要点说明父命令为gog calendar带别名calcreate-calendar本身带别名new-calendar在源码 internal/cmd/calendar.go 中声明CreateCalendar CalendarCreateCalendarCmd cmd: name:create-calendar aliases:new-calendar help:Create a new secondary calendarsummary是必传的位置参数作为日历显示名称若传入空值含纯空格命令会返回用法错误并以退出码 2 终止见 internal/cmd/usage.gousage()返回ExitError{Code: 2}。2. 参数总览2.1 核心业务参数命令结构体定义于 internal/cmd/calendar_create_calendar.gotype CalendarCreateCalendarCmd struct { Summary string arg: name:summary help:Calendar display name Description string name:description help:Calendar description TimeZone string name:timezone aliases:tz help:IANA timezone (e.g., America/New_York) Location string name:location help:Calendar location }参数类型默认值说明summarystring位置参数必填日历显示名称源码中会先strings.TrimSpace再判空--descriptionstring空日历描述--timezone/--tzstring空交由 Google 端使用账户默认时区IANA 时区名如America/New_York客户端本地先行校验非法值直接报错退出码 2不会发起 API 请求--locationstring空日历位置2.2 全局 Flags继承自 gogcli 根命令命令参考页完整列出的全局参数如下适用于本命令也适用于大多数 gogcli 写操作命令Flag类型默认说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring账户邮箱、别名或auto用于需要认证的 Google API 命令--clientstringOAuth 客户端名选择对应存储的凭据 token 桶--colorstringauto颜色输出auto|always|never--disable-commandsstring禁用命令的逗号分隔列表支持点分路径-n/--dry-run/--dryrun/--noop/--previewbool不执行变更打印计划中的操作并成功退出--enable-commandsstring启用命令前缀的逗号分隔列表支持点分路径用于收窄 CLI 能力--enable-commands-exactstring启用命令的精确匹配列表父命令不会连带启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--gmail-no-sendboolfalse阻止 Gmail 发送类操作Agent 安全-h/--helpkong.helpFlag显示上下文帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本消费--no-input/--non-interactive/--noninteractivebool从不提示遇到需要交互时直接失败适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的 TSV 文本无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目以X-Goog-User-Project发送部分 API 在使用--access-token或 ADC 时必填--readonlyboolfalse运行时拦截所有变更类 API 请求auth add也会改为请求只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等包裹字段--select/--pick/--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点分路径-v/--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将拉取的文本字段包裹在外部不可信内容标记内3. 实战示例# 1) 基础用法创建一个名为 Team Calendar 的日历 gog calendar create-calendar Team Calendar # 2) 指定描述、时区与位置 gog calendar create-calendar Sprint Planning \ --description Weekly sprint planning calendar \ --timezone Asia/Shanghai \ --location HQ # 3) dry-run只打印将要发送的请求不接触认证、不发起 API 调用 gog calendar create-calendar Dry Run --timezone UTC --dry-run # 4) JSON 输出便于脚本/Agent 解析 gog calendar create-calendar Team Calendar -j # {calendar:{id:...,summary:Team Calendar,...}} # 5) 多账户场景用别名指定账户或临时使用 access token gog calendar create-calendar Ops Calendar -a my-alias gog calendar create-calendar Ops Calendar --access-token $TOKEN --quota-project my-project # 6) CI 场景不交互 机器可读输出 gog calendar create-calendar CI Calendar --no-input --plaindry-run 模式在 JSON 输出下形如由 internal/cmd/dryrun.go 生成{ dry_run: true, op: calendar.create-calendar, request: { calendar: { summary: Dry Run, timeZone: UTC } } }4. 源码级执行流程剖析Run方法internal/cmd/calendar_create_calendar.go#L21-L77的执行顺序非常清晰可以分为五个阶段4.1 参数清洗与必填校验summary : strings.TrimSpace(c.Summary) if summary { return usage(required: calendar name (positional argument)) }四个字段summary/description/timezone/location在构造calendar.Calendar请求体前都会先做TrimSpace避免把纯空格当作有效值传给 API。4.2 客户端时区预校验if cal.TimeZone ! { if _, tzErr : loadTimezoneLocation(cal.TimeZone); tzErr ! nil { return usagef(invalid timezone %q: %v, cal.TimeZone, tzErr) } }loadTimezoneLocationinternal/cmd/timezone.go#L87-L89内部就是time.LoadLocation即基于系统/嵌入的 tzdata 校验 IANA 时区名。这意味着传入--timezone Nope/Zone这类非法值时命令在本地就失败返回invalid timezone Nope/Zone: ...错误并以退出码 2 退出不会创建 Calendar 服务、更不会发起任何网络请求时区留空时不做校验请求体中timeZone为空串由 Google 端按账户默认时区处理该命令只对显式传入的 flag 值做严格校验。仓库中还存在更完整的时区解析链flag →GOG_TIMEZONE环境变量 → 配置项default_timezone见 internal/cmd/timezone.go#L40-L70但create-calendar走的是显式 flag 校验路径行为更确定、更适合脚本。4.3 dry-run 提前退出if dryRunErr : dryRunExit(ctx, flags, calendar.create-calendar, map[string]any{ calendar: cal, }); dryRunErr ! nil { return dryRunErr }dryRunExitinternal/cmd/dryrun.go#L12-L53在--dry-run时按当前输出模式分三路输出JSON 的{dry_run, op, request}、plain 的 TSV 三行、人类可读文本然后返回退出码 0 的ExitError。其注释明确说明设计意图“在触碰 auth/keyring 或发起 API 调用之前尽早调用”——也就是说 dry-run 连凭据读取都会跳过。测试用例 TestCalendarCreateCalendarCmd_DryRunDoesNotOpenService 用了一个会t.Fatal的 service 工厂来严格证明 dry-run 路径绝不会构造 calendar 服务。4.4 账户解析与服务构造dry-run 之后才进入认证路径account, err : requireAccount(flags) svc, err : calendarService(ctx, account)requireAccountinternal/cmd/account.go#L20-L38 起支持多种认证形态ADC应用默认凭据/服务账号模式下无需用户邮箱常规模式按--account邮箱、别名或auto→ 配置 →--access-token→ 本地已存账户的顺序解析calendarServiceinternal/cmd/runtime_services.go#L217-L223从运行时服务注册表取出按账户惰性构造的calendar.Service测试环境下可被替换为 mock HTTP 服务本命令的单测正是这样做的。4.5 发起 API 调用并格式化输出created, err : svc.Calendars.Insert(cal).Context(ctx).Do()调用即 Google Calendar API v3 的POST /calendar/v3/calendars。单测 TestCalendarCreateCalendarCmd_RunJSON 中的 mock server 精确匹配POST /calendar/v3/calendars并回显请求体验证了四个字段summary/description/timeZone/location都原样进入请求。输出分两种模式JSON 模式-j输出{calendar: 完整 Calendar 资源}由 internal/cmd/calendar_create_calendar.go#L61-L63 决定文本/TSV 模式逐行输出id、summary以及仅当非空时的timezone、description、locationinternal/cmd/calendar_create_calendar.go#L65-L76例如id createdexample.com summary Team Calendar timezone UTC location Remote该行为由 TestCalendarCreateCalendarCmd_RunTextIncludesLocation 断言保证。此外仓库的端到端 dry-run 测试 internal/cmd/dryrun_e2e_test.go#L314-L316 也收录了calendar create-calendar场景确保该命令纳入全仓库统一的 dry-run 契约op 名为calendar.create-calendar退出码 0。5. 安全与 Agent 使用建议从源码结构看create-calendar属于“写操作”因此可叠加多层防护--dry-run/--preview先确认请求内容再执行且完全不触碰凭据--readonly运行时拦截所有变更类 API 请求适合只读审查会话--enable-commands/--enable-commands-exact可为 Agent 会话显式收窄可用命令集--no-inputCI 中避免意外交互挂起--wrap-untrustedJSON 输出中的外部文本字段会被不可信内容标记包裹降低 prompt 注入面。6. 生命周期配套命令create-calendar不是孤立命令它通常与同族日历资源命令配合使用均可在 docs/commands/gog-calendar.md 的子命令列表中查到场景命令参考页创建辅助日历gog calendar create-calendar本页删除自己拥有的辅助日历gog calendar delete-calendargog-calendar-delete-calendar.md列出日历验证创建结果gog calendar calendarsgog-calendar-calendars.md把日历加入/移出日历列表gog calendar subscribe/gog calendar unsubscribegog-calendar-subscribe.md7. 小结与依据索引命令参考页参数表与用法来源docs/commands/gog-calendar-create-calendar.md由gog schema --json生成、make docs-commands维护命令实现internal/cmd/calendar_create_calendar.go字段定义、时区预校验、dry-run、Insert 调用、双格式输出单元与契约测试internal/cmd/calendar_create_calendar_test.goJSON 请求回显、TSV 输出、dry-run 不建服务、非法时区退出码 2与 internal/cmd/dryrun_e2e_test.go通用机制dry-run 输出格式见 internal/cmd/dryrun.go退出码 2 的用法错误见 internal/cmd/usage.go账户解析见 internal/cmd/account.go时区工具见 internal/cmd/timezone.go服务构造见 internal/cmd/runtime_services.go。掌握以上内容后你可以在终端、脚本或 Agent 工作流中安全地创建 Google 辅助日历先用--dry-run预览请求体再用-j拿到calendar.id作为后续create、subscribe、delete-calendar等操作的日历标识。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
