From 616ca976a5d62a11cfeace002ba1d79b1ee89118 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 15 Jun 2026 19:02:35 +0000 Subject: [PATCH] docs: capture HWLAB Code Agent failure detail validation --- docs/reference/hwlab.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 37bd9779..b32b11e0 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -68,6 +68,8 @@ Code Agent trace/result 展示类问题的 typed CLI 关闭证据以 `hwlab-cli `result` 和 `trace --render web` 必须能直接证明 final assistant response、实际工具调用及状态、关键 trace/session/conversation/run/command/runner ID 和 runner/provider/lane 诊断。`inspect` 用于确认 trace 所属 session/conversation/thread、恢复上下文和下一步入口；它可以佐证 ID 和上下文，但不能单独替代 final response 或 Web renderer 行。验证必须打到 issue/CLI 选中的同一 node/lane public origin 或等价 Cloud Web/Cloud API dispatcher，不能用临时 AgentRun manager 调用、手写 raw request 或旧 lane trace 代替。 +失败详情类问题必须优先核对 `client agent result ` 的顶层 `error` 与 `agentRun`。`trace --render web` 只证明 rows/timeline 渲染，可能不携带 terminal result 的 `error`、`agentRun.runId`、`commandId`、`runnerId`、`jobName`、`namespace` 或 `terminalStatus`；Cloud Web 恢复会话时必须从 result 补齐这些诊断，再渲染详情弹窗。空字段不得渲染成大面积“未观测”占位；用户第一眼应看到错误码、错误类别和错误消息，有值的 AgentRun provenance 才进入状态摘要。 + `traceResultSummary.valuesPrinted=false` 只是脱敏声明，不等于免检。关闭前仍应扫描输出中是否出现完整 `HWLAB_API_KEY`、`hwl_live_*`、Authorization Bearer header、DB DSN、Secret payload 或 provider token。若 `upstreamGaps` 出现 `prompt_not_returned_by_upstream`，表示上游 trace/result payload 没有返回可脱敏展示的 prompt metadata；客户端不得发明 prompt 真相，应把该缺口拆到 Agent 编排或 trace payload issue，并说明它是否阻塞当前展示项。 ### Web Live DOM Probe 验收 @@ -84,6 +86,8 @@ Workbench prompt、TraceTimeline、final response、详情弹窗或工具调用 一次完整的 Workbench prompt UI 证据应覆盖：Web session 登录成功；模型通道选择符合目标 provider profile；显式创建或选择 session；prompt 被 `/v1/agent/chat` 接受并得到 `traceId/sessionId/conversationId/threadId`；页面可见用户消息、Agent message、final response；若 TraceTimeline 初始是 compact/result 压缩态，应在 Web 上触发 `回放 Trace` 后展开 timeline，让页面本身可见 `commandExecution` 等工具行。随后在同一 node/lane public origin 上，用 `hwlab-cli client agent result `、`trace ` 和必要的 `inspect ` 交叉确认 terminal status、toolCalls、finalResponse、AgentRun run/command/runner ID 和脱敏状态。 +详情弹窗和恢复会话类验收还应覆盖“从持久化 conversation 恢复”的路径，而不是只在刚完成 turn 的内存态截图。若用户报告的原始 conversation 对当前验收 actor 不可见，但同一 trace 的 `result` 可读，可以创建当前 actor 可见的临时 conversation，消息中挂载同一个真实 `traceId` 和最小 terminal agent message，再在 Web 中选择该临时会话、打开运行详情并等待 result 诊断自动补齐；验收后删除临时 conversation。closeout 必须写明这是同 trace 的恢复路径验证，不能声称修改或读取了原始用户 conversation。 + Cloud Web 登录页的中文错误可能会把 API upstream 502、rollout 中间态或真实 401 都表现成登录失败。遇到登录失败先用目标 public origin probe `/health/live`、`/auth/login` 状态和选中 namespace 的 API/Web/edge-proxy rollout；只有 API 已 ready 且 `/auth/login` 明确返回 401 时，才把它归类为凭据或用户状态问题。rollout 瞬态恢复后重跑同一短生命周期 Playwright 验收即可，不要把 transient `upstream_unavailable` 写成长期功能缺陷。 ## HWLAB FRP 维护