From 1ae7796aa0445857ff93305be3811b618915a390 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 18 Jun 2026 14:07:53 +0000 Subject: [PATCH] docs: clarify Workbench no-response timeout budget --- .../specs/PJ2026-01060505-workbench-performance.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md index d8013e1b..4f449860 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md +++ b/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md @@ -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. 过程控制