pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01060505-workbench-performance.md

PJ2026-01060505 Workbench性能

修改历史

版本	对应 commit id	更新日期	变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-01060505 Workbench性能需求规格

1. 文档控制

字段	内容
编号	PJ2026-01060505
短名	Workbench性能
层级	L3 子课题
状态	已生效
实现引用版本	draft-2026-06-17-p0
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-010605 运维监控
关联规格	PJ2026-010401 Web工作台、PJ2026-010403 API契约、PJ2026-010205 HWLAB接入
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 D601 v0.3 Workbench 用户可感知性能监控的稳定使命、范围、术语、系统边界、内部分工、目标图和原子需求。

2. 目的和范围

2.1 目的

Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待时间、实时消息投递时间、session 切换加载时间和首屏打开时间转化为可查询、可告警、可回归的 Prometheus/RUM 指标。

本规格的目标状态是：用户从 Web 发起动作后，浏览器、Cloud API、Workbench SSE、trace/read model、AgentRun adapter 和 Prometheus 之间拥有同一套低基数性能事件口径；平台运维可以用这些指标判断 D601 v0.3 Workbench 是否变慢，客户端和 Agent编排可以用同一 traceId/runId 的脱敏诊断继续定位，但监控本身不替代业务功能闭环。

相关运维必须按 UniDesk YAML-first ops 设计：scrape target、recording rule、alert rule、dashboard summary、Prometheus 查询 endpoint、采样/保留/阈值和 D601 node/lane 归属都进入 UniDesk owning YAML；受控 UniDesk CLI 只负责读取 YAML、校验结构、渲染计划、apply/status/summary，并通过共享 ops helper 执行。运行面 Kubernetes 对象、Prometheus target 状态和 Grafana/Prometheus 查询结果只能作为观测对象，不得反向成为配置 source of truth。

2.2 范围内

• 用户发出消息到首个 Code Agent 消息或工具调用在 Web 可见的耗时。
• AgentRun backend 事件从产生到最终用户 Web 可见的耗时，包括 codex-stdio、assistant message、tool call、terminal result 等用户可读事件。
• 切换 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 配置和受控运维验证。

2.3 范围外

• 工作台布局、消息投影、Trace阅读视图和会话权威 API 的功能正确性仍由 PJ2026-010401 Web工作台 和 PJ2026-010403 API契约 定义。
• AgentRun run、command、runner、backend profile 和 provider 事件事实归 PJ2026-0102 Agent编排 与 PJ2026-010205 HWLAB接入。
• Prometheus 具体采样间隔、保留周期、阈值、Grafana 面板 URL 和告警路由以 YAML/config 为准，不在本规格硬编码。
• 长 trace、完整 prompt、assistant 正文、tool 参数、命令输出、Secret、token、DSN 和原始 provider payload 不进入性能指标 label 或默认日志。

3. 术语表

术语	定义
用户可感知性能	用户在浏览器工作台中能直接感受到的等待时间、加载进度、首个可读内容和完整可用状态。
Journey	从一个用户动作或页面生命周期起点到一个用户可见终点的端到端性能路径。
Visible ack	浏览器状态更新后，目标消息、工具调用或加载状态至少经过一次 DOM paint 并可被用户看到的确认点。
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 或用户输入。
YAML-first UniDesk ops	UniDesk 自有运维事实先进入 YAML，再由受控 CLI 渲染、校验和下发；运行面对象只作为观测面，不反推配置真相。

4. 系统边界和接口

边界项	内容
外部使用者	平台管理员、Workbench owner、Agent编排 owner、D601 v0.3 值守人员和性能回归调查者。
外部输入	浏览器 navigation/RUM event、Workbench REST/SSE event、DOM visible ack、Cloud API route timing、AgentRun event createdAt/sourceSeq、Prometheus scrape。
受控资源	Workbench RUM buffer、/v1/web-performance 接收入口、Cloud API Prometheus metrics、SSE 连接状态、AgentRun adapter timing、recording rule 和性能摘要。
外部输出	Prometheus histogram/counter/gauge、低噪声性能摘要、Server-Timing header、Web performance dashboard、issue closeout 可引用的查询结果。
用户接口	D601 v0.3 Cloud Web https://hwlab.pikapython.com/workbench、同源 Workbench REST/SSE API、Prometheus 查询入口和受控运维 CLI。
系统边界	Workbench性能只定义性能采集、指标和可见性口径；不改变消息事实、AgentRun 事实、用户权限、会话 authority、业务完成标准或发布流程。

4.1 目标架构图

flowchart LR
  subgraph Browser[Cloud Web / Workbench]
    NAV[Navigation Timing]
    STORE[Workbench Store]
    DOM[DOM Paint Ack]
    RUM[RUM Buffer]
    ES[EventSource Client]
    API[API Client]
    NAV --> RUM
    STORE --> DOM
    DOM --> RUM
    ES --> STORE
    API --> STORE
  end

  subgraph CloudAPI[HWLAB Cloud API]
    ROUTE[REST/SSE Routes]
    PERF[/v1/web-performance/]
    TRACE[Trace Store]
    READ[Workbench Read Model]
    MET[Prometheus Metrics 9100]
    ROUTE --> READ
    ROUTE --> TRACE
    ROUTE --> MET
    PERF --> MET
  end

  subgraph UniDeskOps[UniDesk YAML-first Ops]
    YAML[owning YAML]
    CLI[ops CLI plan/apply/status/summary]
    HELP[shared ops helpers]
    YAML --> CLI
    CLI --> HELP
  end

  subgraph AgentRun[AgentRun / Backend]
    EVT[Run Events]
    CODEX[codex-stdio]
    ADAPT[HWLAB AgentRun Adapter]
    CODEX --> EVT
    EVT --> ADAPT
  end

  ADAPT --> TRACE
  TRACE --> ROUTE
  ROUTE -- SSE / REST --> ES
  API -- REST --> ROUTE
  RUM -- batched RUM --> PERF
  HELP -- scrape/rule/render --> PROM
  MET --> PROM[Prometheus / Rules / Dashboard]

4.2 目标数据流图

flowchart TD
  A[用户动作或页面生命周期起点] --> B[clientJourneyId]
  B --> C[REST request / SSE cursor / route activation]
  C --> D[Cloud API phase timing]
  C --> E[AgentRun event source metadata]
  D --> F[Trace/read model projection]
  E --> F
  F --> G[SSE event or REST page received]
  G --> H[Workbench reducer applies authoritative state]
  H --> I[Timeline/session projection]
  I --> J[nextTick + requestAnimationFrame + requestAnimationFrame]
  J --> K[Visible ack]
  K --> L[RUM event batch]
  D --> M[Prometheus backend metrics]
  L --> N[/v1/web-performance]
  N --> M
  M --> O[PromQL / recording rules / alerts]

数据流必须保证：client journey 起点、后端 phase timing、AgentRun source metadata 和 visible ack 可以在诊断时通过脱敏 correlation id 对齐；Prometheus label 不使用高基数业务 ID，traceId/sessionId/runId 只允许进入 debug payload、日志摘要或 exemplar 类受控扩展，不进入默认 label。

4.3 用户消息到首个可见事件时序图

sequenceDiagram
  participant U as User
  participant W as Cloud Web
  participant A as Cloud API
  participant AR as AgentRun
  participant TS as Trace Store
  participant P as Prometheus

  U->>W: submit prompt
  W->>W: start journey submit_to_first_visible
  W->>A: POST turn admission
  A->>AR: create run/command
  A-->>W: 202 turnId/traceId/message ids
  AR-->>A: backend event assistant/tool/status
  A->>TS: append trace event with source createdAt
  A-->>W: SSE trace event or REST page
  W->>W: reducer + projection
  W->>W: DOM visible ack
  W->>A: batch RUM visible event
  A->>P: observe journey and backend-visible latency

首个可见终点只接受用户可读的 assistant message、tool call、terminal error 或明确失败状态；request accepted、run created、command created、runner job created、backend status heartbeat 和隐藏统计不算首个可见终点。

4.4 AgentRun backend event 到 Web 可见时序图

sequenceDiagram
  participant B as codex-stdio / backend
  participant AR as AgentRun Event Log
  participant H as HWLAB Adapter
  participant TS as Trace Store
  participant SSE as Workbench SSE
  participant W as Cloud Web
  participant P as Prometheus

  B->>AR: emit event createdAt/sourceSeq
  AR-->>H: fetch events after cursor
  H->>TS: map and append trace event
  TS-->>SSE: subscriber notification
  SSE-->>W: trace event
  W->>W: render row and visible ack
  W->>P: RUM backend_event_visible
  H->>P: adapter fetch/map/append phase timing

backend event visible latency 的起点优先使用 AgentRun 事件 createdAt；缺失时使用 sourceSeq 对应的接收时间，并在诊断字段标记 sourceClock=receive_time。终点必须是 Cloud Web 可见 ack，不是 SSE 收到、store 更新或 trace store append。

4.5 Session 切换和首屏打开时序图

sequenceDiagram
  participant U as User
  participant W as Cloud Web
  participant A as Cloud API
  participant S as Session/Conversation Store
  participant T as Trace Store
  participant P as Prometheus

  U->>W: open workbench or select session tab
  W->>W: start journey open/session_switch
  W->>A: GET rail/detail/messages/turn/trace pages
  A->>S: query session/conversation/message page
  A->>T: query trace pages when needed
  A-->>W: first authoritative payload
  W->>W: first visible message/tool/loading body ack
  W->>A: RUM first_visible
  A-->>W: remaining required payloads
  W->>W: full load projection ack
  W->>A: RUM full_load
  A->>P: observe journey durations

session 切换必须分别记录 first_visible 和 full_load。first visible 用于用户体感；full load 用于发现 trace pagination、turn status、rail/detail 补洞和后端 read model 的尾部慢路径。

5. 内部分工与规格索引

编号	模块或课题	规格文档	主责边界	上游依赖	下游支撑
PJ2026-0106050501	Journey口径	本规格 6.1	四类用户可感知 journey 的起点、终点和状态分类	Web工作台、API契约	RUM、PromQL、告警
PJ2026-0106050502	VisibleAck	本规格 6.2	DOM paint ack、first visible、full load 和浏览器 RUM 批量上报	Web工作台	用户体感指标
PJ2026-0106050503	BackendLatency	本规格 6.3	AgentRun backend event createdAt 到 Web visible 的端到端投递耗时	Agent编排、HWLAB接入	Trace/SSE 性能定位
PJ2026-0106050504	Prometheus指标	本规格 6.4	histogram/counter/gauge、低基数 label、Server-Timing 和 RED 指标	运维监控、API契约	Dashboard、recording rule
PJ2026-0106050505	YAML运维	本规格 6.5	UniDesk owning YAML、ops CLI、shared helper、scrape/rule/status/summary 渲染和运行面观测边界	YAML运维、平台运维	D601 v0.3 运维监控接入
PJ2026-0106050506	代码引用	本规格 6.6	SPEC-first、代码文件头部 SPEC 标注和 issue 回写要求	规格治理、全部实现模块	后续实现和 review
PJ2026-0106050507	TurnStatus预算	本规格 6.7	turn status、trace refresh 和 AgentRun result/events 同步的用户可感知预算	API契约、HWLAB接入、Agent编排	Web poll、TraceTimeline、性能回归

6. 原子需求

6.1 OPS-WBPERF-REQ-001 Journey 口径

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-001	Journey口径	PJ2026-0106050501 Journey口径	Web工作台、API契约、HWLAB接入

Workbench性能应定义并采集四类用户可感知 journey：submit_to_first_visible、backend_event_visible、session_switch_first_visible/full_load、workbench_open_first_visible/full_load。

每个 journey 必须有明确起点、终点、状态和失败分类。起点来自用户动作、navigation start 或 AgentRun source event；终点来自浏览器 visible ack。状态至少区分 ok、timeout、aborted、error、stale；错误分类使用低基数枚举，不把 HTTP raw body、prompt、assistant 文本或 Secret 放入指标。

6.2 OPS-WBPERF-REQ-002 Visible Ack 与前端 RUM

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-002	VisibleAck	PJ2026-0106050502 VisibleAck	Web工作台

Cloud Web 应在 Workbench reducer 应用权威状态后，通过 nextTick 加连续 requestAnimationFrame 或等价机制确认目标 DOM 已完成可见 paint，再上报 visible ack。仅记录 API response、SSE receive 或 store mutation 不足以代表用户可见。

RUM 上报应批量发送到同源 /v1/web-performance 或后续等价资源，默认只携带 journey、phase、eventKind、route template、status、duration、sourceClock、采样标记和脱敏 correlation id。traceId、sessionId、conversationId、runId、commandId、userId 只能进入受控 debug 字段或后台日志摘要，不作为 Prometheus label。

6.3 OPS-WBPERF-REQ-003 AgentRun backend event 可见延迟

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-003	BackendLatency	PJ2026-0106050503 BackendLatency	Agent编排、HWLAB接入、Web工作台

HWLAB AgentRun adapter、trace store、Workbench SSE 和 Cloud Web 应保留足够的脱敏 source metadata，使 assistant message、tool call、terminal result、error 和用户可读 backend status 可以从 AgentRun source event 对齐到 Web visible ack。

可见延迟指标应覆盖 adapter fetch、event map、trace append、SSE deliver、browser receive、projection 和 visible ack 的关键阶段。任一阶段缺失时必须显式标记 phase_missing 或 source_clock_missing，不能用当前时间回填后伪装为正常低延迟。

6.4 OPS-WBPERF-REQ-004 Prometheus 指标和低基数标签

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-004	Prometheus指标	PJ2026-0106050504 Prometheus指标	运维监控、API契约

Workbench性能应至少提供以下 Prometheus 指标族：hwlab_workbench_journey_duration_seconds、hwlab_workbench_backend_event_visible_latency_seconds、hwlab_workbench_event_phase_duration_seconds、hwlab_workbench_realtime_events_total、hwlab_workbench_sse_connections、hwlab_http_request_duration_seconds 和 hwlab_http_requests_total。

指标命名、单位和 label 必须符合 Prometheus 常规实践：duration 使用秒，counter 使用 _total 后缀，label 只允许 node、lane、service、route、journey、phase、event_kind、status、method、status_class、source 等有限枚举。禁止把 traceId、sessionId、conversationId、runId、commandId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret、token、DSN 或用户个人信息放入 label。

API 响应可使用 Server-Timing 暴露后端 phase 摘要，但该 header 只能包含阶段名和 duration，不包含敏感值或高基数 ID。

6.5 OPS-WBPERF-REQ-005 YAML-first UniDesk ops

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-005	YAML运维	PJ2026-0106050505 YAML运维	YAML运维、运维监控、公开入口

D601 v0.3 Workbench 性能监控的运维接入必须设计成 YAML-first UniDesk ops。owning YAML 应声明目标 node/lane、runtime namespace、metrics services/endpoints、scrape 形态、recording rules、alert rules、summary query、public/raw metrics 暴露边界、采样/保留/阈值和必要 probe；具体数值以 YAML 为准，SPEC 只定义能力和边界。

UniDesk CLI 应提供薄 domain 入口，例如 hwlab nodes observability plan|apply|status|workbench-summary --node D601 --lane v03 或等价命令。CLI 只校验 YAML 结构、类型、必填项、引用存在性和可渲染性；执行应复用共享 ops helper 做 route 执行、Kubernetes manifest render/apply、Prometheus rule render、bounded query、redacted output 和 summary。禁止把 D601、hwlab-v03、Service 名、Prometheus endpoint、阈值、采样窗口或 rule 内容长期硬编码在 CLI 代码中。

运行面 Kubernetes 对象、Prometheus target、ServiceMonitor、静态 scrape file、Grafana/Prometheus 查询结果和 pod env 只能作为 presence、health、fingerprint、target 状态或 summary 的观测对象。缺配置时修 owning YAML 和受控 CLI，不得从运行面反推、复制或手工回填 desired state；涉及 Secret 或 token 的输出只允许显示 sourceRef、targetKey、presence、fingerprint、字节数和 redacted 摘要。

6.6 OPS-WBPERF-REQ-006 SPEC-first 与代码引用

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-006	代码引用	PJ2026-0106050506 代码引用	规格治理、Web工作台、API契约

本性能监控能力的实现必须先引用本规格，再进入代码变更。新增或修改的前端、后端、CLI/helper、metrics、RUM、trace adapter 和 dashboard 源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0; PJ2026-010401 Web工作台 draft-2026-06-17-r0，并用一句话说明文件职责。

实现文件不得只写 issue 编号、latest、current 或“按最新方案”作为规格引用。自动生成文件、第三方 vendored 文件、纯 YAML/config、锁文件和无法承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器或配置入口必须能追溯到本 SPEC。

6.7 OPS-WBPERF-REQ-007 Turn status 快速返回预算

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-007	TurnStatus预算	PJ2026-0106050507 TurnStatus预算	API契约、HWLAB接入、Agent编排、Web工作台

/v1/agent/turns/:traceId 是 Workbench TraceTimeline 和消息运行态的用户可见 poll 权威入口。该入口必须优先返回当前已知 turn snapshot、runnerTrace、finalResponse 或结构化 degraded reason，不得把一次 Web poll 同步阻塞在 AgentRun result/events 刷新、provider trace 拉取或后台 read model 补洞上。

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. 过程控制

本规格的执行 issue 为 HWLAB #1392，性能问题修复执行 issue 为 HWLAB #1422。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 PJ2026-010605 运维监控、PJ2026-010401 Web工作台 和 PJ2026-010403 API契约 的引用关系，再进入后续实现。

后续实现 issue 或 PR 收口时必须回写：使用的 SPEC 编号和实现引用版本、触达的源码文件头部标注情况、Prometheus 指标/label 审查结果、D601 v0.3 public origin 的原入口验证结果，以及是否需要继续修订本规格。