macOS Calendar Assistant

核心用法

macos-calendar-assistant 是一套面向 macOS 用户的 Calendar.app 自动化工具集，专为 IM-first 工作流设计（支持 Telegram、Discord、飞书、iMessage、Slack 等场景）。其核心能力包括：

1. 智能提取：从聊天截图或消息文本中解析日程信息（标题、时间、时区、地点、备注等），自动识别用户意图与对方约束条件。
2. 幂等操作：通过 upsert_event.py 实现创建/更新/跳过判断，避免重复写入，支持 --dry-run 预览。
3. 冲突管理：写入前自动调用 list_events.swift 检测时段占用，支持显式覆盖（需用户确认）或警告提示。
4. 灵活调度：支持移动/延长/改期（move_event.swift、幂等更新），可设置提醒闹钟（set_alarm.py），并智能路由至对应日历（Training/Work/Product/Life）。
5. 卫生维护：提供重复事件扫描清理（calendar_clean.py）、近两小时事件快查（within_2h.py）、每日自动检查通知等辅助工具。

显著优点

• 深度系统集成：直接调用 EventKit，原生支持 iCloud/CalDAV/本地日历，权限受 macOS 沙盒管控。
• 工作流闭环：从 IM 消息→解析→冲突检查→写入→提醒→复盘同步，形成完整日程管理链路。
• 容错设计：幂等写入、dry-run 预览、快照备份（--snapshot-out），降低误操作风险。
• 智能路由：内置分类映射规则，自动选择目标日历，减少用户决策负担。

潜在局限

• 平台锁定：仅限 macOS，依赖 EventKit 框架与 Calendar 权限，Windows/Linux 用户无法使用。
• 脚本依赖：需本地安装 Swift/Python3 环境，部分命令依赖特定脚本文件路径。
• 时区处理：默认回退 Asia/Shanghai，跨时区协作场景需用户显式指定。
• 语义理解边界：截图/消息解析基于启发式规则，复杂排版或非标准表达可能误识别。

适合人群

• macOS 重度用户，习惯在 IM 中协调日程
• 需要快速将聊天中的会议安排同步至系统日历的职场人士
• 追求日历整洁、关注重复事件清理的效率爱好者
• 开发者/自动化爱好者，希望将日历操作脚本化、流水线化

常规风险

• 权限风险：需授予 Calendar 完全访问权限，脚本理论上可读取/修改全部日历数据（尽管代码意图明确）。
• 误操作覆盖：--apply 与 --confirm yes 组合会直接执行删除/修改，建议始终先 dry-run。
• 时区歧义：未明确指定时区时可能因默认回退导致跨区会议时间错位。
• 外部依赖：脚本运行依赖本地 Python/Swift 环境及配置文件完整性，环境异常可能导致操作失败。

核心用法

macos-calendar-assistant 是一款专为 macOS 设计的本地日历管理 Skill，通过 Python 与 Swift 脚本调用系统 EventKit 框架，实现与 Calendar.app 的深度集成。用户可通过 Telegram、Discord、飞书、iMessage、Slack 等 IM 工具直接对话操作日历，支持从聊天截图中智能提取日程信息，自动识别时间、地点、参与人等关键字段。

该 Skill 采用幂等写入机制，通过 upsert_event.py 实现创建/更新/跳过的一致性操作，避免重复事件。核心工作流包括：提取事件要素 → 冲突检测（list_events.swift）→ 幂等写入 → 设置提醒 → 定期清理重复。同时支持事件移动、延期、调整时长、每日回顾同步等进阶功能，并可通过 Cron 实现自动化通知。

显著优点

1. 纯本地零依赖：仅使用 Python 标准库与系统 Swift 环境，无第三方包，杜绝供应链攻击风险
2. IM-first 设计：深度适配即时通讯场景，支持从聊天截图和消息中提取日程，符合现代工作流
3. 智能冲突处理：内置冲突检测与智能调度策略，优先保护 P0 事件，灵活调整可选项
4. 幂等操作保障：创建/更新/跳过机制确保重复执行不会产生脏数据，适合自动化场景
5. 隐私安全优先：所有数据本地处理，无网络外联，日历信息不上传云端
6. 多日历智能路由：根据事件类型自动归类至 Training/Work/Product/Life 等日历

潜在缺点与局限性

1. 平台锁定：仅限 macOS 系统，Windows/Linux 用户无法使用
2. 权限门槛：需要用户授予 Calendar 完全访问权限，初次设置成本较高
3. 无跨设备同步：依赖 iCloud/CalDAV 底层同步，Skill 本身不解决跨平台状态同步问题
4. Swift 环境依赖：部分功能需要 Xcode Command Line Tools 支持
5. 维护者单一：目前由个人开发者维护，长期更新可持续性存疑

适合的目标群体

• 重度 IM 用户：习惯在 Telegram/Discord/飞书/Slack 中处理事务的远程工作者
• macOS 生态深度用户：已全面使用 Apple 日历、iCloud 同步的苹果用户
• 效率工具爱好者：追求自动化日程管理、定期回顾复盘的生产力极客
• 隐私敏感用户：拒绝将日历数据上传至第三方 SaaS 服务的安全意识人群
• 小型团队管理者：需要快速协调会议时间、检测冲突的敏捷团队负责人

使用风险

1. 数据操作风险：calendar_clean.py 的 --apply 模式会直接删除重复事件，建议始终先 dry-run 验证
2. Cron 任务残留：install.sh 会修改用户 Crontab，停用后需运行 uninstall.sh 清理
3. 时区配置依赖：默认使用 config.json 中的时区设置，配置错误可能导致事件时间偏差
4. 日历权限变更：macOS 系统升级可能重置隐私权限，需重新授权
5. 脚本执行失败：Swift/Python 版本差异或系统更新可能导致脚本异常，建议定期运行 regression_test.py 验证