docs: clarify Workbench no-response timeout budget

2026-06-18 14:07:53 +00:00
parent 05f56fc25d
commit 1ae7796aa0
1 changed files with 8 additions and 0 deletions
@@ -44,6 +44,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
 - 切换 session 标签时，第一个用户可见消息或工具出现的时间，以及该 session 所需主数据、trace、turn 状态全部加载完成的时间。
 - 用户首屏打开 Workbench 时，第一个可操作/可读内容出现时间，以及工作台关键数据全部加载完成时间。
 - Workbench REST、SSE、trace pagination、turn snapshot、API proxy、AgentRun adapter 操作的常规 RED 指标。
+- 运行中 Code Agent turn 的无响应空闲时间、最近活动时间和投影刷新活性口径；该口径只衡量“多久没有新事实或可见进展”，不把 turn 总运行时长作为前端超时。
 - 前端 RUM 与后端 Prometheus 指标的关联键、脱敏边界、低基数 label、histogram bucket、recording rule 和低样本告警边界。
 - UniDesk YAML-first ops 形式的 D601 v0.3 Workbench 监控接入、scrape/render/status/summary CLI、告警/recording rule 配置和受控运维验证。

@@ -64,6 +65,7 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
 | First visible | 某个 journey 中第一条用户可读消息、工具调用、错误或加载完成主体在 Web 中可见。 |
 | Full load | 当前 view 所需权威 REST snapshot、必要 trace page、turn status 和 session rail 数据都已到达并完成可见投影。 |
 | Backend event visible latency | AgentRun backend 事件的 `createdAt` 或源 seq 时间到 Cloud Web visible ack 的耗时。 |
+| 无响应空闲时间 | 从最近一次可证明的 turn 活动到当前观察点的间隔；活动包括 accepted、run/command/runner job 创建、AgentRun event/result 更新、trace/sourceSeq 前进、SSE/REST snapshot 更新、visible ack 或 liveness heartbeat。 |
 | RUM | 浏览器端 Real User Monitoring，通过 Web Performance API、Navigation Timing、Long Task、SSE 接收和 DOM paint ack 采集真实用户性能。 |
 | Server-Timing | HTTP 响应头中的阶段耗时摘要，用于把 API 总耗时拆成 read model、DB、AgentRun adapter、projection 等后端阶段。 |
 | 低基数 label | Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。 |
@@ -325,6 +327,12 @@ UniDesk CLI 应提供薄 domain 入口，例如 `hwlab nodes observability plan|

 Cloud API 可以在 turn status 请求内尝试刷新 AgentRun result/events，但刷新必须有独立的短预算；预算、开关和后续调整必须来自 YAML/env 配置，不得把具体数值写成第二真相。预算耗尽时，API 应返回已有快照并标记 `turn_status_degraded`、`agentrun_result_poll_failed`、`trace_refresh_timeout` 或等价低基数错误，后续 poll、SSE 或后台刷新仍可继续补齐最新事件。除非权限不匹配、trace 不存在或请求参数非法，turn status 不应因为上游刷新慢而让 Web 客户端超时。

+Workbench 前端、Cloud API 投影层和性能监控不得维护或展示“运行总时长达到某阈值即超时”的 Code Agent 前端超时状态。运行中的 turn 只允许按无响应空闲时间判断可见性退化：只要 `lastActivityAt`、`lastActivitySeq`、AgentRun events/result、trace sourceSeq、SSE 消息、REST snapshot 或 visible ack 仍在推进，就必须继续视为 active/running，不得发出 `projection_sync_timeout`、`frontend_timeout`、`backend_timeout` 或等价总时长超时结论。
+
+当无响应空闲时间超过配置预算时，系统可以标记低基数 degraded reason，例如 `no_response_idle_timeout`、`runner_heartbeat_stale`、`provider_stream_inactive` 或 `projection_activity_stale`，并向用户展示“无响应 N 秒/分钟”和最近活动摘要。该 degraded 状态不能把 turn 改写为 terminal，不能取消 AgentRun command，不能替代 finalResponse，也不能创建另一条 polling、fallback 或 read-through repair 路径；后续只要同一权威投影出现新活动，idle 计时必须复位并继续从同一 turn/trace 展示进度。
+
+总 elapsed time 只可作为诊断字段、性能分布统计或长任务说明展示，不能作为 timeout 判定条件、关闭依据、自动重派依据或用户可见失败文案。性能指标应分别记录 `elapsedMs`、`idleMs`、`lastActivityAt`、`lastActivitySeq` 和 `activitySource`，告警和前端退化只使用 idle/no-response 口径。
+
 该需求不得削弱功能正确性：terminal result、billing finalize、session owner record、conversation fact 和 trace terminal evidence 仍由最终同步或后续 poll 完成；快速返回只限制单次用户可见 poll 的等待预算，不丢弃 AgentRun 事实、不伪造 final response、不把未完成 turn 标记为完成。

 ## 7. 过程控制