Agent Step Sequencer

核心用法

Agent Step Sequencer 是一种用于多步骤复杂任务的调度框架，而非直接面向终端用户的工具。其核心工作流程为：

1. 智能识别：Agent 自动检测用户请求是否需要多步骤执行（3个以上动作、存在顺序依赖、输出依赖、高风险操作或用户明确要求分步）
2. 方案提议：生成结构化的步骤计划，等待用户确认后方可执行
3. 状态持久化：将计划写入 state.json，支持断点续作
4. 心跳驱动执行：通过 step-sequencer-check.py 脚本驱动 step-sequencer-runner.py 逐步调用 Agent 完成各步骤

关键特性

• 断点续作：网关重置或中断后，下次心跳自动读取状态并恢复执行
• 延迟配置：支持设置步骤间延迟（推荐2分钟）以规避 API 速率限制
• 自主故障恢复：步骤失败时自动重试一次，尝试替代数据源，无法完成时主动提示用户而非静默失败
• 失败重试机制：最多3次重试，附带故障排查提示

状态结构

包含步骤定义（title/instruction）、执行队列、当前步骤索引、运行记录、延迟设置、阻塞项及产物路径等完整元数据。

配置要求

需设置 STEP_AGENT_CMD 指向受信任的 Agent 二进制文件，拒绝 shell 解释器以防止命令注入。

显著优点

• 可靠性：状态持久化 + 心跳机制确保长时任务不因中断而丢失进度
• 透明可控：执行前必须经用户确认计划，每个步骤有明确标题和指令
• 故障自愈：内置重试、替代方案尝试、用户主动通知的三层容错
• 灵活集成：通过环境变量适配不同 Agent 调用方式（如 OpenClaw）
• 安全设计：命令注入防护、严格的执行权限控制

潜在局限

• 基础设施依赖：需要配置心跳机制（如每5分钟）和持久化存储，对简单场景过度设计
• 非实时交互：步骤执行期间 Agent 不响应用户，需等待完成或失败
• 调试复杂度：分布式执行（check → runner → agent）增加问题定位难度
• 状态文件管理：需确保 state.json 路径正确且可写，多实例并发可能产生冲突
• 重试上限固定：最大3次重试不可动态调整，某些场景可能不足

适合人群

• 自动化工作流开发者：需要可靠执行多步骤 API 调用、数据流水线、报告生成的开发者
• 长时任务需求者：涉及多个数据源聚合、分阶段文档编写的场景
• 高可靠性要求场景：金融数据同步、多系统迁移等不可失败的任务
• OpenClaw/类 Agent 框架用户：已有心跳机制的基础设施环境

常规风险

• 状态损坏风险：state.json 若被手动篡改或并发写入可能导致执行混乱
• 无限循环风险：配置错误的重试逻辑或 flaky 步骤可能消耗过量资源
• 敏感信息泄露：步骤指令可能包含 API 密钥或内部路径，需确保状态文件权限控制
• 心跳堆积：高频心跳 + 慢步骤可能导致 runner 重叠调用，需确保脚本级别的执行锁
• Agent 指令注入：虽对 STEP_AGENT_CMD 有安全校验，但步骤 instruction 内容本身仍需信任边界内的输入

核心功能

Agent Step Sequencer 是一款专为 Claude Code / OpenClaw 设计的多步骤任务调度框架，解决复杂请求需要拆解为多个依赖步骤的执行难题。其核心能力包括：智能识别多步骤场景→生成可确认的执行计划→持久化状态到 JSON→通过心跳机制驱动执行→支持网关中断后的自动恢复。

显著优点

1. 断点续执行能力：网关重置或会话中断后，心跳检查脚本读取 state.json 自动恢复，无需用户干预
2. 失败自愈机制：步骤失败时自动重试（默认最多3次），并注入故障排查提示，避免无限挂起
3. 零第三方依赖：仅使用 Python 标准库，无供应链攻击风险
4. 明确的命令注入防护：内置黑名单禁止 bash/sh/eval 及 -c/-e 参数，强制 shell=False 调用
5. 灵活的延迟配置：用户可选择步骤间0分钟或2分钟延迟，适配 API 速率限制场景

潜在局限

• T3 来源可信度：个人开发者/社区项目，无公开源码托管，需代码审查后使用
• 本地状态单点依赖：state.json 损坏或权限问题会导致调度中断
• Agent 命令配置风险：虽有限制，但 STEP_AGENT_CMD 指向恶意二进制仍可造成危害
• 仅支持顺序执行：不支持步骤并行或复杂 DAG 依赖

适合人群

• 需要编排「搜索→分析→生成报告」等多阶段任务的 Claude Code 用户
• 对任务可恢复性、可观测性有要求的长时运行场景
• 能接受 T3 来源、具备基础代码审查能力的个人或小型团队

常规风险

1. 配置风险：STEP_AGENT_CMD 应使用绝对路径指向可信 Agent
2. 状态文件安全：建议 chmod 600 限制 state.json 访问权限
3. 无限重试陷阱：需根据场景设置合理的 STEP_MAX_RETRIES
4. 隐私合规：读取环境变量用于配置，无上送行为，符合 GDPR 数据最小化原则