失败、重试与恢复
- 文档状态
- draft
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 更新
- 2026/10/16
先定位失败发生在哪一层，再决定重试、修配置、恢复访问或停止执行。反复移动业务状态、重复建任务或重启服务，可能让未解决的问题再次触发。
本页依据官方参考实现 be10a1b79df723d6d7612b5651c8522704dafb2e 的 Orchestrator、Elixir README及 SPEC §14。团队部署需匹配实际版本和项目恢复合同。
正常续跑和失败重试
| 触发 | 参考实现处理 | 含义 |
|---|---|---|
| worker 正常退出，未报告输入阻塞 | 约 1 秒后安排活跃状态续跑检查 | 不是失败；任务仍活跃时可开启后续会话 |
| worker 异常退出或可重试错误 | 指数退避后刷新任务，再决定派发 | 需要检查错误根因；等待不代表问题已恢复 |
| 没有可用并发槽位 | 等待或重排 | 不是业务拒绝，也不需要重复创建任务 |
| 输入、审批或 MCP elicitation 阻塞 | 进入该版本的 blocked 处理 | 需要操作方解决输入或授权问题，不应靠无限自动重试绕过 |
固定版本失败退避按 min(10000 × 2^min(attempt-1,10), agent.max_retry_backoff_ms) 计算，指数先以 10 为上限；示例与默认值不能当作线上配置。到期时按任务 ID 刷新：已终态则清理并释放，仍活跃可路由且有容量则派发，不再符合条件则释放认领。
常见故障从哪里查
| 现象 | 优先核对 | 恢复依据 |
|---|---|---|
| 服务无法启动 | WORKFLOW 路径与 YAML、支持的 tracker、来源范围及认证、启动命令 | 修正启动错误，再按 owning 服务方式启动 |
| 文件改了但行为没变 | 最近加载错误、有效配置、是否只影响后续会话或需要重启监听资源 | 不以磁盘新内容替代生效证明 |
| 有任务但没有派发 | 项目 scope、活跃 / 终态集合、路由、标签、依赖、认领、并发及派发前 ID 刷新 | 先解释具体准入条件，再在原生任务补齐缺口 |
| 有工作目录但没有会话 | after_create / before_run、Git 和依赖访问、app-server 二进制与认证 | 目录存在只证明准备到了某一步 |
| 正在重试 | 最近错误、attempt、due time、工作目录中已有成果 | 修根因并防止重复副作用，再等或按服务合同恢复 |
| 来源已终态仍看到旧信息 | 查询实例、快照时间、来源刷新错误、残留子进程 | 核对当前运行事实，不能只看旧评论 |
超时与停滞
codex.turn_timeout_ms 在这个版本表示流式 turn 的最长静默间隔，每次 app-server 更新都会重置；它不是整轮任务的总耗时上限。调度器另用 codex.stall_timeout_ms 检测运行停滞，从最近事件或启动时间计算；配置不大于零时该停滞检查关闭。
认定停滞后，调度器会停止 worker 并安排重试。操作方仍需确认宿主上的进程、网络请求、Git 操作及已产生副作用，不能把“服务已排重试”等同于旧进程和外部动作全部撤销。
等待输入或审批
该固定参考实现会把需要操作方输入、审批或 MCP elicitation 的任务保持为已认领，并在运行状态、JSON API 或面板展示 blocked。它不是 tracker 的业务状态；不要据此直接把任务改为 Done。
blocked 集合只在内存中。重启会清空它，仍处于活跃状态的原生任务可能再次被派发。因此先查清请求内容和项目允许的处理方式；如必须暂停，使用项目约定的来源状态或路由方式并确认核对结果，再处理服务。本文不承诺存在跨版本通用的“一键继续”接口。
重启恢复
参考实现的调度状态以内存为主，没有用持久化调度数据库恢复所有会话。重启后重新从 tracker 获取任务，并通过文件系统复用目录；启动时还查询终态任务并清理相应目录，查询失败会记录警告并继续启动。
恢复前应核对：
- 当前只有预期的服务实例，旧 Agent / worker 没有继续执行同一任务。
- 来源状态、项目范围与权限仍正确，尚待人工处理的任务不会因重启被意外重新选中。
- 目录中的修改、分支和交付证据已识别，后续提示不会重复已完成的外部写入。
- 新实例采用了预期 WORKFLOW，能重新读取来源，并出现与原生任务对应的新运行记录。
重启不是恢复旧 app-server 对话线程的保证，也不提供跨实例 exactly-once。人工关闭或取消任务可能触发目录清理，操作前先保留项目要求的成果。文档站或业务产品的部署失败，进入部署排障选择其 owning 链路。