用途:在 maestro/ralph 工作流中逐条推进待执行步骤。每个会话的 state 唯一真源为 .workflow/.maestro/{session_id}/status.json;省略 session-id 时取最新 status==running 的会话,session_id 一旦确定,所有 CLI 调用须带 --session。
主要能力:按步骤 kind 分流。decision 步骤(step.decision 非空)经 Skill(maestro-ralph) 直调评估并 handoff;执行步骤(step.decision == null)统一经 maestro ralph next 加载,由 CLI 读取 command_path、解析 required_reading/deferred_reading、拼接 prompt 并写 active_step_index。此外支持占位符替换({phase}、{milestone}、{intent}、{scratch_dir} 等)、按 skill 的上下文补全、-y/auto_mode 透传、以及 analyze→plan→execute 产物的 --from/--dir 自动注入(限无显式参数时,已有参数不覆盖)。执行前加载前序步骤产出与 artifact,必要时用 maestro explore 补充代码上下文。
必要用法:加载用 maestro ralph next --session {session_id}(退出码 0 内联执行,2 全部完成,3 active_step_index 被占用,1 暂停);每步结束必须调用 maestro ralph complete N --session {session_id} --status <DONE|DONE_WITH_CONCERNS|NEEDS_RETRY|BLOCKED>(可带 --summary、--evidence、--decisions、--caveats、--deferred)或 maestro ralph retry N --session {session_id}。--summary 在 DONE/DONE_WITH_CONCERNS 时必填。
限制:仅支持 session.platform == codex;command_path 缺失或 required_reading 文件缺失会被拒绝(E006/E007);complete 与 active_step_index 不一致或状态非 running 会报 E008/E009;跳过步骤须手动改 status.json,无 CLI 子命令;无法确定会话时提示无运行中会话;费用、平台与效果资料暂未提供。