gws-meeting-scheduler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Meeting Scheduler

会议调度工具

Find mutual availability and create Google Calendar events using the

gws

CLI.

使用

gws

CLI查找双方空闲时段并创建Google Calendar事件。

Prerequisites

前提条件

```
gws
```
CLI installed and authenticated

已安装并完成
```
gws
```
CLI的身份验证

Workflow

工作流程

1. Resolve attendee email

1. 获取参会者邮箱

If the user provides a name but no email, search past calendar events:

bash

gws calendar events list --params '{"calendarId":"primary","q":"<name>","maxResults":10}'

Look at the

attendees

array in results to find the matching email. If multiple matches, ask the user to confirm.

如果用户仅提供姓名但未给出邮箱，搜索过往日历事件：

bash

gws calendar events list --params '{"calendarId":"primary","q":"<name>","maxResults":10}'

查看结果中的

attendees

数组以匹配对应的邮箱。如果存在多个匹配结果，请询问用户进行确认。

2. Detect timezones

2. 检测时区

Detect each person's timezone by querying their own calendar directly. When you query a person's calendar via their email as

calendarId

, the API returns

start.dateTime

with that person's local UTC offset — this is the most reliable signal.

bash

gws calendar events list --params '{"calendarId":"<user-email>","maxResults":10}'
gws calendar events list --params '{"calendarId":"<attendee-email>","maxResults":10}'

For each person:

Look at
```
start.dateTime
```
on non-all-day events (skip events with only
```
start.date
```
)
Extract the UTC offset (e.g.,
```
-08:00
```
,
```
+09:00
```
) — this reflects their calendar's timezone
Tally the most frequent offset to determine their timezone
Cross-reference with the
```
start.timeZone
```
field on events matching that offset to get the IANA name (e.g.,
```
-08:00
```
→
```
America/Los_Angeles
```
)

Important: Do NOT rely on

start.timeZone

alone — it often reflects the organizer's or attendee's timezone rather than the calendar owner's. The

dateTime

offset from the person's own calendar is the source of truth.

If no timezone can be determined for either person, ask the user.

通过直接查询个人日历来检测每个人的时区。当你以邮箱作为

calendarId

查询某人的日历时，API返回的

start.dateTime

会包含该用户当地的UTC偏移量——这是最可靠的信号。

bash

gws calendar events list --params '{"calendarId":"<user-email>","maxResults":10}'
gws calendar events list --params '{"calendarId":"<attendee-email>","maxResults":10}'

针对每个人：

查看非全天事件的
```
start.dateTime
```
字段（跳过仅包含
```
start.date
```
的事件）
提取UTC偏移量（例如
```
-08:00
```
、
```
+09:00
```
）——这反映了该用户日历的时区
统计出现频率最高的偏移量以确定其时区
对照匹配该偏移量的事件中的
```
start.timeZone
```
字段，获取IANA时区名称（例如
```
-08:00
```
对应
```
America/Los_Angeles
```
）

重要提示： 不要仅依赖

start.timeZone

字段——它通常反映的是组织者或参会者的时区，而非日历所有者的时区。从个人日历获取的

dateTime

偏移量才是最准确的依据。

如果无法确定任何一方的时区，请询问用户。

3. Determine date range

3. 确定日期范围

Ask the user for a preferred date range, or default to the next 5 business days.

询问用户偏好的日期范围，默认设置为未来5个工作日。

4. Check free/busy

4. 查看空闲/忙碌状态

Query both calendars together. The query range must cover work hours in both timezones:

bash

gws calendar freebusy query --json '{
  "timeMin": "<start-RFC3339>",
  "timeMax": "<end-RFC3339>",
  "items": [{"id": "<user-email>"}, {"id": "<attendee-email>"}]
}'

同时查询双方日历。查询范围必须覆盖双方时区的工作时间：

bash

gws calendar freebusy query --json '{
  "timeMin": "<start-RFC3339>",
  "timeMax": "<end-RFC3339>",
  "items": [{"id": "<user-email>"}, {"id": "<attendee-email>"}]
}'

5. Compute overlapping free slots

5. 计算重叠的空闲时段

Convert all busy times from UTC to each person's timezone
Define work hours per person: 9:00-18:00 in their respective timezone
Find the overlap of both people's work-hour windows, then subtract combined busy blocks
Filter to slots >= requested meeting duration
Double-check every slot against BOTH calendars before presenting — do not skip the user's own busy times
Present slots as a table showing times in both timezones:

Day       | User (JST)    | Attendee (PST) | Duration
Thu Feb 26 | 15:00 - 16:00 | 22:00 - 23:00  | 1h

If work-hour overlap is very limited (e.g., < 1 hour), note this and suggest the user consider extending hours.

将所有忙碌时间从UTC格式转换为每个人的本地时区
定义每个人的工作时间：各自时区的9:00-18:00
找出双方工作时间窗口的重叠部分，再减去共同的忙碌时段
筛选出时长大于等于会议需求的时段
展示前务必对照双方日历验证每个时段——不要忽略用户本人的忙碌时间
以表格形式展示时段，同时显示双方时区的时间：

日期       | 用户（JST）    | 参会者（PST） | 时长
2月26日周四 | 15:00 - 16:00 | 22:00 - 23:00  | 1小时

如果工作时间重叠非常有限（例如不足1小时），请告知用户并建议考虑延长工作时间。

6. Confirm and create the event

6. 确认并创建事件

Once the user picks a slot, duration, and title:

bash

gws calendar +insert \
  --summary "<title>" \
  --start "<start-RFC3339>" --end "<end-RFC3339>" \
  --attendee "<user-email>" --attendee "<attendee-email>"

For Google Meet links or other advanced options, use the raw API instead:

bash

gws calendar events insert --params '{"calendarId":"primary","conferenceDataVersion":1,"sendUpdates":"all"}' \
  --json '{
    "summary": "<title>",
    "start": {"dateTime": "<start-RFC3339>"},
    "end": {"dateTime": "<end-RFC3339>"},
    "attendees": [{"email": "<user-email>"}, {"email": "<attendee-email>"}],
    "conferenceData": {"createRequest": {"requestId": "<unique-id>", "conferenceSolutionKey": {"type": "hangoutsMeet"}}}
  }'

Key notes:

```
--attendee
```
— repeat for each attendee, always include the user themselves
```
conferenceDataVersion=1
```
param required when adding Meet links
```
sendUpdates=all
```
— notify attendees via email

一旦用户选定时段、时长和标题：

bash

gws calendar +insert \
  --summary "<title>" \
  --start "<start-RFC3339>" --end "<end-RFC3339>" \
  --attendee "<user-email>" --attendee "<attendee-email>"

如需添加Google Meet链接或其他高级选项，请使用原生API：

bash

gws calendar events insert --params '{"calendarId":"primary","conferenceDataVersion":1,"sendUpdates":"all"}' \
  --json '{
    "summary": "<title>",
    "start": {"dateTime": "<start-RFC3339>"},
    "end": {"dateTime": "<end-RFC3339>"},
    "attendees": [{"email": "<user-email>"}, {"email": "<attendee-email>"}],
    "conferenceData": {"createRequest": {"requestId": "<unique-id>", "conferenceSolutionKey": {"type": "hangoutsMeet"}}}
  }'

关键说明：

```
--attendee
```
—— 每个参会者重复添加，务必包含用户本人
添加Meet链接时必须传递
```
conferenceDataVersion=1
```
参数
```
sendUpdates=all
```
—— 通过邮件通知所有参会者

7. Confirm to user

7. 向用户确认

Show: title, date/time (in both timezones if cross-timezone), attendees, and Meet link.

展示信息：标题、日期/时间（跨时区会议需显示双方时区）、参会者及Meet链接。

Important Notes

重要注意事项

Always include the user as an attendee, not just as the calendar owner
```
gws
```
uses
```
--params
```
for query/path parameters and
```
--json
```
for request bodies
Use
```
--format json
```
(or omit, as JSON is default) for reliable parsing
RFC3339 times must include timezone offset (e.g.,
```
+09:00
```
for JST)
The freebusy API returns busy times in UTC — convert carefully
When computing free slots, verify against both calendars before presenting
Use
```
gws calendar +insert
```
helper for simple events; use
```
gws calendar events insert
```
raw API for advanced features (Meet links, recurrence, etc.)

务必将用户本人作为参会者添加，而不仅仅是作为日历所有者
```
gws
```
使用
```
--params
```
传递查询/路径参数，使用
```
--json
```
传递请求体
使用
```
--format json
```
（或省略，因为JSON是默认格式）以确保解析可靠
RFC3339格式的时间必须包含时区偏移量（例如，JST对应
```
+09:00
```
）
空闲/忙碌API返回的忙碌时间为UTC格式——转换时需谨慎
在计算空闲时段时，展示前务必对照双方日历进行验证
简单事件使用
```
gws calendar +insert
```
辅助命令；高级功能（如Meet链接、重复会议等）使用
```
gws calendar events insert
```
原生API