用 gws CLI 审查 Google Tasks 逾期任务从三步命令到自动化巡检的完整实践【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli本文以仓库内的 Recipe 技能文档 skills/recipe-review-overdue-tasks/SKILL.md 为核心骨架结合 gwsGoogle Workspace CLI的源码实现与配套技能文档讲解如何通过命令行快速找出已过期、需要关注的 Google Tasks 任务。读完本文你将掌握gws tasks的命令语法、任务列表与任务的查询方式、showCompleted等关键参数的作用以及如何基于 JSON 输出把逾期任务审查做成可定时运行的自动化巡检。gws 是一个由 Google Discovery Service 动态构建、一条命令覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat、Tasks 等 Google Workspace 服务的 CLI 工具。在其技能体系中Recipe 被定义为带有真实命令的多步骤任务序列见 docs/skills.md而recipe-review-overdue-tasks正是其中面向生产力场景domain: productivity的一个典型配方定位所有已过期、需要人工关注的 Google Tasks 任务供你排定处理优先级。一、Recipe 定位它在 gws 技能体系中处于什么位置先看原文档的元数据front matter它精确描述了该 Recipe 的依赖关系name: recipe-review-overdue-tasks description: Find Google Tasks that are past due and need attention. metadata: version: 0.22.5 openclaw: category: recipe domain: productivity requires: bins: - gws skills: - gws-tasks这三点值得注意执行前提是gws二进制可用bins: gws且必须提前加载gws-tasks技能——该技能负责提供 Tasks API 的资源/方法说明详见 skills/gws-tasks/SKILL.md。它属于recipe类别区别于gws-tasks这类 service 技能Recipe 是跨步骤的工作流脚本直接给出照着敲就能跑的命令。同一份内容同时登记在 CLI 的配方注册表 crates/google-workspace-cli/registry/recipes.toml 中review-overdue-tasks条目位于该文件第 244254 行services [tasks]也就是说它既是 AI Agent 的技能文件也是gws生成技能/配方索引时的事实来源。原文档开头的 PREREQUISITE 明确写道PREREQUISITE:Load the following skills to execute this recipe:gws-tasks如果gws-tasks技能缺失可运行gws generate-skills重新生成gws-tasks 文档中提供了这一恢复手段。二、前置准备安装与鉴权在执行任何 Tasks 命令前先确认环境就绪。根据 skills/gws-shared/SKILL.md安装gws二进制必须位于$PATH中具体安装方式见仓库根目录 README。鉴权二选一交互式 OAuth浏览器授权gws auth login服务账号设置环境变量指向 JSON 密钥export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.jsongws-tasks技能文档还提醒读者先阅读 skills/gws-shared/SKILL.md 以了解鉴权、全局标志与安全规则——这是所有 gws 服务技能的共同前提。三、核心三步执行逾期任务审查原文档给出的 Recipe 正文只有三步但每一步都对应真实的 gws 命令。下面逐一展开并结合源码给出参数说明与执行细节。步骤 1列出所有任务列表gws tasks tasklists list --format table命令结构遵循 gws 的统一语法gws service resource method [flags]服务是tasks资源是tasklists方法是list。--format table是全局输出格式标志。根据 skills/gws-shared/SKILL.mdgws 支持的格式为json默认、table、yaml、csv。审查任务时用table一眼看到全部列表的 ID 与标题最直观。这一步的目的拿到后续步骤必需的TASKLIST_ID。Google Tasks 数据按任务列表组织tasks tasks list必须显式指定tasklist参数因此先列列表是必然的第一步。配额背景来自 skills/gws-tasks/SKILL.md一个用户最多可拥有2000 个任务列表这是tasklists list返回规模的上限。步骤 2列出指定列表中的未完成任务gws tasks tasks list --params {tasklist: TASKLIST_ID, showCompleted: false} --format table--params {key: value}用于传递 URL/查询参数showCompleted: false表示只返回未完成任务这是本 Recipe 过滤待处理任务的关键。关于showCompleted的语义skills/gws-tasks/SKILL.md 给出了底层解释tasks clear会把已完成任务标记为hidden默认情况下不再返回。也就是说默认查询本身就以未完成/非隐藏任务为主而显式传入showCompleted: false让意图更明确、结果更可控。这一步是只读操作不修改任何数据可放心重复执行。步骤 3核对截止日期并排定优先级# 观察 table 输出中每个任务的 due截止时间列 # 将 due 早于当前时间的任务标记为“逾期”优先处理这一步不需要额外命令而是对步骤 2 输出的人工研判关注due截止时间字段凡截止时间已过但仍未完成的任务即为逾期任务按逾期天数从多到少、或按任务本身的重要程度排出处理顺序如需把某个任务置为已完成可调用gws tasks tasks update/patch写操作遵循 gws 安全规则需先与用户确认见下文第七节。四、深入底层gws tasks 命令与 Tasks API 资源全景本 Recipe 的两个命令都属于tasks服务。要真正用好它们需要理解该服务的资源与方法构成。skills/gws-tasks/SKILL.md 给出了完整清单tasklists 资源针对任务列表本身方法作用list返回用户全部任务列表上限 2000 个get返回指定的任务列表insert新建任务列表patch/update更新任务列表patch 支持部分字段语义delete删除任务列表若列表含已指派任务指派任务与 Docs/Chat 空间中的原始任务一并删除tasks 资源针对列表内的任务方法作用list返回指定任务列表中的全部任务默认不含来自 Docs/Chat 的指派任务上限 20,000 个非隐藏任务/列表、总计 100,000 个任务get返回指定任务insert在指定列表创建任务Docs/Chat 指派的只能从对应 surface 创建不能经 Tasks API 插入patch/update更新任务move在目标列表内移动任务位置也可挂到新父任务下单任务最多 2,000 个子任务clear清空指定列表的全部已完成任务标记为 hidden默认不再返回delete删除任务若为指派任务指派任务与原始任务一并删除本 Recipe 用到的正是tasklists list与tasks list两个只读方法。用 schema 命令核实参数在拼接--params前gws 提供了本地校验与参考工具实现在 crates/google-workspace-cli/src/schema.rs 的handle_schema_command支持service.resource[.subresource].method路径形式# 浏览 tasks 服务下的资源与方法 gws tasks --help # 查看 tasks.tasks.list 的参数、类型与默认值 gws schema tasks.tasks.listschema命令会基于 Google API Discovery Document 校验 JSON payload做到发送前先在本地点检参数合法性见 schema.rs 模块注释这能显著减少因参数拼写错误导致的请求失败。五、如何判定逾期due 字段与时间处理逾期的定义是任务的due截止时间早于当前时间且任务尚未完成status为 needsAction 而非 completed即步骤 2 中showCompleted: false过滤后的任务。关于due字段的取值格式可参考同仓库的姊妹 Recipe skills/recipe-create-task-list/SKILL.md——它在创建带截止时间的任务时使用的 JSON 是gws tasks tasks insert --params {tasklist: TASKLIST_ID} \ --json {title: Review Q1 metrics, notes: Pull data from analytics dashboard, due: 2024-04-01T00:00:00Z}可见due采用RFC 3339 / ISO 8601 格式的 UTC 时间2024-04-01T00:00:00Z。因此判断逾期时应把当前时间换算为同一时区基准后与due比较若你的任务以本地时间创建注意时区换算避免因 UTC/本地时间偏差误判。一个实用的小技巧如果只想快速概览今天及以后还有哪些未完成任务、而不想手工比对可直接观察 table 输出的due列若要程序化判断则用 JSON 输出交给脚本处理见下节。六、把审查变成自动化巡检table格式适合人工浏览json格式适合脚本消费。结合 skills/gws-shared/SKILL.md 的全局与分页标志可以构建一个可定时运行的巡检脚本#!/usr/bin/env bash # 1) 以 JSON 输出全部任务列表提取 ID 与标题 gws tasks tasklists list --format json # 2) 以 JSON 输出指定列表的未完成任务含 due 字段 gws tasks tasks list \ --params {tasklist: TASKLIST_ID, showCompleted: false} \ --format json脚本内可用jq之类的工具解析并筛选gws tasks tasks list \ --params {tasklist: TASKLIST_ID, showCompleted: false} \ --format json \ | jq -r .items[] | select(.due ! null and .due now) | [.title, .due] | tsv要点与坑JSON 参数必须用单引号包裹skills/gws-shared/SKILL.md 的 Shell Tips--params/--json值内含双引号用单引号可防止 shell 展开。示例gws tasks tasks list --params {tasklist: TASKLIST_ID}。zsh 的历史展开坑如果你的默认 shell 是 zsh!会被当作历史展开符。本 Recipe 的命令不含!但一旦你后续在 Sheets 等场景用到Sheet1!A1这类参数请用双引号并转义内部引号而不是单引号。分页若任务数量大可加--page-all自动分页NDJSON 输出、--page-limit N默认 10 页、--page-delay MS默认 100ms相关参数同样定义在 gws-shared 技能中。将该脚本放入cron/launchd定时执行即可实现每日早晨自动汇总逾期任务的轻量巡检。七、与其他技能的协同源码中的真实调用证据逾期任务审查并非孤岛它与 gws 的 workflow 类技能天然互补。以gws workflow standup-report站会报告为例其实现位于 crates/google-workspace-cli/src/helpers/workflows.rs。在该实现中第 325354 行gws 直接请求 Tasks API// Fetch open tasks let tasks_json get_json( client, https://tasks.googleapis.com/tasks/v1/lists/default/tasks, token, [(showCompleted, false), (maxResults, 20)], ) ...这段源码印证了三点showCompletedfalse是 gws 内部获取未完成任务的标准做法与本 Recipe 步骤 2 的参数完全一致——Recipe 中showCompleted: false的写法在源码层面有据可查站会报告默认取默认任务列表default前 20 条未完成任务并提取title与due两个字段输出见 workflows.rs 中open_tasks的映射逻辑说明标题 截止时间正是逾期审查关注的最小信息集workflow 技能对应文档 skills/gws-workflow-standup-report/SKILL.md 明确指出它是只读操作、不会修改数据这与本 Recipe 的只读性质一致。因此一个完整的任务健康度闭环可以是用本 Recipe 定位逾期项 → 用gws tasks tasks patch/update调整截止时间或标记完成 → 用gws workflow standup-report在站会上展示今日未完成任务概览。八、安全与最佳实践本 Recipe 全程只读但 gws 的安全规则skills/gws-shared/SKILL.md仍值得遵守尤其当你从审查进入处理阶段时绝不直接输出密钥/令牌等敏感信息写操作前必须与用户确认如tasks update、tasks delete、tasklists delete等破坏性操作优先--dry-run本地校验涉及 PII/内容安全筛查时使用--sanitize TEMPLATE。此外因为tasklists delete可能级联删除 Docs/Chat 中的指派任务见 gws-tasks 技能文档删除类操作务必三思。而tasks list、tasklists list这类只读查询可以放心高频执行。小结recipe-review-overdue-tasks用三条命令讲清了定位逾期任务的最小工作流tasklists list找列表 →tasks list配合showCompleted: false取未完成任务 → 人工比对due与当前时间排定优先级。在此基础上配合--format json、分页参数与定时任务即可升级为自动化巡检配合gws schema可随时核实任意参数配合 workflow 类技能则可融入站会、周报等更大的生产力闭环。所有命令与参数都以本仓库的技能文档与源码实现为据可直接复制运行。相关仓库资源索引Recipe 本体skills/recipe-review-overdue-tasks/SKILL.md前置技能Tasks API 资源全景skills/gws-tasks/SKILL.md公共参考鉴权/全局标志/安全规则skills/gws-shared/SKILL.md配方注册表同源登记crates/google-workspace-cli/registry/recipes.tomlschema 校验实现crates/google-workspace-cli/src/schema.rs站会报告对 Tasks 的调用实现crates/google-workspace-cli/src/helpers/workflows.rs技能总索引docs/skills.md【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考