gws workflow weekly-digest 实战指南用 Google Workspace CLI 一键生成周例会与未读邮件摘要【免费下载链接】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/cligws workflow weekly-digest是 Google Workspace CLIgws内置的高层生产力助手命令它一次性拉取未来 7 天的主日历会议安排与 Gmail 未读邮件总数输出结构化摘要全程只读、绝不修改任何数据。本文以 skills/gws-workflow-weekly-digest/SKILL.md 为骨架结合仓库源码深入讲解该命令的用法、输出格式、底层实现原理及其在 AI Agent 工作流中的典型应用场景读完即可在自己的终端或 Agent 技能体系中直接使用。一、weekly-digest 在 gws 中的定位gws是一个由 Google Discovery Service 动态构建的单体命令行工具覆盖 Drive、Gmail、Calendar、Sheets、Docs、Chat 等 Google Workspace 服务。在标准 API 调用之外它还提供了一批前缀的 Helper 命令把多个服务的高频操作编排成「一条命令解决一个场景」的快捷入口。weekly-digest属于 workflow 命令组跨服务生产力工作流下的五个 Helper 之一其余四个分别是standup-report、meeting-prep、email-to-task和file-announce完整清单见 skills/gws-workflow/SKILL.md 的 Helper Commands 表格。它的职责一句话即可概括本周会议安排 未读邮件数量 每周总结Weekly summary。该命令的注册与分发逻辑位于源码 crates/google-workspace-cli/src/helpers/workflows.rsinject_commands()L30-L41负责把weekly-digest等子命令注入gws workflow的命令树handle()L43-L72在匹配到weekly-digest时转调handle_weekly_digest()L535-L618后者是真正的业务实现同文件测试模块中的test_build_weekly_digest_cmd()L755-L758断言命令名注册正确。二、前置条件安装与认证运行该命令前需要满足两个前提详见 skills/gws-shared/SKILL.md安装gws二进制并确保其在$PATH中。仓库 README.md 提供了多种安装途径从 GitHub Releases 下载预编译二进制解压后放入$PATHnpm install -g googleworkspace/cli需 Node.js 18cargo install --git https://github.com/googleworkspace/cli --lockedmacOS/Linux 亦可brew install googleworkspace-cli。完成 OAuth 认证两种方式任选# 浏览器交互式 OAuth gws auth login # 或使用服务账号 export GOOGLE_APPLICATION_CREDENTIALS/path/to/key.jsongws workflow weekly-digest需要同时访问 Calendar 与 Gmail 数据认证时会申请calendar.readonly与gmail.readonly两个只读 scope见 workflows.rs不会请求任何写权限。三、命令用法与 Flags基本用法gws workflow weekly-digest这是唯一必须记住的调用形式命令无必填参数直接执行即可输出从当前时刻起 7 天的会议列表与未读邮件统计。Flags 一览Flag是否必填默认值说明--format否json输出格式json默认、table、yaml、csv--format是全局标志global(true)在 build_weekly_digest_cmd() 中声明。注意当前命令不支持--calendar之类的参数会议固定读取主日历calendars/primary如需指定其他日历可参考同文件的meeting-prep其--calendar参数默认值为primary。示例# 默认 JSON 输出 gws workflow weekly-digest # 表格输出便于终端直接阅读 gws workflow weekly-digest --format table四、输出结构详解命令的结果由format_and_print()workflows.rs经 crates/google-workspace-cli/src/formatter.rs 统一格式化后输出。核心 JSON 结构包含四个字段{ meetings: [ { summary: 产品周会, start: 2026-09-21T10:00:0008:00 } ], meetingCount: 5, unreadEmails: 23, periodStart: 2026-09-18T07:32:0308:00, periodEnd: 2026-09-25T07:32:0308:00 }字段类型含义meetings数组未来 7 天主日历事件每项含summary标题缺省为(No title)与startRFC3339 起始时间兼容全天事件的date字段meetingCount整数会议总数unreadEmails整数Gmail 未读邮件数量Gmail API 的估算值resultSizeEstimateperiodStart/periodEnd字符串统计时间窗起止RFC3339--format table会将该结构渲染为对齐文本表格yaml输出 YAML 文档csv输出逗号分隔值方便导入表格软件或后续脚本处理。formatter.rs中OutputFormat::parse()L42-L50接受json/table/yaml含yml/csv四种取值未知值回退为 JSON。五、底层实现原理一次调用背后的两条 API 链路handle_weekly_digest()workflows.rs的实现非常直观可以拆解为四个步骤1. 解析账户时区L544-L549通过timezone::resolve_account_timezone()获取账户所在时区以「当前时刻」为time_min、「当前时刻 7 天」为time_max构造统计窗口。这意味着摘要覆盖的不是自然周周一到周日而是从你执行命令的那一刻起接下来的 168 小时适合「滚动周报」类场景。2. 拉取主日历事件L551-L586调用 Google Calendar v3 APIGET https://www.googleapis.com/calendar/v3/calendars/primary/events ?timeMinnowtimeMaxnow7d singleEventstrueorderBystartTimemaxResults50关键参数singleEventstrue把重复性事件展开为单个实例避免拿到重复规则orderBystartTime按开始时间排序输出即时间线顺序maxResults50单次最多取 50 条足以覆盖普通一周的会议量。 每条事件只保留summary与start两个字段start优先取dateTime全天事件回退到date保证输出轻量。3. 统计 Gmail 未读邮件L588-L606调用 Gmail v1 API 的列表接口查询条件为is:unreadGET https://gmail.googleapis.com/gmail/v1/users/me/messages?qis:unreadmaxResults1这里只请求maxResults1真正的计数取自响应的resultSizeEstimate字段Gmail API 返回的匹配总数估算值因此几乎零开销——不需要逐封拉取邮件元数据。4. 容错与输出L565-L571、L596-L602、L608-L617两处 API 调用都做了防御性处理失败时向 stderr 打印Warning: Failed to fetch ...内容经sanitize_for_terminal清洗并以空对象兜底继续执行保证即使 Calendar 或 Gmail 某一侧异常命令也不会崩溃另一侧数据仍能正常输出。这也解释了为什么文档明确标注该命令是只读且安全的。与 gmail triage 的对比weekly-digest只取未读数量而 crates/google-workspace-cli/src/helpers/gmail/triage.rs 实现的gws gmail triage会逐封拉取未读邮件的 From/Subject/Date 明细默认最多 20 封并发度 10。两者使用相同的gmail.readonlyscope 与qis:unread查询区别仅在于「要数量」还是「要明细」可以按需组合先weekly-digest看总量再triage深入处理。六、在 AI Agent 与 Persona 中的组合应用weekly-digest是为 Agent 场景设计的技能skill其 Frontmatter 声明了requires.bins: [gws]与cliHelp: gws workflow weekly-digest --help并强调前置阅读 skills/gws-shared/SKILL.md认证、全局标志与安全规则若缺失可运行gws generate-skills重新生成全部技能索引见 docs/skills.md。在 crates/google-workspace-cli/registry/personas.toml 中weekly-digest被多个角色技能包引用例如管理助理exec-assistantworkflows [standup-report, weekly-digest]用于每周开始的日程与收件箱快照销售运营sales-ops提示语建议「Get a weekly sales pipeline summary withgws workflow weekly-digest」项目经理、团队负责人等角色同样把它作为周度例行任务的第一环。典型 Agent 使用模式Agent 收到指令「给我一份本周摘要」→ 执行 gws workflow weekly-digest → 解析 JSON 输出中的 meetingCount / unreadEmails / meetings → 结合其他命令如 gws calendar agenda、gws gmail triage生成自然语言汇报由于命令只读且输出为结构化 JSONAgent 可以放心地把它的 stdout 交给jq或 LLM 解析而无需担心副作用。七、注意事项与最佳实践只读安全weekly-digest不修改任何数据可放心在定时脚本、CI 或 Agent 上下文中反复调用。若需验证其他写操作请遵循 skills/gws-shared/SKILL.md 的安全规则写命令前必须与用户确认、优先使用--dry-run。时区语义统计窗口基于账户时区的当前时刻向后滚动 7 天不是固定自然周。需要「本周一至周日」口径时建议在周初执行。未读数为估算值unreadEmails来自 Gmail API 的resultSizeEstimate在超大邮箱中可能与精确值有少量偏差属于 API 语义并非缺陷。窗口容量会议上限为 50 条maxResults50对一周会议量完全够用若日历事件极多可自行用gws calendar系列命令补充查询。管道友好默认 JSON 输出可直接| jq .meetingCount, .unreadEmails如需表格请显式传--format table避免把 JSON 与人类可读文本混在 stdout 中。八、延伸阅读skills/gws-workflow-weekly-digest/SKILL.md — 本文对应技能文档命令、Flags、示例与提示skills/gws-workflow/SKILL.md — workflow 命令组总览与其他四个 Helperskills/gws-shared/SKILL.md — 认证、全局标志、安全规则与 Shell 使用技巧crates/google-workspace-cli/src/helpers/workflows.rs —weekly-digest及全部 workflow Helper 的源码实现与单元测试crates/google-workspace-cli/src/formatter.rs — json/table/yaml/csv 格式化实现crates/google-workspace-cli/src/helpers/gmail/triage.rs — 未读邮件明细查询实现crates/google-workspace-cli/registry/personas.toml —weekly-digest在各类 Agent 角色技能包中的引用【免费下载链接】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），仅供参考