长任务模式

把这个技能当成长任务执行协议，不是普通提示词。

触发边界（最严格版硬规则）

• - 当用户明确说出 长任务模式 或 进入长任务模式 时，才触发长任务模式。
• 除 进入长任务模式 外，其他任何表达一律不触发，包括但不限于：继续、接着来、往下做、一直做，不停、持续推进、不要停下来问。
• 遇到上述非口令表达时，只按普通任务续做；不要登记长任务状态、不要启动保活/看门狗、不要套用长任务前台心跳规则。
• 如果上下文里已经处于长任务模式，后续普通 继续 只表示在已开启的长任务里继续执行；但开启动作本身仍然只能由 进入长任务模式 触发。

核心目标只有两条：

1. 1. 长任务不能悄悄空转
2. 用户必须持续看得见任务还活着

先读什么

• - 状态字段：references/state-schema.md
• 执行协议：references/protocol.md

脚本索引

主路径

• - scripts/taskstate.py：登记、更新、清理任务状态与发送相关时间戳。
• scripts/validatetaskstart.py：校验任务是否真正绑定到目标 originsessionkey；只有它返回 ok: true 才能宣称启动成功。
• scripts/checkforegroundprogress.py：检查单任务前台进度是否到点。
• scripts/buildprogressupdate.py：构造单任务前台短进度消息。
• scripts/foregroundtick.py：单任务前台心跳入口。
• scripts/workcycletick.py：每轮工作循环后的前台钩子；若 mustsendnow=true，必须先发再继续。

前台自动触发 / 分发辅助

• - scripts/emitforegrounddue.py：扫描所有到点前台任务，生成前台自动消息事件。
• scripts/dispatchforegrounddue.py：把前台自动消息事件整理成 dispatcher 计划；真正发送仍需 OpenClaw tool/agent 层执行。

保活 / 恢复 / 审计

• - scripts/keepalivetick.py：检查单任务是否长时间无活动、是否需要续跑。
• scripts/emitkeepaliveresume.py：生成单任务保活续跑事件。
• scripts/runkeepaliveonce.py：批量跑一次保活检查，产出可执行计划。
• scripts/watchdog.py：审计长任务是否失联、超时、卡住或到检查点。
• scripts/runwatchdogonce.py：批量跑一次 watchdog，并生成后续恢复计划。
• scripts/recoverduetasks.py：根据 watchdog 结果整理恢复建议。
• scripts/emitrecoverymessage.py：把恢复建议转成可发送的恢复消息事件。
• scripts/buildsessionssendpayloads.py：把恢复消息事件整理成 sessions_send payload。

运维 / 清理辅助

• - scripts/cleanupstate.py：清理旧状态、测试残留、坏锁和缺少 originsessionkey 的脏记录。
• scripts/installwatchdogcron.sh：安装 watchdog cron 示例。
• scripts/watchdogloop.sh：本地循环跑 watchdog 的辅助脚本。

启动动作

text
当前状态：分析中 / 执行中 / 等待外部 / 被阻塞 / 需转派 / 已完成
任务目标：...
完成条件：...
阻塞条件：...
所属边界：...
下一步：...

然后立刻登记状态：

bash
python3 skills/long-run-mode/scripts/task_state.py set \
--task <任务名> \
--session <人类可读会话名> \
--origin-session-key <真实目标 sessionKey> \
--state analyzing|executing|waiting|blocked|handoff|done \
--goal <任务目标> \
--done-when <完成条件> \
--blocked-when <阻塞条件> \
--boundary <所属边界> \
--next-check \
--note <当前下一步> \
--progress-every 3m

登记后必须立刻跑一次启动校验：

bash
python3 skills/long-run-mode/scripts/validatetaskstart.py \
--task <任务名> \
--expect-session-key <真实目标 sessionKey>

只有当校验返回 ok: true 时，才能对用户说已进入长任务模式或已开启长任务模式。

硬规则：

• - 对 analyzing / executing / waiting 这类已启动态，必须提供真实 --origin-session-key。
• 如果拿不到真实目标会话，就只能先说明还没绑定成功，不能宣称已进入长任务模式或已开启长任务模式。
• session 只是人类可读名字；真正的发送、保活、恢复都靠 originsessionkey。

如果你要最基础的会话别断保活链，直接再加一层 1 分钟无活动检测：

bash
python3 skills/long-run-mode/scripts/keepalive_tick.py --task <任务名> --idle-seconds 60
python3 skills/long-run-mode/scripts/runkeepaliveonce.py --idle-seconds 60

可选环境变量：

• - OPENCLAWBIN：覆盖 openclaw 可执行文件名或路径
• OPENCLAWSESSIONSFILE：覆盖 sessions 索引文件路径
• LOGFILE：覆盖 watchdog/cron 日志输出位置

它会综合判断这些活动信号的最近值：

• - lastvisiblereplyat
• lasttoolresultat
• lastprogressat
• updated_at

如果任务仍处于 analyzing / executing，且这些信号都沉默超过阈值，就返回 should_resume: true。

如果要直接产出保活续跑事件，用：

bash
python3 skills/long-run-mode/scripts/emitkeepaliveresume.py --task <任务名> --idle-seconds 60

它会返回：

• - delivery: session
• sessionKey
• message（续跑消息）
• onSuccess: task_state.py mark-resume

默认目标是：检测到长时间无输出后，先生成可审计的续跑计划。
只有显式设置 LONGRUNMODEAUTORESUME=1 时，才会真正把当前任务续起来。

状态机

• - analyzing
• executing
• waiting
• blocked
• handoff
• done

禁止模糊状态。

主规则：前台心跳优先

铁律：长任务一旦开始，后续每次继续推进前，若距上次可见进度已超 3m（或任务自己的 progress_every），必须先发一条短进度，不能先做别的。

只要任务还在 analyzing 或 executing：

• - 超过 progress_every（默认 5m）没有可见更新，就必须发一条短进度
• 当前执行流不能靠想起来再检查；必须把前台心跳嵌进每一轮工作循环
• 每完成一轮有意义推进后，固定跑一次循环钩子；如果到点，先汇报，再继续下一轮
• 短进度必须包含三件事：

推荐直接走工作循环钩子：

bash
python3 skills/long-run-mode/scripts/workcycletick.py --task <任务名> --step <这一轮刚做了什么>

它会：

• - 先判断现在是否到点
• 如果到点，返回 mustsendnow: true，这不是建议，而是硬信号
• 如果没到点，明确告诉你继续下一轮

强协议：

• - 只要返回 mustsendnow: true，当前这一轮就不得继续埋头做事
• 这是前台心跳，默认直接回当前会话，不要默认走跨会话 sessionssend
• session / boundary 字段表示任务归属边界，不等于真实可发送会话；真正可发送目标以 originsessionkey 为准
• 只有后台回收、跨会话转派、handoff 时，才应尝试 sessionssend
• 成功后必须执行：

bash
python3 skills/long-run-mode/scripts/task_state.py touch-progress --task <任务名>

• - 失败后必须执行：

bash
python3 skills/long-run-mode/scripts/task_state.py mark-pro