Live Task Pulse
Real-time task execution tracking with live push notifications.
Why This Exists
Other trackers write to files — users can't see progress until they ask. Live Task Pulse pushes every step change to the user's chat instantly via OpenClaw's message tool, while persisting state to JSON for crash recovery.
Architecture
CODEBLOCK0
Dual-layer = no other skill does both.
Quick Reference
Create task → push start notification
TASK_ID=$(python3 scripts/task_pulse.py create "任务名" "步骤1" "步骤2" "步骤3")
Then immediately call
message tool:
CODEBLOCK2
Advance to next step → push progress
python3 scripts/task_pulse.py next "$TASK_ID" "抓取了25条数据"
Then push: INLINECODE2
Heartbeat (long step, >1min)
python3 scripts/task_pulse.py heartbeat "$TASK_ID" "已处理60%"
Push only if meaningful progress (avoid spam).
Complete
python3 scripts/task_pulse.py done "$TASK_ID" "发布成功 https://..."
Push: INLINECODE3
Fail
python3 scripts/task_pulse.py error "$TASK_ID" "登录过期"
Push: INLINECODE4
Query status
CODEBLOCK7
Cleanup (>7 days completed)
CODEBLOCK8
Mandatory Rules
- 1. Always push after file update — file update alone is invisible to users
- Push format: emoji +
[done/total] + current step + one-line info (≤3 lines) - Push frequency: every step transition; long steps max once per 30s
- Stall = running + no update for 3 minutes — detected on
status query - On stall detection: push INLINECODE7
- Cleanup: run in heartbeat, keep completed tasks 7 days
Status Icons
| Status | Icon | Meaning |
|---|
| running | 🔄 | Executing |
| done |
✅/🎉 | Completed |
| error | ❌ | Failed |
| stalled | ⚠️ | No update >3min |
| pending | ⏳ | Step not started |
Integration
- - Cron jobs: Wrap cron task payload with create/next/done calls
- Sub-agents: Parent agent creates task, sub-agent updates via file, parent pushes
- Heartbeat cleanup: Add
python3 scripts/task_pulse.py cleanup to HEARTBEAT.md - Multi-channel:
message tool auto-routes to the active channel
See references/integration-guide.md for cron and sub-agent patterns.
实时任务脉冲
通过实时推送通知进行任务执行追踪。
存在意义
其他追踪器仅写入文件——用户必须主动查询才能看到进度。实时任务脉冲通过OpenClaw的message工具将每一步状态变更即时推送到用户聊天窗口，同时将状态持久化到JSON文件以实现崩溃恢复。
架构
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ task_pulse.py│───>│ JSON on disk │ │ Users chat │
│ (CLI工具) │ │ (持久化存储) │ │ (Telegram/ │
└──────┬───────┘ └──────────────┘ │ Discord/..)│
│ └──────▲──────┘
│ ┌──────────────┐ │
└────────>│ message工具 │──────────────┘
│ (实时推送) │
└──────────────┘
双层架构 = 其他技能无法同时实现这两点。
快速参考
创建任务 → 推送开始通知
bash
TASK
ID=$(python3 scripts/taskpulse.py create 任务名 步骤1 步骤2 步骤3)
然后立即调用message工具：
message(action=send, message=🚀 开始【任务名】\n📋 步骤1 → 步骤2 → 步骤3\n🔄 当前: 步骤1)
推进到下一步 → 推送进度
bash
python3 scripts/task
pulse.py next $TASKID 抓取了25条数据
然后推送：message(action=send, message=✅ [1/3] 步骤1完成（抓取了25条数据）\n🔄 → 步骤2)
心跳（长步骤，>1分钟）
bash
python3 scripts/task
pulse.py heartbeat $TASKID 已处理60%
仅在进度有意义时推送（避免刷屏）。
完成
bash
python3 scripts/task
pulse.py done $TASKID 发布成功 https://...
推送：message(action=send, message=🎉 【任务名】完成！\n结果: https://...)
失败
bash
python3 scripts/task
pulse.py error $TASKID 登录过期
推送：message(action=send, message=❌ 【任务名】失败\n错误: 登录过期)
查询状态
bash
python3 scripts/task_pulse.py status
清理（超过7天的已完成任务）
bash
python3 scripts/task_pulse.py cleanup
强制规则
- 1. 文件更新后必须推送——仅更新文件对用户不可见
- 推送格式：表情符号 + [已完成/总数] + 当前步骤 + 单行信息（≤3行）
- 推送频率：每步转换时推送；长步骤每30秒最多一次
- 卡顿检测 = 运行中 + 3分钟无更新——在status查询时检测
- 检测到卡顿时：推送⚠️ 【任务名】可能卡住了（3分钟无更新）
- 清理：在心跳中运行，保留已完成任务7天
状态图标
✅/🎉 | 已完成 |
| 错误 | ❌ | 失败 |
| 卡顿 | ⚠️ | 超过3分钟无更新 |
| 待处理 | ⏳ | 步骤未开始 |
集成
- - 定时任务：用create/next/done调用包装cron任务负载
- 子代理：父代理创建任务，子代理通过文件更新，父代理推送
- 心跳清理：将python3 scripts/task_pulse.py cleanup添加到HEARTBEAT.md
- 多通道：message工具自动路由到活跃通道
有关cron和子代理模式，请参阅references/integration-guide.md。
