---

name: longtask_system version: 1.1.0 description: | 长程任务执行管理系统 | Long-running Task Execution Management System 通过状态文件驱动，将长任务拆分为子任务，由守护进程按顺序触发执行，确保每步完成后再执行下一步。 State-file driven system that breaks long tasks into subtasks, triggered sequentially by daemon to ensure each step completes before next. 支持多 Agent 协作 | Multi-Agent collaboration supported.

重要：为了确保长程任务执行的效果，每一个子任务会强制通过/new重置对话后执行！如果你是单agent模式，可以在notify_agent.sh脚本中的消息构建删除/new命令。如果是多agent模式，请尽量确保你的任务中仅包含执行agent，不要包含监督agent。

---

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   # 标记任务完成
├── 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. 启动守护进程

# 后台运行
nohup ./daemon.sh my_task > longtask_log/daemon.log 2>&1 &

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

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                   # 检查任务状态

注意事项

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

更新日志

• v1.1 (2026-03-13)

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

• v1.0 (2026-03-12)

  • 初始版本