核心功能: 本技能提供化工作流场景等能力。

Calendar Reminder 日历提醒

输入规范

付费版扩展能力

技能简介

Calendar Reminder 是一个日历提醒自动化 Skill,核心目标是在每晚 22:00 自动扫描明日 Outlook 日历的全部日程,并按时段策略设置差异化的飞书提醒,确保用户在第二天早晨前就能掌握全天日程安排,避免错过上午的晨会与重要会议. 该 Skill 通过 skill-platform cron 注册每日定时任务,调用 owa-outlook skill 提供的 owa_calendar.py 拉取日历数据,基于 Python zoneinfo 模块处理跨时区日程,最终通过飞书机器人推送提醒消息到指定用户.

依赖与配置

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

主要能力

1. 每日定时扫描明日日历

在每晚 22:00(Asia/Shanghai 时区)自动触发扫描,拉取明日 00:00 至 23:59 的全部 Outlook 日历事件,包括会议主题、开始时间、结束时间、组织者、地点、是否全天事件等字段。扫描结果会立即生成一份汇报消息推送到飞书,让用户在睡前就能预览明日全天安排。- 验证返回数据的完整性和格式正确性

2. 按时段差异化提醒策略

针对明日日程按开始时间划分两个时段,采用不同的提醒时机:

• 上午日程(开始时间 < 12:00):提前 2 小时飞书提醒。例如明日 09:30 的晨会,会在当日 07:30 推送提醒,确保用户有充足时间准备材料.
• 下午日程(开始时间 >= 12:00):在当天 12:00 统一汇总提醒。将所有下午日程打包成一条消息推送,避免下午日程过多导致消息轰炸.

3. 跨时区日程处理

基于 Python zoneinfo 模块将 Outlook 返回的 UTC 时间转换为本地时区(默认 Asia/Shanghai),正确处理跨时区会议、夏令时切换、全天事件等边界场景,确保提醒时间不会因时区错位而提前或延后.

4. Cron 定时任务注册

通过 skill-platform cron add 命令注册每日扫描任务,支持自定义时区、session 名称、system-event 消息内容。注册后任务持久化在 skill-platform 中,即使 Agent 重启也会按时触发.

5. 扫描结果汇报

扫描完成后立即发送一条汇报消息到飞书,包含明日日程总数、上午/下午日程分布、全天事件列表、需重点关注的会议(如组织者为高管或外部客户),让用户一眼掌握明日重点。- 验证返回数据的完整性和格式正确性

场景说明

场景一：独立开发者每日晨会提醒

• 输入: 开发者配置飞书 open_id 后,每晚 22:00 自动触发
• 输出: 次日 07:30 收到飞书提醒"09:30 产品晨会,议题:周报同步",12:00 收到下午日程汇总"14:00 代码评审 / 16:00 客户演示"
• 价值: 避免早晨匆忙错过晨会,提前准备周报材料

场景二：跨时区团队协作提醒

• 输入: 用户 Outlook 日历中存在 UTC 时间 02:00 的海外团队同步会(对应北京时间 10:00)
• 输出: 系统正确识别时区,在当日 08:00(提前 2 小时)推送飞书提醒,而非按 UTC 时间错误提醒
• 价值: 跨时区会议不会因时区换算错误而错过

场景三：全天事件与多日程汇总

• 输入: 明日有 1 个全天事件(出差) + 3 个下午会议
• 输出: 22:00 扫描汇报"明日全天:上海出差 / 下午3场会议";12:00 统一推送下午 3 场会议的汇总提醒
• 价值: 全天事件不会淹没在多个分段提醒中,下午日程汇总减少消息打扰

场景四：企业团队日程共享提醒

• 输入: 团队 leader 将飞书机器人加入团队群,配置群 chat_id 作为 target
• 输出: 每晚 22:00 在团队群推送明日全员日程汇报,12:00 推送下午会议汇总
• 价值: 团队成员共享日程可见性,协调会议时间

使用说明

步骤一：确认依赖已就位

检查 owa-outlook skill 已安装且 owa_calendar.py 可正常调用,确认 Python 3.9+ 环境(需要 zoneinfo 模块),确认 skill-platform CLI 可执行:

python3 --version  # 需要 3.9+
skill-platform --version
python3 -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Shanghai'))"

步骤二：部署脚本并配置飞书 open_id

将 calendar_reminder.py 部署到 ~/.skill-platform/workspace/skills/calendar-reminder/ 目录,编辑脚本中的 send_feishu 函数,将 target 改为你自己的飞书 open_id 或群 chat_id:

"--target", "user:ou_xxxxxxxxxxxxxxxx",  # 个人提醒
# 或
"--target", "chat:oc_xxxxxxxxxxxxxxxx",  # 群提醒

步骤三：注册每晚 22:00 扫描 cron

执行以下命令注册定时任务:

skill-platform cron add \
  --name "calendar-daily-scan" \
  --cron "0 22 * * *" \
  --tz "Asia/Shanghai" \
  --session main \
  --system-event "CALENDAR_SCAN: 请立即运行 python3 ~/.skill-platform/workspace/skills/calendar-reminder/calendar_reminder.py 并等待完成" \
  --description "每晚22:00扫描明天日历并设置提醒"

步骤四：手动验证扫描流程

在注册 cron 后,手动运行一次脚本验证端到端流程是否通畅:

# 本技能的核心实现逻辑
# 请参考上方使用说明进行配置和调用
echo "implementation_ready"

检查飞书是否收到扫描汇报消息,并确认明日日程被正确分段.

步骤五：确认 cron 持续生效

skill-platform cron list

确认 calendar-daily-scan 任务存在于列表中且状态为 active. 结果验证: 任务完成后,查看输出确认状态。成功时返回摘要和数据;失败时根据错误信息排查,参考恢复章节获取修复步骤. 使用步骤:

1. 阅读依赖说明章节,确认运行环境已就绪
2. 根据任务需求,参考核心能力章节选择对应能力
3. 按照能力描述提供输入参数,执行操作
4. 查看输出结果,确认任务完成状态

案例展示

案例1:产品经理的晨会准备流

用户背景: 产品经理,每日 09:30 有产品晨会,经常因早晨处理邮件错过准备时间. 配置: 飞书 open_id 已配置,cron 已注册. 实际运行数据:

• 22:00:00 扫描启动,拉取明日 5 条日程
• 22:00:03 飞书收到汇报:"明日共 5 场会议,上午 2 场,下午 3 场,其中 09:30 产品晨会议题:Q3 路线图评审"
• 次日 07:30:00 飞书收到提醒:"09:30 产品晨会即将开始(提前 2 小时提醒),议题:Q3 路线图评审,组织者:张三"
• 次日 12:00:00 飞书收到汇总:"下午 3 场会议:14:00 技术评审 / 15:30 用户访谈 / 17:00 周会"

效果: 产品经理在 07:30 就开始准备 Q3 路线图材料,晨会表现更从容.

案例2:跨时区远程团队的会议同步

用户背景: 远程工程师,与美西团队协作,美西 10:00 同步会对应北京时间次日 01:00,经常因时区换算错误错过. 配置: Outlook 日历中事件时间为 UTC 17:00(美西 10:00),脚本使用 Asia/Shanghai 时区转换. 实际运行数据:

• 22:00 扫描识别到该事件开始时间为本地次日 01:00(属上午时段)
• 22:03 汇报消息标注:"01:00 美西同步会(跨时区,请注意)"
• 次日 23:00(提前 2 小时)飞书提醒:"01:00 美西同步会即将开始"

效果: 工程师在 23:00 收到提醒后提前设置闹钟,不再错过跨时区会议.

案例3:团队群的日程共享

用户背景: 5 人小团队,leader 希望全员共享明日日程. 配置: target 配置为群 chat_id oc_xxxxx. 实际运行数据:

• 22:00 群内推送:"@全员 明日团队日程:09:30 站会(全员) / 14:00 与客户A的演示(张三、李四) / 16:00 周会(全员)"
• 次日 07:30 群内推送:"09:30 站会即将开始"
• 次日 12:00 群内推送:"下午:14:00 客户演示 / 16:00 周会"

效果: 团队成员在群内即可看到共享日程,无需逐人询问,会议协调效率提升.

异常处置

1. owa_calendar.py 调用失败

原因: owa-outlook skill 未安装、Outlook 凭据过期、或网络无法访问 Exchange 服务. 处理: 先执行 python3 -c "import owa_calendar; owa_calendar.list_events()" 验证 skill 可用;若凭据过期,重新运行 owa-outlook 的登录流程刷新 token;若网络问题,检查代理配置后。脚本应在调用失败时跳过当日扫描并发飞书告警"日历扫描失败,请检查 owa-outlook".

2. 飞书消息推送失败(HTTP 4xx)

原因: open_id 格式错误、机器人未加入目标群、或 app_access_token 过期. 处理: 检查 target 是否以 user: 或 chat: 前缀开头;若是群提醒,确认机器人已被群管理员加入;若返回 99991663 等 token 错误码,重新获取 app_access_token。建议脚本对飞书 API 失败做 3 次.

3. zoneinfo 时区数据缺失

原因: Linux 系统未安装 tzdata 包,或 Python 版本低于 3.9. 处理: 在 Debian/Ubuntu 执行 sudo apt install tzdata;在 macOS 通常已内置;若 Python < 3.9,升级到 3.9+ 或回退使用 pytz。脚本启动时应先 try: from zoneinfo import ZoneInfo 并在失败时给出明确提示.

4. cron 任务未触发

原因: skill-platform 服务未运行、cron 时区配置错误、或 system-event 消息格式不匹配. 处理: 执行 skill-platform cron list 确认任务存在且 next_run 时间正确;检查 --tz 参数使用 IANA 时区名(如 Asia/Shanghai 而非 +08:00);手动触发一次 skill-platform cron trigger calendar-daily-scan 验证 system-event 是否被 Agent 正确接收并执行.

5. 扫描结果中日程缺失

原因: Outlook 日历中部分日程为"私有"标记,或 owa_calendar 默认只拉取主日历未含子日历. 处理: 在 owa-outlook 配置中开启拉取私有事件;检查是否存在多个日历文件夹(如 Birthdays、Holidays),在脚本中明确指定要扫描的日历名称;对全天事件单独标注避免与时段提醒混淆.

6. 提醒时间在凌晨导致打扰

原因: 明日上午日程过早(如 06:00 早班),提前 2 小时即在凌晨 04:00 推送飞书. 处理: 在脚本中增加"安静时段"判断(如 23:00-07:00 不推送),将落在安静时段的提醒延后到 07:00 合并推送;或在汇报消息中提示"06:00 早班日程,提醒已延后至 07:00".

7. 脚本路径变更导致 cron 执行失败

原因: 用户重装 skill-platform 或迁移 workspace,导致 ~/.py 路径失效. 处理: 重新部署脚本到新路径,执行 skill-platform cron update calendar-daily-scan --system-event "CALENDAR_SCAN: 请运行 python3 <新路径>/calendar_reminder.py";建议在脚本部署后用 readlink -f 确认绝对路径.

8. 全天事件被误判为上午日程

原因: 全天事件的开始时间在 Outlook 中通常为 00:00,被脚本归入上午时段(< 12:00)导致提前 2 小时即在 22:00 当晚重复推送. 处理: 在脚本中通过 is_all_day 字段过滤全天事件,将其单独列入汇报消息的"明日全天事项"区块,不参与提前 2 小时提醒逻辑.

常见疑问汇编

Q1: 如何将提醒从个人飞书改为团队群提醒?

py中send_feishu的--target参数从user:ou_未指定改为chat:oc_未指定,并确保飞书机器人已被群管理员加入目标群。若希望同时推送个人与群,可调用两次 send_feishu` 分别传入不同 target.

Q2: 明日没有日程时还会推送消息吗?

默认会推送一条"明日无日程安排"的汇报消息,确保用户知道扫描已正常执行。若希望无日程时静默,可在脚本中增加判断:if not events: return 跳过飞书推送,但建议保留日志记录以便排查.

Q3: 如何调整上午/下午的分界时间(默认 12:00)?

在 calendar_reminder.py 中找到 afternoon_threshold 变量(通常为 datetime.time(12, 0)),修改为目标时间(如 13:00 适配午休较长的团队)。同时需调整下午统一提醒的 cron 时间(从 12:00 改为 13:00).

Q4: 提醒消息中可以包含会议链接或地点吗?

可以。owa_calendar.py 返回的事件对象通常包含 location 和 online_meeting_url 字段,在 send_feishu 的消息模板中加入这两个字段即可。若会议链接为空,显示"地点:待定".

Q5: 如何临时禁用某一天的扫描(如假期)?

执行 skill-platform cron pause calendar-daily-scan 暂停任务,假期结束后执行 skill-platform cron resume calendar-daily-scan 恢复。不建议直接删除任务,避免重新注册的麻烦.

Q6: 脚本支持飞书以外的通知渠道吗?

当前版本仅内置飞书推送。若需钉钉、企业微信、Slack 等渠道,可参考 send_feishu 的实现新增 send_dingtalk / send_wecom 函数,在脚本末尾根据配置切换通知后端。飞书 API 的 HTTP 调用模式可复用到其他 IM.

故障处理体系

功能边界

• 仅支持 Outlook 日历(通过 owa-outlook skill),不支持 Google Calendar、Apple Calendar 等其他日历服务
• 提醒时段策略固定为"上午提前 2 小时 / 下午 12:00 汇总"两档,不支持按事件优先级差异化提醒
• 依赖 skill-platform cron 触发,若 skill-platform 服务停止则扫描不会执行
• 飞书推送频率受机器人 API 限流(默认 5 条/秒),日程过多时需做批量合并
• 全天事件与跨天事件的处理较简单,不区分多日跨事件的中途提醒
• 时区处理依赖系统 tzdata,Windows 系统需确保已安装最新累积更新

输出规范

{
  "success": true,
  "data": {
    "result": "日历提醒处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "calendar-reminder"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

创新优势

效率提升量化分析

差异化对比

核心痛点解决

诊断与修复

安全规范

1. 确保API Key安全，避免泄露到公共代码库。
2. 定时任务配置应避免使用敏感信息。
3. 飞书机器人配置应确保消息发送安全，避免信息泄露。
4. 定期检查系统日志，及时发现并处理异常。
5. 确保运行环境安全，避免恶意软件感染。

安全风险防范

功能亮点

• 自动化执行: 每晚22点扫描明日Outlook日历,按上下午时段差异化飞书提醒,自动注册定时任务并汇报扫描结果。面向独立开发者与企业团
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果