gws workflow +weekly-digest 实战指南：用 Google Workspace CLI 一键生成周例会与未读邮件摘要

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/cli

gws workflow +weekly-digest是 Google Workspace CLI（gws）内置的高层生产力助手命令，它一次性拉取未来 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.rs：

• inject_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：

1. 安装gws二进制并确保其在$PATH中。仓库 README.md 提供了多种安装途径：
   • 从 GitHub Releases 下载预编译二进制，解压后放入$PATH；
   • npm install -g @googleworkspace/cli（需 Node.js 18+）；
   • cargo install --git https://github.com/googleworkspace/cli --locked；
   • macOS/Linux 亦可brew install googleworkspace-cli。
2. 完成 OAuth 认证，两种方式任选：

   # 浏览器交互式 OAuth gws auth login # 或使用服务账号 export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

gws workflow +weekly-digest需要同时访问 Calendar 与 Gmail 数据，认证时会申请calendar.readonly与gmail.readonly两个只读 scope（见 workflows.rs），不会请求任何写权限。

三、命令用法与 Flags

基本用法

gws workflow +weekly-digest

这是唯一必须记住的调用形式：命令无必填参数，直接执行即可输出从当前时刻起 7 天的会议列表与未读邮件统计。

Flags 一览

--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:00+08:00" } ], "meetingCount": 5, "unreadEmails": 23, "periodStart": "2026-09-18T07:32:03+08:00", "periodEnd": "2026-09-25T07:32:03+08:00" }

--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 API：

GET https://www.googleapis.com/calendar/v3/calendars/primary/events ?timeMin=<now>&timeMax=<now+7d> &singleEvents=true&orderBy=startTime&maxResults=50

关键参数：

• singleEvents=true：把重复性事件展开为单个实例，避免拿到重复规则；
• orderBy=startTime：按开始时间排序，输出即时间线顺序；
• maxResults=50：单次最多取 50 条，足以覆盖普通一周的会议量。 每条事件只保留summary与start两个字段（start优先取dateTime，全天事件回退到date），保证输出轻量。

3. 统计 Gmail 未读邮件（L588-L606）调用 Gmail v1 API 的列表接口，查询条件为is:unread：

GET https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread&maxResults=1

这里只请求maxResults=1，真正的计数取自响应的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 与q=is: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-assistant）：workflows = ["+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）生成自然语言汇报

由于命令只读且输出为结构化 JSON，Agent 可以放心地把它的 stdout 交给jq或 LLM 解析，而无需担心副作用。

七、注意事项与最佳实践

1. 只读安全：+weekly-digest不修改任何数据，可放心在定时脚本、CI 或 Agent 上下文中反复调用。若需验证其他写操作，请遵循 skills/gws-shared/SKILL.md 的安全规则：写命令前必须与用户确认、优先使用--dry-run。
2. 时区语义：统计窗口基于账户时区的当前时刻向后滚动 7 天，不是固定自然周。需要「本周一至周日」口径时，建议在周初执行。
3. 未读数为估算值：unreadEmails来自 Gmail API 的resultSizeEstimate，在超大邮箱中可能与精确值有少量偏差，属于 API 语义，并非缺陷。
4. 窗口容量：会议上限为 50 条（maxResults=50），对一周会议量完全够用；若日历事件极多，可自行用gws calendar系列命令补充查询。
5. 管道友好：默认 JSON 输出可直接| jq '.meetingCount, .unreadEmails'；如需表格请显式传--format table，避免把 JSON 与人类可读文本混在 stdout 中。

八、延伸阅读

• skills/gws-workflow-weekly-digest/SKILL.md — 本文对应技能文档（命令、Flags、示例与提示）
• skills/gws-workflow/SKILL.md — workflow 命令组总览与其他四个 Helper
• skills/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