企业官网建设流程全解析

• CLI
• 开发工具
• AI Agent
• 人工智能
• 包管理器

本文以 x-cmd Claw 心跳 Agent（heartbeat 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.md（"Tool 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 进程如果不先 source，x <mod>命令将直接失败。心跳 Agent 与普通 Agent 均运行在独立进程/工作区中，这条加载前提同样适用。

三、定时任务：只用x claw cron，其余都是红线

3.1 为什么禁止 CronCreate / CronDelete / 系统 cron

TOOLS.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 标准操作流程

文档给出的三步走：

1. 先看帮助：x claw cron --help，查看全部子命令与示例；
2. 确认时区：添加第一个任务前，用x claw cron tz <timezone>设置/确认用户时区，避免"9:00 闹钟"在错误时区触发；
3. 添加任务：使用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/agentrequest：x 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 完整命令集

4.3 如何读懂 jobdir 里的状态文件

文档给出了查看任务进度时的"读文件路线图"：执行x agent job status后，先进入输出中显示的jobdir目录，再按需读取以下关键文件：

• DESC.md或AGENTS.md—— 任务描述与上下文；
• status.yml—— 详细运行状态；
• *.response.md—— 各轮迭代日志及实际结果。

同时要重点关注 YAML 输出中的两个字段：ai.recommendation（AI 对下一步的评估）与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/run：x 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；只需要"到点触发" → 用定时任务。

同样的判断逻辑也出现在 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 中的完整列表）：

• WeChat：x claw weixin send --chatid <CHATID> --text '<msg>'
• Telegram：x claw telegram send --chatid <CHATID> --text '<msg>'
• Feishu：x claw feishu send --chatid <CHATID> --text '<msg>'
• 企业微信（Qywx）：x 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.md）：

• HEARTBEAT_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 的选型可以浓缩为四句话：

1. 需要底层能力→ 直接使用 x-cmd 的 300+ shell 工具与 1000+ 软件包，无需 sudo；
2. 需要"到点精确执行"→ 只用x claw cron（唯一合法入口），配合tz确认时区、单引号包裹agentrequest消息；
3. 需要"长时间不阻塞"→ 用x agent run创建自包含的后台任务，并用x agent job status --llms跟踪jobdir内的status.yml与迭代日志；
4. 需要"分享文件/部署站点"→ 用x hub login+x hub file upload+x hub file share，不确定就加--help。

同时牢记两条红线：绝不使用会话内/系统级调度工具替代x claw cron；后台任务永不自动通知用户，结果必须由心跳检查后主动上报。掌握这四点，心跳 Agent 就能在"少打扰、高可靠、可追溯"的原则下完成绝大多数周期性与后台工作。

• CLI
• 开发工具
• AI Agent
• 人工智能
• 包管理器