- name
- longtask_system
- version
- 1.2.0
- description
- |
LongTask System - 长程任务执行管理
核心原则：保持自动化运行。任一环节断链（Agent 离线、CLI 失败等）都会打断自动化流程并标记任务失败。为此引入 Agent Inbox 作为 fallback 机制，支持原子级进度记录和崩溃后重启续做。
解决长任务执行中的"睡着"、跳步、上下文丢失问题。
核心机制
daemon.sh ──▶ task_state.json ──▶ Agent 执行 ──▶ complete_step.sh ──▶ 下一任务
▲ │
└────────────────── 状态更新 ────────────────────────┘- daemon.sh 每15秒检查任务状态
- 发现
pending子任务 → 标记为doing→ 通知 Agent（CLI 或 inbox） - Agent 执行任务 → 调用
complete_step.sh标记完成 - 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_id3. 启动守护进程
# 方案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.json2. 防重复消费
- 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
注意事项
- 不要手动修改
doing状态的任务 - 默认不重试：
max_retry默认为 0，失败即停 - 超时时间：默认 5分钟，可通过环境变量
TIMEOUT调整 - 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)
- 初始版本