LongTask System

State-file driven long task manager splitting tasks into sequential subtasks, supporting multi-agent collaboration and real-time visual monitoring.

LongTask System - 长程任务执行管理

核心原则：保持自动化运行。任一环节断链（Agent 离线、CLI 失败等）都会打断自动化流程并标记任务失败。为此引入 Agent Inbox 作为 fallback 机制，支持原子级进度记录和崩溃后重启续做。

解决长任务执行中的"睡着"、跳步、上下文丢失问题。

核心机制

daemon.sh ──▶ task_state.json ──▶ Agent 执行 ──▶ complete_step.sh ──▶ 下一任务
   ▲                                                    │
   └────────────────── 状态更新 ────────────────────────┘

1. daemon.sh 每15秒检查任务状态
2. 发现 pending 子任务 → 标记为 doing → 通知 Agent（CLI 或 inbox）
3. Agent 执行任务 → 调用 complete_step.sh 标记完成
4. daemon 触发下一任务

文件结构

longtask_system/
├── daemon.sh          # 守护进程
├── notify_agent.sh    # 通知 Agent（CLI/inbox 双模式）
├── consume_inbox.sh   # Agent 读取并删除 inbox 任务
├── complete_step.sh   # 标记任务完成
├── cockpit_renderer.py # 可视化驾驶舱生成器 (Cockpit Visualizer) ⭐ NEW
├── agents.json        # Agent 配置
├── agent_inbox.json   # 消息收件箱（CLI 失败时备用）
├── task_template.json # 任务模板
├── tasks/             # 任务文件目录
└── longtask_log/      # 日志目录

快速开始

1. 配置 Agent

编辑 agents.json：

{
  "agents": [
    {"agent_id": "bibi", "agent_name": "笔笔"},
    {"agent_id": "tutu", "agent_name": "图图"}
  ]
}

2. 创建任务

cp task_template.json tasks/my_task.json
# 编辑：定义 steps 数组，指定 agent_id

3. 启动守护进程

# 方案1: screen（推荐，跨平台，可恢复查看）
screen -d -m -S longtask bash daemon.sh my_task

# 方案2: setsid（Linux 环境）
setsid bash daemon.sh my_task > longtask_log/daemon.log 2>&1 &

# 或前台调试
./daemon.sh my_task

注意：OpenClaw 等 Agent 框架在 session 结束时会清理子进程，必须使用 screen 或 setsid 确保 daemon 不被杀掉。

4. Agent 消费任务

方式1：CLI 直接通知（正常流程）

• Agent 收到消息 → 执行任务
• 回调时必须使用任务标识（文件名）：./complete_step.sh 任务名 step_id success

方式2：Inbox 消费（崩溃恢复/CLI 失败）

# 读取并删除自己的 pending 任务（原子操作）
TASK_JSON=$(./consume_inbox.sh bibi)

if [ -n "$TASK_JSON" ]; then
    # 解析任务信息
    TASK_NAME=$(echo "$TASK_JSON" | jq -r '.task_name')
    STEP_ID=$(echo "$TASK_JSON" | jq -r '.step_id')
    
    # 执行任务...
    
    # 标记完成
    ./complete_step.sh "$TASK_NAME" "$STEP_ID" success
fi

关键：consume_inbox.sh 是读取即删除，防止重复消费。

任务定义

{
  "task_id": "batch_writing_20260313",
  "description": "批量写作15篇文章",
  "status": "running",
  "total_steps": 15,
  "agent_id": "bibi",
  "session_name": "main",
  "max_retry": 0,
  "steps": [
    {
      "id": 1,
      "name": "文章1：伊朗警告美国科技公司",
      "status": "pending",
      "params": {"topic": "...", "fingerprint": "..."}
    }
  ]
}

关键字段

字段	说明	默认
agent_id	执行 Agent	-
session_name	Session 名称	main
max_retry	单步骤失败重试次数	0（不重试）
global_retry	全局自动复苏次数（离线恢复用）	0（最多3次）
steps[].status	pending/doing/done/failed	-

状态流转

子任务: pending ──▶ doing ──▶ done
                    │
                    ▼ (超时或失败)
                  failed ──▶ pending (重试，若 retry < max_retry)
                    │
                    ▼ (重试用尽)
                  任务标记 failed，daemon 退出

超时：doing 状态默认 5分钟 超时（环境变量 TIMEOUT 可调）。

断点续传：重启任务时（status 改回 running）：

• done → 跳过
• failed → 重置 retry_count 为 0，重新尝试
• pending → 执行

多 Agent 协作

Session ID 格式：agent:{agent_id}:{session_name}

示例：agent:bibi:main、agent:tutu:main

在任务中指定 agent_id 即可分配给不同 Agent。

关键设计

1. 原子写入

jq '...' state.json > tmp.json && mv tmp.json state.json

2. 防重复消费

• CLI 成功：直接送达 Agent
• CLI 失败：写入 inbox，Agent 用 consume_inbox.sh 读取即删除

3. Fail-Stop 闭环（任务复苏）

CLI 投递失败时的处理流程：

1. CLI 失败 → 写入 Inbox → daemon 标记 failed → daemon 自杀
2. Agent 重启 → consume_inbox.sh → 执行任务 → complete_step.sh
3. 自动复苏：子任务成功时，若全局状态为 failed，自动重置为 pending
4. 重启 daemon → 继续执行

防重保护：notify_agent.sh 写入 Inbox 前检查是否已存在相同任务，避免重复投递。

全局重试上限：global_retry 字段记录自动复苏次数，超过 3 次不再自动重置，需手动检查。

调试

tail -f longtask_log/daemon.log              # 全局守护进程日志
tail -f longtask_log/task_任务名.log         # 单个任务的独立日志
tail -f longtask_log/trigger.log             # 任务触发日志
cat agent_inbox.json | jq                    # 检查 inbox
cat tasks/任务名.json | jq                   # 检查任务状态

---

🎨 Cockpit 可视化驾驶舱 / Visual Cockpit ⭐ NEW

实时监控任务执行状态的可视化界面。

功能特性 | Features

• 🐕 萌宠主题 - Pet Workshop 可爱风格，缓解等待焦虑
• 🔄 实时刷新 - 每 3 秒自动更新状态
• 📊 进度可视化 - 果酱流动效果进度条
• 🎭 状态动画 - 不同状态对应不同小动物动画:
  • 🐱 done - 猫咪满意
  • 🐕 doing - 小狗挖土（摇摆动画）
  • 💤 pending - 小猫睡觉（呼吸动画）
  • 👻 failed - 小鬼出现

自动生成

Cockpit 会在以下情况自动生成/更新：

• 任务状态变更时（daemon 自动触发）
• 手动运行: python3 cockpit_renderer.py tasks/任务名.json

查看驾驶舱

# 生成后打开浏览器查看
open tasks/cockpit.html

截图预览 / Screenshot

See preview in GitHub README

---

注意事项

1. 不要手动修改 doing 状态的任务
2. 默认不重试：max_retry 默认为 0，失败即停
3. 超时时间：默认 5分钟，可通过环境变量 TIMEOUT 调整
4. daemon 自动退出：状态文件超过 20 分钟未更新时退出

更新日志

• v1.2 (2026-03-17)

  • 新增 cockpit_renderer.py 可视化驾驶舱，萌宠主题设计
  • 修复 daemon 在 OpenClaw 环境下被 session 杀掉的问题（使用 screen/setsid）
  • 优化 agent_id 读取逻辑，支持 step 级别覆盖
  • 优化驾驶舱 Agent 显示，正确显示 step 级 agent_id

• v1.1 (2026-03-13)

  • 新增 consume_inbox.sh，实现读取即删除
  • 新增多 Agent 支持
  • 新增 agents.json 配置

• v1.0 (2026-03-12)

  • 初始版本