google-calendar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Calendar Sync

Google Calendar 同步

Overview

概述

여러 Google 계정(회사, 개인 등)의 캘린더를 한 번에 조회하여 통합된 일정을 제공한다.

사전 인증된 refresh token 사용 (매번 로그인 불필요)
Subagent 병렬 실행으로 빠른 조회
계정 간 일정 충돌 감지

可同时查看多个Google账户（工作、个人等）的日历，提供整合后的日程。

使用预认证的refresh token（无需每次登录）
通过Subagent并行执行实现快速查询
支持检测账户间的日程冲突

트리거 조건

触发条件

조회

查询

"오늘 일정", "이번 주 일정 알려줘"
"캘린더 확인", "스케줄 뭐야"
"다음 미팅", "내일 뭐 있어"
"일정 충돌 확인해줘"

"今日日程"、"告诉我本周日程"
"查看日历"、"日程是什么"
"下一个会议"、"明天有什么安排"
"帮我检查日程冲突"

생성

创建

"새 일정 만들어줘", "미팅 추가해줘"
"내일 3시에 회의 잡아줘"
"다음 주 월요일 팀 미팅 생성"

"帮我新建日程"、"添加会议"
"明天3点帮我安排会议"
"创建下周一的团队会议"

수정

修改

"일정 시간 변경해줘", "미팅 시간 바꿔줘"
"sync 미팅 14시 21분으로 변경"
"회의 제목 수정해줘"

"帮我更改日程时间"、"修改会议时间"
"把sync会议改成14点21分"
"帮我修改会议标题"

삭제

删除

"일정 삭제해줘", "미팅 취소해줘"
"이벤트 지워줘"

"帮我删除日程"、"取消会议"
"帮我删除这个事件"

사전 요구사항

前置要求

1. Google Cloud 프로젝트 설정

1. Google Cloud 项目设置

Google Cloud Console에서 프로젝트 생성
Calendar API 활성화
OAuth 2.0 Client ID 생성 (Desktop 유형)

credentials.json

다운로드 →

references/credentials.json

에 저장

在Google Cloud Console中创建项目
启用Calendar API
创建OAuth 2.0 Client ID（Desktop类型）

下载

credentials.json

→ 保存到

references/credentials.json

2. 계정별 인증 (최초 1회)

2. 账户认证（首次1次）

bash

undefined

bash

undefined

회사 계정

工作账户

uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account work

개인 계정

个人账户

uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account personal


브라우저에서 Google 로그인 → refresh token이 `accounts/{name}.json`에 저장됨

uv run python .claude/skills/google-calendar/scripts/setup_auth.py --account personal


在浏览器中完成Google登录 → refresh token会保存到`accounts/{name}.json`

워크플로우

工作流程

1. 등록된 계정 확인

1. 检查已注册账户

bash

ls .claude/skills/google-calendar/accounts/

bash

ls .claude/skills/google-calendar/accounts/

→ work.json, personal.json

undefined

undefined

2. Subagent 병렬 실행

2. Subagent 并行执行

각 계정별로 Task 도구를 병렬로 호출:

python

undefined

针对每个账户，并行调用Task工具：

python

undefined

병렬 실행 - 단일 메시지에 여러 Task 호출

并行执行 - 在单个消息中调用多个Task

Task(subagent_type="general-purpose", prompt="fetch calendar for work account") Task(subagent_type="general-purpose", prompt="fetch calendar for personal account")


각 subagent는 다음을 실행:
```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account {account_name} \
  --days 7

Task(subagent_type="general-purpose", prompt="fetch calendar for work account") Task(subagent_type="general-purpose", prompt="fetch calendar for personal account")


每个subagent会执行：
```bash
uv run python .claude/skills/google-calendar/scripts/fetch_events.py \
  --account {account_name} \
  --days 7

3. 결과 통합

3. 结果整合

모든 계정의 이벤트를 시간순 정렬
동일 시간대 이벤트 = 충돌로 표시
계정별 색상/아이콘 구분

将所有账户的事件按时间排序
同一时间段的事件标记为冲突
按账户用不同颜色/图标区分

출력 형식

输出格式

📅 2026-01-06 (월) 일정

[09:00-10:00] 🔵 팀 스탠드업 (work)
[10:00-11:30] 🟢 치과 예약 (personal)
[14:00-15:00] 🔵 고객 미팅 - 삼양 (work)
              ⚠️ 충돌: 개인 일정과 겹침
[14:00-14:30] 🟢 은행 방문 (personal)

📊 오늘 총 4개 일정 (work: 2, personal: 2)
   ⚠️ 1건 충돌

📅 2026-01-06 (周一) 日程

[09:00-10:00] 🔵 团队站会 (work)
[10:00-11:30] 🟢 牙科预约 (personal)
[14:00-15:00] 🔵 客户会议 - 三养 (work)
              ⚠️ 冲突：与个人日程重叠
[14:00-14:30] 🟢 银行办理 (personal)

📊 今日共4个日程 (work: 2, personal: 2)
   ⚠️ 1个冲突

실행 예시

执行示例

사용자: "이번 주 일정 알려줘"

1. accounts/ 폴더 확인
   └── 등록된 계정: work, personal

2. Subagent 병렬 실행
   ├── Task: work 계정 이벤트 조회
   └── Task: personal 계정 이벤트 조회

3. 결과 수집 (각 subagent 완료 대기)
   ├── work: 8개 이벤트
   └── personal: 3개 이벤트

4. 통합 및 정렬
   └── 11개 이벤트, 2건 충돌 감지

5. 출력
   └── 일별로 그룹화하여 표시

用户：“告诉我本周日程”

1. 检查accounts/文件夹
   └── 已注册账户：work, personal

2. Subagent并行执行
   ├── Task：查询work账户事件
   └── Task：查询personal账户事件

3. 收集结果（等待每个subagent完成）
   ├── work：8个事件
   └── personal：3个事件

4. 整合与排序
   └── 11个事件，检测到2个冲突

5. 输出
   └── 按日期分组显示

에러 처리

错误处理

상황	처리
accounts/ 폴더 비어있음	초기 설정 안내 (setup_auth.py 실행 방법)
특정 계정 토큰 만료	해당 계정 재인증 안내, 나머지 계정은 정상 조회
API 할당량 초과	잠시 후 재시도 안내
네트워크 오류	연결 확인 요청

情况	处理方式
accounts/文件夹为空	引导初始设置（说明setup_auth.py的执行方法）
特定账户token过期	引导该账户重新认证，其余账户正常查询
API配额超限	提示稍后重试
网络错误	请求检查网络连接

Scripts

脚本

파일	용도
`scripts/setup_auth.py`	계정별 OAuth 인증 및 token 저장
`scripts/fetch_events.py`	특정 계정의 이벤트 조회 (CLI)
`scripts/manage_events.py`	이벤트 생성/수정/삭제 (CLI)
`scripts/calendar_client.py`	Google Calendar API 클라이언트 라이브러리

文件	用途
`scripts/setup_auth.py`	按账户进行OAuth认证并保存token
`scripts/fetch_events.py`	查询特定账户的事件（CLI）
`scripts/manage_events.py`	事件的创建/修改/删除（CLI）
`scripts/calendar_client.py`	Google Calendar API客户端库

일정 관리 (생성/수정/삭제)

日程管理（创建/修改/删除）

일정 생성

创建日程

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "팀 미팅" \
    --start "2026-01-06T14:00:00" \
    --end "2026-01-06T15:00:00" \
    --account work

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "团队会议" \
    --start "2026-01-06T14:00:00" \
    --end "2026-01-06T15:00:00" \
    --account work

종일 일정 생성

创建全天日程

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "연차" \
    --start "2026-01-10" \
    --end "2026-01-11" \
    --account personal

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py create \
    --summary "年假" \
    --start "2026-01-10" \
    --end "2026-01-11" \
    --account personal

일정 수정

修改日程

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py update \
    --event-id "abc123" \
    --summary "팀 미팅 (변경)" \
    --start "2026-01-06T14:21:00" \
    --account work

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py update \
    --event-id "abc123" \
    --summary "团队会议（已修改）" \
    --start "2026-01-06T14:21:00" \
    --account work

일정 삭제

删除日程

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py delete \
    --event-id "abc123" \
    --account work

bash

uv run python .claude/skills/google-calendar/scripts/manage_events.py delete \
    --event-id "abc123" \
    --account work

옵션

选项

옵션	설명
`--summary`	일정 제목
`--start`	시작 시간 (ISO format: 2026-01-06T14:00:00 또는 2026-01-06)
`--end`	종료 시간
`--description`	일정 설명
`--location`	장소
`--attendees`	참석자 이메일 (쉼표 구분)
`--account`	계정 (work, personal 등)
`--adc`	gcloud ADC 사용
`--timezone`	타임존 (기본값: Asia/Seoul)
`--json`	JSON 형식 출력

选项	说明
`--summary`	日程标题
`--start`	开始时间（ISO格式：2026-01-06T14:00:00 或 2026-01-06）
`--end`	结束时间
`--description`	日程说明
`--location`	地点
`--attendees`	参会者邮箱（逗号分隔）
`--account`	账户（work、personal等）
`--adc`	使用gcloud ADC
`--timezone`	时区（默认值：Asia/Seoul）
`--json`	以JSON格式输出

References

参考资料

문서	내용
`references/setup.md`	초기 설정 상세 가이드
`references/credentials.json`	Google OAuth Client ID (gitignore)

文档	内容
`references/setup.md`	初始设置详细指南
`references/credentials.json`	Google OAuth Client ID（需加入gitignore）

파일 구조

文件结构

.claude/skills/google-calendar/
├── SKILL.md                    # 이 파일
├── scripts/
│   ├── calendar_client.py      # API 클라이언트
│   ├── setup_auth.py           # 인증 설정
│   ├── fetch_events.py         # 이벤트 조회 CLI
│   └── manage_events.py        # 이벤트 생성/수정/삭제 CLI
├── references/
│   ├── setup.md                # 설정 가이드
│   └── credentials.json        # OAuth Client ID (gitignore)
└── accounts/                   # 계정별 토큰 (gitignore)
    ├── work.json
    └── personal.json

.claude/skills/google-calendar/
├── SKILL.md                    # 本文件
├── scripts/
│   ├── calendar_client.py      # API客户端
│   ├── setup_auth.py           # 认证设置
│   ├── fetch_events.py         # 事件查询CLI
│   └── manage_events.py        # 事件创建/修改/删除CLI
├── references/
│   ├── setup.md                # 设置指南
│   └── credentials.json        # OAuth Client ID（需加入gitignore）
└── accounts/                   # 按账户存储的token（需加入gitignore）
    ├── work.json
    └── personal.json

보안 주의사항

安全注意事项

```
accounts/*.json
```
: refresh token 포함, 절대 커밋 금지
```
references/credentials.json
```
: Client Secret 포함, 커밋 금지
```
.gitignore
```
에 추가 필수

```
accounts/*.json
```
：包含refresh token，绝对禁止提交到版本库
```
references/credentials.json
```
：包含Client Secret，禁止提交
必须添加到
```
.gitignore
```
中