calendar-reminder

面向独立开发者与企业团队的 Outlook 日历智能提醒 Skill。每晚 22:00 自动扫描明日全部日程, 按时段策略差异化推送飞书通知:上午日程提前 2 小时提醒,下午日程在当天 12:00 统一汇总提醒, 扫描完成立即发送汇报消息。基于 owa-outlook skill 提供的 owa_calendar.py 读取日历数据, 通过 skill-platform CLI 注册 cron 定时任务,使用 Python zoneinfo 处理时区. 适用于需要每日日程前置提醒、跨时区协作、避免错过晨会的自动化工作流场景.

天轰穿@thcjp

Install

openclaw skills install @thcjp/calendar-reminder

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

Calendar Reminder 日历提醒

输入规范

参数名	类型	必填	说明
input	string	是	日历提醒处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

付费版扩展能力

能力	免费版	付费版
基础功能	支持	支持
日历提醒每晚22点扫描	不支持	支持
日历提醒册定时任务并汇报扫描	不支持	支持
多渠道消息批量发送	不支持	支持
消息模板与变量注入	不支持	支持
送达状态实时回调	不支持	支持

技能简介

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

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

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

可用性分类

分类: MD+EXEC（）

API Key配置方式:

bash

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 可执行:

bash

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:

python

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

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

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

bash

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 后,手动运行一次脚本验证端到端流程是否通畅:

bash

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

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

步骤五：确认 cron 持续生效

bash

skill-platform cron list

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

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

案例展示

案例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.

故障处理体系

错误场景	原因	处理方式
LLM响应超时或无响应	网络延迟或模型负载过高	请求重试；确认Agent平台LLM服务正常
输入内容格式不正确	用户输入不符合skill预期格式	检查输入是否符合skill使用说明中的格式要求，参考示例章节
执行结果与预期不符	指令描述不够明确或上下文不足	提供更详细的指令描述，补充必要的上下文信息
命令执行失败	运行环境不满足要求或权限不足	确认运行环境符合依赖说明中的要求；检查命令权限设置

功能边界

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

输出规范

json

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

创新优势

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
手动检查日历	15分钟/天	2分钟/天	13分钟/天	5%
手动发送提醒	5分钟/次	1分钟/次	4分钟/次	10%
处理跨时区日程	10分钟/次	1分钟/次	9分钟/次	8%
手动汇总日程	20分钟/天	5分钟/天	15分钟/天	7%
手动记录重要会议	10分钟/次	1分钟/次	9分钟/次	9%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
自动化程度	高	低	中	高
跨时区处理	支持	不支持	支持	支持
提醒策略	灵活	固定	灵活	灵活
成本	低	高	中	高
易用性	高	低	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
忘记重要会议	容易忘记重要会议，导致错过	个人或团队	自动提醒功能	95%的会议不再错过
跨时区混淆	跨时区会议时间处理困难	个人或团队	跨时区日程处理	100%的日程准确
日程管理效率低	手动管理日程耗时，效率低	个人或团队	自动化日程管理	80%的时间节约

诊断与修复

错误现象	可能原因	诊断步骤	解决方案
提醒未按时发送	定时任务未注册或失败	检查定时任务配置	重新注册定时任务
提醒内容错误	日历数据读取错误	检查日历数据格式	修正日历数据格式
提醒未到达指定用户	飞书机器人配置错误	检查飞书机器人配置	修正飞书机器人配置
跨时区计算错误	时区设置错误	检查时区设置	修正时区设置
扫描结果未汇报	汇报功能未启用	检查汇报功能配置	启用汇报功能

安全规范

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

安全风险防范

风险项	等级	防护措施	验证方法
API密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志

功能亮点

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