用途:puff 用于在不阻塞本地 CLI 会话的情况下启动 Codex Cloud 任务,通过 run_puff_tool 运行 Zig 版 puff CLI,提交工作、分离状态监视器,并保留日志与结果供后续 diff/apply 使用。
主要能力:提供 launch(异步后台执行,默认先跑 doctor,可用 --skip-doctor 跳过预检)、create(仅输出手动创建环境的说明)、submit(仅需任务 id/url)、doctor(认证与环境就绪检查)、watch(前台阻塞轮询)、jobs 与 stop(管理分离式监视器)、join-operator(生成并启动云端 join 循环提示,强制 manifest-first 路由与 seq -> join 执行,可用 --max-cycles 限制轮次,--canary 表示单轮)。
使用方式:先确保 ChatGPT 认证存在,执行 codex login;再运行 run_puff_tool doctor --env <env-id-or-label> 做就绪检查;随后用 run_puff_tool launch --env <env-id-or-label> --prompt "Implement X" 启动云端工作;用 run_puff_tool jobs 查看运行与完成的监视任务,必要时 tail -f <watch_log_path> 跟踪日志;结果就绪后用 codex cloud diff <task-id> 与 codex cloud apply <task-id> 检查或应用。--env 可传环境 id 或唯一环境标签。
安装:macOS 默认通过 brew install tkersey/tap/puff 安装;非 macOS 回退到从 skills-zig 仓库直接构建,需已安装 Zig,执行 zig build -Doptimize=ReleaseSafe 后将 zig-out/bin/puff 安装到 ~/.local/bin/puff。
适用场景:需要快速在云端启动编码任务并异步跟踪生命周期时使用;当编排需求超出简单云端任务生命周期控制时,改用 $cas。
限制:监视循环中 READY 与 APPLIED 视为成功终态,ERROR 视为终态失败,需用 codex cloud status <task-id> 与 codex cloud diff <task-id> 排查。其他细节暂未提供。