如何把Raven变成7×24小时自动助手：Cron定时任务与心跳机制完整指南

如何把Raven变成7×24小时自动助手：Cron定时任务与心跳机制完整指南

【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven

Raven是一个可信任、持久运行、自我进化的多智能体协作平台。借助它内置的Cron 定时任务与心跳（Heartbeat）机制，你可以让 Raven AI 助手在无人值守时自动执行提醒、巡检与周期性任务，真正成为 7×24 小时在线的自动助手。本指南将带你用最少的步骤完成配置，并理解背后的防打扰设计。

一、为什么需要"定时任务 + 心跳"这两套机制？

大多数 AI 助手是"被动"的：你说一句，它答一句。而 Raven 的主动性设计（可参考 docs/Proactivity-Plan.md）刻意把助手分成了两层"时钟"：

简单说：Cron 管"在什么时间叫醒它"，心跳管"醒来后自己判断该不该干活"。两者共享同一套防打扰账本，不会就同一件事重复打扰你。

二、快速上手：用一句话创建第一个定时提醒

最简单的方式不需要敲任何命令——直接对你的 Raven 助手说自然语言即可，助手会通过内置的cron工具自动解析并建好任务（实现见 raven/proactive_engine/schedulers/cron/tool.py）：

• 「50 分钟后提醒我休息」→ 一次性提醒（at），响一次就自动删除
• 「每天早上 7 点提醒我吃药」→ 固定时刻循环（cron_expr='0 7 * * *'），支持时区
• 「每隔 30 分钟巡检一次服务器」→ 固定间隔循环（every_seconds）

💡 小技巧：创建循环提醒时，助手会给任务打上一个topic_tag（如medication_morning）。同一个主题再次创建时会自动更新旧任务而不是叠加新任务，避免一个月后收到 5 条"吃药提醒"。

三种调度类型怎么选？

任务创建时会绑定当时的聊天渠道与会话（fire-at-origin）：在哪聊的，提醒就发回哪，触发时不会"跑丢"到其他对话。

三、命令行管理定时任务：raven cron 常用命令

如果你偏好脚本化操作或想审计任务状态，Raven 提供了完整的raven cron子命令（源码见 raven/cli/cron_commands.py）。所有任务持久化在~/.raven/cron/jobs.json，核心命令一览：

raven cron list # 查看全部任务：调度方式、下次运行时间、最近状态 raven cron get <id> # 查看单个任务详情（支持 ID 前缀缩写） raven cron run <id> # 手动试跑一次，验证调度是否符合预期 raven cron disable <id> # 暂停任务（保留配置，假期前很好用） raven cron enable <id> # 恢复任务 raven cron delete <id> -y # 删除任务

几个实用细节：

• raven cron list顶部会显示下次唤醒时间，以及"哪些任务需要raven gateway保持运行才会触发"——这是 7×24 运行的关键：IM 渠道的任务必须有一个常驻的 gateway 进程在跑才会真正触发。
• 间隔参数支持90m、1h30m、7d这类 systemd 风格写法，如raven cron add --channel telegram --every 90m（具体参数用raven cron add --help查看）。
• 想验证"下一次运行时间算得对不对"，用raven cron run <id>试跑一次即可，它会把调度指针真实推进到下次触发时间。

四、心跳机制详解：让助手自己"醒来"干活

心跳服务的核心思想是：把"活"写进一个 Markdown 文件，助手按固定节律醒来自己看。

1. 编辑 HEARTBEAT.md 任务清单

每个代理主目录下都有一个HEARTBEAT.md（内置模板见 raven/templates/HEARTBEAT.md），内容结构非常简单：

## Active Tasks <!-- 在这里写下你希望助手周期性处理的任务 --> - 检查 inbox 邮件摘要，有紧急邮件就提醒我 ## Completed

只要文件里有"超出模板骨架"的内容，心跳就会把它交给模型处理；如果只有标题和注释，本次心跳直接跳过、不消耗任何模型调用。

2. 两阶段决策，省钱又可靠

心跳服务（raven/proactive_engine/schedulers/heartbeat/service.py）每次醒来分两步：

1. 决策阶段：把文件内容和"刚发生的系统事件"喂给模型，让它通过一个虚拟heartbeat工具回答skip（没事）或run（有活要干）；
2. 执行阶段：只有判定为run时，才走完整的智能体循环去执行任务，并把结果主动推送给你。

3. 事件唤醒：Cron 和心跳会"互相通气"

当某个 Cron 任务执行完成（或失败）时，Raven 会把它作为一个系统事件入队，并请求心跳提前醒来处理后续（见 raven/core/cron_stack.py）。也就是说：凌晨 3 点某个巡检任务失败了，心跳会被立刻唤醒并替你判断"要不要通知你"——这正是 7×24 自动助手"闭环"的精髓。

4. 心跳参数配置

心跳默认开启，每 30 分钟一次；配置定义在 raven/config/schema.py：

心跳与哨兵（Sentinel）等主动能力在 gateway 中统一装配（见 raven/cli/gateway_commands.py），所以保持raven gateway常驻，就是 7×24 自动助手的地基。

五、7×24 稳定运行必备：防打扰设计

一个全天候在线的助手，最大的风险不是"不干活"，而是"太能叨叨"。Raven 内置了三道护栏：

• 🔕静默触发熔断：循环提醒若连续 N 次触发后你毫无回应，任务会被自动停用（raven cron list会标黄警告），想恢复只需raven cron enable <id>——防止半夜每 45 分钟弹一条提醒；
• 🧾共享防重复账本：Cron 触发会写入 NudgePolicy 账本，L3 哨兵在 24 小时内就同一主题不再主动唠叨，杜绝"双重提醒"；
• ⏱️唤醒节流：即使你配了每 60 秒一次的任务，事件唤醒也会折叠到"每 5 分钟至多一次决策调用"，模型开销始终有界。

六、最佳实践清单 ✅

1. 先常驻 gateway：7×24 场景下让raven gateway长期运行（可配合 Docker/系统服务），否则 IM 渠道的定时任务不会触发；
2. 一次性任务用at，别用every：对助手说"一小时后提醒我"，它会自动算出绝对时间、只响一次；
3. 循环任务必须"明确要求"：只有你说出"每天/每小时/每周一"这类词，助手才会建循环任务——抱怨"我总忘喝水"不会自动变成无限循环提醒；
4. 周期性杂活丢进 HEARTBEAT.md：邮件摘要、服务器巡检等"看情况处理"的事，比精确闹钟更适合心跳；
5. 用raven cron run <id>试跑：上线前先验证调度时间，比事后查日志高效得多。

按这套配置，你的 Raven 助手就能在提醒、巡检、事件跟进三条线上持续待命——白天当随叫随到的伙伴，深夜当可靠的值班员。🦉

延伸阅读：docs/Proactivity-Implementation.md 提供了主动性子系统的完整实现参考；raven/proactive_engine/schedulers/ 下可分别找到 Cron 与心跳的调度器源码。

【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven