用途
automating-calendar 是一个 macOS 日历自动化技能，聚焦于日历事件、日历和 EventKit 桥接功能。它通过 JXA（JavaScript for Automation）配合 AppleScript 字典发现来操作 macOS 日历，同时提供 PyXA 和 PyObjC/EventKit 的 Python 方案。该技能与通用的 macOS 自动化技能 automating-mac-apps 相关联：后者负责通用应用权限、shell 命令、UI 脚本和跨应用自动化模式，而本技能专门处理日历相关操作。
主要能力
- 使用 JXA 创建日历事件，设置标题、开始时间、结束时间等属性。
- 通过 PyXA 以更简洁的 Python 语法创建事件，可设置地点等字段。
- 通过 PyObjC 与 EventKit 桥接进行高级查询，例如按日期范围查询事件。
- 使用 EventKit 实现带重复规则的事件创建、时区处理、例外/发生实例查询以及取消单次发生等高级模式。
- 支持批量读取，避免使用重量级的 .whose() 查询。
使用方式
默认工作流：
- 在 Script Editor 中发现 Calendar 字典术语。
- 用最小 AppleScript 命令做原型验证。
- 移植到 JXA，并加入防御式错误处理。
- 实现批量读取（避免重量级 .whose()）。
- 加入 EventKit 桥接以支持高级查询。
- 用示例事件测试并验证结果。
错误处理要求：将操作包裹在 try-catch 中；验证日历访问（Calendar.calendars.length > 0）；检查事件创建是否成功（如 if (!event.id()) throw new Error('Event creation failed')）；记录操作日志以便调试。
验证清单：日历权限已授予（系统设置 > 隐私与安全性 > 日历）；确认日历可访问；事件具有有效的开始/结束日期；保存后事件在日历 UI 中可见；EventKit 桥接查询返回预期结果；所有操作被错误处理包裹；输出与预期事件属性匹配。
核心示例覆盖：基础事件创建（JXA 旧版与 PyXA 推荐方式）、PyObjC 配合 EventKit 创建事件、EventKit 桥接查询（JXA 旧版与 PyObjC 现代方式）。
适用场景
- 在 macOS 上批量或脚本化创建日历事件。
- 按日期范围查询日历事件。
- 需要重复规则、时区、例外/发生实例等高级 EventKit 功能。
- 希望用 Python（PyXA 或 PyObjC）而非 JavaScript 自动化日历。
限制
- 不适用于跨平台日历自动化（应使用 Google Calendar API 或 CalDAV）。
- 不适用于 iCloud 同步操作（应直接使用 EventKit）。
- 不支持非 macOS 平台。
- 对于纯 AppleScript 即可完成的简单任务，可跳过 JXA 的复杂性。
- 日历共享或权限管理应使用日历 UI。
- 使用 PyXA 示例前需参考 automating-mac-apps 技能中的 PyXA 安装说明。
可加载的参考文件
- calendar-basics.md：Calendar JXA 基础。
- calendar-recipes.md：事件、闹钟、重复规则配方。
- calendar-advanced.md：时区、批量读取、EventKit 桥接等高级模式。
- calendar-dictionary.md：字典翻译表。
- calendar-pyxa-api-reference.md：PyXA API 参考（完整类/方法文档）。
- eventkit-query.md：EventKit 查询示例。
- eventkit-create.md：带重复的 EventKit 创建。
- eventkit-timezones.md：EventKit 时区示例。
- eventkit-exceptions.md：EventKit 例外/发生实例。
- eventkit-occurrence-cancel.md：EventKit 取消单次发生示例。