任务引擎

使用基于JSON持久化的状态机，跨多个智能体（Claude Code、Eva等）编排多步骤项目。每个任务都有分派给智能体的子任务，通过心跳进行跟踪，并通过Discord报告。

CLI命令

所有命令均从技能根目录运行：

bash
cd /home/zeron/.openclaw/workspace/skills/task-engine

所有命令均支持--json参数以输出机器可读格式：
json
{ok: true, task_id: TASK-001, status: PLANNING, message: 已创建 TASK-001}

创建任务

bash
python3 scripts/task_engine.py create 实现功能X --priority P0 --plan 3个阶段：模型、API、测试
python3 scripts/task_engine.py create 功能Y --priority P1 --json

查看状态

bash
python3 scripts/task_engine.py status # 所有活跃任务（表格形式）
python3 scripts/task_engine.py status TASK-001 # 单个任务详情
python3 scripts/task_engine.py status TASK-001 --json # 机器可读格式
python3 scripts/task_engine.py status --all # 包含已终止任务

转换任务状态

bash
python3 scripts/task_engine.py transition TASK-001 approve --note 计划已批准 --json
python3 scripts/task_engine.py transition TASK-001 block --note 等待API密钥
python3 scripts/task_engine.py transition TASK-001 complete --note 全部已验证 --json

向智能体分派子任务

bash
python3 scripts/task_engine.py dispatch TASK-001 实现认证模型 \
--agent claude-code --type dev --json
python3 scripts/task_engine.py dispatch TASK-001 运行集成测试 \
--agent eva --type test --deps subtask01,subtask02

分派第一个子任务会自动将状态从APPROVED转换为IN_PROGRESS。

更新子任务进度

bash
python3 scripts/taskengine.py subtask TASK-001 subtask01 start --progress 30 --json
python3 scripts/taskengine.py subtask TASK-001 subtask01 done --note 模型已完成 --json
python3 scripts/taskengine.py subtask TASK-001 subtask02 fail --note 模式不匹配 --json

检查任务（心跳集成）

bash
python3 scripts/task_engine.py check # 检查所有活跃任务（详细模式）
python3 scripts/task_engine.py check TASK-001 # 检查单个任务
python3 scripts/task_engine.py check --quiet # 最小化输出（适用于cron）
python3 scripts/task_engine.py check --json # 机器可读JSON
python3 scripts/task_engine.py check --discord # Discord格式摘要

归档已完成任务

bash
python3 scripts/task_engine.py archive TASK-001 --json # 仅适用于已终止任务

自动分派

自动分派会扫描子任务并将就绪的子任务分派给合适的智能体：

bash
python3 scripts/task_engine.py auto-dispatch TASK-001 # 分派就绪子任务
python3 scripts/task_engine.py auto-dispatch TASK-001 --dry-run # 预览而不执行
python3 scripts/task_engine.py auto-dispatch --all # 所有活跃任务
python3 scripts/taskengine.py auto-dispatch TASK-001 --subtask subtask02 # 指定子任务
python3 scripts/taskengine.py auto-dispatch TASK-001 --subtask subtask01 --show-context # 查看分派上下文

输出始终为JSON格式，包含dispatches和skipped数组。

通知（Discord格式）

生成Discord格式的通知消息：

bash
python3 scripts/task_engine.py notify digest # 完整心跳摘要
python3 scripts/task_engine.py notify TASK-001 created # 任务创建消息
python3 scripts/task_engine.py notify TASK-001 status # 带进度的状态更新
python3 scripts/task_engine.py notify TASK-001 transition # 最近一次转换
python3 scripts/task_engine.py notify TASK-001 completed # 完成摘要
python3 scripts/taskengine.py notify TASK-001 alert --type stuck --subtask-id subtask01

重建索引（恢复）

如果index.json损坏，从任务目录重建：

bash
python3 scripts/task_engine.py rebuild-index # 扫描并重建
python3 scripts/task_engine.py rebuild-index --json # 机器可读输出

心跳集成

在心跳的cmd_beat()函数中，在ongoing.json检查之后添加步骤4.3：

python

4.3 任务引擎检查

logger.info([4.3/8] 任务引擎检查)
try:
import sys
sys.path.insert(0, str(Path(/home/zeron/.openclaw/workspace/skills/task-engine/scripts)))
from engine.checker import checkalltasks
teresult = checkall_tasks()
if te_result.get(alerts):
alerts.extend(te_result[alerts])
all_ok = False
if te_result.get(summary):
logger.info( 任务：%s, te_result[summary])
except ImportError:
logger.debug( 任务引擎未安装，跳过)
except Exception as e:
logger.warning( 任务引擎检查失败：%s, e)

该检查开销很小（对于1-3个活跃任务，每次心跳约300-500个token）。它首先读取index.json，然后仅加载活跃任务的任务/子任务文件。

状态机

PLANNING ──approve──> APPROVED ──start──> IN_PROGRESS ──test──> TESTING ──review──> REVIEW ──complete──> COMPLETED
│ │ │ │ │ │
│reject block│ │fail reopen│ │fail reopen│ fail
v v v v v v v
REJECTED BLOCKED FAILED INPROGRESS FAILED INPROGRESS FAILED
│
unblock│
v
IN_PROGRESS

终止状态：COMPLETED、FAILED、REJECTED。

完整转换表请参见references/state-transitions.md。

子任务状态

PENDING -> ASSIGNED -> IN_PROGRESS -> DONE
│ │
│block │fail / block
v v
BLOCKED FAILED / BLOCKED

自动转换（由心跳检查）

条件	操作
所有type: dev子任务DONE	任务 -> TESTING
所有type: test子任务DONE

任务 -> REVIEW | | 第一个子任务已分派 | 任务 APPROVED -> IN_PROGRESS | | 任何子任务FAILED | 提醒人工干预 | | 子任务卡住3次以上心跳 | 通过Discord发送警报 | | 任务超过预计完成时间 | 标记为逾期警报 |

Discord格式

discord_formatter.py模块生成用于Discord通知的格式化消息。所有格式化均为纯字符串生成——不涉及API调用。

可用格式：

• - 任务已创建：带优先级和计划的新任务公告
• 状态更新：进度条和子任务树
• 状态转换：带表情符号指示器的状态变更
• 警报：紧急卡住/逾期/失败警报，附带人工@提醒
• 完成摘要：带子任务结果的最终报告
• 心跳摘要：所有活跃任务的完整摘要

进度条渲染为：[████░░░░░░] 40%

智能体能力

智能体	键值	最适合	最大并行数
Claude Code	claude-code	开发、重构、调试、文档	3
Eva

eva | 测试、验证、系统运维 | 1 |

智能体选择优先级：

1. 1. 首选智能体（如果指定且有能力）
2. 按preferred_types匹配
3. 按更广泛的capabilities匹配
4. 回退到Eva

详细信息请参见references/agent-capabilities.md。

故障排除

index.json损坏

bash
python3 scripts/task_engine.py rebuild-index --json

扫描所有tasks/TASK-*/task.json文件并重建