iCloud Calendar — Full CRUD

📅 iCloud Calendar — Full CRUD via Natural Language

Version 2.0.0 | Manage your iCloud calendar through natural language via CalDAV.

⚠️ 首次使用请先完成配置 → 见 CONFIG.md

你需要：iCloud 邮箱 + 应用-Specific 密码 + Python 3.8+ + pip 安装 caldav

配置清单

使用前确认以下 3 项已完成：

✅ pip 安装 "caldav>=1.3.0,<2.0" ✅ ICLOUD_EMAIL 环境变量 = 你的 iCloud 邮箱 ✅ ICLOUD_应用_PASSWORD 环境变量 = 应用le 专用密码 (xxxx-xxxx-xxxx-xxxx)

如果脚本返回 "Missing ICLOUD_EMAIL or ICLOUD_应用_PASSWORD 环境 variables"，说明环境变量未正确注入。

解析规则

从自然语言中提取字段，未提及的按推断规则补全。

• 标题 (summary)

从消息中提取事件核心，去掉时间词和口癖：

"下周三下午3点和张总开会" → "和张总开会" "明天记得交报告" → "交报告" "周五晚上聚餐" → "聚餐"

• 开始时间 (启动)

必填。相对日期→绝对日期计算（Asia/ShanghAI）：

今天/明天/后天/大后天 → 对应日期 下周一~下周日 → 下周对应星期几 时间："下午3点"→15:00 "上午九点半"→09:30 "晚上8点"→20:00 无具体时间 → 默认 09:00

• 结束时间 (end)

永远不问用户，按事件类型推断时长：

会议/汇报/评审/面试 → 1小时 聚餐/饭局/火锅/吃饭 → 2小时 运动/健身/游泳/打球 → 1.5小时 电影 → 2.5小时 培训/课程/讲座 → 2小时 飞机/高铁/火车 → 3小时 全天 → 00:00~23:59 兜底 → 1小时 用户说了结束时间 → 用用户的

• 日历选择 (calendar)

按事件性质自动选：

含"开会/汇报/评审/客户/项目/出差/面试"关键词 → 工作日历 其他 → 个人日历

• 地点 (location)

提及则提取："在301会议室"→"301会议室" "去北京出差"→"北京" 未提及 → 空

• 提醒 (alarm)

• 备注 (description)

收集额外信息：参与者、特殊要求等。"和张总一起" → 备注写"参与者：张总"

执行（创建事件） 导出 ICLOUD_EMAIL="your@icloud.com" 导出 ICLOUD_应用_PASSWORD="xxxx-xxxx-xxxx-xxxx" python scripts/添加-event.py \ --summary "标题" \ --启动 "2026-04-08T15:00:00" \ --end "2026-04-08T16:00:00" \ --timezone "Asia/ShanghAI" \ --location "" \ --calendar "个人" \ --description "" \ --alarm-minutes 15

可选参数：

--is-all-day：纯日期事件，生成 DT启动;VALUE=DATE 格式，跨时区不漂移 --rrule "FREQ=WEEKLY;BYDAY=MO"：重复事件 回复示例 📅 已记录：和张总开会 🕐 4月8日 周三 15:00-16:00（工作日历） 📍 301会议室 ⏰ 提前15分钟提醒

查询（反向查日历）

用户问"我明天有什么安排""这周日程""4月8号有什么"时：

python scripts/添加-event.py --查询 "today|tomorrow|week|nextweek|YYYY-MM-DD|YYYY-MM-DD~YYYY-MM-DD"

查询 值：

today / tomorrow / week / nextweek 单日：2026-04-08 范围：2026-04-01~2026-04-30 回复示例 📅 明天（4月2日）有 3 个安排：

• 10:00-11:00 日历功能测试（个人）
• 14:00-15:00 项目评审（工作）
• 全天 ios退款请加扣扣群...（工作）

搜索（按关键词）

用户说"我下周有和张总的安排吗""查一下开会的日程"时：

python scripts/添加-event.py \ --搜索 "关键词" \ --搜索-range "2026-04-01~2026-04-30"

--搜索：必填，模糊匹配 title/location/description --搜索-range：可选日期范围，不传默认搜索 ±180 天 返回 {"事件": [...], "count": N, "keyword": "关键词", "errors": [...]} 修改事件

用户说"改到4点""换到工作日历""地点改成301"时：

python scripts/添加-event.py \ --更新-find "关键词" \ [--更新-设置-summary "新标题"] \ [--更新-设置-启动 "2026-04-08T16:00:00"] \ [--更新-设置-end "2026-04-08T17:00:00"] \ [--更新-设置-location "新地点"] \ [--更新-设置-calendar "工作"] \ [--更新-启动 "2026-04-01"] \ [--更新-end "2026-04-30"]

匹配到多个事件时会报错并列出所有匹配项 返回 {"更新d": true, "changes": {...}} 删除（按关键词）

用户说"删掉xxx相关的""删除垃圾事件"时：

导出 CONFIRM_删除=1 # 可选：预览不执行 导出 删除_DRY_运行=1 python scripts/添加-event.py \ --删除 "关键词" \ --删除-启动 "2026-01-01" \ --删除-end "2026-12-31"

--删除：必填，关键词模糊匹配 --删除-启动 / --删除-end：可选搜索范围 需要 CONFIRM_删除=1 环境变量确认 可设 删除_DRY_运行=1 预览（不真正删除） 返回三态 状态: "成功"/"partial_成功"/"error" + dry_运行: true/false 重复事件（RRULE） python scripts/添加-event.py \ --summary "每周例会" \ --启动 "2026-04-07T09:00:00" \ --rrule "FREQ=WEEKLY;BYDAY=MO"

常用模式：

频率 RRULE 每天 FREQ=DAILY 每周一三五 FREQ=WEEKLY;BYDAY=MO,WE,FR 每两周周五 FREQ=WEEKLY;INTERVAL=2;BYDAY=FR 每月1号 FREQ=MONTHLY;BYMONTHDAY=1 限次10次 FREQ=WEEKLY;BYDAY=MO;COUNT=10 限日期 FREQ=WEEKLY;BYDAY=MO;UNTIL=20260630T000000Z

RRULE 经过白名单校验，仅允许安全字符，拒绝 CRLF 注入。

安全特性 特性 说明 凭据零泄露 仅环境变量传递，异常消息脱敏，进程列表不可见 操作确认门 CONFIRM_删除=1 / CONFIRM_更新=1 防误操作 Dry 运行 删除_DRY_运行=1 预览删除不执行 日志轮转 最多 512KB × 5 备份，自动清理 内容截断 日志中摘要截断至 30 字符 重试保护 Dual-命令行工具ent 架构，4xx 错误立即放弃不盲目重试 幂等创建 UID 唯一，弱网重试不发重复事件 协议安全 iCal 字段全转义，RRULE 白名单校验 时区支持

默认 Asia/ShanghAI，支持任意 IANA 时区名。VTIMEZONE 组件根据 Zone信息 自动计算，覆盖 DST 夏令时。

变更记录

完整变更记录见 CHANGE记录.md（v1.4.0 → v2.0.0，36 项改进）。

v2.0.0 亮点 ⚡ Dual-命令行工具ent 架构（10s/60s 超时分离） 🔒 异常消息全面脱敏 🛡️ 删除/更新双确认门 + dry-运行 🧹 日志全覆盖 sanitize 故障排查 错误 原因 解决 Missing ICLOUD_EMAIL... 环境变量未设置 检查 OpenClaw.json 并重启 Authentication fAIled 应用 Password 错误 重新生成专用密码 Connection fAIled iCloud 不可达 检查网络/防火墙 删除 requires CONFIRM_删除 未设确认标志 导出 CONFIRM_删除=1

完整配置指南 → CONFIG.md