iCalendar 同步

使用此技能从 OpenClaw 代理执行 iCloud 日历的增删改查操作。

1. 安全准备凭证

仅使用应用专用密码（切勿使用主 Apple ID 密码）。

首选密钥环存储：

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

仅在密钥环不可用时（无头或 GUI 受限的运行时环境）使用文件存储：

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

2. 审慎选择提供程序

• --provider auto：macOS 使用原生桥接，非 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

获取事件：

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. 输入约定

对于create操作，至少需要：

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

可选字段：

• 描述
• 地点
• 状态
• 优先级(0-9)
• 提醒
• 重复规则

5. 安全规则

• 验证日历名称；拒绝类似路径的负载。
• 确保日志/输出中不包含凭证材料。
• 优先使用密钥环而非文件存储。
• 如果必须使用文件存储，强制执行严格的文件权限（0600）。

6. 故障处理

如果在 macOS 上 CalDAV 认证/网络失败，且提供者为自动/caldav，则切换到macos-原生并重试同一操作。

如果JSON有效载荷是以文件路径形式提供，请在解析前确保文件大小保持在安全限制内。