smart-calendar(分发版 / 单机)
定位
单机版。每台 Mac 独立维护一份本地任务数据库(~/.smart-calendar/tasks.json)。日历事件和提醒事项本身会通过你已有的 iCloud 账号自动同步到其他 Apple 设备,但本 skill 的元数据(formal_title / 标签 / 项目 / 任务类型等)不跨机同步。如需跨设备保留完整上下文,请在同一台 Mac 上集中管理任务,或参考多机协同改造方案另行设计。
When to use
用户在以下场景触发:
- 输入待办事项的口语描述(如"明天之前把 A 项目方案改完发给协作方")
- 上传聊天截图、邮件截图等非结构化信息
- 要求更新或删除之前创建的日程 / 任务
- 要求生成工作周报
- 要求管理标签(添加 / 删除 / 修改任务标签)
- 任何涉及"把 XX 加到日历 / 提醒里"、"帮我排个日程"、"生成周报"的请求
Prerequisites
- macOS 系统(操作 Calendar 和 Reminders app)
- Calendar 和 Reminders app 需被允许脚本控制 — 首次运行时会弹出 系统设置 → 隐私与安全性 → 自动化 的权限请求,必须授权
- Python 3 已安装(macOS 系统自带)
- Apple Reminders 已建好「工作」和「生活」两个列表
- Apple Calendar 已建好「工作」和「生活」两个 iCloud 日历
运作模型(v4.0 — Apple 当真源)
Apple Calendar / Reminders 是真源,本 skill 的
tasks.json是本地缓存。
[写入]
用户 / agent ─────────────────────────► Apple Reminders / Calendar
│
│ 列表名 = 主标签的物理载体
│ description / body 末尾 = metadata block
│(project, task_type, aux_tags, formal_title)
│
iCloud 跨设备同步 ◄──┘
│
[读取 / sync] ▼
tasks.json ◄─────────────────────── Mac / iPhone
(本地缓存,可重建)
核心规则:
- 创建任务时,agent 决定主标签
--tag-major work|life→ 自动写入对应列表 / 日历 - 元数据(project / task_type / aux_tags / formal_title)走 metadata block 跟着事件本体同步
- 跨机一致 + iPhone 友好(手动加到「工作」列表的任务也会被 skill 识别为「工作」)
sync命令随时从 Apple 真源重建tasks.json
Loop 层(可选自动心跳)
harness 让 agent 能干活,loop 让"同步 + 周报"被持续调度、验证、记录。默认不启用。
两个心跳命令(手动可跑,也可挂 launchd 自动跑 — 见 README「启用自动 loop」节):
python3 .../task_manager.py loop-tick --mode daily # 每日 sync
python3 .../task_manager.py loop-tick --mode weekly # sync + 出周报
python3 .../task_manager.py loop-status # 查看 loop 健康
A+B minimum viable loop:automation(launchd)+ skill(本 skill)+ state file(loop-state.json,含 30 条 history 滚动)+ gate(结构性断言:SYNC_DONE + tasks.json 可解析 + 报告 size>800 + 含必需段落;失败弹 Basso 通知 + 写 last_error + exit 1)。
设计原则:确定性机械操作用结构性断言 gate,不引 maker/checker;cron 单跑天然 hard-stop;失败必显式上报。判断类工作(哪些算重点、对外投递)不进 loop。
首次配置
首次使用时 skill 会自动创建默认配置(~/.smart-calendar/config.json)。建议确认 / 修改以下字段:
周报标题与团队名(默认标题为"个人工作周报",team_name 为空):
# 个人使用:默认即"个人工作周报",无需配置;如需改名再 set-config python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-config \ --key weekly_report.report_title --value "重点项目周报" # 团队 / 小组场景:设置 team_name,标题变成 "{team_name}{report_title}" python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-config \ --key weekly_report.team_name --value "项目组"最终周报标题 =
{team_name}{report_title};team_name 为空时只用 report_title。周报输出目录(必须设置,否则周报只能输出到控制台):
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-config \ --key weekly_report.output_dir \ --value "/path/to/your/weekly/report/folder"查看当前配置:
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py get-config可选:自定义数据目录(指向 iCloud Drive 或其他位置,用于测试隔离):
export SMART_CALENDAR_DATA_DIR="$HOME/Library/Mobile Documents/com~apple~CloudDocs/smart-calendar"⚠️ 注意:iCloud Drive 跨机同步不是事务性的,两端同时写会产生
.conflicted文件。单机版不建议把 DATA_DIR 放 iCloud Drive,仅作测试用途。
Steps
阶段一:解析输入
- 接收用户输入(文字或图片)。如果是图片,使用多模态能力提取文字内容。
- 从输入中提取以下结构化字段:
- 任务标题(核心描述)
- 任务类型:文件审阅 / 反馈 / 调研 / 文书撰写 / 会议 / 其他
- 所属项目(用户根据自己业务确定,例如"A 项目"、"X 收购"、"客户 Y"等)
- 截止时间(日期 + 可选时间)
- 开始时间(如有明确起止时段则提取)
- 结束时间(如有明确起止时段则提取)
- 优先级:高 / 中 / 低
- 相关人员(协作方 / 相关方 / 管理层等)
- 备注(额外上下文)
- 信息不完整时(缺少截止时间、任务类型模糊、所属项目不明确),向用户确认。每个待确认字段提供"留白 / 不回答"选项。用户选择留白时基于已有信息和上下文推断默认值。
阶段二:主标签判定 + 次标签收集(v4.0 关键设计)
- 主标签:基于任务内容判断「工作」or「生活」。判断规则:
- 涉及业务项目名、专业术语(方案、审阅、调研、评审会等)、工作相关人员(协作方、外部顾问、管理层)→ 工作
- 涉及家庭、购物、健身、休闲、个人事务 → 生活
- 无法明确判断时,主动询问用户:"这个任务属于工作还是生活?"
- 主标签的物理载体是 Apple 列表 / 日历(不是 tasks.json 字段):
- 工作任务 → 写入「工作」列表 + 「工作」日历
- 生活任务 → 写入「生活」列表 + 「生活」日历
- 这是真源 — 即使在 iPhone 上把一条 reminder 从「工作」拖到「生活」,sync 后 skill 也会立即识别为「生活」
- 次标签(紧急、自定义)走 metadata block,与主标签分层:
- 不为每个次标签建 Apple 列表(避免列表爆炸)
- 次标签通过
--meta-aux-tags写入 reminder body / event description 末尾的 metadata block - 用户可随时添加自定义次标签:
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py add-tag "紧急"
标签别名说明:内部规范用中文标签(工作 / 生活)。agent 用英文写入 work / Work / WORK / life / Life / LIFE 会自动归一化为对应中文。--tag-major 同样接受这些别名。
阶段三:确认与正式用语生成
将提取的结构化信息展示给用户:
📋 识别到的任务信息 ────────────────────────────── 任务标题:[提取的标题] 任务类型:[类型] 所属项目:[项目名] 截止时间:[日期 时间] 优先级:[高/中/低] 标签:[工作/生活/自定义] 相关人员:[人员列表] 备注:[备注] ────────────────────────────── 🎯 将创建:提醒事项 / 日历事件 / 两者用户确认后生成正式用语(专业书面语):
- 标题正式化:口语化描述转专业书面语
- 备注正式化:补充完整上下文,使用专业术语
- 示例:"明天把 A 项目方案改完" → "A 项目方案修订及定稿 —— 根据内部审阅意见完成方案文本修订并发送协作方确认"
阶段四:冲突检测
- 写入前检查时间冲突:
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py check-conflict \ --date "YYYY-MM-DD" [--time "HH:MM"] [--duration 60]- 给定
--time时按[time, time + duration)区间做真正的重叠判断 - 不给
--time时返回当天全部事件
- 给定
- 有冲突时展示详情并询问用户是否继续:
⚠️ 时间冲突提示 该时段已有以下日程: - 14:00-15:30 A 项目内部讨论会 是否继续创建?
阶段五:智能路由与写入
根据任务特征智能路由:
- 仅提醒事项:只有截止时间、无明确起止时段的任务型工作(如"周五前提交审阅意见")
- 仅日历事件:有明确起止时间的会议 / 约会(如"周三下午 2-4 点评审会")
- 两者同时创建:有截止时间的复杂任务,提醒事项记录任务本身、日历事件预留工作时段
- 默认偏好:任务型居多时路由到提醒事项;有明确时段时路由到日历
执行写入(v4.0:用
--tag-major+--meta-*参数):# 创建提醒事项(不指定 --list 时自动按 --tag-major 选「工作」/「生活」列表) python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py create-reminder \ --title "正式标题" \ --tag-major work \ --due "YYYY-MM-DD HH:MM" \ --notes "正式备注" \ --priority [1|2|3] \ --meta-project "项目名" \ --meta-task-type "文件审阅" \ --meta-aux-tags "紧急,待审" \ --meta-formal-title "正式标题" # 创建日历事件(同理,不指定 --calendar 时自动按 --tag-major 选) python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py create-event \ --title "正式标题" \ --tag-major work \ --start "YYYY-MM-DD HH:MM" \ --end "YYYY-MM-DD HH:MM" \ --notes "正式备注" \ --meta-project "项目名" \ --meta-task-type "会议"--tag-major接受work/life/工作/生活,自动归一化。 metadata block 会被追加到 reminder body / event description 末尾,跨机同步、跨端可读。
阶段六:本地索引(可选)+ sync
- v4.0 下 Apple 是真源,tasks.json 是本地缓存。如果只是创建任务,无需手动 save-task — 跑
sync命令可随时从 Apple 重建 tasks.json。但如果想立即更新本地索引(避免下次跑 search 时漏掉刚创建的任务),可显式保存:python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py save-task \ --task-id "auto-generated-uuid" \ --user-input "原始输入" \ --parsed-json '{...}' \ --formal-title "..." \ --formal-notes "..." \ --calendar-event-id "..." \ --reminder-id "..." \ --project "项目名" \ --task-type "类型" \ --major-tag work \ --aux-tags "紧急" sync命令 — 从 Apple 真源重建 tasks.json(推荐定期跑,尤其在 iPhone 手动加任务后):
sync 行为:python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py sync # 可选参数: # --months-back 6 / --months-forward 3 日历事件扫描范围 # --dry-run 只 print 不写盘- 扫白名单内的 Reminders 列表(
work_lists+life_lists)的未完成 reminders - 扫白名单内的 Calendar 日历(
work_calendars+life_calendars)的指定时间范围内事件 - 解析每条 description / body 末尾的 metadata block 还原 project / task_type / aux_tags / formal_title
- 主标签由所在列表 / 日历名物理推断(不读 metadata 里的 tags 字段)
- 写盘前自动备份
tasks.json.bak
- 扫白名单内的 Reminders 列表(
- 数据库路径:
~/.smart-calendar/tasks.json(可通过SMART_CALENDAR_DATA_DIR环境变量覆盖)
阶段七:更新 / 删除
- 用户要求更新 / 删除时:
- 搜索本地数据库匹配关键词:
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py search "关键词" - 展示匹配结果,让用户选择要操作的记录
- 执行更新或删除:
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py update \ --task-id "xxx" --field "title" --value "新标题" python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py delete \ --task-id "xxx"
- 搜索本地数据库匹配关键词:
阶段八:周报生成
- 用户主动触发周报(本版本不实现自动定时;如需周五自动提示请用 launchd / cron 自行配置):
# 输出到控制台 python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py weekly-report # 写入文件(使用配置的输出目录) python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py weekly-report \ --output-dir "/path/to/output" - 周报规则:
- 时间范围:上周五 18:00 至 本周五 17:00(在 Mon-Thu 触发时返回上一个已结束的周期)
- 过滤条件:只提取带"工作"标签的日程和待办
- 结构:项目 - 进展 - 待办 三级结构
- 进展:本周时间范围内有活动的任务(创建 / 更新 / 截止)
- 待办:截止时间在本周期结束后、或没有截止时间但状态仍为 active 的任务
- 期号计算:基于固定锚点(2026-01-02)按周递推,跨机一致
- 输出格式:Markdown 文件
- 文件名:
{team_name}{report_title}(YYYY-MM-DD).md(默认个人工作周报(YYYY-MM-DD).md)
Pitfalls
- Calendar / Reminders 权限:首次运行 AppleScript 会弹权限请求。用户拒绝后所有写入都会失败,且不会再次弹窗 — 需手动到 系统设置 → 隐私与安全性 → 自动化 重新授权。
- AppleScript 字符转义:标题 / 备注中的双引号、反斜杠、换行符都会被自动转义,但极少数情况可能仍需手动检查。
- 时间格式:AppleScript 的 date 构造对格式敏感,必须使用
YYYY-MM-DD HH:MM:SS格式。 - 时区:Calendar 和 Reminders 使用系统时区。
created_at/updated_at落盘时带本地时区,周报范围判断已做 timezone-aware 处理。 - 并发写入:JSON 数据库采用原子重命名写入。单进程使用安全,但多进程并发写入仍有竞态风险(读 - 改 - 写之间不持锁)。单机交互式使用一般不会触发。
- 模糊时间解析:用户说"明天""下周一"等相对时间,需要 agent 根据当前日期正确计算绝对日期。
- 日历 / 列表名约定(v4.0 关键):skill 假设 Apple 已有「工作」和「生活」两个 Reminders 列表 + 两个 Calendar 日历(首次配置时必须建好)。默认
--tag-major work写入「工作」列表 / 「工作」日历,不要手写--list "提醒事项"或--calendar "Work"(v3 旧法,会落到错误列表)。如需 override 列表名,确认目标真实存在,并通过work_lists/life_lists/work_calendars/life_calendars配置白名单(允许多名共存)。第一次写入前可用list-calendars/list-reminder-lists验证。 - 截图解析失败:图片 OCR 可能识别错误,关键字段(尤其是时间和人名)必须向用户二次确认。
- 多端同步限制:本 skill 不做多端协同。Mac A 创建的任务在 Mac B 上跑搜索 / 更新 / 周报命令会完全看不到 — 因为元数据数据库
tasks.json是本地文件。Apple 日历 / 提醒本身会跨设备同步,但脱离本 skill 的元数据上下文。如需多机协同,请按用户需求定制改造。
Verification
- 创建任务后,打开 Calendar / Reminders app 验证事件 / 提醒是否成功创建
- 检查 iPhone / iPad 上是否同步出现
- 运行
list-recent --limit 5查看最近创建的记录 - 运行
list-tags查看标签列表 - 周报生成后,核对任务数量与数据库记录是否一致,确认"生活"标签任务未被包含
数据持久化格式
任务记录
每个任务以 JSON 对象存储在 ~/.smart-calendar/tasks.json:
{
"task_id": "uuid-v4",
"user_input": "用户原始输入",
"parsed": {
"title": "提取标题",
"task_type": "文件审阅|反馈|调研|文书撰写|会议|其他",
"project": "项目名",
"deadline_date": "2026-05-22",
"deadline_time": "17:00",
"start_datetime": null,
"end_datetime": null,
"priority": "高|中|低",
"related_people": ["人员1", "人员2"],
"notes": "额外上下文"
},
"formal_title": "正式用语标题",
"formal_notes": "正式用语备注",
"calendar_event_id": "Apple Event UID 或 null",
"reminder_id": "Apple Reminder ID 或 null",
"tags": ["工作"],
"created_at": "2026-05-20T14:30:00+08:00",
"updated_at": "2026-05-20T14:30:00+08:00",
"status": "active|completed|cancelled"
}
配置文件
~/.smart-calendar/config.json:
{
"tags": ["工作", "生活"],
"weekly_report": {
"enabled": true,
"output_dir": "",
"generate_day": "friday",
"generate_time": "17:00",
"team_name": "",
"report_title": "个人工作周报"
},
"first_run": true
}
CLI 命令速查
# 日历 / 提醒操作(v4.0:用 --tag-major + --meta-*)
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py list-calendars
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py list-reminder-lists
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py create-event \
--title "..." --tag-major work --start "YYYY-MM-DD HH:MM" --end "YYYY-MM-DD HH:MM" \
--meta-project "..." --meta-task-type "..."
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py create-reminder \
--title "..." --tag-major work --due "YYYY-MM-DD HH:MM" \
--meta-project "..." --meta-aux-tags "紧急" --meta-formal-title "..."
# v4.0:从 Apple 真源重建 tasks.json
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py sync
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py sync --dry-run
# 任务管理
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py save-task \
--task-id "..." --parsed-json '{...}' --tags "工作"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py search "关键词"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py update \
--task-id "xxx" --field "status" --value "completed"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py delete --task-id "xxx"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py list-recent --limit 10
# 标签管理
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py list-tags
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py add-tag "紧急"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py remove-tag "紧急"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-task-tags \
--task-id "xxx" --tags "工作,紧急"
# 冲突检测
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py check-conflict \
--date "YYYY-MM-DD" --time "HH:MM" --duration 60
# 周报
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py weekly-report
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py weekly-report \
--output-dir "/path/to/output"
# 配置
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py get-config
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-config \
--key weekly_report.team_name --value "项目组"
python3 ~/.claude/skills/smart-calendar/scripts/task_manager.py set-config \
--key weekly_report.output_dir --value "/path"
文件结构
~/.claude/skills/smart-calendar/
├── SKILL.md # 本文件
├── README.md # 安装与定位说明
├── scripts/
│ ├── task_manager.py # Python 核心控制器
│ └── smoke_test.py # 冒烟测试
├── references/
│ └── applescript_api.md # AppleScript API 参考
└── templates/
└── weekly_report.md # 周报模板(参考用,当前由代码直接拼装)
~/.smart-calendar/ # 数据目录(运行时自动创建)
├── tasks.json # 任务数据库
├── config.json # 配置文件
└── tmp_*.scpt # 临时 AppleScript 文件(用完自动清理)
已知边界
v4.0 已实现方向 B(Apple 真源 + metadata block + sync),单机版上限大致到这里。剩余边界:
- 写入并发锁:多进程同时写 tasks.json 仍有竞态风险(单进程交互使用不触发)
- 周五自动触发:周报生成需用户或外部 scheduler(如 launchd / cron)触发,skill 不内嵌
- Reminder 标记完成:update task status 到 completed 不会反向标记 Reminders.app 里的提醒
- sync 性能:大型 Apple 库下首次 sync 可能 30~60 秒(实测:少量 active reminder + 几十 calendar event ≈ 51 秒)
- 多机协同(部分实现):Apple Calendar / Reminders 通过 iCloud 跨机同步是真源;tasks.json 仍是各机本地缓存。如需在 Mac B 同样体验完整 skill,需另行安装本 skill 并跑一次
sync重建本地缓存