docs: record hwlab agentrun failure attribution

This commit is contained in:
Codex
2026-06-02 04:44:01 +00:00
parent b7fe55a33a
commit 9f8a10ac26
4 changed files with 132 additions and 3 deletions
+1 -1
View File
@@ -111,7 +111,7 @@ HWLAB 负责自身产品和接入层,包括用户鉴权、Cloud Web/CLI 对外
HWLAB 通过 AgentRun 执行 Code Agent turn 时,失败归因必须以 AgentRun backend adapter 的结构化 failure kind 为准。AgentRun 负责把 provider、thread、runner、bundle 和 command lifecycle 的失败分类成稳定语义;HWLAB 负责原样消费并映射到用户可读分类。不得为了让 UI 或 issue 收口看起来更顺,把 AgentRun/provider 错误改写成 device-pod、gateway、Cloud API endpoint 或前端渲染问题。
Codex thread resume 失败必须由 AgentRun 明确归因和处理。当 `thread/resume` 遇到旧 app-server rollout 缺失、返回 `no rollout found for thread id` 这类可判定的 stale thread 时,AgentRun 应输出 `thread/resume:non-resumable`启动 replacement `thread/start` 继续当前 turn,并在成功后回写新的 `threadId` 到 sessionRef;不得让用户轮次直接失败,也不得要求 HWLAB 通过清会话、隐藏错误或重开路径迁就。只有不可恢复的 resume 协议错误或 replacement 也失败时,才输出 `thread-resume-failed`。HWLAB 收到该 failure kind 时,应显示为 AgentRun thread resume/replacement 层错误,不要把它解释成硬件执行通道或 Cloud API 不可达。
Codex thread resume 失败必须是单一路径失败。当 `thread/resume` 遇到旧 app-server rollout 缺失、返回 `no rollout found for thread id` 这类可判定的 stale thread 时,AgentRun 应终止当前 turn 并输出 `thread-resume-failed`不得启动替代 `thread/start`、替换 session 指针或在同一轮混入第二条 thread 路径。HWLAB 收到该 failure kind 时,应显示为 AgentRun thread resume 失败和当前轮次终止;不要把它解释成硬件执行通道或 Cloud API 不可达,也不要通过清会话、隐藏错误或重开路径迁就
Codex app-server/provider 返回 tool-call 参数 JSON 错误时,AgentRun 应输出 `provider-invalid-tool-call`。HWLAB adapter/Web 应映射为 provider/tool-call 层错误,并保留 `providerTrace.failureKind` 与简明 failure message,明确这不是 device-pod、gateway 或 Cloud API endpoint 故障。后续修复应进入 AgentRun provider/backend adapter 或上游 provider 请求构造,不要在 HWLAB 设备侧增加兼容路径。