智能体步骤序列器

针对深度请求的多步骤调度器。支持基于步骤的操作并集成了心跳机制——即使在网关重置的中间步骤也能保持存活。

核心模式

1. 解析当用户请求需要多个步骤时
2. 建议步骤计划，等待确认
3. 持久化state.json（包含计划格式）
4. 智能体调用 scripts/step-sequencer-check.py立即执行（无需等待心跳）
5. 心跳机制（例如每5分钟）也会触发该脚本——确保序列器与邮件任务及其他心跳任务保持同步

关键特性：若网关在步骤执行中途重置，下次心跳将读取状态并正确恢复执行。

计划格式

当用户批准时，智能体将构建计划。在确认过程中，智能体会询问：步骤间是否采用2分钟延迟？推荐用于对速率限制敏感的API调用。用户选择；代理设置stepDelayMinutes（0或2）在状态中。每个步骤都有title、instruction，以及可选的requiredOutputs（相对于工作空间的路径，必须在步骤标记为完成前存在）：

{
  "plan": {
    "steps": {
      "step-1": { "title": "Research topic X", "instruction": "Research topic X and produce a concise summary", "requiredOutputs": ["study/summary.md"] },
      "step-2": { "title": "Write paper", "instruction": "Using the summary from step 1, write a research paper..." }
    }
  },
  "stepQueue": ["step-1", "step-2"],
  "currentStep": 0,
  "stepRuns": {},
  "stepDelayMinutes": 0,
  "status": "IN_PROGRESS"
}

• title：人类可读的标签
• instruction：给代理的完整指令（研究、总结、从Y中提取X等）
• requiredOutputs（可选）：路径列表（相对于工作空间）。仅当代理以0退出且所有这些路径都存在时，运行器才会将步骤标记为完成；否则步骤将失败，并显示“缺少所需的输出：…”。

角色

• 代理：制定计划，持久化状态；在步骤执行期间不接触状态。接收提示。
• 运行器（step-sequencer-runner.py): 调用代理执行步骤指令，等待退出，标记为完成/失败。应用步骤延迟分钟数。重试时，代理会收到故障排除提示。
• 检查脚本(step-sequencer-check.py): 如有待处理任务，则调用运行器。处理失败 → 重试（重置为待定状态，调用运行器）。
• 心跳: 按计划调用检查脚本。

步骤执行：自主恢复

不要中途停止向用户询问。执行步骤时，如果发生故障（抓取为空、API错误、源不可用）：

1. 重试一次（同一源/URL），如果可能是暂时性问题。
2. 尝试替代方案（例如使用CoinGecko替代CoinMarketCap，或不同的端点或代币），并尽可能完成步骤。
3. 记录并退出仅在你确实无法完成步骤时——然后以非零状态退出，以便运行器标记为失败；调度器将使用故障排除提示进行重试。

不要静默停止。如果重试和尝试其他方法后仍无法完成步骤：请主动提示用户——发布一条简短消息，说明你遇到了问题、什么失败了以及你尝试了哪些方法（例如"步骤2（研究Meteora）失败：CoinMarketCap获取结果为空，尝试了CoinGecko——结果也为空。需要另一个数据源或跳过此代币。"）。然后以非零状态退出，以便运行器标记为失败，调度器可以重试或将其添加到阻塞项中。切勿在不告知用户的情况下直接停止。

代理如何确定多步骤操作

代理必须在继续执行前提出建议。当涉及多步骤操作时，提出步骤计划并在执行前等待确认。

MULTI_STEP =
  (action_count >= 3)
  OR has_sequential_language
  OR has_output_dependency
  OR high_scope_or_risk
  OR user_requests_steps
  OR contains_setup_keywords

SINGLE_STEP =
  (action_count == 1)
  AND NOT has_output_dependency
  AND immediate_execution

DECISION =
  IF MULTI_STEP THEN suggest_multi_step → wait for confirm → proceed
  ELSE single_step

定义：

状态模式

参见references/state-schema.md。关键字段：

• plan.steps：步骤定义（标题、说明、可选的requiredOutputs）
• stepQueue、currentStep、stepRuns
• stepDelayMinutes：0 = 无延迟；2 = 步骤间延迟2分钟
• blockers、lastHeartbeatIso,工件

心跳流程

心跳调用scripts/step-sequencer-check.py。代理在持久化状态后也会立即调用它。

1. 读取 state.json
2. 若无状态或状态=完成 → 不执行任何操作
3. 若步骤失败 → 增加尝试次数，重置为待处理，调用运行器（立即重试）
4. 若步骤完成 → 推进当前步骤，调用运行器
5. 若步骤待处理或进行中 → 调用运行器
6. 更新 lastHeartbeatIso

运行器调用代理（可通过STEP_AGENT_CMD配置）。运行器应用 stepDelayMinutes。

失败流程

1. 运行器标记步骤失败，将错误存储在 stepRuns 中
2. 运行器立即调用检查脚本（不等待心跳）
3. 检查脚本增加尝试次数，将状态重置为待处理，调用运行器
4. 运行器使用故障排除提示调用智能体："步骤X失败（尝试次数：N）。上次运行以：[错误]结束。请进行故障排除并重试：[指令]"
5. 重复直到完成或达到最大重试次数/阻塞项

流程图

检查脚本 → 运行器

flowchart TD
    A[Heartbeat or Agent] --> B[step-sequencer-check.py]
    B --> C{Work to do?}
    C -->|No| D[Do nothing]
    C -->|Yes| E[Invoke runner]
    E --> F[step-sequencer-runner.py]
    F --> G[Invoke agent with instruction]
    G --> H{Agent exit}
    H -->|Success| I[Mark DONE]
    H -->|Fail| J[Mark FAILED, invoke check script]
    I --> K[Check advances or done]
    J --> B

用户流程（提议 + 持久化）

flowchart TD
    U[User Request] --> V{Complex enough?}
    V -->|No| W[Execute directly]
    V -->|Yes| X[Propose step plan]
    X --> Y[User confirms]
    Y --> Z[Persist state.json with plan]
    Z --> AA[Agent invokes step-sequencer-check]
    AA --> AB[Runner invokes agent - step 1]
    AB --> AC[Heartbeat also invokes on schedule]

配置

OpenClaw：连接步骤_智能体_命令连接到OpenClaw的智能体调用（例如：openclaw agent --message）。

安全：设置STEP_AGENT_CMD仅指向您信任的代理二进制文件。请勿使用 shell 解释器（例如bash、sh等）或-c/-e参数——运行器会拒绝这些以防止命令注入。来自 state.json 的指令会作为单个参数传递；它永远不会由 shell 执行。

最终交付步骤

当所有步骤完成后：

• 确认满足所有步骤的要求
• 生成摘要，包含所有创建/写入文件的链接或路径
• 将状态标记为 DONE → 在后续心跳中，调度器将不执行任何操作

安装

clawhub install agent-step-sequencer

手动复制：

cp -r agent-step-sequencer ~/.openclaw/skills/agent-step-sequencer

心跳集成——将此添加到您的心跳中（或让代理添加）：

# Agent Step Sequencer check (add to heartbeat cycle)
python3 ~/.openclaw/skills/agent-step-sequencer/scripts/step-sequencer-check.py ~/.openclaw/workspace/state.json

或者，如果技能位于工作空间内：python3 ~/.openclaw/workspace/skills/agent-step-sequencer/scripts/step-sequencer-check.py ~/.openclaw/workspace/state.json

设置STEP_AGENT_CMD为您的代理调用命令，然后再运行。代理应在持久化状态后立即调用检查脚本。