x-cmd claw HEARTBEAT.md 任务委派指南:把延迟跟进与周期检查交给 Heartbeat Agent

原创2026-10-13 21:42:451,974 阅读
文章标签:CLI开发工具人工智能AI 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.md yourself 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 中有三层节流与防重入:

  1. 60 秒最小间隔:通过 lastheartbeat_ts 文件记录上次心跳时间,current_ts - lastheartbeat_ts >= 60 才继续;
  2. 全局空闲计数器:tick 中探测所有活动聊天(connect 目录下每个 <im>/<chatid> 文件),若任一聊天有外部活动(未读消息、消息 worker 仍在运行)则计数清零,否则 idle_count 加一;idle_count >= 3(即连续 3 分钟完全空闲)才启动 heartbeat agent;
  3. worker 防重入:若 heartbeat-orchestrator worker 仍在运行则跳过本周期,避免并发。

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

  1. Scan:遍历各活动聊天工作区,读取 HEARTBEAT.md,分别处理 In Progress(一次性)与 Recurring(周期)两类;
  2. Check:读取全局 PLAN.md 检查清单(如每日日历提醒、每周临时文件清理等跨平台主动监控项,见 hb/PLAN.md);
  3. Decide:只在确有值得打扰的事项时开口——一次性条目到期/逾期、周期检查发现异常、全局清单需要关注、用户明确要求提醒;无事可说时保持沉默;
  4. Act:向最近活跃平台发送简洁消息,并在对应聊天的 memory/YYYY-MM-DD.md 追加一条 System Notification 记录(含 Trigger、Sent、Method、Next step),让 msg agent 在用户回复时能衔接上下文;
  5. 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>''

六、最佳实践小结

  1. 按任务特征选路径:立即执行写 PLAN.md;精确时间用 x claw cron add;模糊时间/周期检查/需要聊天上下文写 HEARTBEAT.md;复杂长任务用 x agent run 并在 HEARTBEAT.md 登记监控记录;
  2. 遵守格式:一次性条目放在 ## In Progress(执行后移除),周期条目放在 ## Recurring(执行后保留并更新 last_run);
  3. 任务描述自包含:后台执行的 agent 没有会话记忆,Task 字段必须写清目标、工具与预期输出,避免模糊指令(如"检查一下 HN"这种描述无法执行);
  4. 尊重静默机制:无事可报时 heartbeat agent 会创建 HEARTBEAT_OK(默认 4 小时有效)抑制唤醒,这是正常设计而非故障;
  5. 善用状态文件:周期任务的调度与防轰炸依赖 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。

登录后查看全文
x-cmd