gogcli 实战指南：使用 `gog tasks add` 在终端创建与管理 Google Tasks 任务

gogcli 实战指南使用gog tasks add在终端创建与管理 Google Tasks 任务【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog tasks add是 gogcliGoogle Workspace in your terminal提供的 Google Tasks 命令行入口用于在任意任务列表中创建任务并支持子任务、排序、截止日期以及重复任务物化materialize repeated tasks等高级能力。读完本文你将掌握该命令的完整语法、全部参数含义、重复任务的底层实现原理并能通过 dry-run、JSON 输出等模式把它安全地嵌入脚本与自动化流程。命令概览gog tasks add是gog tasks命令组下的一个子命令另有list、get、update、done、undo、delete、clear、raw等。命令组定义于 internal/cmd/tasks.goadd的别名是createAdd TasksAddCmd cmd: name:add help:Add a task aliases:create因此gog tasks create与gog tasks add完全等价。Google Tasks API 目前不支持在服务端维护重复规则元数据因此gog tasks add会在客户端展开重复计划schedule expansion将每次出现物化为独立任务——这也是本命令区别于简单 INSERT 调用的核心特性。基本用法gog tasks (task) add (create) tasklistId [flags]tasklistId位置参数目标任务列表 ID必填。源码中会对该参数做TrimSpace处理空值直接报错empty tasklistId见 internal/cmd/tasks_add_plan.go。--title任务标题必填空值报错required: --title。别名形式gog tasks add与gog tasks create等价task一词在命令路径中可省略即gog tasks add与gog task add均可解析。最小可用示例gog tasks add MDk5NTIwNTc0NDU5MjU1MzYxNjU6MDow --title 提交季度报告先确认任务列表 ID任务列表 ID 可通过以下命令查看gog tasks listsgog tasks add在执行时会对传入的 tasklistId 调用resolveTasklistID进行解析见 internal/cmd/tasks_items.go因此直接使用列表 ID 或可解析的别名形式均可。任务内容与结构参数Flag类型说明--titlestring任务标题必填--notesstring任务备注/描述--duestring截止日期RFC3339 或YYYY-MM-DDGoogle Tasks 可能忽略时间部分--parentstring父任务 ID作为子任务创建--previousstring前一个兄弟任务 ID控制排序位置截止日期--due的解析规则--due接受两种格式解析逻辑位于 internal/cmd/tasks_repeat.go纯日期YYYY-MM-DD按日期解析DueHasTimefalse最终以 UTC 的2006-01-02T00:00:00Z形式提交给 APIRFC3339 时间如2026-01-02T10:00:00Z保留时间部分DueHasTimetrue以原 RFC3339 字符串提交。需要提醒的是Google Tasks API 的due字段本身只支持日期粒度因此当传入带时间的 RFC3339 值时命令在非 JSON 模式下会输出一条提示warnTasksDueTime告知用户时间可能被 Google 忽略。具体逻辑见 internal/cmd/tasks_items.go。子任务与排序--parent taskId通过svc.Tasks.Insert(...).Parent(...)将该任务挂在指定父任务之下--previous taskId通过Insert(...).Previous(...)把新任务放到指定兄弟任务之后。在重复任务场景中--previous会被链式推进每创建一个任务后plan.Previous会更新为新任务的 ID从而保证整批物化的任务保持稳定的先后顺序见 internal/cmd/tasks_items.go。重复任务把一次命令展开成多个任务Google Tasks API 不提供服务端递归规则gog tasks add通过在客户端展开计划并逐个调用Tasks.Insert来实现“每日/每周/每月/每年重复”。三个重复参数入口Flag说明--repeat物化重复任务daily、weekly、monthly、yearly--recur--repeat的别名相同 cadence 值--recur-rrule通过 RRULE 指定 cadence支持FREQ与可选INTERVAL三者不能混用。源码中的校验规则internal/cmd/tasks_add_plan.go明确要求--repeat与--recur/--recur-rrule互斥--recur与--recur-rrule互斥使用任一重复参数时必须同时提供--due否则报错--due is required必须提供终止条件--repeat-count或--repeat-until否则报错--repeat requires --repeat-count or --repeat-until使用--recur/--recur-rrule时则提示“Google Tasks API does not support server-side recurring metadata; use --repeat-count or --repeat-until ... to materialize occurrences”。终止条件参数Flag类型说明--repeat-countint创建的出现次数要求配合重复参数值必须 0--repeat-untilstring重复截止日期/时间RFC3339 或YYYY-MM-DDRRULE 支持范围--recur-rrule的解析器位于 internal/cmd/tasks_repeat.go支持前缀RRULE:可省略FREQ仅支持DAILY、WEEKLY、MONTHLY、YEARLY大小写不敏感缺失或非法报错INTERVAL正整数默认 1如FREQDAILY;INTERVAL2表示每 2 天其余 key如BYDAY、UNTIL等暂不支持解析时报错unsupported key。示例每两天一次共 3 次gog tasks add tasklistId \ --title 站会纪要 \ --due 2026-01-01 \ --recur-rrule FREQDAILY;INTERVAL2 \ --repeat-count 3日期对齐与空计划保护当--due带时间而--repeat-until只给日期时until 会自动对齐到 due 的时刻如 due 为2026-01-01T10:00:00Z、until 为2026-01-03则最后出现落在2026-01-03T10:00:00Z反之如果 due 是纯日期而 until 带时间until 会被归一到 UTC 零点。若展开后的首个出现时间晚于 until如 due 晚于 until命令会直接报错repeat produced no occurrences避免产生空计划。以上逻辑与对应测试分别见 internal/cmd/tasks_add_plan.go 与 internal/cmd/tasks_add_plan_test.go。展开算法internal/cmd/tasks_repeat.go按AddDate推进daily 加天、weekly 加 7 天、monthly 加月、yearly 加年并以count或until二者之一作为终止条件另有防御性保护避免无限循环。物化任务的命名当展开出多个任务时每个任务的标题会自动追加序号格式为原始标题 (#i/N)例如站会纪要 (#1/3)仅单个任务时保持原标题不变见 internal/cmd/tasks_items.go。输出、安全与运行控制参数以下全局参数在本命令同样可用完整列表见 docs/commands/gog-tasks-add.md输出格式Flag类型默认说明-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本处理-p--plain--tsvboolfalse向 stdout 输出稳定可解析的文本TSV无颜色--colorstringauto颜色输出auto\|always\|never--results-onlyboolJSON 模式下只输出主结果去掉nextPageToken等信封字段--select--pick--projectstringJSON 模式下按逗号分隔选择字段best-effort支持点路径--wrap-untrustedboolfalseJSON/raw 输出中把拉取的文本字段包裹在外部不可信内容标记中JSON 模式下的输出结构单个任务返回{task: {...}}重复任务批量创建返回{tasks: [...], count: N}。非 JSON 模式下单任务输出id、title、status、due、link键值对批量创建则输出ID/TITLE/DUE三列表格见 internal/cmd/tasks_items.go。安全与预演Flag类型默认说明-n--dry-run--dryrun--noop--previewbool不实际修改数据打印计划动作后成功退出--readonlyboolfalse运行时阻断所有变更类 API 请求--no-input--non-interactive--noninteractivebool绝不交互式提问直接失败适合 CI-y--force--assume-yes--yesbool跳过破坏性命令的确认--dry-run的实现位于 internal/cmd/tasks_items.go调用dryRunExit(ctx, flags, tasks.add, plan.dryRunPayload())payload 包含tasklist_id、title、notes、due、parent、previous、repeat、recur、recur_rrule、repeat_step、repeat_count、repeat_until等字段见 internal/cmd/tasks_add_plan.go。因此可以先预演再执行# 预演打印将要做的事不真正调用 API gog tasks add tasklistId --title 每周例会 --due 2026-01-05 \ --recur weekly --repeat-count 4 --dry-run # 确认无误后正式执行 gog tasks add tasklistId --title 每周例会 --due 2026-01-05 \ --recur weekly --repeat-count 4认证与账户选择Flag说明--access-token直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a--account--acct账户邮箱、别名或auto用于需要认证的 Google API 命令--clientOAuth client 名称选择存储的凭据与 token 桶--quota-project计费的 Google Cloud 项目以X-Goog-User-Project头发送某些 API 与--access-token/ADC 搭配时需要--home覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME底层服务构造通过 internal/googleapi/tasks.go 的NewTasks完成它按账户选择 Tasks 服务并注册到运行时依赖中测试中可注入自定义 service factory见 internal/cmd/tasks_testutil_test.go便于隔离验证命令逻辑。命令开关与其他Flag类型说明--disable-commandsstring逗号分隔的禁用命令列表支持点路径--enable-commandsstring逗号分隔的启用命令前缀支持点路径限制 CLI 范围--enable-commands-exactstring逗号分隔的精确启用命令父命令不会连带启用子命令--gmail-no-sendbool阻断 Gmail 发送操作agent 安全开关默认false-h--helpkong.helpFlag显示上下文相关帮助-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出实践示例汇总# 1) 最简单的创建 gog tasks add tasklistId --title 买牛奶 # 2) 带截止日期与备注 gog tasks add tasklistId --title 提交报销 \ --notes 附上发票 PDF --due 2026-01-20 # 3) 创建子任务 gog tasks add tasklistId --title 写测试 --parent parentTaskId # 4) 每月 1 号体检共 12 次 gog tasks add tasklistId --title 月度体检 \ --due 2026-02-01 --repeat monthly --repeat-count 12 # 5) 每 2 周一次截止到 2026-06-30 gog tasks add tasklistId --title 双周同步 \ --due 2026-01-05 --recur-rrule FREQWEEKLY;INTERVAL2 \ --repeat-until 2026-06-30 # 6) 供脚本消费的 JSON 输出重复任务批量创建 gog tasks add tasklistId --title 每日备份检查 \ --due 2026-01-01 --recur daily --repeat-count 7 --json关联命令与更多资源父命令 gog tasksadd、clear、delete、done、get、list、lists、raw、undo、update的完整索引通过gog tasks list查看已创建任务、gog tasks done完成任务、gog tasks undo重新打开、gog tasks delete删除破坏性命令默认要求确认可用-y/--force跳过命令参考全文由gog schema --json生成可运行make docs-commands重新生成实现源码internal/cmd/tasks_items.go命令与 API 调用、internal/cmd/tasks_add_plan.go参数校验与重复计划、internal/cmd/tasks_repeat.go日期解析与 RRULE/展开算法相关行为均有 internal/cmd/tasks_add_plan_test.go 与 internal/cmd/tasks_repeat_test.go 等测试覆盖。注意事项tasklistId与--title为必填项二者缺失时命令会返回明确的使用错误Google Tasks API 的due只支持日期粒度带时间的截止值在非 JSON 输出下会收到提示重复任务必须同时给出--due与终止条件--repeat-count或--repeat-until否则校验失败所有任务列表与任务 ID 均来自gog tasks lists/gog tasks list的返回结果直接复制粘贴即可使用。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考