核心用法
opy-calendar-skill 是一款以 Markdown 为数据源的本地日历管理工具，采用 CLI 优先的设计理念。用户通过 npm run cli -- <command> 执行所有操作，包括事件增删改查、分类管理以及导入导出。事件数据以 YAML frontmatter 格式存储在 calendar.md 的 ## Event Records 区块中，支持 externalId 和 googleEventIds 实现跨系统去重与同步。
显著优点
1. 本地优先的数据主权：所有日历数据以纯文本 Markdown 存储，用户完全掌控数据，便于版本控制与长期归档。
2. 智能冲突处理：add 和 update 命令内置时间冲突检测，支持 --shift-to-next 自动寻找下一个可用时段，或 --allow-overlap 强制重叠，兼顾自动化与灵活性。
3. 双向 Google 同步：通过 OAuth 2.0 实现与 Google Calendar 的双向合并，同步状态持久化到本地 JSON 文件，避免重复同步。
4. Agent 友好设计：每此变更自动生成滚动快照（agent-snapshot.md），支持通过环境变量自定义历史窗口，便于 AI Agent 追踪与审计。
5. 分离式 UI 架构：数据操作限定于 CLI，UI 仅提供可视化拖拽、缩放和勾选功能，降低操作复杂度与误操作风险。
潜在缺点与局限性
- CLI 学习成本：无图形化的事件创建界面，新用户需要熟悉命令行参数与 ISO 时间格式。
- Node.js 环境依赖：必须安装 npm 并运行本地服务，对非技术用户门槛较高。
- Google 同步配置复杂：需手动配置 OAuth 凭证与回调地址，且同步逻辑为"合并"而非"完全镜像"，可能存在边界情况。
- 并发写入风险：虽然通过
updatedAt时间戳支持冲突检测，但 Markdown 文件的并发修改仍依赖文件锁或外部协调。 - 移动端支持缺失：无原生移动应用，依赖浏览器访问本地服务。
适合人群
- 技术型用户、开发者、极客爱好者
- 需要版本控制日历数据的知识工作者
- 希望将日历与笔记工作流深度整合的 Obsidian/Logseq 用户
- 需要通过 CLI 自动化日程安排的效率工具玩家
常规风险
1. 数据丢失风险：Markdown 文件损坏或误删将导致不可恢复的数据丢失，建议定期使用 export 备份。
2. OAuth 凭证泄露：.env 文件中的 Google 凭证若被提交至公共仓库，可能导致日历数据被恶意访问。
3. 时区处理隐患：ISO 时间字符串若未明确指定时区，可能在跨时区场景下产生歧义。
4. 快照文件膨胀：长期运行后 agent-snapshot.md 可能体积过大，需定期清理或调整 CALENDAR_AGENT_DAYS。
总结
opy-calendar-skill 代表了"本地优先、文本存储、CLI 驱动"的新一代日历管理范式，特别适合将日程视为知识资产进行长期管理的用户。其设计哲学与 Obsidian、Org-mode 等工具一脉相承，但对技术能力有明确要求，不适合追求开箱即用的普通用户。