核心用法
Calendar Markdown + Google Sync Skill 是一套面向技术用户的日历管理系统，采用 Markdown 作为数据存储格式，结合 CLI 工具实现完整的事件生命周期管理。核心数据存储于 calendar.md 文件，其中 ## Event Records 区块为权威数据源，使用 YAML frontmatter 定义事件属性；## Event Checklist 则提供人类可读的事件概览。
CLI 操作体系
该 Skill 提供丰富的命令行接口，覆盖查询、增删改查及分类管理：
- 查询：
npm run cli -- summary获取概览，export导出原始 Markdown - 新增事件：
add命令支持--shift-to-next或--allow-overlap自动处理时间冲突 - 更新：
update修改事件属性，时间变更时同样需指定冲突策略 - 状态切换：
check/undone快速标记完成状态 - 删除与分类管理：
delete、category-add、category-remove维护数据结构
Google 日历集成
支持 OAuth 登录后的双向同步，通过 UI 中的 Sync Now 按钮触发合并流程，同步状态持久化于 .calendar-google-sync-state.json。
显著优点
1. 数据主权：纯 Markdown 存储，用户完全掌控数据，便于版本控制与文本处理
2. 开发者友好：CLI-first 设计，天然适配自动化脚本与 Git 工作流
3. 智能冲突处理：自动检测时间重叠，提供交互式选择与非交互式自动处理策略
4. 同步透明：双向合并机制避免单向覆盖导致的数据丢失
5. 快照追踪：每次变更自动生成滚动 Markdown 快照，便于审计与回滚
潜在局限
- UI 功能受限：明确禁止通过 UI 添加事件，新事件必须通过 CLI 创建，对非技术用户门槛较高
- 同步依赖手动：Google 同步需人工点击触发，缺乏实时自动同步机制
- 单文件瓶颈：所有事件集中于单一 Markdown 文件，长期高频使用可能面临性能与版本冲突问题
- 外部 ID 维护：
externalId与googleEventIds的多标识符系统增加了数据一致性复杂度
适合人群
- 偏好纯文本工作流的开发者与技术写作者
- 需要将日历数据纳入 Git 版本控制的用户
- 对 Google Calendar 有同步需求但希望保留本地备份的用户
常规风险
- 时间冲突误操作：非交互模式下若未显式指定
--shift-to-next或--allow-overlap，可能导致命令失败或预期外行为 - 同步状态漂移：手动同步机制可能导致本地与 Google Calendar 状态不一致
- Markdown 手动编辑风险：虽推荐 CLI 操作，但手动修改 frontmatter 可能破坏
id、label、color等字段有效性，进而影响解析 - 快照路径泄露：默认快照路径包含用户名（
/Users/nrav/...），多用户环境需注意权限配置