From d25a0e0c528f0b4ce34ac1094e6446894e09be80 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 16 Jun 2026 11:55:35 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20HWLAB=20Code=20Age?= =?UTF-8?q?nt=20=E7=8A=B6=E6=80=81=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/hwlab.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 1713670a..34631361 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -88,9 +88,11 @@ Workbench prompt、TraceTimeline、final response、详情弹窗或工具调用 详情弹窗和恢复会话类验收还应覆盖“从持久化 conversation 恢复”的路径，而不是只在刚完成 turn 的内存态截图。若用户报告的原始 conversation 对当前验收 actor 不可见，但同一 trace 的 `result` 可读，可以创建当前 actor 可见的临时 conversation，消息中挂载同一个真实 `traceId` 和最小 terminal agent message，再在 Web 中选择该临时会话、打开运行详情并等待 result 诊断自动补齐；验收后删除临时 conversation。closeout 必须写明这是同 trace 的恢复路径验证，不能声称修改或读取了原始用户 conversation。 -Session 切换、session rail 或 Workbench 恢复路径类问题必须同时验证点击态和持久化恢复态。浏览器证据应在同一 public origin 中选择一个非当前 session，等待足够覆盖 `hydrate`、`select-conversation`、active trace repair 等异步返回的空闲窗口，确认 active tab 没有回退；随后读取 `/v1/workbench/workspace?projectId=` 确认后端 `selectedConversationId` 已改变并持久化；最后刷新页面并再次等待 session tabs，确认同一个 session 仍是 active。若当前 selected conversation 没有出现在 `/v1/agent/conversations` 当前列表窗口中，前端必须把 workspace 当前选中 conversation 合入 session rail；刷新后没有 active tab、状态显示“等待 workspace”，或只靠内存态显示成功，均不能作为通过证据。自定义 Playwright 验收不要只按 tab index 或重复标题判断，应锁定唯一 title、conversationId 或后端 selected id，并记录 `select-conversation` response；与 session 切换无关的 health/RPC 噪声应拆成独立 issue，不阻塞已经通过的切换闭环。 +Session 切换、session rail 或 Workbench 恢复路径类问题必须同时验证点击态和持久化恢复态。浏览器证据应在同一 public origin 中选择一个非当前 session，等待足够覆盖 `hydrate`、`select-conversation`、active trace repair 等异步返回的空闲窗口，确认 active tab 没有回退；随后读取 `/v1/workbench/workspace?projectId=` 确认后端 `selectedConversationId` 已改变并持久化；最后刷新页面并再次等待 session tabs，确认同一个 session 仍是 active。若当前 selected conversation 没有出现在 `/v1/agent/conversations` 当前列表窗口中，前端必须把 workspace 当前选中 conversation 合入 session rail；刷新后没有 active tab、状态显示“等待 workspace”，或只靠内存态显示成功，均不能作为通过证据。session rail 的刷新列表只是候选窗口，不是 selected session 的完整真相；list API 临时缺当前 conversation 时，不得清空当前 tab、取消 active 状态或让标签在刷新/深链恢复中闪烁消失。自定义 Playwright 验收不要只按 tab index 或重复标题判断，应锁定唯一 title、conversationId 或后端 selected id，并记录 `select-conversation` response；与 session 切换无关的 health/RPC 噪声应拆成独立 issue，不阻塞已经通过的切换闭环。 -Code Agent 会话恢复的状态权威必须以最新 message 和同 turn trace 为准。conversation 顶层 `status=idle` 只能表示当前没有进行中的 turn，不能覆盖 message 自身的 `running` / `completed` / `failed`，也不能把 agent message 降级成 `source`；conversation 顶层 `lastTraceId` 若与最新 user/agent message trace 脱节，后端 summary 应按最新同 turn user/agent trace 修正，前端 hydrate/select/retry 后也应从最新 active message reattach trace。关闭刷新、deep link 或切换 session 后丢消息/卡住类 issue 时，验收必须同时看 DOM 最后一条 agent 的 `data-status`、conversation API 顶层 `lastTraceId`、最后 user/agent message 的 `traceId` 和 `runnerTrace.status`，不能只看 session rail 文案或 trace 面板是否出现占位文本。 +Code Agent turn 运行状态的权威入口是 `/v1/agent/turns/:traceId`，`traceId` 是单一查询键；`hwlab-cli client agent result `、Web composer、cancel 按钮、session 标签动效和最终消息状态都应消费同一 turn snapshot 的 `running`、`terminal`、`status`、`finalResponse`、`error` 和 AgentRun provenance。`/v1/agent/trace*`、conversation list、workspace summary、message status、runnerTrace rows 和 currentRequest 只能作为详情、列表或上下文来源，不能再反向推断 turn 是否运行中、是否完成或是否失败，也不能作为 fallback 与 turn endpoint 竞争覆盖 UI 状态。CLI 等待 terminal 时也应优先使用 submit 返回的 `turnUrl` 或 `/v1/agent/turns/:traceId`，只有详情展示才读取 trace rows。 + +Code Agent 会话恢复的状态权威必须以最新 message 和同 turn trace 为准。conversation 顶层 `status=idle` 只能表示当前没有进行中的 turn，不能覆盖 message 自身的 `running` / `completed` / `failed`，也不能把 agent message 降级成 `source`；conversation 顶层 `lastTraceId` 若与最新 user/agent message trace 脱节，后端 summary 应按最新同 turn user/agent trace 修正，前端 hydrate/select/retry 后也应从最新 active message reattach trace。关闭刷新、deep link 或切换 session 后丢消息/卡住类 issue 时，验收必须同时看 DOM 最后一条 agent 的 `data-status`、conversation API 顶层 `lastTraceId`、最后 user/agent message 的 `traceId`、`runnerTrace.status` 和 `/v1/agent/turns/:traceId` 的 `running` / `terminal`，不能只看 session rail 文案或 trace 面板是否出现占位文本。 Workbench session URL 是恢复路径的一部分。每个可见或当前选中的 session 都应能映射到 `/workbench/sessions/`，`/workspace/sessions/` 仅作为兼容 alias；从 `/workbench` 进入、创建 session 或点击 session rail 后，地址栏应反映当前 active `conversationId`，复制 session 信息时也应包含可直接打开的 session URL。直接打开 deep link 时，Cloud Web 静态层必须返回 SPA `index.html` 而不是 404；登录 redirect 必须保留原 path；登录后或 hydrate 后应通过 `/v1/agent/conversations/` 与 workspace select 路径把后端 `selectedConversationId` 收敛到 URL 中的 id。关闭 session URL/恢复类 issue 时，浏览器证据至少包含最终 URL、workspace API 的 `selectedConversationId`、active tab 判断，以及一次无 cookie direct GET 或等价探针确认 deep link 是 `200 text/html`。