Agent Step Sequencer

核心功能

Agent Step Sequencer 是一款专为复杂AI代理请求设计的多步骤调度框架，解决传统单次响应无法处理的深度任务场景。当用户请求包含3个以上动作、存在步骤依赖关系或涉及高风险操作时，该技能自动识别并建议分步执行计划，经用户确认后持久化状态，通过心跳机制保障任务在网关重置等异常情况下仍能正确恢复。

显著优点

1. 状态持久化与容错恢复：核心创新在于state.json状态文件机制，配合心跳检测脚本step-sequencer-check.py，即使执行中途遭遇网关重启，下次心跳自动读取状态并准确定位续接步骤，彻底解决长时任务易丢失的行业痛点。

2. 智能步骤编排：内置MULTI_STEP决策引擎，通过动作计数、顺序语言识别、输出依赖分析等维度自动判定任务复杂度，避免过度拆分或遗漏关键步骤。

3. 故障自主处理：执行失败时不中断等待用户，而是执行"重试→替代源→主动告知"的三级策略，既保证任务推进又确保用户知情权。

4. 安全设计：STEP_AGENT_CMD强制拒绝shell解释器，指令以单参数传递永不经过shell解析，有效防范命令注入攻击。

潜在局限

• 环境依赖较重：需正确配置STEP_AGENT_CMD心跳集成及Python运行环境，手动部署门槛对非技术用户偏高。
• 延迟权衡：建议的2分钟步间延迟虽保护API限流，但会显著拉长整体耗时，高频任务场景需精细调参。
• 状态文件单一：所有任务状态集中存储于单文件，并发多任务时可能产生竞争条件（文档未明确锁机制）。

适用人群

• 开发复杂AI工作流的工程师（多API调用链、数据流水线）
• 需要高可靠性任务执行的生产环境运维者
• 构建自动化研究、报告生成等长周期代理应用的用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 配置注入 | `STEP_AGENT_CMD`设置不当可能引入执行风险 | 仅使用可信二进制，禁止shell包装 |

| 状态损坏 | `state.json`异常修改导致调度混乱 | 定期备份，利用`blockers`字段人工干预 |

| 资源耗尽 | 失败步骤无限重试占用计算资源 | 默认3次上限，超限转入blockers队列 |

| 信息泄露 | 步骤指令含敏感数据写入明文state | 避免在instruction中硬编码密钥 |

核心功能

Agent Step Sequencer 是一个面向复杂 AI 请求的多步骤调度框架，解决单次对话无法完成的长周期任务问题。其核心能力包括：

• 智能步骤拆解：自动识别需多步骤执行的请求（3+ 动作、顺序依赖、输出依赖、高风险操作等），生成结构化执行计划
• 状态持久化：将执行计划写入 state.json，支持网关重置后的断点续传
• 心跳驱动执行：通过定时心跳（如每5分钟）或即时触发，驱动步骤顺序执行
• 故障自愈：步骤失败时自动重试（最多3次），每次重试附带故障诊断提示，支持备选数据源切换

显著优势

1. 可靠性设计：step-sequencer-runner.py 独立管理子进程，结合 step-sequencer-check.py 实现状态机驱动的执行流程，确保任务不中断
2. 安全防护：强制 shell=False 子进程调用，内置 _validate_agent_cmd 阻止 bash/sh/-c/-e 等危险命令，有效防御命令注入
3. 零依赖：纯 Python 标准库实现（json/os/subprocess/sys/time/pathlib），无供应链攻击风险
4. 灵活配置：支持 stepDelayMinutes 设置步骤间隔（推荐2分钟用于速率敏感 API），STEP_AGENT_CMD 可对接 OpenClaw 等外部 agent

潜在局限

• T3 来源级别：社区项目维护，需持续关注作者信誉和更新
• 本地状态依赖：state.json 文件权限管理由用户负责，误删或损坏将导致任务丢失
• 无分布式能力：单节点执行，不支持多机协作或云端状态同步
• 重试策略固定：最大重试次数通过环境变量配置，无法针对单步骤定制

适合人群

• 需执行跨会话长周期任务的开发者（如批量数据处理、多源调研报告生成）
• 对任务可靠性要求高、不能接受网关中断导致失败的生产环境
• 使用 OpenClaw 等框架构建自动化工作流的用户

常规风险

1. 配置风险：STEP_AGENT_CMD 若配置不当（如指向不可信二进制）可能导致非预期执行，建议仅使用可信 agent 路径
2. 状态污染：state.json 手动修改可能导致执行异常，建议通过工具接口操作
3. 资源占用：长期挂起的任务会持续触发心跳检查，需定期清理已完成状态
4. 调试复杂度：多步骤失败时需查看 stepRuns 历史定位问题，对新手有一定门槛