介绍
# gcalcli-calendar
使用 `gcalcli` 以最少的工具调用和最少的输出读取/搜索/管理 Google Calendar。
## 规则
### CLI 标志位置（关键） - 全局标志（`--nocolor`、`--calendar`）位于子命令之前。 - 子命令特定标志位于子命令名称之后。 - 示例：`gcalcli --nocolor delete --iamaexpert "query" start end` —— 而不是 `gcalcli --nocolor --iamaexpert delete ...`。 - 这适用于所有子命令标志：`--iamaexpert`（delete）、`--noprompt`/`--allday`（add）、`--use-legacy-import`（import）等。
### 输出与语言 - 除非用户明确要求（例如“显示使用的命令”、“/debug”、“/commands”），否则不要打印 CLI 命令/标志/工具详细信息。 - 如果被要求显示命令：按顺序打印所有执行的命令（包括重试），不打印其他内容。 - 不要在同一个回复中混合语言。 - 简明扼要。除非未找到任何内容，否则不显示范围。
### 日期与格式 - 默认使用人类友好的日期格式。仅在明确要求时使用 ISO 格式。 - 除非需要消除歧义，否则不要给活动标题加引号。
### 日历范围 - 信任 gcalcli 配置（默认/忽略的日历）。除非用户要求“跨所有日历”或结果明显错误，否则不要扩大范围。
### 日程（默认仅限今天） - 如果用户在没有指定时间段的情况下询问“agenda”，则仅返回今天的内容。 - 仅在明确要求时扩展（明天 / 接下来的 N 天 / 日期范围）。
### 工作日请求（无需心算） 如果用户说“在周一/周二/...”但没有指定日期： 1) 获取接下来 14 天的议程一次， 2) 从工具输出中挑选匹配的日期/事件， 3) 继续操作（如果有多个匹配，则进行消除歧义）。
### 查找事件：优先使用确定性日程扫描（语义优先） 当定位要取消/删除/编辑的事件时： - 优先使用 `agenda` 而不是 `search`。 - 使用有界的窗口并通过含义（语义匹配）而不是精确文本来匹配事件。 - 默认定位窗口： - 如果用户给出了确切日期：仅扫描那一天。 - 如果用户给出了星期几：扫描接下来的 14 天。 - 如果用户仅给出了含义词（“火车”、“讲座”等）而没有日期：首先扫描接下来的 30 天。 - 如果仍未找到：扩展到 180 天，且只有在仍然没有结果时才说明。
仅在以下情况下将 gcalcli `search` 作为备用方案： - 时间窗口太大，无法通过议程扫描（消耗大量 token），或者 - 用户明确要求“搜索”。
### 搜索（有界） - 默认搜索窗口：接下来约 180 天（除非用户另有指定）。 - 如果没有匹配项：说明“在接下来约 6 个月内（<from>-><to>）未找到匹配项”并提供扩大范围的选项。 - 仅在未找到任何内容时显示范围。
### 工具效率 - 默认：使用 `--nocolor` 以减少格式噪音和 token。 - 仅在必须解析/去重/排序时才使用 `--tsv`。
## 操作策略（为对话速度优化）
该技能专为个人助理使用而设计，用户期望快速、低摩擦的日历管理。以下确认策略是有意的 UX 选择——有关基本原理和安全保障，请参阅 README.md。
### 明确的操作：立即执行 对于取消/删除/编辑操作，当满足以下所有条件时跳过确认： - 用户明确请求了该操作（例如“删除我的牙医预约”）。 - 在严格的时间窗口内仅有一个事件匹配。 - 匹配是明确的（确切日期上的单一清晰结果，或用户指定了日期+时间）。
### 模糊的操作：始终先询问 如果有多个候选匹配，或者匹配不确定： - 提出一个简短的消除歧义问题，列出候选项（1-3 行），并等待用户的选择。
### 创建事件：重叠检查必须是跨日历的（非忽略范围） 创建事件时： - 始终通过扫描不带 `--calendar` 的议程，在所有非忽略日历上运行尽力而为的重叠检查。 - 这确保即使将新事件创建到特定日历中也能检测到重叠。 - 如果与忙碌事件存在重叠： - 创建前请求确认。 - 如果没有重叠： - 立即创建。
### 选择正确的创建方法 - **`add`** —— 单次事件的默认方法。支持 `--allday`、`--reminder`、`--noprompt`。不支持重复或忙/闲（透明度）。 - **`import` via stdin** —— 仅在需要重复（RRULE）或忙/闲（TRANSP:TRANSPARENT）时使用。通过 stdin 管道传输 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 <start> <end>`
### 搜索（备用 / 显式请求） - 默认（~6 个月）：`gcalcli --nocolor search "<query>" today +180d` - 自定义：`gcalcli --nocolor search "<query>" <start> <end>`
### 创建 — `add`（单次事件） - 重叠预检（严格，跨日历）： - `gcalcli --nocolor agenda <start> <end>` - 重要：此处不要添加 `--calendar`；必须跨所有非忽略日历检查重叠。 - 定时事件： - `gcalcli --nocolor --calendar "<Cal>" add --noprompt --title "<Title>" --when "<Start>" --duration <minutes>` - 全天事件： - `gcalcli --nocolor --calendar "<Cal>" add --noprompt --allday --title "<Title>" --when "<Date>"` - 带提醒（可重复标志）： - `--reminder "20160 popup"` → 14 天前（20160 = 14×24×60） - `--reminder "10080 popup"` → 7 天前 - `--reminder "0 popup"` → 事件开始时 - 时间单位后缀：`w`（周）、`d`（天）、`h`（小时）、`m`（分钟）。无后缀 = 分钟。 - 方式：`popup`（默认）、`email`、`sms`。
### 创建 — `import` via stdin（重复 / 忙/闲） 仅当 `add` 无法满足需求时（重复事件、TRANSP 等）使用。 通过 stdin 直接管道传输 ICS —— 切勿写入临时文件。 ``` echo 'BEGIN:VCALENDAR VERSION:2.0 BEGIN:VEVENT DTSTART;VALUE=DATE:20260308 SUMMARY:Event Title RRULE:FREQ=YEARLY TRANSP:TRANSPARENT END:VEVENT END:VCALENDAR' | gcalcli import --calendar "<Cal>" ``` - `DTSTART;VALUE=DATE:YYYYMMDD` 用于全天；`DTSTART:YYYYMMDDTHHmmSS` 用于定时。 - `RRULE:FREQ=YEARLY` — 每年重复。还有：`DAILY`、`WEEKLY`、`MONTHLY`。 - `TRANSP:TRANSPARENT` — 空闲；`TRANSP:OPAQUE` — 忙碌（默认）。 - 一次导入调用 = 一个事件（一个 VEVENT 块）。对于多个事件，运行单独的管道导入。 - 添加 `--reminder "TIME"` 标志以设置提醒（覆盖 ICS 中的任何 VALARM）。 - 所有导入特定标志（`--use-legacy-import`、`--verbose` 等）位于 `import` 之后。
### 删除（带删除后验证） - 通过日程定位（首选）： - `gcalcli --nocolor agenda <dayStart> <dayEnd>`（确切日期） - `gcalcli --nocolor agenda today +14d`（工作日） - `gcalcli --nocolor agenda today +30d`（仅含义） - 删除（非交互式，有界）： - `gcalcli --nocolor delete --iamaexpert "<query>" <start> <end>` - 验证（同一窗口）： - `gcalcli --nocolor agenda <dayStart> <dayEnd>` - 可选的一次重试（如果仍然存在）： - `gcalcli --nocolor --refresh agenda <dayStart> <dayEnd>`
### 编辑 / 修改现有事件 - `gcalcli edit` 是交互式的 —— 不能在非交互式 exec 中使用。 - 要更改无法就地编辑的属性：**删除 + 重新创建**事件。 - 定位 → 删除（使用 `--iamaexpert`）→ 使用更新后的属性创建 → 验证。 - 对于批量属性更改（例如将所有事件设置为空闲）：逐个事件迭代删除+重新创建。