Cron 与 Heartbeat：何时使用
心跳（heartbeat）与 cron 都可以按计划运行任务。本指南帮助你在具体场景中做选择。快速决策指南
Heartbeat：周期性意识
心跳会在 主会话 中按固定间隔运行（默认 30 分钟）。它用于让代理主动检查并提示重要事项。何时用心跳
- 多个周期检查：与其设 5 个 cron 分别检查收件箱、日历、天气、通知、项目状态，不如用一次心跳批处理。
- 上下文驱动：代理具备完整主会话上下文，能判断紧急程度。
- 对话连续性：心跳共享同一会话，能自然跟进最近对话。
- 低开销监控：一个心跳替代多个小轮询任务。
心跳优势
- 批处理多个检查：一次代理回合可同时查看收件箱、日历和通知。
- 减少 API 调用：一次心跳比 5 个隔离 cron 便宜。
- 上下文感知：代理了解你在做什么并能优先级排序。
- 智能抑制：若无关注事项，代理返回
HEARTBEAT_OK，不会投递消息。 - 自然时间：会随着队列负载略有漂移，但对大多数监控无影响。
心跳示例：HEARTBEAT.md 清单
配置心跳
Cron：精确调度
Cron 任务在 精确时间 运行，并可在隔离会话中执行，不影响主会话上下文。何时用 cron
- 需要精确时间：比如“每周一 9:00 发送”。
- 独立任务：不需要对话上下文。
- 不同模型/思考：重分析可用更强模型。
- 一次性提醒：用
--at。 - 噪声高/频繁任务：避免污染主会话历史。
- 外部触发：任务需要独立于代理活跃状态运行。
Cron 优势
- 精确时间：5 字段 cron 表达式 + 时区支持。
- 会话隔离：在
cron:<jobId>中运行，不污染主历史。 - 模型覆盖：每个任务可选更便宜或更强模型。
- 投递控制：可直接投递到渠道；默认仍会向主会话发摘要（可配置）。
- 无需主会话上下文：即使主会话闲置或已压缩也能运行。
- 一次性支持：
--at指定精确未来时间戳。
Cron 示例：每日早报
Cron 示例：一次性提醒
决策流程图
组合使用
最高效的配置往往是 两者搭配：- Heartbeat 处理常规监控（收件箱、日历、通知），每 30 分钟一次合并处理。
- Cron 处理精确调度（日报、周报）与一次性提醒。
示例：高效自动化配置
HEARTBEAT.md（每 30 分钟检查）：Lobster：带审批的确定性工作流
Lobster 是用于 多步骤工具流水线 的工作流运行时，强调确定性执行与显式审批。 当任务不止一个代理回合、且需要可恢复流程与人工检查点时使用它。Lobster 适用场景
- 多步自动化：需要固定工具调用流水线，而不是一次性提示。
- 审批关卡：有副作用的步骤需要你确认后继续。
- 可恢复运行：暂停后继续执行，无需重跑前面步骤。
它与心跳/cron 的配合
- Heartbeat/cron 决定 何时 触发。
- Lobster 定义 触发后执行哪些步骤。
运行说明（来自代码）
- Lobster 以 本地子进程（
lobsterCLI）在工具模式下运行，并返回 JSON envelope。 - 工具返回
needs_approval时，用resumeToken+approve继续。 - 该工具为 可选插件；建议通过
tools.alsoAllow: ["lobster"]启用。 - 如果传入
lobsterPath，必须是 绝对路径。
主会话 vs 隔离会话
心跳与 cron 都会与主会话产生交互，但方式不同：何时使用主会话 cron
在你希望以下行为时，使用--session main + --system-event：
- 提醒/事件出现在主会话上下文中
- 代理在下一次心跳里用完整上下文处理
- 不产生独立隔离运行
何时使用隔离 cron
当你需要：- 无历史上下文的干净环境
- 不同的模型或思考设置
- 输出直接投递到渠道（默认仍会向主会话发摘要）
- 不污染主会话历史的运行记录
成本考量
建议：
- 保持
HEARTBEAT.md简洁，降低 token 开销。 - 把类似检查合并进心跳，而非多个 cron 任务。
- 若只需内部处理，心跳可用
target: "none"。 - 日常任务可用更便宜模型的隔离 cron。