定时任务

桌面应用和 Android 的「定时任务」页。到点后，Hub 给指定节点派一条会话任务。它不是任务页上的卡片，也不是命令行的 Goal 与 Loop。派出去的那条任务用任务生命周期里的状态。

iOS 仍走 TestFlight，公开链接还没开。本页按桌面和 Android 上能点到的界面来写。新建、筛选和详情上的字目前仍是中文。冲突对比，以及下面说的连续跳过那一行，会跟着应用语言变。

Hub 计划和节点计划

页上有两个标签。

Hub 计划是在这里建的。点「新建定时任务」，Hub 按你设的时间把任务内容派给一个节点。节点页的「定时任务」也能打开同一张表，并预先选中那个节点。

节点计划不是用这张表建的。节点把自己机器上的计划上报上来，种类有 crontab、systemd、tmux、playwright 和自定义。还没有上报时，页面写「节点升级后会自动上报本机 crontab 等计划。」

下面的频率、时区、错过和跳过，都只说 Hub 计划。

怎么建

• 名称。最多 120 个字。
• 执行节点。必须是当前网络里已经有的节点，例如 demo-node。
• 任务内容。到点发给节点的正文。最多 10000 个字。
• 优先级。高、普通、低。不选就是普通。
• 类型。只有四种，没有 cron 表达式。
• 错过执行。见下。
• 时区。IANA 名字，例如 Asia/Shanghai。打开表单时填的是这台设备的时区。通过接口创建时如果没带时区，Hub 用 UTC。写错的时区会被拒绝。每天和每周的钟点按这个时区解释，夏令时也走这个时区的规则。列表里只有时区和设备不一样时才把时区附在频率后面，避免把「每天 09:00」看成设备本地的 9 点。详情里始终看得到时区。

类型：

• 单次。一个还没到的时刻。跑完之后变成「已完成」，不能再改回「进行中」。
• 间隔。最短 1 分钟，最长 365 天。
• 每天。HH:mm。
• 每周。HH:mm，至少选一天。

错过：晚了不超过 1 分钟仍算这一次，照常执行。超过 1 分钟才算错过。

• 补跑一次。不选时就是这个。Hub 停过，或这次已经晚了超过 1 分钟，恢复后最多补跑一次，不会把错过的每一次都补回来，然后排到下一个还没到的时刻。更早的 Hub 如果没带这个字段，也按补跑一次。
• 跳过本次。错过的那次不跑，执行记录里留一行，直接等下一次。

「进行中」可以「暂停」。暂停后没有下次时间，详情写「已暂停，恢复后继续」。点「恢复」再算下一次。「取消计划」之后不会再执行；再点一次也还是已取消。已完成和已取消不能改回进行中。

改名称、任务内容或优先级，不会把下次时间重算一遍。改了频率或时区、从暂停恢复、或者这条进行中的计划没有下次时间，才会重算。

进行中和已暂停还可以「立即执行」。它也遵守下一节的跳过规则，而且不会改掉原来的下次时间。

桌面是居中对话框，手机是整页。够宽时左边列表、右边详情。列表按进行中、已暂停、已完成、已取消筛选。

上一次还没结束就跳过

新建的 Hub 计划都是：上一次没结束，这一次就跳过。

到点时，如果这个计划上一次派出的任务还停在 created（已创建）、delivered（已送达）、acked（已确认）或 running（执行中），这一次不派新任务。执行记录记「已跳过」，原因是「上一次还没结束」。计划自己的下次时间照样往前走。Hub 0.9.0-preview.88 之前，这种跳过没有等待上限；从这一版起，上一次卡住太久会被按超时结束，见下一节。

节点离线时，这一次记成「排队中 · 节点离线」，不推送。它仍算没结束，所以后面的点会继续跳过，直到这次任务结束。

桌面 0.2.150 起，执行记录里连续两条及以上、原因都是「上一次还没结束」的跳过，合成一行：「已跳过 N 次（HH:MM–HH:MM）」，并写在等哪一次。单独一条跳过，或者别的原因（节点不存在、节点不可用、错过被跳过），仍各占一行。Hub 仍是每个点存一行，合成只发生在客户端这一页。被等的那次不在这一页记录里时，行内会说明，不会猜。更早的桌面版逐条列出，不合行。

卡住时的提醒与超时

Hub 0.9.0-preview.88 起，一个计划被同一次没结束的任务一直挡着时：

• 提醒：同一个任务挡掉第 3 次时，给建这条计划的人发一条通知「定时任务被卡住」，出现在 app 里和目标节点的会话中。通知写明计划名、挡路的任务 id、节点和那次任务的开始时间，以及多久后会自动放行。每段卡住只发一次；等下一次真的派出去了，再卡住会重新提醒。Hub 重启不会重发。计划没有创建者，或者创建者已不在网络里时，不发。

• 超时放行：挡路的任务开着超过超时，就把它按超时结束（任务状态 expired，和 24 小时没被取走的任务同一个状态），这一次照常派发。

  • 超时 = 6 × 计划间隔，最少 1 小时，最多 24 小时。按天、按周的计划间隔按一天算，所以是 24 小时。
  • 例子：每 1 分钟、每 10 分钟 → 1 小时；每 30 分钟 → 3 小时；每小时 → 6 小时；每天 → 24 小时。
  • 被结束的任务记录还在，照样能查。它的执行记录变成 expired，原因写明是调度器超时结束。
  • 节点之后再回复这条任务会被拒绝（reply_task_terminal），什么都不会改，不影响新派出去的那条。
  • 如果在第 3 次跳过之前就超时了（间隔长的计划常见），就在放行时发一条「定时任务已超时放行」。所以每段卡住恰好一条通知。

• 调参（运维用，改 Hub 的环境变量）：

  环境变量	默认	含义
  COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS	3	同一个任务挡掉第几次时提醒
  COMMHUB_SCHEDULE_STUCK_TIMEOUT_FACTOR	6	超时 = 这个倍数 × 计划间隔
  COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC	3600	超时下限（秒）
  COMMHUB_SCHEDULE_STUCK_TIMEOUT_CAP_SEC	86400	超时上限（秒）

执行记录接口 GET /api/scheduled-tasks/:id/runs 的每条跳过记录带 blocked_by_task_id（挡路的任务）和 blocked_by_state（not_received 节点还没取走 / in_progress 节点在处理）。

目标节点处于降级状态时（Hub 0.9.0-preview.86 起，见健康与降级），这一次执行直接记失败，原因 node_degraded，不建任务。

连续失败时的提醒

Hub 带上 #523 的版本起（尚未发布到 latest），一个计划每次都执行失败时也会提醒，不再一直默默失败下去：

• 算什么失败：执行记录状态是 failed 的那一次。包括派出去的任务被节点以失败结束（例如上游模型拒绝），以及派发时就失败（节点不存在、未启用、降级、创建者已无权限）。已跳过、已取消、超时结束（expired，由上一节负责）和还没结束的执行都不算，也不打断连续。

• 提醒：最近一次成功之后累计失败到第 5 次时，给建这条计划的人发一条通知「定时任务连续失败」，和卡住提醒走同一条路，出现在与目标节点的会话里。通知写明计划名、目标节点、连续失败次数、最近一次的错误（截断到 300 字）和怎么暂停。

• 不重复：这之后只要还没成功过，24 小时内不再提醒；成功一次后，再连续失败 5 次才会重新提醒。Hub 重启不会重发。计划没有创建者，或创建者已不在网络里时，不发。

• 默认只提醒，不自动暂停。运维可以打开自动暂停：连续失败到第 M 次时把计划改成「已暂停」（和手动暂停一样，没有下次时间），并发一条「定时任务连续失败，已自动暂停」。处理好原因后点「恢复」即可。

• 调参（运维用，改 Hub 的环境变量）：

  环境变量	默认	含义
  COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS	5	连续失败第几次时提醒
  COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC	86400	一直没成功时，多久后再提醒一次（秒）
  COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS	0（关）	设为 M（≥1）时，连续失败第 M 次自动暂停

执行记录接口 GET /api/scheduled-tasks/:id/runs 同时返回 consecutive_failures（最近一次成功之后的失败次数）、failure_alert_threshold（上面的 N）和 last_failure_alert_at（上次提醒时间，没有则为 null）。任务被节点以失败结束的那条记录，error_message 是节点回复的失败原因（最多 500 字）。

编辑时刚好执行了一次

桌面 0.2.150 起，正在编辑时这条计划执行了一次，保存不会把表单里的内容丢掉。客户端比较你改过的项和服务器上改过的项。两边改的不是同一项，就留着你的草稿再保存。只有同一项被改成了不同的值，才显示对比：「你的修改」和「最新版本」。可以「用我的覆盖」（按你的改动保存）、「用最新的」（冲突项改成服务器上的，先留在表单里）或「继续编辑」（草稿不动，对着新的一版接着改）。计划已被取消或删除时，改动仍留在表单里，但不能保存。更早的桌面版在这种保存冲突时可能把整份草稿丢掉。

已知问题

Hub 0.9.0-preview.67 起修复。Claude Code 节点在这版发布并升级之前，可能收不到定时任务推送。执行记录会像节点离线那样记成排队，节点却没有收到，后面的执行又因为「上一次还没结束」被跳过。

agent-network 2.3.0-preview.118 起，Claude Code 节点收到回复也会被唤醒。节点要更新到这版并重启后才生效。

相关

• 桌面与手机客户端
• 任务
• 任务生命周期
• Goal 与 Loop。排障页「定时任务没有运行」讲的是命令行循环，不是本页。