x-cmd 的 Claw Heartbeat 委托机制:用 HEARTBEAT.md 把跟进任务交给心跳代理
x-cmd 的 Claw Heartbeat 委托机制:用 HEARTBEAT.md 把跟进任务交给心跳代理
导读
heartbeat-delegation 是 x-cmd 的 Claw 多智能体(Manager / Heartbeat / Msg)协作体系中用于任务委托的核心技能:当当前会话中的 Manager 智能体遇到"需要跟进但不适合立刻执行"的事项时,把它写入 HEARTBEAT.md,由空闲时被周期性唤醒的 heartbeat 代理代为检查、执行与回报。读完本文,你将掌握 HEARTBEAT.md 的四段式结构与三种任务格式(一次性跟进、循环检查、后台任务记录),理解心跳节拍、空闲判定、HEARTBEAT_OK 静默机制与 memory/state.yml 状态记录如何共同驱动这套"后台代办"系统,并能在实操中正确使用 x agent run、x agent job status --job-id <id> --llms、x claw agentrequest <im> <chatid> '<msg>' 等命令完成委托闭环。
一、什么是 Heartbeat 委托:把"以后要做的事"写进 HEARTBEAT.md
在 Claw 的会话模型中,Manager 智能体在处理用户请求的当前会话内执行任务,而 heartbeat 代理是一个后台进程,会在系统空闲时周期性醒来,检查工作区状态并处理积压的跟进事项。heartbeat-delegation 技能文档(SKILL.md)把 HEARTBEAT.md 定义为"交给 heartbeat 代理的委托表单"(delegation form):Manager 只需把"要做什么、什么时候做"写清楚,heartbeat 代理会在空闲时段读取并处理。
该技能的核心纪律是职责分离:
当前会话中的你不要亲自执行
HEARTBEAT.md里的条目。你的角色是读取它、了解待办跟进事项;执行是 heartbeat 代理的责任。若用户问起某个条目的状态,简要汇报即可;只有当用户明确说"现在就做"(do it now)或类似指令时,才亲自执行。
这与 manager/PLAN.md 中"当前会话任务板与 HEARTBEAT.md 的分工"互为印证——PLAN.md 只放当前会话内实际执行的任务,需要跟进但不适合立刻执行的条目应写入 HEARTBEAT.md:
需要跟进但不适合立即执行的事项,应写入
HEARTBEAT.md。
两类委托任务
SKILL.md 明确区分了两种任务的生命周期:
- 一次性任务(
## In Progress):heartbeat 代理执行完毕后会将其标记完成或从文件中移除; - 循环任务(
## Recurring):heartbeat 代理每次执行后,会把本次运行记录到自己的memory/state.yml,但保留HEARTBEAT.md中的条目,供后续周期继续触发。
二、格式参考:三种可复制的委托模板
SKILL.md 给出了三种标准格式,写入 HEARTBEAT.md 时直接套用即可。
一次性跟进(写在 ## In Progress 下)
- **Follow-up**: `<task-id>`
- **Due**: YYYY-MM-DD HH:MM
- **Task**: <description>
Due 字段是到期时间点,heartbeat 代理会根据当前时间判断是否到期或已超期;<task-id> 建议使用有辨识度的短标识(参见 background-jobs 技能中 manager-<brief> 的命名约定,如 manager-loganalysis),便于在 memory/state.yml 中追踪。
循环检查(写在 ## Recurring 下)
- **Recurring**: `<task-id>`
- **Frequency**: <hourly | daily | weekly>
- **Task**: <description>
Frequency 支持 hourly / daily / weekly 三档。heartbeat 代理每次醒来会读取 memory/state.yml 中的 last_run 时间戳,与 Frequency 比较以决定本次是否到点执行;执行后更新 last_run 并追加日志,但不移除 HEARTBEAT.md 中的条目。
后台任务记录(写在 ## In Progress 下)
当你通过 x agent run 创建后台任务时,SKILL.md 要求同时在 HEARTBEAT.md 的 ## In Progress 下登记一条记录:
- **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>'`
这条模板中嵌入了两个关键命令:
x agent job status --job-id <job-id> --llms:以 AI 可解析的 YAML 格式查询后台任务状态。在 mod/agent/lib/job/status 中可以看到--llms参数把输出格式切换为llms(否则默认yml),并调用渲染函数输出无 ANSI 颜色的纯 YAML 状态,便于 heartbeat 代理直接读取判断任务是completed/error/failed还是仍在运行。x claw agentrequest <im> <chatid> '<summary>':向指定平台(如weixin、telegram)的会话发送一条代理请求。其实现位于 mod/claw/lib/run/agentrequest,参数签名依次为 IM 平台名、chatid 与消息内容,消息缺失时会报错Please provide message。
三、检查完成:heartbeat 代理如何验证后台任务
SKILL.md 给出了 heartbeat 代理周期性检查后台任务的三个步骤:
- 执行
x agent job status --job-id "<id>" --llms; - 读取输出,判断任务是已完成(done)、失败(failed)还是仍在运行(still running);
- 完成后,在下一个会话中通过 stdout 直接把摘要汇报给用户;若合适,也可向相关平台发送通知。
在 background-jobs/SKILL.md 中可以看到这条链路的设计意图:x agent run 创建的任务在全新环境中异步执行、不携带聊天记忆,且不会自动通知用户,Claw 正是通过 heartbeat 周期性查状态、再用 x claw agentrequest 汇报结果来补上"完成后通知"这一环。该技能还补充了配套命令族:
x agent job ls --active --llms:列出所有活跃任务;x agent job stop --job-id "<id>":停止后台进程。
四、HEARTBEAT.md 的标准结构:一份开箱即用的委托表单
仓库中的 manager/HEARTBEAT.md 是 heartbeat 任务列表的实时模板,包含四个区块,每个区块都带有一行"用途说明"注释,Manager 与 heartbeat 代理均以该文件为唯一事实来源:
| 区块 | 用途 | 执行后处理 |
|---|---|---|
## In Progress |
一次性跟进与后台任务 | heartbeat 代理执行后标记完成(- [x])或移除 |
## Recurring |
周期性检查 | 按 Frequency 执行,记录 last_run,不移除条目 |
## Completed |
已完结的一次性任务历史 | 循环任务不在此出现 |
## Notes |
备注 | 随需记录 |
模板头部还给出了一条重要的边界提示:
精确时间的提醒(如"14:00 开会")应使用定时任务(
x claw cron add),不要写进此文件。Heartbeat 任务的特点是时间灵活、需要聊天上下文、或适合批量检查。
这条边界在 cron/SKILL.md 中有更完整的对照表:
| 使用场景 | 机制 | 原因 |
|---|---|---|
| 批量周期性检查(收件箱 + 任务 + 通知) | Heartbeat | 合并检查、复用会话上下文 |
| 精确时间("每周一上午 9 点") | 定时任务 | 精确调度、隔离执行 |
| 一次性提醒("20 分钟后提醒我") | 定时任务 | 无需会话历史 |
| 与聊天上下文无关的独立任务 | 定时任务 | 与对话干净分离 |
经验法则:需要对话上下文 → heartbeat;需要精确时间或隔离 → 定时任务。另外注意 cron 技能的红线:Claw 场景只允许 x claw cron,系统 cron / at 不受 Claw 管理,不会被追踪或清理。
五、源码视角:心跳节拍与空闲判定如何驱动委托
SKILL.md 描述的是"写入规范",而 heartbeat 代理"何时醒来、何时该处理"由 mod/claw/lib/run/heartbeat 驱动。梳理源码可以得到完整的后台调度链路:
- 节拍生成:
___x_cmd_claw_run___heartbeat_generator以约 60 秒为周期向消息队列发送HEARTBEAT:<ts>事件(对齐到整分钟)。 - 去重与频率控制:
___x_cmd_claw_run___mq___dispatch_heartbeat读取lastheartbeat_ts文件,两次心跳间隔不足 60 秒直接跳过,避免重复触发。 - 空闲探测:
___x_cmd_claw_run___heartbeat___tick遍历所有活跃聊天($___X_CMD_CLAW_BOT_CONNECT_DIR下的每个 IM/chatid),检查是否有未读消息或消息处理 worker 仍在运行;若所有聊天都无活动,则全局idle_count自增,否则归零。 - 触发阈值:
idle_count >= 3(即至少连续 3 分钟完全空闲)才启动全局 heartbeat 代理;且同一时刻只允许一个heartbeat-orchestratorworker 运行,防止并发重复执行。 - 代理执行:最终调用
___x_cmd_claw_run___agent___exec_heartbeat(实现在 mod/claw/lib/run/agentrequest),它收集活跃平台、默认回复目标与各平台发送命令,把 hb 工作区模板 同步到实际工作区,组装heartbeat.md提示词后以x agent request --timeout 1800发起一次最长 30 分钟的代理会话。
静默标记 HEARTBEAT_OK:避免打扰用户
heartbeat 代理"无事可报就闭嘴"的机制由 HEARTBEAT_OK 标记文件实现(见 hb/AGENTS.md):
- 当
HEARTBEAT.md缺失、为空或没有未处理条目时,代理不得凭空编造任务,应创建HEARTBEAT_OK并静默退出; HEARTBEAT_OK是短期静默标记而非永久开关,默认HEARTBEAT_OK_TTL=4h自动过期,之后 heartbeat 会恢复检查(即使没有新消息);- 新的用户消息到达时会立刻清除该标记(见 session 对
HEARTBEAT_OK的处理)。
发言纪律:什么值得打断用户
hb/AGENTS.md 规定 heartbeat 代理只在以下情况发言:一次性条目到期或超期、循环检查发现异常、全局清单(PLAN.md)需要关注、或用户在 HEARTBEAT.md 中明确要求提醒。同时遵守:不问候用户、stdout 对用户完全不可见(发送消息必须用平台 send 命令)、不启动长时间后台任务、不编造话题。
六、状态与记忆:memory/state.yml 与每日日志
循环任务的"上次执行时间"记录在 heartbeat 工作区的 memory/state.yml 中,SKILL.md 所述"记录运行但不删除条目"的机制在这里落地。其结构为:
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"
字段语义(来自 hb/AGENTS.md):
last_run:实际执行检查/任务的时间;last_result:执行结果;last_notify:上次就此事给用户发消息的时间,用于避免重复打扰;count_today:当日执行次数,00:00 重置。
除此之外,heartbeat 代理还会以追加方式维护人读日志 memory/YYYY-MM-DD.md(如 ## HH:MM:SS — <task-id> (<chat-workspace-or-global>),记录 Action / Result / Summary / Notified),仅在真正执行了动作时才写入,空跑不记录。
七、实操闭环:从委托到回报的完整流程
综合 SKILL.md 与配套技能,一个完整的委托闭环如下:
- 判断是否委托:凡是超过"单条简单命令"的多步任务(文件操作、数据分析、研究、外部 API 调用),都应当用
x agent run --job-id "<id>" --max-iterations <n> "<task>"卸载到后台(参见 background-jobs/SKILL.md)。 - 登记委托:按本文第二节的后台任务模板,把
job-id、Check command、Notify command写入HEARTBEAT.md的## In Progress。 - 立即收尾并停止:
x agent run立即返回,不要轮询、不要验证、不要继续对话;向用户回复"已启动<job-id>,完成后会通过 heartbeat 跟进"即可。 - 心跳代查:系统空闲 ≥3 分钟后 heartbeat 代理醒来,读取
HEARTBEAT.md,对到期的条目执行x agent job status --job-id "<id>" --llms判断结果。 - 结果回报:任务完成时,在下个会话经 stdout 汇报摘要,或通过
x claw agentrequest <im> <chatid> '<summary>'把结果推送到指定平台(如x claw weixin send --chatid <CHATID> --text '<msg>',发送方法由 heartbeat 提示词按平台注入)。 - 状态清理:一次性条目被标记完成或移除,循环任务更新
memory/state.yml的last_run后保留待下次触发。
小结
heartbeat-delegation 技能回答了一个朴素但关键的问题:当前会话不便执行的事,如何可靠地交给后台在合适时机完成。它的答案是一个文件(HEARTBEAT.md)、一套格式(一次性 / 循环 / 后台任务三种模板)、一条纪律(当前会话只读不执行)以及一整套由 mod/claw/lib/run/heartbeat 空闲判定、HEARTBEAT_OK 静默标记、memory/state.yml 状态记忆组成的后台调度机制。理解并遵守这些约定,Claw 的 Manager 与 heartbeat 代理就能各司其职,让"以后要做的事"既不丢失、也不打扰、更不重复执行。