paulstraw/g-scheduler

g-scheduler 是做什么的？

找出每个参与者都在其工作时间内空闲的会议时段，然后（仅在用户请求时）创建邀请。两个内置脚本负责 Google 调用和时间计算。切勿自行进行时区或夏令时运算，直接使用脚本输出。

在技能目录下使用 python3（Windows 上使用 python 或 py）运行脚本：scripts/gcal.py 和 scripts/slots.py。需要 Python 3.9+。

1. 检查访问权限

运行 python3 scripts/gcal.py check。

• 如果因缺少 gws 或未登录而失败，或者 Python 报错要求 tzdata，请停止并引导用户逐步完成 SETUP.md 中的操作。没有其他方法可以继续。
• 如果成功，则继续。my_working_hours: "not set" 是正常的。

2. 收集输入

• 参与者： 将所有人解析为 Google Workspace 电子邮件地址。对于没有邮箱的名称，运行 python3 scripts/gcal.py find "Ada Lovelace" "Grace"，该命令会搜索组织的通讯录；您拥有的其他工具（Slack、用户消息）同样有效。如果 find 失败（缺少作用域、accessNotConfigured 或管理员禁用了目录共享），则无法进行姓名查找：一次性说明原因，指向 SETUP.md 中的故障排除部分，并使用其他工具。如果某个邮箱缺失、不明确或看起来不在用户组织内，请询问用户。当前用户会自动添加；仅在用户表示他们不参加时传递 --exclude-me。
• 日期范围： 保持简单。"未来2周" 表示从今天起约18天（更近的时段排序更靠前）。特定日期表示仅那一天。日期格式为 YYYY-MM-DD；结束日期包含在内。
• 时长： 默认为60分钟。无需询问；直接说明已假设此值。
• 可选人员： 不要提前询问。默认将所有人视为必需参与者。

3. 查找时段

python3 scripts/gcal.py gather [email protected] [email protected] --start 2026-11-10 --end 2026-11-27 \
  | python3 scripts/slots.py

gather 选项：--duration MIN、--optional EMAIL（可重复）、--exclude-me、--time-zone TZ（默认为用户日历的时区，也用于排序和显示）。

输出包含 slots（最多5个，每天最多2个，最早的优先）、all_required_free、attendees 和 warnings。每个时段包含每位参与者的本地时间和用户时区时间、missing、missing_optional 和 at_day_edge（指那些该时段位于其工作日首末30分钟内的人）。

读取整个输出。不要过滤输出（例如使用 jq 或 python -c），因为这会丢失 warnings。

检查特定时间（用户提议了一个时间、某个时段未列出、或者后添加了参与者），使用所有参与者运行相同的管道，并将 --start 和 --end 精确设置为该会议的 RFC3339 带偏移量时间：--start 2026-11-19T11:00:00-08:00 --end 2026-11-19T12:00:00-08:00。输出中的单个时段会说明谁无法参加。切勿自行根据原始忙碌时间计算可用性。

4. 呈现结果

• 以用户时区列出时段，当各时区不同时显示每位参与者的本地时间。
• 用通俗语言重复每条警告。指出工作时间为假设值（其所在时区的工作日09:00-17:00）的人员，以及因无法读取日历而被排除的人员。
• 如果用户未提供时长，说明假设的时长。
• 如果 all_required_free 为 false，说明每个时段中谁无法参加，并询问是否将这些人员中的某些作为 --optional 重新运行。只有用户能决定谁是可选人员；切勿自行将某人标记为可选。
• 如果 slots 为空，请告知用户并建议扩大范围或缩短会议。

5. 创建邀请（仅在用户要求时）

1. 根据上下文拟定标题和简短描述（如果存在，则包含来源链接，例如 Slack 讨论串）。

2. 询问是否添加视频会议链接。如果提供，将其放入 location 和描述中。不要创建 Meet 或 Zoom 会议。

3. 展示确切事件（标题、本地时间、参与者、描述、地点），并等待用户明确确认“是的，发送”。发送邀请会通知所有参与者且无法撤销。

4. 将事件写入临时 JSON 文件，作为 Calendar Events 资源，时间使用用户的时区：

   {
     "summary": "项目启动会",
     "description": "计划自 https://example.slack.com/archives/...",
     "location": "https://zoom.us/j/123",
     "start": {"dateTime": "2026-11-18T10:00:00", "timeZone": "America/Los_Angeles"},
     "end": {"dateTime": "2026-11-18T11:00:00", "timeZone": "America/Los_Angeles"},
     "attendees": [{"email": "[email protected]"}, {"email": "[email protected]"}]
   }
   

5. 运行 python3 scripts/gcal.py invite EVENT.json。它始终会向所有参与者发送邀请。如果希望先检查请求，请使用 --dry-run。

6. 将输出中的 htmlLink 提供给用户，并删除临时文件。

规则

• 除 invite 外，所有操作均为只读。切勿更改任何人的日历或工作时间。
• 未经用户对预览事件的明确确认，绝不发送邀请。
• 如果某时区的时间看起来差了1小时，可能是计算机的时区数据过旧（时区规则会变化，例如不列颠哥伦比亚省在2026年的调整）。请参阅 SETUP.md 中的故障排除部分。