LongTask System - 长程任务执行管理

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

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

核心机制

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

1. 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：

json
{
agents: [
{agentid: bibi, agentname: 笔笔},
{agentid: tutu, agentname: 图图}
]
}

2. 创建任务

bash
cp tasktemplate.json tasks/mytask.json

编辑：定义 steps 数组，指定 agent_id

3. 启动守护进程

bash

方案1: screen（推荐，跨平台，可恢复查看）

screen -d -m -S longtask bash daemon.sh my_task

方案2: setsid（Linux 环境）

setsid bash daemon.sh mytask > longtasklog/daemon.log 2>&1 &

或前台调试

./daemon.sh my_task

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

4. Agent 消费任务

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

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

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

bash

读取并删除自己的 pending 任务（原子操作）

TASKJSON=$(./consumeinbox.sh bibi)

if [ -n $TASK_JSON ]; then
# 解析任务信息
TASKNAME=$(echo $TASKJSON | jq -r .task_name)
STEPID=$(echo $TASKJSON | jq -r .step_id)

# 执行任务...

# 标记完成
./completestep.sh $TASKNAME $STEP_ID success
fi

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

任务定义

json
{
taskid: batchwriting_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: ...}
}
]
}

关键字段

字段	说明	默认
agentid	执行 Agent	-
sessionname

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:{agentid}:{sessionname}

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

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

关键设计

1. 原子写入

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

2. 防重复消费

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

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

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

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

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

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

调试

bash
tail -f longtask_log/daemon.log # 全局守护进程日志
tail -f longtasklog/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

查看驾驶舱

bash

生成后打开浏览器查看

open tasks/cockpit.html

截图预览 / Screenshot

See preview in GitHub README

---

注意事项

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