google-calendar

Google Calendar (gws)

此 Skill 专用于 gws 0.22.5。

定位可执行文件

始终使用此 Skill 随附的副本；切勿使用 PATH 中碰巧存在的 gws，它可能是无关版本。每个会话解析一次：

1. 确定平台目录 — 在 macOS 上运行 uname -m（arm64 → darwin-arm64，x86_64 → darwin-x64）；在 Windows 上使用 win32-x64。
2. 根据本文档所在目录解析 scripts/bin/<platform>/gws — 在 Windows 上，文件名为 gws.exe — 并在下方所有命令中使用该绝对路径。

此软件包仅提供 macOS 和 Windows 版本；在其他任何平台上，请说明 Google Calendar 在该平台不可用，而不是寻找其他安装版本。

为便于阅读，下方示例使用不带路径的命令名；实际运行时始终使用已解析出的绝对路径。

如果该文件缺失，请说明 Google Calendar 尚未就绪 — 切勿将其描述为账号问题或连接器故障。

像 Cola 一样对话

这些规则约束你对用户所说的内容，不会改变你运行的命令。

• 可以使用产品相关词汇。 配置、授权、连接、账号、日程、App 专用密码 — 用户应始终清楚自己正在进行哪一步。
• 不要向用户透露实现细节。 工具名称、CLI 标志、配置文件、协议、PATH、原始命令、原始错误输出。按目标进行说明（“正在查看你的日历”），将每个错误转化为一条明确的下一步操作，并用用户能理解的方式确认结果。

使用场景

• 查日程：“看看我明天谷歌日历有哪些安排”“这周有没有空的整段下午”
• 建与改：“帮我在周四下午约一个一小时的评审会，拉上 Alice”“把周会挪到十点”
• 汇总：“把下周的日程整理成一份议程”

当请求未指定服务提供方时。 可能安装了多个日历 Skill，单说“查下我的日程”并未说明要查看哪个账号。只有当这是唯一已连接的日历，或对话中已确认使用 Google Calendar 时，才无需询问而使用此 Skill。否则请询问用户指的是哪个日历 — 切勿为用户未要求的账号启动连接流程。

此安装仅支持日历。授权范围仅包括 Google Calendar，不包括其他任何 Google 服务（gmail、drive、sheets、docs、tasks 等）；这些服务会因权限错误而失败。不要尝试使用，也不要暗示这些服务可用。

授权

OAuth 由 Cola 管理，授权范围仅限日历（calendar.events，以及只读的日历列表）。你调用的 gws 命令所需凭据已配置完成。

• 切勿运行 gws auth login 或任何其他交互式授权流程，也不要设置 GOOGLE_APPLICATION_CREDENTIALS。用户需在 Cola 的应用中心完成授权。
• 如果命令因授权或权限错误而失败，请告知用户前往 Cola 的 Skill 设置，打开 Google Calendar 应用并完成授权或续期。不要循环重试。

范围边界

已授予的权限仅允许：

• events — 对日历活动进行完整读写
• calendarList — 只读（list、get）

不在授权范围内（会失败；不要调用）：日历 acl、创建或删除日历（calendars insert/delete/clear）、settings、channels/watch 订阅，以及所有非日历服务。

辅助命令

显示日程（只读）

gws calendar +agenda --timezone <IANA>

标志	说明
--today	显示今天的活动
--tomorrow	显示明天的活动
--week	显示本周的活动
--days <N>	显示未来天数
--calendar <NAME_OR_ID>	筛选指定日历
--timezone <IANA>	覆盖时区（例如 Asia/Shanghai）。务必传入此参数——见下文

gws calendar +agenda --today --timezone 'Asia/Shanghai'
gws calendar +agenda --week --format table --timezone 'Asia/Shanghai'
gws calendar +agenda --days 3 --calendar 'Work' --timezone 'Asia/Shanghai'

只读——不会修改活动。默认查询所有日历。

务必传入 --timezone。该辅助工具的默认设置会从 settings 读取账户时区，但此安装不包含该权限范围，因此它会悄然回退到机器的本地时区。如果机器时区与日历时区不同，--today 和 --week 查询的日期范围就会出错。请询问用户所在时区，或从某个活动自身的时区获取，并明确传入。

创建活动

gws calendar +insert --summary <TEXT> --start <TIME> --end <TIME>

标志	必填	说明
--summary	✓	活动标题
--start	✓	开始时间（RFC 3339，例如 2026-06-17T09:00:00+08:00）
--end	✓	结束时间（RFC 3339）
--calendar	—	日历 ID（默认值：primary）
--location	—	活动地点
--description	—	活动说明／正文
--attendee	—	参加者邮箱（可重复指定）。不会通知对方——见下文
--meet	—	添加 Google Meet 链接

gws calendar +insert --summary 'Standup' --start '2026-06-17T09:00:00+08:00' --end '2026-06-17T09:30:00+08:00'
gws calendar +insert --summary 'Review' --start ... --end ... --attendee [email protected] --meet

注意

这是一个写入命令——执行前请与用户确认。

**+insert 不会通知参加者。**该辅助工具不会设置 Calendar API 的 sendUpdates 参数，其默认值是不发送任何通知，因此虽然访客会被添加到活动中，却不会收到邀请。如果用户想邀请某人，请改用资源级命令创建活动并设置该参数，然后告知用户邀请已发出：

gws calendar events insert \
  --params '{"calendarId":"primary","sendUpdates":"all"}' \
  --json '{"summary":"Review","start":{"dateTime":"2026-06-17T09:00:00+08:00"},"end":{"dateTime":"2026-06-17T10:00:00+08:00"},"attendees":[{"email":"[email protected]"}]}'

+insert --meet 会自动添加 Meet 链接，但此资源级形式不会——请明确请求创建会议，否则邀请发出后将不包含加入会议的方式：

gws calendar events insert \
  --params '{"calendarId":"primary","sendUpdates":"all","conferenceDataVersion":1}' \
  --json '{"summary":"Review","start":{"dateTime":"2026-06-17T09:00:00+08:00"},"end":{"dateTime":"2026-06-17T10:00:00+08:00"},"attendees":[{"email":"[email protected]"}],"conferenceData":{"createRequest":{"requestId":"<unique-string>","conferenceSolutionKey":{"type":"hangoutsMeet"}}}}'

API 资源（在权限范围内）

gws calendar <resource> <method> [flags]

events

• list — 列出日历中的活动（--params '{"calendarId":"primary","timeMin":"...","timeMax":"...","singleEvents":true,"orderBy":"startTime"}'）
• get — 按 ID 获取单个活动
• instances — 获取重复活动的各个实例
• insert — 创建活动（优先使用 +insert）
• quickAdd — 根据文本字符串创建活动
• patch — 修改活动；所有编辑都使用此命令。如果活动有参加者，请在 --params 中添加 "sendUpdates":"all"，以便访客了解更改——默认情况下不会通知任何人，他们看到的仍是旧时间
• update — 完整替换；如果请求正文中缺少参加者、重复规则、提醒、地点和说明，这些内容就会被删除，因此只有在获取完整活动并原样传回所有字段后才使用
• delete — 删除活动。如果有参加者，也请传入 "sendUpdates":"all"，否则访客仍会保留组织者已取消的会议

calendarList（只读）

• list — 列出用户日历列表中的日历
• get — 获取单个日历列表条目

方法标志

标志	说明
--params '{"key": "val"}'	URL／查询参数
--json '{"key": "val"}'	请求正文（POST/PATCH/PUT）
--format <FMT>	输出格式：json（默认）、table、yaml、csv
--dry-run	在本地验证，不调用 API
--page-all	自动分页（NDJSON 输出）
--page-limit <N>	使用 --page-all 时的最大页数（默认值：10）

请用单引号括起 --params 和 --json 的值，避免 Shell 解释其中的双引号。

查找命令

gws calendar --help
gws schema calendar.<resource>.<method>   # required params, types, defaults

使用 gws schema 的输出构建 --params 和 --json。

安全规则

• 绝不直接输出机密信息（令牌、凭据文件）。
• 执行写入或删除命令前，务必先征得用户确认。
• 对于破坏性操作，优先先使用 --dry-run。
• 使用带明确时区偏移的 RFC 3339 时间；遵循用户的时区（在 +agenda 中使用 --timezone）。