介绍
# Calendar Reference
本文档提供了有关使用 `gcalcli` 查看和管理日历事件的详细信息。
## 安装
`gcalcli` 是一个适用于 Google Calendar 的 Python CLI，可与 `uvx` 配合以进行一次性执行。
**重要提示：始终使用支持附件的自定义分支：** ```bash 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 格式，包含完整详情（带附件的结构化数据）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all --json ```
**备选：TSV 格式（制表符分隔，可解析）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all --tsv ```
**人类可读格式（可能会截断长描述）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all ```
**基本日程视图（最少详细信息）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] ```
### 日期范围
**重要提示：`gcalcli agenda` 默认显示从现在开始的事件。**
当您在下午 2 点运行 `gcalcli agenda "today"` 时，它将显示今天从下午 2 点开始及未来发生的事件。今天早些时候的过去事件不会出现。
**特定日期范围：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "tomorrow" "2 weeks" ```
**仅限今天（从当前时间开始）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "today" ```
**查看今天早些时候的事件（使用绝对日期）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "2025-10-07" "2025-10-07" ```
**下周：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] "monday" "friday" ```
### 搜索日历
**按文本搜索事件：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli search --calendar [email protected] "MCP Server" ```
### 访问会议附件和 Gemini 笔记
**重要提示：自定义 gcalcli 分支在 JSON/TSV 输出中包含 `attachments` 数组。**
每个事件的 `attachments` 数组包含具有以下内容的对象： - `attachment_title`：附件标题（例如，“Notes by Gemini”、“Recording”、“Chat”） - `attachment_url`：指向 Google Drive 文件或 Google Doc 的直接链接
**常见附件类型：** - **"Notes by Gemini"**：来自 Google Meet 的 AI 生成会议笔记 - **Recording**：会议录音（视频文件） - **Chat**：会议聊天记录 - **Shared docs**：议程、规划文档、演示文稿
**搜索带有 Gemini 笔记的事件：** ```bash # 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 [email protected] --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 [email protected] --details all --json | jq -r '.[] | select(.attachments[]? | .attachment_title | contains("Notes by Gemini")) | "\(.title): \(.attachments[] | select(.attachment_title | contains("Notes by Gemini")) | .attachment_url)"' ```
**按附件类型过滤事件：** ```bash # 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 [email protected] --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 [email protected] --json | jq '.[] | select(.attachments | length > 0)' ```
**使用 gcmd 导出 Gemini 笔记：**
单次会议导出： ```bash # 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 [email protected] --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 笔记（并行）：** ```bash # 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 [email protected] --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 进行去重
**常见工作流程 - 查看最近的会议笔记：** ```bash # 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 [email protected] --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 [email protected] --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 输出 - 包含附件数组，其中包含每个附件的标题和 fileUrl - 保留所有事件字段 - 易于使用 `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 工具 解析 - 无 ANSI 颜色代码或格式
### 默认格式 - 人类可读的彩色输出 - 显示时间、标题、基本详细信息 - 可能会用 "..." 指示符截断长描述
### --details all - 包含完整描述 - 显示所有与会者及其响应状态 - 会议/会议链接 - 位置信息 - 附件（人类可读格式）
## 用例
### 1. 晨间回顾
查看今天的日程安排（从当前时间开始显示）： ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --json "today" ```
注意：这显示从现在开始的事件。要查看包括过去事件在内的全天情况，请使用特定日期： ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --json "2025-10-07" "2025-10-07" ```
### 2. 每周计划
查看即将到来的一周，以规划深度工作时间： ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --json "monday" "friday" ```
### 3. 会议准备
查看即将召开的会议的详细信息： ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --details all --json "today" "tomorrow" ```
### 4. 查找会议链接和笔记
获取会议的会议链接和会议笔记： ```bash # 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 [email protected] --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 [email protected] --details all --tsv | grep "Meeting Name" ```
### 5. 工作前的上下文
在开发某个功能之前，检查是否有相关的同步会议： ```bash uvx gcalcli search --calendar [email protected] "ANSTRAT-1673" ```
## 与工作跟踪集成
### 日历感知计划
规划当天的日程时： 1. 检查日历中即将召开的相关会议 2. 注意会议是否发生在重要截止日期之前（例如，发布前 2 天的同步） 3. 规划工作以为讨论做准备 4. 确定专注工作的良好时间段（会议之间）
### 示例
**ANSTRAT-1673 场景：** - 10 月 8 日：与 Demetrius Lima 的同步会议 - 10 月 10 日：预计 llama-stack 发布 - 操作：检查日历以确认时间，准备讨论要点
**会前准备：** ```bash # 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 [email protected] --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 [email protected] --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` 标志
## 附加命令
**列出所有日历：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli list ```
**以日历格式查看（月视图）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli calm ```
**使用 JSON 快速查看（接下来的 5 个事件）：** ```bash uvx --from "git+https://github.com/shanemcd/gcalcli@attachments-in-tsv-and-json" --with "google-api-core<2.28.0" gcalcli agenda --calendar [email protected] --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、文本）