名称： gcalcli
描述： 通过 gcalcli 与 Google 日历交互

日历参考文档

本文档详细介绍了如何使用 gcalcli 查看和管理日历事件。

安装

gcalcli 是一个用于 Google 日历的 Python CLI 工具，可通过 uvx 一次性执行。

重要提示：务必使用支持附件功能的定制版本：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli

此定制版本在 TSV 和 JSON 输出中包含了附件信息，这对于访问会议笔记和其他事件附件至关重要。

认证

首次运行 gcalcli 时，它会：
1. 打开浏览器进行 Google OAuth 认证
2. 缓存凭据供后续使用
3. 请求日历读取权限

常用命令

查看即将到来的日程

推荐：JSON 格式（包含完整详情和附件的结构化数据）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --json

备选：TSV 格式（制表符分隔，易于解析）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --tsv

人类可读格式（可能截断长描述）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all

基础日程视图（最少详情）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com

日期范围

重要：gcalcli agenda 默认显示从当前时间开始的事件。

当你在下午 2 点运行 gcalcli agenda "today" 时，它会显示从今天下午 2 点开始到未来的事件。今天早些时候的过去事件不会出现。

指定日期范围：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com "tomorrow" "2 weeks"

仅今天（从当前时间开始）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com "today"

查看今天早些时候的事件（使用绝对日期）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com "2025-10-07" "2025-10-07"

下周：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com "monday" "friday"

搜索日历

按文本搜索事件：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search --calendar smcdonal@redhat.com "MCP Server"

访问会议附件和 Gemini 笔记

重要：定制的 gcalcli 分支在 JSON/TSV 输出中包含了 attachments 数组。

每个事件的 attachments 数组包含以下对象：
- attachment_title：附件标题（例如 "Notes by Gemini"、"Recording"、"Chat"）
- attachment_url：指向 Google Drive 文件或 Google 文档的直接链接

常见附件类型：
- "Notes by Gemini"：来自 Google Meet 的 AI 生成会议笔记
- Recording：会议录制（视频文件）
- Chat：会议聊天记录
- Shared docs：议程、规划文档、演示文稿

搜索包含 Gemini 笔记的事件：

# 查找所有包含 Gemini 笔记的事件
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar smcdonal@redhat.com --details all --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | {title, attachments: [.attachments[] | select(.attachment_title | contains("Notes by Gemini"))]}'

# 仅获取标题和 Gemini 笔记 URL
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar smcdonal@redhat.com --details all --json | jq -r '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | "\(.title): \(.attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url)"'

按附件类型筛选事件：

# 包含录制的事件
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Recording"))'

# 包含任何附件的事件
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json | jq '.[] | select(.attachments | length > 0)'

使用 gcmd 导出 Gemini 笔记：

单次会议导出：

# 1. 查找包含 Gemini 笔记的会议
GEMINI_URL=$(uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP proposals" --calendar smcdonal@redhat.com --json | jq -r '.[0].attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url' | head -1)

# 2. 使用 gcmd 导出为 markdown
cd /var/home/shanemcd/github/shanemcd/gcmd
uv run gcmd export "$GEMINI_URL" -o ~/Downloads/

批量导出搜索结果中的所有 Gemini 笔记（并行）：

# 提取 Gemini 笔记 URL 并并行导出（8 个并发进程）
cd /var/home/shanemcd/github/shanemcd/gcmd
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "MCP" --calendar smcdonal@redhat.com --details all --json "2 months ago" "today" | jq -r '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | .attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url' | sort -u | xargs -P 8 -I {} sh -c 'uv run gcmd export "{}" -o ~/Downloads/meeting-notes/'

此方法高效地：
- 搜索日历中匹配查询的会议
- 筛选出仅包含 Gemini 笔记的会议
- 并行导出所有笔记（每次 8 个）到组织好的目录
- 使用直接管道（无中间文件）
- 使用 sort -u 去重 URL

常见工作流 - 查看近期会议笔记：

# 搜索特定主题的近期会议
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "ANSTRAT-1567" --calendar smcdonal@redhat.com --json

# 筛选仅显示包含 Gemini 笔记的事件
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search "ANSTRAT-1567" --calendar smcdonal@redhat.com --json | jq '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | {title, date: .s, gemini_notes: [.attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url]}'

# 导出最新的 Gemini 笔记以供查看
# （提取 URL，然后使用 gcmd export）

输出格式

--json (JSON 格式) 推荐

• 结构化的 JSON 输出，包含完整事件数据
• 包含带有标题和文件 URL 的附件数组
• 保留所有事件字段
• 易于使用 jq 或 Python 进行程序化解析
• 无字段截断
• 访问会议笔记和附件的最佳选择

--tsv (制表符分隔值)

• 每行一个事件
• 制表符分隔的字段：
• id
• start_date, start_time
• end_date, end_time
• html_link
• hangout_link
• conference details
• title
• location
• description（完整，无截断）
• calendar
• email
• attachments（管道分隔：title|url|title|url...）
• action
• 适合使用标准 Unix 工具（grep、awk、cut）解析
• 无 ANSI 颜色代码或格式

默认格式

• 人类可读的彩色输出
• 显示时间、标题、基本详情
• 可能用 "..." 指示符截断长描述

--details all

• 包含完整描述
• 显示所有参与者及其响应状态
• 会议/视频链接
• 位置信息
• 附件（人类可读格式）

使用场景

1. 晨间回顾

查看今日日程安排（显示从当前时间开始的事件）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "today"

注意：此命令显示从当前时间开始的事件。要查看包括过去事件的完整一天，请使用特定日期：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "2025-10-07" "2025-10-07"

2. 每周规划

查看即将到来的一周，规划深度工作时间：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "monday" "friday"

3. 会议准备

查看即将到来的会议详情：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --json "today" "tomorrow"

4. 查找会议链接和笔记

获取会议的会议链接和笔记：

# 使用 JSON（推荐用于访问附件）
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --json | jq '.[] | select(.title | contains("Meeting Name"))'

# 使用 TSV
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --details all --tsv | grep "Meeting Name"

5. 工作前上下文

在开始处理某个功能前，检查是否有相关的同步会议：

uvx gcalcli search --calendar smcdonal@redhat.com "ANSTRAT-1673"

与工作跟踪集成

日历感知规划

规划每日议程时：
1. 检查日历中是否有即将到来的相关会议
2. 注意会议是否发生在重要截止日期之前（例如，发布前两天同步）
3. 规划工作以准备讨论
4. 识别专注工作的良好时间块（会议之间）

示例

ANSTRAT-1673 场景：
- 10月8日：与 Demetrius Lima 的同步会议
- 10月10日：预期的 llama-stack 发布
- 操作：检查日历以确认时间安排，准备讨论要点

会议前准备：

# 查看本周即将到来的事件及其附件
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json "monday" "friday"

# 检查特定会议详情
uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search --calendar smcdonal@redhat.com --json "ANSTRAT"

提示

1. 始终使用带约束的定制分支：使用 uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" 以获得附件支持
2. 始终使用 --json 标志：默认使用 JSON 格式以获取包含附件的结构化数据
3. 使用 jq 进行解析：JSON 输出与 jq 完美配合，用于筛选和提取数据
4. 在会话开始时检查日历：作为标准工作流的一部分
5. 时间盒专注工作：寻找会议之间的间隙
6. 为同步会议做准备：在重要会议前 1-2 天检查日历
7. 访问会议笔记：使用 jq 筛选 Gemini 笔记，然后使用 gcmd 导出
8. 导出前先搜索：使用 gcalcli search 查找相关会议，然后筛选附件数组
9. 理解时间范围："today" 显示从当前时间开始的事件，而非完整一天。使用特定日期查看完整的一天。

限制

• 只读（本文档未记录通过 CLI 创建/修改事件）
• 需要 OAuth 认证
• 可能需要定期重新认证
• 多个日历需要单独的 --calendar 标志

附加命令

列出所有日历：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli list

以日历格式查看（月视图）：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli calm

快速查看（接下来 5 个事件）并输出 JSON：

uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar smcdonal@redhat.com --json | jq '.[0:5]'

参考

• 官方 gcalcli 文档：https://github.com/insanum/gcalcli
• 支持附件的定制分支：https://github.com/shanemcd/gcalcli/tree/attachments-in-tsv-and-json
• 使用 Google Calendar API v3
• 支持多种输出格式（JSON、TSV、文本）