日历参考

本文档提供了使用gcalcli查看和管理日历事件的详细信息。

安装

gcalcli是一个用于 Google 日历的 Python 命令行界面工具，可与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分支包含attachments数组在JSON/TSV输出中。

每个事件的附件数组包含以下属性的对象：

• attachment_title：附件的标题（例如："Gemini笔记"、"录音"、"聊天记录"）
• attachment_url：Google Drive文件或Google文档的直接链接

常见附件类型：

• "Gemini笔记"：来自Google Meet的AI生成会议笔记
• 录音：会议录音（视频文件）
• 聊天记录：会议聊天记录文本
• 共享文档：议程、规划文档、演示文稿

搜索包含Gemini笔记的事件：

# Find all events with Gemini notes
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"))]}'

# Get just the titles and Gemini note URLs
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)"'

按附件类型筛选事件：

# Events with recordings
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"))'

# Events with any attachments
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. Find meeting with Gemini notes
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. Export to markdown using gcmd
cd /var/home/shanemcd/github/shanemcd/gcmd
uv run gcmd export "$GEMINI_URL" -o ~/Downloads/

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

# Extract Gemini note URLs and export in parallel (8 concurrent processes)
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进行去重

常见工作流程 - 审阅近期会议笔记：

# Search for recent meetings on a topic
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

# Filter to show only events with Gemini notes
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]}'

# Export the most recent Gemini notes for review
# (extract URL, then use gcmd export)

输出格式

--json（JSON格式）推荐使用

• 结构化的JSON输出，包含完整的事件数据
• 包含附件数组，每个附件均有标题和文件URL
• 保留所有事件字段
• 易于通过程序解析，例如使用jq或Python
• 所有字段均无截断
• 最适合访问会议笔记和附件

--tsv（制表符分隔值）

• 每行一个事件
• 制表符分隔的字段：
  • id
  • 开始日期，开始时间
  • 结束日期，结束时间
  • HTML链接
  • Hangouts链接
  • 会议详情
  • 标题
  • 地点
  • 描述（完整，不截断）
  • 日历
  • 电子邮件
  • 附件（管道分隔：标题|网址|标题|网址...）
  • 操作
• 适合使用标准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. 查找会议链接与笔记

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

# Using JSON (recommended for accessing attachments)
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"))'

# Using 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 发布
• 行动：检查日历以确认时间，准备讨论要点

会前准备：

# See what's coming up this week with attachments
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"

# Check specific meeting details
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. 理解时间范围："今天"显示的是从现在开始的时间，并非完整一天。要查看完整一天，请使用具体日期。

限制

• 只读（本文档未记录通过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

JSON格式快速查看（接下来5个事件）：

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、文本）