精选案例 · Agent / 实践案例

iCloud CalDAV：AI Agent 自动添加苹果日历日程

这个案例围绕「iCloud CalDAV：AI Agent 自动添加苹果日历日程」记录了一条真实 AI 实践线索，正文重点集中在「背景」「AI 工具」，适合先按任务意图阅读再判断复用。

案例速读

README 标题「iCloud CalDAV：AI Agent 自动添加苹果日历日程」下已经出现运行/配置路径、脚本或接口线索，正文重点集中在「背景」「AI 工具」，比纯概念介绍更适合进入精选阅读流。这篇案例的阅读价值在于，它把真实任务、模型辅助过程和可迁移做法放在同一个上下文里，读者可以从「iCloud CalDAV：AI Agent 自动添加苹果日历日程」、「背景」、「AI 工具」、「实现原理」进入正文。

建议重点看可参考其中的运行与配置路径、包含可迁移的命令、脚本或接口线索、继续补充结果证据后推荐度会更高。结合 Agent / 实践案例和「任务驱动用户、AI 实践者」这一受众定位，它更适合作为任务检索后的精读材料，而不是只看一句短摘要后快速跳过。
正文目录和原始材料仍然是判断依据；导读只帮助你更快定位阅读重点。

看点: iCloud CalDAV：AI Agent 自动添加苹果日历日程
读者: 任务驱动用户、AI 实践者
复用: 可参考其中的运行与配置路径
结构: 10 个目录入口

原文内容

iCloud CalDAV：AI Agent 自动添加苹果日历日程

通过 CalDAV 协议让 AI 助手直接往 iCloud 日历写事件，自然语言即日程

背景

日常工作中经常需要添加日程：会议、截止日期、提醒事项。手动打开日历 → 点新建 → 填时间 → 填标题，一套操作下来至少 4-5 步。

如果 AI 助手能直接从对话里抓取时间信息，自动往 iCloud 日历写事件，就能实现"说一句就安排好"的体验。

AI 工具

Hermes Agent（自托管 AI 助手）— 驱动工作流
Python（requests + pytz）— 实现 CalDAV 协议交互
Apple iCloud CalDAV — 苹果日历后端

实现原理

iCloud 日历支持 CalDAV 协议（WebDAV 扩展），可以通过标准的 HTTP 请求进行操作。整体流程：

用户说"明天下午3点开会"
    ↓
Hermes Agent 解析自然语言 → {title, start, end}
    ↓
CalDAV PROPFIND 发现用户身份和日历列表
    ↓
PUT iCalendar (.ics) 文件到目标日历
    ↓
iCloud 日历同步到所有设备 ✅

关键实现细节

1. 身份发现

用 WebDAV 的 PROPFIND 请求发现用户 principal 和 calendar home：

# 发现 principal URL
PROPFIND / → current-user-principal
# 发现日历集合
PROPFIND /principal/ → calendar-home-set

2. 创建事件用 PUT，不是 POST

iCloud 要求用 PUT 写入 .ics 文件，POST 会返回 501 Not Implemented。文件名用事件的 UID：

PUT /<user-id>/calendars/home/<uid>.ics
Content-Type: text/calendar; charset=utf-8
If-None-Match: *

3. 默认日历不能直接写

iCloud 的默认个人日历（“Feng Wang”）不接受 PUT 写入（返回 400）。需要写到命名子日历：Home、Work 或自定义日历。

4. 时区处理

所有时间用 Asia/Shanghai 时区，iCalendar 格式中通过 TZID 参数指定：

DTSTART;TZID=Asia/Shanghai:20260516T150000
DTEND;TZID=Asia/Shanghai:20260516T160000

使用方式

脚本用法：

python3 add_event.py --summary "开会" --start "2026-05-16 15:00" --duration 60

python3 add_event.py --summary "讨论Q3计划" \
  --start "2026-05-16 15:00" \
  --end "2026-05-16 16:00" \
  --location "会议室A" \
  --description "讨论Q3路线图"

python3 add_event.py --list-calendars    # 查看可用日历

环境变量配置

变量	说明
`CALDAV_URL`	`https://caldav.icloud.com/`
`CALDAV_USERNAME`	Apple ID 邮箱
`CALDAV_PASSWORD`	App-Specific Password
`CALDAV_CALENDAR_NAME`	目标日历名称（默认 Home）

Apple ID 密码不行，需要去 https://appleid.apple.com/ 生成 App-Specific Password（应用专用密码）。

效果

一句话加日程：说"明天下午3点开会" → 自动写入日历
全设备同步：写入 iCloud 后 iPhone、Mac、iPad 自动出现
零第三方依赖：只用 Python 标准库 + requests + pytz

心得与建议

App-Specific Password 是必须的 — Apple ID 密码不能用于 CalDAV，必须生成专用密码
If-None-Match: * 不能少 — 不加这个头 iCloud 可能拒绝新建事件
行尾必须 CRLF — iCloud CalDAV 要求 \r\n 换行，\n 会静默失败
用 requests 替代 caldav 库 — caldav 依赖的 niquests 在某些环境有兼容性问题，手写 WebDAV 更可靠
自然语言解析是瓶颈 — 时间表达的灵活性决定了体验上限，建议用 LLM 做 NL → 结构化时间转换

脚本

add_event.py — 完整实现，开箱即用。

返回顶部