feishu-smart-alarm

# Feishu Smart Alarm ## 概述 这个 Skill 用于在飞书消息中自动识别“需要在某个时间前提醒”的内容，并完成三个动作： 1. 读取消息文本并判断是否需要建立提醒 2. 解析截止时间，并计算 **由系统根据消息语义和时间跨度自动判断，更偏宽松一点的预留时间** 的提醒时间 3. 立即在原会话发送确认消息：`我已经记住并在$时间点$提醒` 4. 到点后仅提醒一次，并把提醒发回原飞书会话 提醒时间不再固定为 30 分钟前，而是根据消息语义、时间跨度、是否包含“重要/务必/开会/评审”等关键词，以及是否显式写了“提前多久提醒”来自动判断。整体策略偏保守，会给事情留出稍微宽松一点的预留时间。 默认约定： - 只读取**飞书消息文本** - 支持较宽松的中文时间表达 - 默认提醒对象是**原消息发送者** - 默认把提醒消息发回**原飞书会话** - 每条提醒**只发送一次** - 默认时区：`Asia/Shanghai` ## 适用消息 优先识别以下类型： - `今天 5 点前给我` - `明天下午三点提醒我开会` - `周五前记得把这个提交` - `今晚 8 点前把材料发我` - `后天上午记得找我确认` - `下周一 10 点别忘了评审` ## 不建立提醒的情况 以下情况默认不建提醒： - 纯闲聊，没有任务或截止语义 - 没有可解析时间 - 明显是历史回顾而非未来待办 - 时间解析结果早于当前时间且无法合理滚动到未来 ## 时间解析规则 脚本支持以下常见时间表达： - 绝对时间：`2026-03-20 15:00`、`2026/3/20 15:00` - 月日时间：`3月20日 15:00`、`3月20号下午3点` - 相对日期：`今天`、`明天`、`后天` - 周几：`周一`、`周五`、`下周二` - 时段：`上午`、`中午`、`下午`、`晚上`、`凌晨` - 纯时间：`5点`、`5:30`、`下午三点` 默认补全策略： - 仅有日期但无具体时间：默认 `18:00` - 仅有“上午 / 下午 / 晚上”无具体小时：分别默认 `10:00 / 15:00 / 20:00` - 仅有纯时间且今日该时刻已过：顺延到明天 ## 消息分析规则 建立提醒必须同时满足： 1. 能解析出未来时间 2. 消息里存在待办/提醒/截止语义中的至少一种 强触发关键词示例： - `提醒` - `记得` - `别忘` - `截止` - `前给我` - `前发我` - `前提交` - `要做` - `要交` - `开会` - `评审` - `确认` - `安排` 如果消息虽然没有“提醒”字样，但具有明显的“任务 + 时间”结构，也可以建立提醒。 ## 确认消息规则 一旦建立提醒，必须立刻在原会话发送确认消息： `我已经记住并在$时间点$提醒` 其中 `$时间点$` 填入**提醒时间**，不是截止时间。例如： - `今天 17:00 前给我` → 可能提醒在 `16:20` 或 `15:30`，取决于任务紧急程度 - `下周一开会别忘了` → 可能更早预留数小时甚至前一天提醒 - 确认消息会使用系统自动判断出来的提醒时间 ## 到点提醒规则 到达提醒时间后，发送一次提醒消息到原飞书会话。 建议提醒模板： - 私聊：`提醒你：{summary}（截止时间 {deadline_text}）` - 群聊：`提醒 {sender_name}：{summary}（截止时间 {deadline_text}）` 发送成功后，将提醒状态标记为已发送，不再重复提醒。 ## 脚本入口 ### 1. 分析消息 ```bash python scripts/main.py analyze-message --text "今天 5 点前给我" ``` 返回： - 是否需要提醒 - 解析到的截止时间 - 提醒时间 - 确认消息 ### 2. 创建提醒并立即回确认 ```bash python scripts/main.py create-reminder \ --text "今天 5 点前给我" \ --receive-id oc_xxx \ --receive-id-type chat_id \ --sender-open-id ou_xxx \ --sender-name 张三 ``` 这个命令会： - 分析消息 - 如有提醒需求则存入本地 SQLite - 立刻向原会话发送确认消息 ### 3. 轮询并发送到期提醒 ```bash python scripts/main.py poll-due ``` ### 4. 以常驻循环方式运行 ```bash python scripts/main.py run-loop --interval 30 ``` 表示每 30 秒检查一次是否有到期提醒。 ## 环境变量 默认只要求： ```env FEISHU_APP_ID=... FEISHU_APP_SECRET=... ``` 可选项： ```env FEISHU_BASE_URL=https://open.feishu.cn FEISHU_SMART_ALARM_DB=./data/reminders.db FEISHU_SMART_ALARM_TZ=Asia/Shanghai ``` ## 与 PicoClaw 的接法 推荐在飞书消息进入后这样使用： 1. 对每条飞书消息调用 `create-reminder` 2. 如果返回 `need_reminder=false`，继续普通聊天逻辑 3. 如果返回 `need_reminder=true`： - 确认消息已发出 - 后台由 `run-loop` 常驻检查并在到点时发送提醒 更详细的接法见： - `references/integration_cn.md` - `references/time_rules_cn.md`