agent-step-sequencer

核心用法

Agent Step Sequencer 是一个专为复杂 Agent 请求设计的多步骤调度器。当用户请求包含 3 个以上动作、存在顺序依赖、输出依赖或高风险操作时，Agent 会自动检测并建议分步执行计划。用户确认后，系统生成结构化的 state.json 状态文件，包含步骤队列、延迟设置和输出要求。执行由 step-sequencer-check.py 心跳脚本驱动，通过 step-sequencer-runner.py 依次调用 Agent 完成各步骤，支持 0 或 2 分钟的步骤间延迟以应对 API 限流。

显著优点

该技能的最大亮点是网关重置后的自主恢复能力。传统 Agent 执行在长任务中因网络中断或网关重启而丢失上下文的问题，通过状态持久化和心跳机制得到彻底解决。其次，严格的故障处理策略要求 Agent 在失败时主动重试、寻找替代方案，仅在穷尽选项后才标记失败并通知用户，避免静默卡死。此外，输出验证机制通过 requiredOutputs 确保步骤真正完成而非仅退出成功，提升了任务可靠性。安全设计方面，明确阻止 shell 解释器和 -c/-e 参数，强制使用安全的二进制调用方式。

潜在缺点与局限性

首要限制是配置依赖：必须正确设置 STEP_AGENT_CMD 环境变量，错误配置可能导致执行失败或安全风险。其次，单步 1 小时超时虽防止无限挂起，但对于某些重型任务可能不足。状态文件 state.json 若被恶意篡改，可能导致执行非预期步骤，需依赖文件系统权限保护。此外，该技能专为 OpenClaw 生态设计，迁移至其他 Agent 框架需要适配工作。最后，步骤计划的生成质量完全依赖 Agent 的判断能力，复杂边界场景可能出现误判。

适合的目标群体

该技能最适合需要高可靠性长周期任务自动化的用户，包括：DevOps 工程师执行多阶段部署流水线、数据分析师运行依赖型 ETL 作业、研究人员进行文献综述→分析→撰写的连贯工作流、以及任何需要"设置后遗忘"（set-and-forget）且能从中断恢复的自动化场景。对于简单单步请求，该技能反而增加不必要的交互开销。

使用风险

性能风险：心跳机制引入周期性检查开销，高频心跳（如每分钟）在大量并发状态下可能累积负载。依赖风险：强依赖 Python 3 环境和正确的 STEP_AGENT_CMD 配置，环境迁移时需重新验证。状态一致性风险：若手动修改 state.json 或发生磁盘故障，可能导致步骤状态混乱。资源占用：失败步骤的重试机制可能重复消耗 API 配额或计算资源，需合理设置 STEP_MAX_RETRIES。

核心用途

Agent Step Sequencer 是一个面向复杂代理任务的多步骤调度框架，专为需要分解执行、状态持久化和故障恢复的场景设计。当用户请求包含3个以上动作、存在顺序依赖或输出依赖时，系统会自动建议分步计划，经用户确认后持久化到 state.json，并通过心跳机制保障任务在网关重置后仍能正确恢复。

显著优点

1. resilient 执行：网关中断不影响任务进度，下次心跳自动从断点恢复
2. 自主故障恢复：步骤失败时自动重试（最多3次），并提供故障排查提示
3. 零依赖安全：仅使用 Python 标准库，无第三方包，供应链攻击面为零
4. 灵活延迟控制：支持配置步骤间延迟（0或2分钟），适应速率限制敏感的 API 调用
5. 输出依赖校验：通过 requiredOutputs 机制确保步骤真正完成，而非仅依赖退出码

潜在局限

• 当前仅支持单机本地执行，无分布式协调能力
• 状态文件无并发锁机制，多进程同时访问可能损坏状态
• 路径校验存在边界情况，建议使用 relative_to 替代 in parents 判断
• 缺乏内置审计日志，故障排查依赖 state.json 内容

适合人群

• 需要执行多步骤研究/写作/数据分析工作流的 AI 代理用户
• 运行环境不稳定（网关可能重置）但需要任务可靠完成的场景
• 希望精细控制步骤执行节奏、避免 API 速率限制的开发团队

常规风险

• 环境变量配置风险：STEP_AGENT_CMD 必须指向可信代理二进制，禁止配置 shell 解释器
• 路径遍历：虽然已实施防护，但建议用户避免在 requiredOutputs 中使用绝对路径或 .. 序列
• 状态文件完整性：异常终止可能导致状态文件损坏，建议定期备份或实现文件锁机制