Agent Step Sequencer

核心用法

Agent Step Sequencer 是一款专为复杂多步骤任务设计的智能调度系统。当用户请求包含3个以上独立操作、存在步骤间依赖关系、或涉及高风险操作时，该技能会自动介入，将任务拆解为结构化的执行计划。

工作流程：
1. 智能识别：Agent 根据内置规则（操作数量、顺序语言、输出依赖、风险等级等）判断是否需要多步骤执行
2. 计划生成与确认：向用户展示步骤计划，询问是否添加2分钟延迟（适用于限频API调用），等待用户确认
3. 状态持久化：将计划、队列、当前步骤、重试计数等信息写入 state.json
4. 即时启动：Agent 立即调用 step-sequencer-check.py，无需等待心跳
5. 心跳保活：定时心跳（如每5分钟）同步检查任务状态，支持网关重置后的断点续执行

关键组件：

• Runner (step-sequencer-runner.py)：执行单个步骤，应用延迟，处理成功/失败状态
• Check Script：状态仲裁中心，处理工作调度、失败重试、步骤推进
• Heartbeat：定时触发保障机制

失败处理机制：
步骤失败时自动重试，最多3次。每次重试会将错误信息注入 troubleshoot prompt，帮助 Agent 诊断问题并修复后重新执行。

显著优点

• 高可靠性：状态持久化 + 心跳机制确保即使网关中断也能从中断点恢复
• 用户可控：执行前必须获得用户确认，支持自定义步骤间延迟
• 智能容错：自动重试 + 错误诊断提示，显著降低人工干预需求
• 灵活配置：通过环境变量可自定义 Agent 调用命令、重试次数等
• 清晰可审计：完整的 stepRuns 记录，便于追踪执行历史和故障排查

潜在局限

• 确认依赖：必须等待用户确认才能启动，不适合完全自动化场景
• 单点状态：依赖 state.json 文件，若存储损坏可能导致状态丢失
• 延迟限制：仅支持固定分钟级延迟（0或2分钟），不支持动态退避
• 无并行执行：步骤严格串行，无法利用并行加速独立子任务
• 人工阻塞处理：blockers 机制仅记录，需人工介入解除

适合人群

• 需要执行复杂多步骤工作流的技术用户（如系统迁移、多API协调、长文本生成链）
• 对任务可靠性要求高、不能接受中断后从头重来的场景
• 使用 OpenClaw 等 Agent 平台、需要与心跳机制集成的开发者

常规风险

• 状态文件损坏：需定期备份 state.json，避免磁盘故障导致进度丢失
• 无限重试陷阱：若错误为系统性问题（如配置错误），3次重试可能耗尽后仍需人工处理
• 敏感数据泄露：state.json 可能包含步骤指令中的敏感信息，需确保文件权限安全
• 心跳频率冲突：过高频率可能导致资源竞争，建议与邮件任务等其他心跳任务协调调度

核心功能

Agent Step Sequencer 是一款专为复杂代理任务设计的多步骤调度框架。它通过状态持久化、心跳同步和智能重试机制，确保长时间运行的多步骤工作流即使在网关重置或系统中断后仍能可靠恢复。

显著优点

1. 断点续传能力
采用 state.json 持久化设计，完整记录任务队列、当前步骤、执行历史等状态。配合心跳机制（建议每5分钟），系统可在任何中断点精确恢复，无需从头执行。

2. 零依赖安全架构
完全基于 Python 标准库（json, os, subprocess, datetime, pathlib）实现，无第三方包引入供应链攻击风险。代码仅372行、8个文件，结构清晰易于审计。

3. 智能步骤编排
自动检测多步骤需求（3+动作、顺序依赖、输出依赖、高风险操作），生成结构化执行计划。支持用户自定义步骤间延迟（0或2分钟），有效规避API速率限制。

4. 健壮的错误处理
内置失败重试机制（默认最多3次），每次重试附带完整的错误上下文和故障排查提示。支持 blocker 标记阻塞任务，避免无效重试。

潜在局限

• T3来源可信度：作为社区/个人项目，缺乏 GitHub 星级、贡献者等公开信誉指标
• 许可证未声明：文档未明确许可证，存在使用权限不确定性
• 配置依赖环境变量：STEP_AGENT_CMD 等关键配置需正确设置，误配置可能导致执行失败

适合人群

• 需要执行多步骤复杂任务（代码迁移、多文件重构、研究-撰写流水线）的开发者
• 运行环境不稳定、需要断点续传能力的生产系统
• 对供应链安全敏感、要求零外部依赖的安全意识用户

常规风险

低风险：子进程调用完全通过环境变量配置，无硬编码命令；3600秒超时保护防止挂起；无网络通信杜绝外泄风险。建议生产部署前设置 STEP_MAX_RETRIES 和验证 STEP_AGENT_CMD 格式，避免 shell 元字符注入。