gcalcli 日历

使用gcalcli以最少的工具调用和最简洁的输出来读取/搜索/管理谷歌日历。

规则

CLI 标志放置（关键）

• 全局标志（--nocolor、--calendar）放在子命令之前。
• 子命令特定的标志放在子命令名称之后。
• 示例：gcalcli --nocolor delete --iamaexpert "查询" 开始 结束— 而不是gcalcli --nocolor --iamaexpert delete ...。
• 这适用于所有子命令标志：--iamaexpert（删除）、--noprompt/--allday（添加）、--use-legacy-import导入等。

输出与语言

• 除非用户明确要求（例如"显示使用的命令"、"/debug"、"/commands"），否则不要打印CLI命令/标志/工具细节。
• 如果要求显示命令：按顺序打印所有执行的命令（包括重试），并且不要打印其他内容。
• 不要在同一次回复中混合使用多种语言。
• 保持简洁。除非未找到任何内容，否则不要说明范围。

日期与格式

• 默认使用人类易读的日期。只有在明确请求时才使用ISO格式。
• 除非需要消除歧义，否则不要引用事件标题。

日历范围

• 信任gcalcli配置（默认/忽略的日历）。除非用户要求"在所有日历中"或结果明显错误，否则不要扩大范围。

日程（默认仅限今日）

• 如果用户仅询问"agenda"而未指定时间段，则仅返回今日的日程。
• 仅在明确要求时（例如明天/未来N天/日期范围）才扩展范围。

星期几的请求（无需心算）

如果用户提到"在周一/周二/……"但没有指定具体日期：

1. 则一次性获取未来14天的日程，
2. 从工具输出中选取匹配的日期/事件，
3. 然后继续处理（如果存在多个，则进行消歧）。

查找事件：优先使用确定性的日程扫描（意义优先）

在定位要取消/删除/编辑的事件时：

• 优先使用日程而非搜索。
• 使用有界窗口，并通过含义（语义匹配）而非精确文本来匹配事件。
• 默认定位窗口：
  • 如果用户提供了确切日期：仅扫描该日。
  • 如果用户提供了星期几：扫描接下来14天。
  • 如果用户仅提供了含义词（如"会议"、"讲座"等）而没有日期：首先扫描接下来30天。
  • 如果仍未找到：扩展到180天，并且仅在仍然为空时才告知用户。

使用 gcalcli搜索仅作为后备方案，在以下情况时使用：

• 时间窗口过大，无法通过议程扫描（会消耗大量令牌），或
• 用户明确要求"搜索"。

搜索（有界）

• 默认搜索窗口：接下来约180天（除非用户另有指定）。
• 如果没有匹配项：告知"在接下来约6个月内未找到匹配项（<起始日期>-><结束日期>）"，并提供扩展搜索的选项。
• 仅在未找到任何结果时显示搜索范围。

工具效率

• 默认：使用--nocolor以减少格式噪音和令牌消耗。
• 使用--tsv仅当你必须进行解析/去重/排序时。

操作策略（针对对话速度优化）

此功能专为个人助手场景设计，用户期望快速、低阻力的日历管理。以下确认策略是经过深思熟虑的用户体验选择——具体设计理念与安全防护机制详见README.md文档。

明确操作：立即执行

当满足以下全部条件时，取消/删除/编辑操作将跳过确认步骤：

• 用户明确请求该操作（例如"删除我的牙医预约"）
• 在紧凑时间窗口内仅有一个日程匹配
• 匹配结果明确无误（精确日期的唯一结果，或用户指定了日期+时间）

模糊操作：始终先行询问

若存在多个候选匹配项，或匹配结果不确定时：

• 提出简短澄清问题（1-3行）列出候选事项，等待用户选择

创建日程：必须进行跨日历重叠检测（非忽略范围）

创建日程时：

• 必须通过扫描日程表（不使用--calendar参数），对所有非忽略日历执行尽力而为的重叠检测--calendar。
  • 此举可确保即使新日程创建到特定日历中，也能检测到时间冲突
• 若与繁忙日程存在时间重叠：
  • 创建前需请求确认
• 若无时间冲突：
  • 立即创建

选择正确的创建方式

• add——单次日程的默认创建方式。支持--allday、--reminder,--noprompt. 不支持重复事件或忙闲状态（透明度）。
• import通过标准输入— 仅当您需要重复事件（RRULE）或忙闲状态（TRANSP:TRANSPARENT）时才使用。通过标准输入传输ICS内容；切勿写入临时.ics文件（在exec沙盒中工作目录不可靠）。
• quick— 除非用户明确要求自然语言添加，否则避免使用。确定性较低。

删除操作必须经过验证

• 使用非交互式删除并配合--iamaexpert（一个delete子命令标志 — 置于delete之后）。这是gcalcli内置的用于非交互式/脚本化删除的标志。
• 删除后务必在同一紧凑时间窗口内通过日程安排进行验证。
• 如果验证仍显示该事件，请使用--refresh重试一次。
• 除非验证确认事件已消失，否则切勿声称成功。

规范命令

日程安排（确定性列表）

• 今天：gcalcli --nocolor agenda today tomorrow
• 未来14天（工作日粒度）：gcalcli --nocolor agenda today +14d
• 未来30天（含义优先查找）：gcalcli --nocolor agenda today +30d
• 自定义：gcalcli --nocolor agenda <开始日期> <结束日期>

搜索（备用方案 / 明确请求时）

• 默认（约6个月）：gcalcli --nocolor search "<查询内容>" today +180d
• 自定义：gcalcli --nocolor search "<查询内容>" <开始日期> <结束日期>

创建 —添加（一次性事件）

• 重叠预检（严格，跨日历）：
  • gcalcli --nocolor agenda <开始日期> <结束日期>
  • 重要：此处请勿添加--calendar参数；必须检查所有未被忽略日历的事件重叠情况。
• 定时事件：
  • gcalcli --nocolor --calendar "<日历名称>" add --noprompt --title "<标题>" --when "<开始时间>" --duration <分钟数>
• 全天事件：
  • gcalcli --nocolor --calendar "<日历名称>" add --noprompt --allday --title "<标题>" --when "<日期>"
• 设置提醒（可重复标志）：
  • --reminder "20160 popup"→ 提前14天提醒（20160 = 14×24×60）
  • --reminder "10080 popup"→ 事件开始前7天
  • --提醒 "0 弹出窗口"→ 事件开始时
  • 时间单位后缀：w（周），d（天），h（小时），m（分钟）。无后缀 = 分钟。
  • 方法：弹出窗口（默认），电子邮件，短信。

创建 —导入通过标准输入（重复事件 / 空闲/忙碌状态）

仅在添加无法满足需求时使用（重复事件、TRANSP 等）。 通过标准输入直接管道传输 ICS 数据 — 切勿写入临时文件。

echo 'BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART;VALUE=DATE:20260308
SUMMARY:事件标题
RRULE:FREQ=YEARLY
TRANSP:TRANSPARENT
END:VEVENT
END:VCALENDAR' | gcalcli import --calendar "<日历>"

• DTSTART;VALUE=DATE:YYYYMMDD表示全天事件；DTSTART:YYYYMMDDTHHmmSS表示定时事件。
• RRULE:FREQ=YEARLY— 表示每年重复。此外：每日、每周、每月。
• TRANSP:TRANSPARENT— 空闲；TRANSP:OPAQUE— 忙碌（默认）。
• 一次导入调用对应一个事件（一个VEVENT块）。如需导入多个事件，请运行独立的管道导入。
• 添加--reminder "时间"标志来设置提醒（这会覆盖ICS文件中的任何VALARM设置）。
• 所有导入专用标志（--use-legacy-import、--verbose等）应放在import.

删除（需进行删除后验证）

• 通过日程查找（首选方法）：
  • gcalcli --nocolor agenda <开始日期> <结束日期>（具体日期）
  • gcalcli --nocolor agenda today +14d（工作日）
  • gcalcli --nocolor agenda today +30d（仅表意）
• 删除（非交互式，限定范围）：
  • gcalcli --nocolor delete --iamaexpert "<查询内容>" <开始时间> <结束时间>
• 验证（同一窗口）：
  • gcalcli --nocolor agenda <开始日期> <结束日期>
• 若事件仍存在，可选择性重试一次：
  • gcalcli --nocolor --refresh agenda <开始日期> <结束日期>

编辑 / 修改现有事件

• gcalcli edit是交互式命令——无法在非交互式执行中使用。
• 若要修改无法就地编辑的属性：删除 + 重新创建该事件。
  • 查找 → 删除（使用--iamaexpert参数）→ 使用更新后的属性重新创建 → 验证。
• 对于批量属性更改（例如将所有事件设置为空闲）：对每个事件迭代执行删除+重新创建操作。