x-cmd claw HEARTBEAT.md 任务委派指南:把延迟跟进与周期检查交给 Heartbeat Agent
x-cmd claw HEARTBEAT.md 任务委派指南:把延迟跟进与周期检查交给 Heartbeat Agent
本文讲解 x-cmd 中 claw(ClawBot 消息代理)工作区的
HEARTBEAT.md机制:它是什么、如何编写一次性跟进(One-time Follow-up)、周期检查(Recurring Check)与后台任务(Background Job)记录,以及与定时任务(x claw cron)的边界划分。读完本文,你将掌握在聊天会话中正确委派"时间不精确、需要聊天上下文、适合批量检查"的待办事项给后台 heartbeat agent 的完整方法,并能从源码层面理解 heartbeat 的触发、静默与状态记录机制。
一、HEARTBEAT.md 是什么
HEARTBEAT.md 是 claw 每个聊天工作区(<im>-<chatid>)中的一份任务委派清单。它的定义写在其文件头注释中:
Items delegated to the heartbeat agent to check during idle periods. Write here when you find something needs follow-up but is not suitable to execute immediately in the current session.
即在当前会话中发现了"需要跟进、但不适合立刻执行"的事项时,写入 HEARTBEAT.md,由 heartbeat agent(一个在空闲时段周期性唤醒的后台进程)代为检查与执行。
模板文件位于 mod/claw/lib/data/workspace/msg/HEARTBEAT.md,由四个小节组成,各小节语义如下:
| 小节 | 用途 | 执行后是否移除 |
|---|---|---|
## In Progress |
一次性跟进与后台任务记录 | 是(标记完成或删除) |
## Recurring |
周期性检查项 | 否(按 Frequency 重复执行) |
## Completed |
已完成一次性任务的历史 | —(周期任务不记录于此) |
## Notes |
补充说明 | — |
heartbeat agent 的完整运行规范见 mod/claw/lib/data/workspace/hb/AGENTS.md:它是"周期唤醒、检查工作区状态、审视上下文、把值得用户注意的事情浮出水面"的后台进程。
与定时任务的边界(原文档核心约束)
HEARTBEAT.md 文件头有一则硬性约束:
Note: Reminders at exact times (e.g., "14:00 meeting") should use scheduled tasks (
x claw cron add), not this file.
也就是说,精确时间的提醒(如"14:00 开会")必须走定时任务 x claw cron add,不要写入本文件。heartbeat 任务的特征是:时间可以浮动(源码注释中允许约 30 分钟漂移)、需要聊天上下文、或者适合批量检查。二者取舍规则(见 msg/AGENTS.md 任务路由表):
| 任务类型 | 路径 | 原因 |
|---|---|---|
| 立即执行(部署、处理、修复) | PLAN.md |
当前会话内执行 |
| 明天/后天的提醒或跟进 | HEARTBEAT.md |
空闲时段由 heartbeat agent 处理 |
| 每日/每周的周期检查 | HEARTBEAT.md |
heartbeat agent 周期检查 |
| 精确时间(9:00、14:30) | x claw cron add |
精确触发,常驻调度 |
| 模糊未来检查(下周、稍后) | HEARTBEAT.md |
延迟跟进,不属于当前会话 |
| 复杂/长耗时(分析、大数据) | x agent run 后台任务 |
不阻塞聊天,异步运行 |
简单规则:立即做 → PLAN.md;有精确时间点 → cron;只有日期或模糊时间 → HEARTBEAT.md;复杂长耗时 → x agent run。
二、写入格式:三类委派条目
HEARTBEAT.md 不是自由文本,需要按结构化格式写入,heartbeat agent 才能准确解析。格式参考来自 msg/AGENTS.md 的 HEARTBEAT.md Format Reference 与 heartbeat-delegation 技能。
1. 一次性跟进(写在 ## In Progress 下)
- **Follow-up**: `<task-id>`
- **Due**: YYYY-MM-DD HH:MM
- **Task**: <description>
<task-id>:唯一任务标识,便于 heartbeat agent 在状态文件中按 id 追踪;Due:期望执行的时间点(日期+时间),heartbeat agent 判断"到期/逾期"的依据;Task:任务描述,应写得足够清晰,使后台 agent 无需回会话也能执行。
2. 周期性检查(写在 ## Recurring 下)
- **Recurring**: `<task-id>`
- **Frequency**: <hourly | daily | weekly>
- **Task**: <description>
Frequency 支持 hourly、daily、weekly 三档。heartbeat agent 每次唤醒时会读取自己的 memory/state.yml 中该任务的 last_run 时间戳,与 Frequency 比对决定是否执行;执行后更新 last_run 但保留条目,因此周期任务永不从 HEARTBEAT.md 移除(见 hb/AGENTS.md 工作流)。
3. 后台任务记录(写在 ## In Progress 下)
当会话用 x agent run 创建了异步后台任务后,应同步在 HEARTBEAT.md 登记一条监控记录,交给 heartbeat agent 周期检查任务是否完成:
- **Background Job**: `<job-id>`
- **Display Name**: <friendly name>
- **IM**: <im>
- **Chat ID**: <chatid>
- **Task**: <brief description>
- **Created**: <timestamp>
- **Check command**: `x agent job status --job-id <job-id> --llms`
- **Notify command**: `x claw agentrequest <im> <chatid> '<summary>'`
heartbeat agent 检查完成后,读取 x agent job status 输出判断任务是 done / failed / 仍在运行,并通过 x claw agentrequest 向用户汇总结果(见 background-jobs 技能)。
重要:会话代理不执行 HEARTBEAT.md
HEARTBEAT.md 中的条目由 heartbeat agent 执行,当前 msg 会话代理只读不写。规范明确:
Do NOT execute items in
HEARTBEAT.mdyourself during the current msg session. Your role is to read it for awareness of pending follow-ups, but execution is the heartbeat agent's responsibility.
如果用户问起 HEARTBEAT.md 中的某个条目,会话代理只需简要汇报状态;只有用户明确说"现在就做"之类的话才代为执行(msg/AGENTS.md)。
三、heartbeat agent 的工作流程(源码视角)
要理解 HEARTBEAT.md 如何被消费,需要知道 heartbeat agent 从触发到收尾的完整链路。
1. 触发链路:MQ → 调度 → 空闲判定
从 mod/claw/lib/run/_index 看,claw 启动时会拉起一个常驻 heartbeat-generator worker(___x_cmd_claw_run___heartbeat_generator),它每 60 秒向 MQ 发送一条 HEARTBEAT:<unix_ts> 消息;消息队列分发器(___x_cmd_claw_run___mq___dispatch)识别 HEARTBEAT:* 前缀后调用 ___x_cmd_claw_run___mq___dispatch_heartbeat(mod/claw/lib/run/heartbeat)。
dispatch_heartbeat 中有三层节流与防重入:
- 60 秒最小间隔:通过
lastheartbeat_ts文件记录上次心跳时间,current_ts - lastheartbeat_ts >= 60才继续; - 全局空闲计数器:
tick中探测所有活动聊天(connect目录下每个<im>/<chatid>文件),若任一聊天有外部活动(未读消息、消息 worker 仍在运行)则计数清零,否则idle_count加一;idle_count >= 3(即连续 3 分钟完全空闲)才启动 heartbeat agent; - worker 防重入:若
heartbeat-orchestratorworker 仍在运行则跳过本周期,避免并发。
2. 执行链路:提示词构建与变量注入
___x_cmd_claw_run___agent___exec_heartbeat(mod/claw/lib/run/agentrequest)负责真正启动 heartbeat agent:
- 扫描
connect目录,收集活动平台列表(ACTIVE_PLATFORMS)、各平台回复方法(REPLY_METHODS,如x claw weixin send --chatid ... --text '...')、默认回复目标(最近活跃的平台DEFAULT_REPLY_IM); - 将 mod/claw/lib/data/prompt/heartbeat.md 提示词模板与上述变量拼接,通过
x agent request --timeout 1800 --workspace <全局工作区>启动 agent; - 若
idle_count >= 30(半小时级长空闲),还会额外注入HEARTBEAT_IDLE_PROMPT,提示 agent 在无事可做时可创建HEARTBEAT_OK静默标记。
3. 处理 HEARTBEAT.md 的五步流程
heartbeat agent 按其操作手册 mod/claw/lib/data/workspace/hb/AGENTS.md 执行:
- Scan:遍历各活动聊天工作区,读取
HEARTBEAT.md,分别处理In Progress(一次性)与Recurring(周期)两类; - Check:读取全局
PLAN.md检查清单(如每日日历提醒、每周临时文件清理等跨平台主动监控项,见 hb/PLAN.md); - Decide:只在确有值得打扰的事项时开口——一次性条目到期/逾期、周期检查发现异常、全局清单需要关注、用户明确要求提醒;无事可说时保持沉默;
- Act:向最近活跃平台发送简洁消息,并在对应聊天的
memory/YYYY-MM-DD.md追加一条System Notification记录(含Trigger、Sent、Method、Next step),让 msg agent 在用户回复时能衔接上下文; - Mark:无事可报时创建
HEARTBEAT_OK标记文件,抑制下一轮心跳(见下文)。
4. HEARTBEAT_OK:静默标记机制
HEARTBEAT_OK 是 heartbeat agent 主动创建的短期静默标记(位于工作区根目录)。源码 run/heartbeat 的 heartbeat_ok_check_ 用 x fileage --in 检查其年龄:TTL 默认 4h(可通过环境变量 ___X_CMD_CLAW_HEARTBEAT_OK_TTL 调整),标记有效期内跳过 heartbeat agent,到期自动恢复检查;新用户消息到达会立即清除该标记(heartbeat 的 probe 逻辑)。
提示:
HEARTBEAT_OK是短期静默开关而非永久关闭。它存在的意义是避免"没有任何新事项"时无意义地周期性唤醒 agent 消耗资源。
四、状态记录:state.yml 与每日日志
heartbeat agent 用两个文件记录自己的执行状态(hb/AGENTS.md 的 Memory & State 一节):
memory/state.yml(机器可读快照)
模板见 mod/claw/lib/data/workspace/hb/memory/state.yml。只在真正执行了动作后更新(执行任务或发送通知),空跑不更新:
tasks:
<task-id>:
last_run: "YYYY-MM-DDTHH:MM:SS"
last_result: <ok | error | brief-summary>
last_notify: "YYYY-MM-DDTHH:MM:SS"
count_today: <number>
meta:
last_action: "YYYY-MM-DDTHH:MM:SS"
last_run:上次实际执行检查/任务的时间——周期任务的调度依据;last_result:执行结果;last_notify:上次为该任务给用户发消息的时间,用于防止消息轰炸;count_today:今日执行次数,午夜归零。
memory/YYYY-MM-DD.md(人类可读日志)
按天追加、仅在有内容可记时创建,空跑不记录。格式:
# Heartbeat Log — YYYY-MM-DD
## HH:MM:SS — <task-id> (<chat-workspace-or-global>)
- **Action**: execute | notify | skip
- **Result**: <brief result>
- **Summary**: <what happened>
- **Notified**: true | false
这类日志用于排查与回答"你今天做了什么"之类的问题,而非详尽的操作流水。
五、与 cron 定时任务的完整对比
heartbeat 与 x claw cron 的分工,在 cron 技能、msg/TOOLS.md 与 hb/AGENTS.md 中反复强调,汇总如下:
| 使用场景 | 机制 | 理由 |
|---|---|---|
| 批量周期检查(收件箱+任务+通知) | Heartbeat | 合并检查、使用会话上下文 |
| 精确时间("每周一 9 点") | 定时任务 | 精确调度、独立执行 |
| 一次性提醒("20 分钟后提醒我") | 定时任务 | 无需会话历史 |
| 无聊天上下文的独立任务 | 定时任务 | 与会话干净隔离 |
经验法则:需要知道最近聊了什么 → heartbeat;只需要精确时间触发 → 定时任务。
在 claw 环境中,定时任务只能使用 x claw cron(源码见 mod/claw/lib/cron):禁止 Claude Code 内置的 CronCreate/CronDelete(仅活跃会话有效、agent 退出即失效)与系统 cron/at(不受 claw 管理、无法追踪清理)。添加定时任务的完整命令:
x claw cron add --name "<name>" --desc "<desc>" "<cron_expr>" "x claw agentrequest <im> <CHATID> '<msg>'"
其中 <msg> 会被发送给一个零记忆的新 agent,因此必须自包含地写明 Goal、Tools、Steps、Output 与结果投递方式(用单引号包裹)。例如:
x claw cron add --name "hn-daily" --desc "daily top HN posts" "0 9 * * *" 'Use x hn top for top 5 posts. Extract title, URL, score. Send: x claw feishu send --chatid "<CHATID>" --text '<formatted_list>''
六、最佳实践小结
- 按任务特征选路径:立即执行写
PLAN.md;精确时间用x claw cron add;模糊时间/周期检查/需要聊天上下文写HEARTBEAT.md;复杂长任务用x agent run并在HEARTBEAT.md登记监控记录; - 遵守格式:一次性条目放在
## In Progress(执行后移除),周期条目放在## Recurring(执行后保留并更新last_run); - 任务描述自包含:后台执行的 agent 没有会话记忆,
Task字段必须写清目标、工具与预期输出,避免模糊指令(如"检查一下 HN"这种描述无法执行); - 尊重静默机制:无事可报时 heartbeat agent 会创建
HEARTBEAT_OK(默认 4 小时有效)抑制唤醒,这是正常设计而非故障; - 善用状态文件:周期任务的调度与防轰炸依赖
state.yml中的last_run/last_notify,不要手工删除该文件(hb/AGENTS.md)。
深入阅读:模板文件 HEARTBEAT.md 与 manager 工作区同名模板;任务路由全表 msg/AGENTS.md;heartbeat agent 操作手册 hb/AGENTS.md;全局检查清单 hb/PLAN.md;运行时实现 run/heartbeat 与 run/agentrequest;系统提示词模板 prompt/heartbeat.md;定时任务实现 lib/cron;委托技能 heartbeat-delegation/SKILL.md。