Skip to content

重试与失败关闭 ​

文档导航

失败关闭同样受任务提交门禁约束:有任务改动未提交时保持开放;无改动无需提交。提交与失败关闭是独立决定,不能自动提交失败代码。

检查失败可在原授权范围修复后显式重跑。需要保留失败结果归档时,必须满足声明策略和真实人工确认;失败不会因归档变成通过。

职责与适用范围 ​

Pi 记录执行尝试、受理显式重试并保留真实质量结果。runtime/attempts 与业务领域无关;workflows/default/retry.ts 提供质量检查自动修复策略,并为审查执行设置三次未解决尝试的预算。质量命令和独立方案审查器共用此机制,但使用任务内相互独立的通道。

系统没有自动修复智能体。只有审查适配器可为前两次超时签发可追溯的恢复许可;质量检查由显式 wenext_check 重跑,包括环境修复后源码未变的情况。普通质量重试不需要人工许可。wenext_finish 用于用户确认的归档,并复用当前成功证据。领域工具仍是普通命令,业务仓库维护声明、技能和规则。

工具与接口 ​

ts
wenext_retry({ action: "status" | "authorize", target: "quality" | "plan_review",
  kind?: "environment" | "after_fix", reason?: string })
wenext_finish({ ...existingFinishFields,
  resolution?: "failed" | "blocked", closureReason?: string })
AttemptService({ maxUnresolved: 2, automaticRepair: true })
// 内部受信任接口,不构成单独发布的 SDK:
service.begin(directory, lane, taskId, inputHash, runId?): attemptId
service.settle(directory, lane, attemptId, status, environment, reason, runId?)
service.propose(directory, lane, taskId, inputHash, kind, reason): RetryProposal
service.authorize(directory, proposal, human): AttemptState

失败关闭默认可由用户明确确认,保留失败结果;不需要为每个检查预先开启例外。严格仓库可在嵌套的 quality.schemaVersion: 2 中显式禁止某项检查失败关闭:

json
{
  "schemaVersion": 1,
  "quality": {
    "schemaVersion": 2,
    "checks": [{ "id": "tests", "command": ["npm", "test"], "allowFailureClosure": false }]
  }
}

省略或设为 true 允许请求人工失败关闭,显式 false 拒绝;该标记也约束对应检查的 verifyCommand。任务级追加检查默认同样允许请求失败关闭。成功完成仍要求所有适用必需检查通过。执行后修改此值会使冻结计划失效,不能追溯授权关闭。无需新增环境变量或 npm 包。

状态与执行 ​

  • <task>/attempts/<quality|plan_review>/state.json 指向经哈希校验的不可变事件。事件保留前序引用、输入哈希、上一次尝试 ID、真实运行 ID、状态、原因、进程持有者和计数。attempts-required.json 防止缺失状态被误当作新任务。
  • 重试许可绑定任务/通道、上一次结果、当前输入和策略,在准入时消耗。after_fix 要求输入发生变化,仅换一段说明不够。这是机械性的变化检查,不证明修复正确。
  • 质量输入包括冻结规则、提供方版本、阶段声明、源码输入和批准范围。审查输入绑定方案与写入路径。申请质量重试许可前会刷新范围观测。
  • environment 用于真实超时、取消或环境缺失。在默认质量自动修复策略下,显式质量重试无需人工确认,包括未分类的环境失败。严格的自定义策略可以要求许可。审查通道耗尽预算后仍需真实交互界面确认(审查预算为三次);无界面的调用方不能向工具提交布尔值或伪造人工批准。
  • 确认时重新核对任务、会话指针、输入和结果。取消或过期确认不会授予权限。人工继续会开启新的预算段,同时保留累计连续失败和历史;通过的尝试会重置连续失败计数。质量输入变化会开启新的修复预算段,同时保留失败历史。环境失败不消耗质量修复预算。
  • 进行中的尝试阻止另一次运行。已确认退出的本地 PID 恢复为 blocked,不会假定远端或仍存活的持有者已退出。恢复不重放命令。主检查等待复核时以 verification_pending 保持未解决;后续复核器使用原计数结算同一次尝试,覆盖检查与复核之间的崩溃窗口。
  • 普通命令失败不阻止后续检查。证据采集或工具异常会留下不可豁免的不完整计划。复核器针对成功且适用的检查运行,保留独立证据,同一已完成计划不重复复核。外部可变依赖必须声明,或在明确授权的新尝试中检查。
  • 失败关闭先读取完整的当前计划、结果和复核记录,再请求人工确认。<task>/quality/failure-closures/<id>.json 将批准绑定到任务、项目根、计划/运行和结果哈希。直接完成接口会再次校验此引用,调用方仅提供 approvedBy 不够。
  • 为兼容既有归档,任务状态仍为 completed,同时写入 completionResolution: failed|blocked。模式版本 2 的收据保留所有执行/领域判定、可选 verifications 和 closure(原因、例外、人工授权引用),结果仍是 result: failed。发件箱使用 task_closed_with_failure,与 task_finished 区分。

关闭时,默认 Git/范围钩子仍校验当前状态。任意自定义 checkRun 钩子不能跳过;当前额外提供方只有使用声明式检查才能支持失败关闭。所有 beforeFinish 门禁照常运行。这是明确的兼容边界,不代表可以豁免其它插件门禁。

结果与错误处理 ​

条件结果
失败后显式执行质量检查,包括输入未变的情况记录一次新尝试,普通重试无需批准
检查成功后由用户确认归档复用当前完整证据,不重新执行测试
after_fix 的相关输入完全相同拒绝
未分类的环境失败默认策略下质量重试无需批准;严格自定义策略/审查策略仍适用
审查或严格自定义通道预算耗尽,且无界面、确认被拒绝或取消拒绝并保留历史
确认期间任务、指针、输入或结果变化拒绝过期许可或关闭请求
尝试状态或批准证据缺失/被篡改拒绝,绝不静默重置
必需检查发生退出码/领域失败,未显式禁止失败关闭且证据完整人工可按 failed 关闭
仅存在未显式禁止关闭的超时、取消、环境或领域阻断人工可按 blocked 关闭,失败收据仍保持失败
tool_error、报告格式错误、计划不完整、产物缺失/被篡改拒绝关闭
请求的结论不匹配,或不存在阻断性失败拒绝关闭
未批准写入、审查过期、阶段缺失或其它插件门禁未满足仍拒绝完成
后续钩子或规范写入改变输入/配置最终同步门禁拒绝

协调与边界 ​

完成租约位于生成状态的 tasks/.coordination。本地摘要用于一致性校验,不是签名或操作系统沙箱;隐藏文件、外部服务和非协作进程仍受观察覆盖限制。

独立审查超时恢复见方案审查。人工接管不完整的智能体审查与质量失败关闭是不同授权,不能免除测试。