quick-gcalcli

使用 gcalcli 以最少的工具调用和最少的输出读取、搜索、管理 Google 日历。

快速配置

在使用本技能前，请参考该技能目录下的 README.md 文件，获取详细的配置说明。配置流程包括安装 gcalcli、配置 OAuth2 凭据，以及设置默认日历和时区。

规则

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 配置（默认日历 / 忽略日历列表）；除非用户明确要求“跨所有日历”查询，或当前结果明显错误，否则不得擅自扩大作用域。

日程表（默认仅限今日）

• 若用户仅说“日程表”而未指定时间范围，则仅返回今日日程。
• 仅在用户明确要求时扩展范围（如“明天”、“未来 N 天”、“某日期区间”）。

工作日请求（禁止心算）

若用户仅说“在周一/周二/……”而未提供具体日期：

1. 一次性获取未来 14 天的日程表（agenda）；
2. 从工具输出中选取匹配的工作日或事件；
3. 继续执行操作；若存在多个匹配项，则需先向用户澄清。

查找事件：优先采用确定性日程扫描（语义优先）

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

• 优先使用 agenda 而非 search。
• 使用有界时间窗口，并基于语义（而非精确文本）匹配事件。
• 默认定位窗口如下：
  • 若用户提供确切日期：仅扫描该日。
  • 若用户提供工作日（如“周一”）：扫描未来 14 天。
  • 若用户仅提供语义关键词（如“火车”、“讲座”等）且无日期：首先扫描未来 30 天。
  • 若仍无结果：再扩展至未来 180 天，并仅在最终仍为空时说明此扩展行为。

仅在以下情况将 gcalcli search 作为回退方案使用：

• 时间窗口过大，导致通过 agenda 扫描开销过高（token 消耗大）；或
• 用户明确要求执行“搜索”操作。

搜索（有界）

• 默认搜索窗口：未来约 180 天（除非用户另行指定）。
• 若无匹配结果：提示“未来约 6 个月内无匹配（ 至 ）”，并主动提供扩展选项。
• 仅在未找到任何结果时才说明搜索范围。

工具效率

• 默认启用 --nocolor 以减少格式化噪声及 token 消耗。
• 仅在必须解析/去重/排序时才使用 --tsv。

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

本技能专为个人助理场景设计，用户期望获得快速、低摩擦的日历管理体验。下方确认策略是刻意为之的用户体验设计——详见 README.md 中的原理说明与安全防护机制。

明确无歧义的操作：立即执行

对于取消/删除/编辑类操作，在同时满足以下全部条件时跳过确认步骤：

• 用户明确提出了该操作请求（例如：“删除我的牙医预约”）。
• 在紧凑时间窗口内恰好匹配到一个事件。
• 匹配结果明确无歧义（例如：在确切日期上仅有一个清晰结果；或用户已明确指定了日期+时间）。

存在歧义的操作：必须先询问

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

• 提出简短的消歧问题，列出候选事件（控制在 1–3 行），并等待用户选择。

创建事件：冲突检测必须跨日历（非忽略范围）

创建新事件时：

• 始终通过不带 --calendar 参数的 agenda 扫描，尽最大努力在所有非忽略日历中执行冲突检测。
  • 此举确保即使新事件被创建到特定日历中，也能检测到其他日历中的忙碌时段冲突。
• 若检测到与忙碌事件存在时间冲突：
  • 创建前须向用户请求确认。
• 若无冲突：
  • 立即创建。
• 添加任意事件前，均须检查是否存在同名、同时间段的已有事件，以防重复。

选择合适的创建方式

• add —— 单次性事件的默认方式。支持 --allday、--reminder、--noprompt；但不支持重复规则（RRULE）或空闲/忙碌状态（TRANSP）。
• import（通过 stdin） —— 仅在需要重复规则（RRULE）或空闲/忙碌状态（TRANSP:TRANSPARENT）时使用。直接通过 stdin 管道传入 ICS 内容；切勿写入临时 .ics 文件（exec sandbox 中工作目录不可靠）。
• quick —— 除非用户明确要求自然语言添加，否则应避免使用。其确定性较低。

删除操作必须验证

• 使用非交互式删除参数 --iamaexpert（这是 delete 子命令的参数，必须置于 delete 之后）。该参数是 gcalcli 内置的非交互/脚本化删除标志。
• 删除后，必须在同一紧凑时间窗口内再次通过 agenda 进行验证。
• 若验证仍显示该事件存在，则使用 --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 ""

创建 —— add（单次性事件）

• 冲突预检（紧凑、跨日历）：
  • gcalcli --nocolor agenda
  • 重要：此处严禁添加 --calendar；冲突检测必须覆盖所有非忽略日历。
• 定时事件：
  • gcalcli --nocolor --calendar "" add --noprompt --title "