精选案例 · Agent 自动化 / 知识库与文档

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

本项目通过CalDAV协议和Hermes AI Agent，实现从自然语言指令自动向iCloud日历添加日程的功能。使用Python（requests+pytz）手写WebDAV客户端，完成身份发现、日历列表获取、事件创建等步骤，支持时区设置和多日历选择，最终实现全设备同步的'一句话加日程'体验。

案例速读

项目文档完整，提供了从背景、原理到具体代码的闭环。CalDAV的实现细节（如必须用PUT而非POST、默认日历不可写、行尾CRLF等）都是实际踩坑后的经验，极具参考价值。附带可运行的Python脚本，降低了复现门槛，对想实现AI自动写入苹果日历的开发者是高质量参考资料。建议从「iCloud CalDAV：AI Agent 自动添加苹果日历日程」、「背景」、「AI 工具」、「实现原理」进入正文，先确认真实任务和模型辅助过程。

重点看 CalDAV协议与iCloud交互的完整实现、自然语言到日程结构化解析的流程设计、Python手写WebDAV客户端（PROPFIND、PUT）。结合 Agent 自动化 / 知识库与文档 / 自然语言解析 / 日历集成和「开发者、AI爱好者、苹果用户」，它更适合作为任务检索后的精读材料。
正文目录和原始材料仍然是判断依据；导读只帮助你更快定位阅读重点。

首读入口: 背景
读者: 开发者、AI爱好者、苹果用户
复用: CalDAV协议与iCloud交互的完整实现
结构: 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 — 完整实现，开箱即用。

返回顶部