★ FEATURED ARTICLE CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载本文以 x-cmd Claw 心跳 Agentheartbeat agent工作区中的 TOOLS.md 为核心骨架系统梳理心跳 Agent 在运行中可依赖的四类工具能力x-cmd 技能库、定时任务x claw cron、后台任务x agent run/x agent job以及云端文件与站点托管x hub。读完本文你将掌握心跳 Agent 与定时任务之间的选型判断、后台任务的完整生命周期操作、以及心跳场景下跨平台回复的标准流程并能直接照抄本文的命令模板投入实战。一、工具指南的定位心跳 Agent 的操作手册在 x-cmd 的 Claw 体系中heartbeat agent心跳 Agent是一个周期性唤醒的后台进程职责是检查各聊天工作区状态、按HEARTBEAT.md与全局PLAN.md执行到期检查并在发现值得汇报的事项时主动向用户发声。它的完整工作流定义在 AGENTS.md 中启动时按顺序读取RUNONCE.md、操作手册、PLAN.md、memory/state.yml 和 TOOLS.mdTool reference, consult as needed。TOOLS.md 正是一份随心跳 Agent 一起分发的工具参考文档回答心跳 Agent 在什么场景下该用哪个命令、绝对禁止用哪个命令这一问题。它被心跳提示词模板 prompt/heartbeat.md 和 hb/AGENTS.md 多处引用是心跳 Agent 每次唤醒后查命令的案头手册。二、x-cmd心跳 Agent 的底层工具底座文档第一部分提醒x-cmd 本身就是一个可直接调用的技能库——Use x-cmd skill to access 300 shell utilities, 1000 packages—all without sudo。对心跳 Agent 而言这意味着它不需要 sudo、不需要预装软件即可借助 x-cmd 提供的数百个 shell 工具与上千个软件包完成检查任务如解析 YAML、处理日期、调用网络接口。其底层入口是x这个 POSIX shell 函数因此在使用前需要先加载 x-cmd 环境在 manager 工作区的 TOOLS.md 中对此有明确提醒xis a POSIX shell function. Every new shell process must load it first:. ~/.x-cmd.root/X——任何新起的 shell 进程如果不先 sourcex mod命令将直接失败。心跳 Agent 与普通 Agent 均运行在独立进程/工作区中这条加载前提同样适用。三、定时任务只用x claw cron其余都是红线3.1 为什么禁止 CronCreate / CronDelete / 系统 cronTOOLS.md 用醒目方式给出了定时任务的第一条铁律DO NOT use CronCreate, CronDelete, or any built-in/system scheduling tools.In claw context, ONLYx claw cronis allowed.理由有两条本质上是生命周期归属问题CronCreate/CronDelete只在 Agent 活跃会话期间有效Agent 退出后任务即消失系统级cron/at不受 Claw 管理不会被跟踪、不会被清理容易成为无人维护的僵尸任务。而x claw cron在 Agent 退出后依然持久生效、由 Claw 统一管理。从源码看claw/lib/cron 中所有子命令add/rm/ls/match/run/exec/tz/history都会在内部转发给___x_cmd cron ... --ns x-claw-default即所有任务都登记在x-claw-default这个命名空间下由 x-cmd 的 cron 基础设施统一调度、可查询、可清理。3.2 标准操作流程文档给出的三步走先看帮助x claw cron --help查看全部子命令与示例确认时区添加第一个任务前用x claw cron tz timezone设置/确认用户时区避免9:00 闹钟在错误时区触发添加任务使用x claw cron add完整命令形如manager 工作区 TOOLS.md 中的写法x claw cron add --name name --desc desc expr cmd源码 claw/lib/cron 对add的参数解析为--name唯一任务名必填、--desc任务描述、--once一次性任务开关位置参数依次是 cron 表达式与要执行的命令例如0 9 * * *。值得注意的一个细节如果命令不是以x claw agentrequest开头源码会通过claw:warn输出警告提示确认该命令可执行且不依赖 tty——这是为定时任务这种无人值守、无交互终端的运行环境设计的防御性检查。3.3 用x claw agentrequest调度一个零记忆 Agent文档特别强调当 cron 命令使用x claw agentrequest时msg会被发送给一个零记忆zero-memory的全新 Agent因此消息必须自包含至少包含五项要素Goal目标Tools可用工具Steps步骤Output输出格式How to deliver results如何交付结果同时要求msg必须使用单引号包裹防止 shell 展开破坏消息内容。底层实现可参考 claw/lib/run/agentrequestx claw agentrequest im chatid msg会先确保对应 IM 服务可用再以agentrequest作为消息来源source构建提示词最终通过___x_cmd agent request --timeout 1800 --workspace ...发起请求——1800 秒的超时时间说明该调用允许较长的 Agent 处理时长适合在定时任务中承载需要思考的检查报告类任务。四、后台任务把耗时工作从会话中剥离4.1 使用原则与判断标准文档给出了明确的使用经验法则多步骤任务、数据分析、研究类任务或任何预计超过 2 分钟的工作都应使用x agent run交给后台任务执行而快速问答、简单命令、需要来回澄清的任务则应留在会话内直接处理。4.2 完整命令集操作命令说明创建并启动x agent run --job-id id --max-iterations n taskAI 会自动生成 PLAN.md 并迭代执行直到完成或达到最大迭代次数查看状态x agent job status --job-id id --llms输出 LLM 友好的 YAML 状态报告列出活跃任务x agent job ls --active --llms查看所有正在运行的后台任务停止任务x agent job stop --job-id id中断后台进程4.3 如何读懂 jobdir 里的状态文件文档给出了查看任务进度时的读文件路线图执行x agent job status后先进入输出中显示的jobdir目录再按需读取以下关键文件DESC.md或AGENTS.md—— 任务描述与上下文status.yml—— 详细运行状态*.response.md—— 各轮迭代日志及实际结果。同时要重点关注 YAML 输出中的两个字段ai.recommendationAI 对下一步的评估与progress.todo剩余工作量的量化数据。这些字段的产出逻辑可以从 agent/lib/job/status 的实现中得到印证x agent job status支持--job-dir、--job-id与位置参数三种方式定位任务并对status.yml逐行解析出iter、max_iterations、todo_completed、todo_remaining、harness、ai.status、ai.recommendation、files_modified、tests_status等完整指标当status.yml缺失时会回退检测DONE.md视为 completed、进度 100%或PLAN.md视为 active并以 worker 存活状态worker isalive --ns x-agent-job判断任务是否仍在运行。--llms模式则额外输出带阅读优先级的报告头、done_content完成后读取DONE.md与error_content失败后读取ERROR.md专为让 LLM 快速消化而设计。任务启动侧的实现见 agent/lib/job/runx agent run支持--job-id、--job-dir、--goal、--prompt、--skill、--exp、--harness、--max-iterations、--inrow、--continuous、--batch等参数如果未显式指定--job-id会自动生成一个时间戳型 ID任务最终通过___x_cmd worker run --ns x-agent-job --name $jobid以 worker 形式注册运行这正是Agent 退出后任务依然存活的机制来源。此外如果同名的job-id已存在命令会直接报错并提示改用x agent job retry --job-id id重试。4.4 Job ID 命名约定与两条硬约束命名约定使用im-chatid-brief格式保证可追溯性例如weixin-user123-loganalysis硬约束一无记忆x agent run在全新环境执行、无任何会话记忆task必须自包含清晰目标、所需工具、预期输出硬约束二不自动通知后台任务不会自动通知用户需要由 Claw 通过心跳机制检查状态再用x claw agentrequest上报结果。4.5 何时不该用后台任务文档同样列出了反向判断标准快速问答或简单命令——直接回复即可需要来回澄清的任务——留在聊天中进行。五、Heartbeat 与 Scheduled Tasks 的选型对比TOOLS.md 用一张表给出了两类机制的适用场景这是心跳 Agent 日常决策的核心依据使用哪种适用场景Heartbeat心跳 Agent批量检查、需要聊天上下文、时间可以浮动约 30 分钟偏差可接受Scheduled tasks定时任务需要精确时间如9:00 AM 整点、一次性提醒、无需会话历史经验法则需要知道最近聊了什么 → 用 heartbeat只需要到点触发 → 用定时任务。同样的判断逻辑也出现在 AGENTS.md 与 skills/cron/SKILL.md 中属于心跳 Agent 工作区中反复强调的核心准则。六、x hub文件托管、静态站点与云端编译6.1 功能定位文档对x hub的定位是三项能力云端文件托管cloud file hosting、静态站点部署static site deployment、云端编译cloud compilation。心跳 Agent 在需要分享文件/图片、部署静态网站或做云端编译时使用。从 hub/lib/main 的模块结构看x hub实际包含account登录/登出/bind、file上传/下载/分享/加密/链接、access、org、keypair、site站点管理、cc云端编译、ai、rag、share等子模块服务端默认指向https://hub.x-cmd.net。6.2 登录与常用命令登录x hub login仅首次需要已登录可跳过。后续命令若发现未登录会提示引导登录跟着提示操作即可探索能力x hub --help上传文件x hub file upload path获取分享链接x hub file share不确定子命令用法时任意子命令追加--help例如x hub file --help。从源码看hub/lib/file/_index 中upload实际映射到___x_cmd_hub_file_put底层调用/api/v0/file接口上传远程路径支持me:xxx、im:xxx等资源格式未加前缀时自动归一化为me:xxx。同目录下的 hub/lib/file 还提供了cat、get、link、ls、rm、which、encrypt等文件子命令供进一步探索。七、平台回复命令心跳 Agent 的发声方式心跳 Agent 的 stdout 对用户完全不可见必须通过平台发送命令才能触达用户。TOOLS.md 给出的原则是任务提示词中已包含各活跃平台的回复方式优先使用不确定时默认回复最近活跃的平台。各平台的实际发送命令manager 工作区 TOOLS.md 与 claw/lib/run/agentrequest 中的完整列表WeChatx claw weixin send --chatid CHATID --text msgTelegramx claw telegram send --chatid CHATID --text msgFeishux claw feishu send --chatid CHATID --text msg企业微信Qywxx claw qywx send --chatid CHATID --text msg心跳 Agent 还会在每次成功发送通知后向对应聊天工作区的memory/YYYY-MM-DD.md追加一条记录含 Trigger / Sent / Method / Next step保证用户回复时 msg Agent 能理解上下文——这一流程的完整模板定义在 AGENTS.md 中。八、附心跳 Agent 的其他关键机制供上下文理解TOOLS.md 虽未展开但与工具使用直接相关的心跳机制还包括详见 AGENTS.mdHEARTBEAT_OK 静默标记检查完毕无事项可报时touch HEARTBEAT_OK默认 4 小时HEARTBEAT_OK_TTL内不再触发到期自动恢复新用户消息会立即清除该标记状态文件memory/state.yml记录每个任务的last_run、last_result、last_notify、count_today用于判断是否该运行/是否该提醒运行纪律不主动问候、不编造话题、不启动长任务、破坏性操作如rm -rf必须先经用户确认、优先用 trash 替代 rm——这些纪律决定了心跳 Agent 对工具的使用边界与 TOOLS.md 一脉相承。九、总结围绕 TOOLS.md 这一工具参考心跳 Agent 的选型可以浓缩为四句话需要底层能力→ 直接使用 x-cmd 的 300 shell 工具与 1000 软件包无需 sudo需要到点精确执行→ 只用x claw cron唯一合法入口配合tz确认时区、单引号包裹agentrequest消息需要长时间不阻塞→ 用x agent run创建自包含的后台任务并用x agent job status --llms跟踪jobdir内的status.yml与迭代日志需要分享文件/部署站点→ 用x hub loginx hub file uploadx hub file share不确定就加--help。同时牢记两条红线绝不使用会话内/系统级调度工具替代x claw cron后台任务永不自动通知用户结果必须由心跳检查后主动上报。掌握这四点心跳 Agent 就能在少打扰、高可靠、可追溯的原则下完成绝大多数周期性与后台工作。赞分享CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载相关推荐x-cmd Claw 心跳 AgentHeartbeat Agent深度解析后台周期巡检、空闲降噪与多平台通知机制x cmd Claw 心跳 AgentHeartbeat Agent深度解析后台周期巡检、空闲降噪与多平台通知机制 Claw 是 x cmd 仓库中面向CLI开发工具AI Agent人工智能包管理器ripgrep 快速上手指南:5 个问题装好 rg,让命令行搜索只搜该搜的ripgrep 快速上手指南:5 个问题装好 rg,让命令行搜索只搜该搜的 ripgrep 终端里写作 rg 是一个递归正则搜索工具:给定一个模式,它就把当前目人工智能计算机视觉深度学习TickerQ高效的后台任务调度工具TickerQ高效的后台任务调度工具 项目介绍 TickerQ 是一个针对 .NET 应用的强大、自适应且精确的后台任务调度器。它支持基于 cron 表达式的上一篇pnpm setup 在 GitHub Actions 中持久化 PNPM_HOME 与全局 binGITHUB_ENV / GITHUB_PATH 机制与源码剖析下一篇COSTAR 反事实自监督 Transformer 完整实战指南环境搭建、数据集配置与实验复现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
