x-cmd 的 Claw Heartbeat 委托机制:用 HEARTBEAT.md 把跟进任务交给心跳代理

原创2026-10-13 21:20:391,341 阅读
文章标签:CLI开发工具人工智能AI Agent

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 代理周期性检查后台任务的三个步骤:

  1. 执行 x agent job status --job-id "<id>" --llms;
  2. 读取输出,判断任务是已完成(done)、失败(failed)还是仍在运行(still running);
  3. 完成后,在下一个会话中通过 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 驱动。梳理源码可以得到完整的后台调度链路:

  1. 节拍生成:___x_cmd_claw_run___heartbeat_generator 以约 60 秒为周期向消息队列发送 HEARTBEAT:<ts> 事件(对齐到整分钟)。
  2. 去重与频率控制:___x_cmd_claw_run___mq___dispatch_heartbeat 读取 lastheartbeat_ts 文件,两次心跳间隔不足 60 秒直接跳过,避免重复触发。
  3. 空闲探测:___x_cmd_claw_run___heartbeat___tick 遍历所有活跃聊天($___X_CMD_CLAW_BOT_CONNECT_DIR 下的每个 IM/chatid),检查是否有未读消息或消息处理 worker 仍在运行;若所有聊天都无活动,则全局 idle_count 自增,否则归零。
  4. 触发阈值:idle_count >= 3(即至少连续 3 分钟完全空闲)才启动全局 heartbeat 代理;且同一时刻只允许一个 heartbeat-orchestrator worker 运行,防止并发重复执行。
  5. 代理执行:最终调用 ___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 与配套技能,一个完整的委托闭环如下:

  1. 判断是否委托:凡是超过"单条简单命令"的多步任务(文件操作、数据分析、研究、外部 API 调用),都应当用 x agent run --job-id "<id>" --max-iterations <n> "<task>" 卸载到后台(参见 background-jobs/SKILL.md)。
  2. 登记委托:按本文第二节的后台任务模板,把 job-id、Check command、Notify command 写入 HEARTBEAT.md 的 ## In Progress。
  3. 立即收尾并停止:x agent run 立即返回,不要轮询、不要验证、不要继续对话;向用户回复"已启动 <job-id>,完成后会通过 heartbeat 跟进"即可。
  4. 心跳代查:系统空闲 ≥3 分钟后 heartbeat 代理醒来,读取 HEARTBEAT.md,对到期的条目执行 x agent job status --job-id "<id>" --llms 判断结果。
  5. 结果回报:任务完成时,在下个会话经 stdout 汇报摘要,或通过 x claw agentrequest <im> <chatid> '<summary>' 把结果推送到指定平台(如 x claw weixin send --chatid <CHATID> --text '<msg>',发送方法由 heartbeat 提示词按平台注入)。
  6. 状态清理:一次性条目被标记完成或移除,循环任务更新 memory/state.yml 的 last_run 后保留待下次触发。

小结

heartbeat-delegation 技能回答了一个朴素但关键的问题:当前会话不便执行的事,如何可靠地交给后台在合适时机完成。它的答案是一个文件(HEARTBEAT.md)、一套格式(一次性 / 循环 / 后台任务三种模板)、一条纪律(当前会话只读不执行)以及一整套由 mod/claw/lib/run/heartbeat 空闲判定、HEARTBEAT_OK 静默标记、memory/state.yml 状态记忆组成的后台调度机制。理解并遵守这些约定,Claw 的 Manager 与 heartbeat 代理就能各司其职,让"以后要做的事"既不丢失、也不打扰、更不重复执行。

登录后查看全文
x-cmd