iCalendar 同步

使用此技能，可让 OpenClaw 智能体执行 iCloud 日历的增删改查（CRUD）操作。

1. 安全地准备凭据

仅使用应用专用密码（App-Specific Password），切勿使用主 Apple ID 密码。

优先使用 keyring 存储：

python -m icalendar_sync setup --username user@icloud.com

如需自动化部署，请使用非交互式设置：

export ICLOUD_USERNAME="user@icloud.com"
export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
python -m icalendar_sync setup --non-interactive

仅当 keyring 不可用时（例如无图形界面或 GUI 受限的运行环境），才使用文件存储：

python -m icalendar_sync setup --non-interactive --storage file --config ~/.openclaw/icalendar-sync.yaml

2. 明确选择同步提供者

• --provider auto：macOS 使用原生桥接（native bridge），非 macOS 系统使用 CalDAV。
• --provider caldav：强制直连 iCloud CalDAV 服务。
• --provider macos-native：强制通过 Calendar.app 桥接（仅限 macOS）。

如需 CalDAV 调试信息，请添加以下参数：

--debug-http --user-agent "your-agent/1.0"

3. 执行日历操作

列出所有日历：

python -m icalendar_sync list

获取指定日历中的事件（未来 7 天）：

python -m icalendar_sync get --calendar "Personal" --days 7

创建事件：

python -m icalendar_sync create --calendar "Personal" --json '{
  "summary": "Meeting",
  "dtstart": "2026-02-15T14:00:00+03:00",
  "dtend": "2026-02-15T15:00:00+03:00"
}'

更新事件（简单模式）：

python -m icalendar_sync update --calendar "Personal" --uid "event-uid" --json '{"summary":"Updated title"}'

更新重复事件的某一个实例：

python -m icalendar_sync update 
  --calendar "Work" 
  --uid "series-uid" 
  --recurrence-id "2026-03-01T09:00:00+03:00" 
  --mode single 
  --json '{"summary":"One-off change"}'

重复事件更新支持的模式：

• single：仅更新单个实例（需指定 --recurrence-id）
• all：更新整个重复系列
• future：将系列拆分为两段，并更新当前实例及其后续所有实例（需指定 --recurrence-id）

删除事件：

python -m icalendar_sync delete --calendar "Personal" --uid "event-uid"

4. 输入契约（Input Contract）

对于 create 操作，至少需提供以下字段：

• summary（字符串）
• dtstart（ISO 格式日期时间）
• dtend（ISO 格式日期时间，且必须晚于 dtstart）

可选字段包括：

• description
• location
• status
• priority（取值范围：0–9）
• alarms
• rrule

5. 安全规则

• 校验日历名称，拒绝含路径特征的输入（如包含 /、.. 等）。
• 确保凭据信息不出现在日志或标准输出中。
• 优先选用 keyring 存储，而非文件存储。
• 若必须使用文件存储，则须严格限制文件权限（应设为 0600）。

6. 故障处理

若在 macOS 上使用 auto 或 caldav 提供者时发生 CalDAV 认证或网络错误，则自动切换至 macos-native 提供者，并重试相同操作。

若 JSON 负载以文件路径形式传入，请在解析前确认该文件大小处于安全范围内。