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-19-p0; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-22-p1-workbench-redis-derived-cache; PJ2026-010401080313 Workbench实时权威 draft-2026-07-14-p0-pure-kafka-authority
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-010605 运维监控
关联规格	PJ2026-010401 Web工作台、PJ2026-010401080313 Workbench实时权威、PJ2026-010403 API契约、PJ2026-010205 HWLAB接入
规格治理索引	规格治理

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

2. 目的和范围

2.1 目的

Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待时间、实时消息投递时间、session 切换加载时间和首屏打开时间转化为可查询、可告警、可回归的权威性能观测。该观测必须先进入单一权威 observation history 或等价 read model，再由窗口化 summary、Prometheus 指标、dashboard、告警和 drill-down 消费；不得让 RUM summary、Prometheus raw query、浏览器实时 probe、后端日志或前端诊断互相覆盖同一个展示事实。

本规格的目标状态是：用户从 Web 发起动作后，浏览器、Cloud API、Workbench SSE、trace/read model、AgentRun adapter 和性能观测存储之间拥有同一套低基数性能事件口径；平台运维可以按时间窗口判断 D601 v0.3 Workbench 是否变慢，客户端和 Agent编排可以用同一脱敏 correlation 继续定位，但监控本身不替代业务功能闭环。直接探针、synthetic check、Prometheus histogram、RUM field data 和服务端 request metric 分属不同 metric family；它们可以在同一 dashboard 中并列展示，不能用一个 family 的结果裁判或覆盖另一个 family 的结果。

Workbench timing 观测必须以唯一投影的 aggregate event stream revision 为业务顺序锚点。web-probe、RUM、dashboard 和 OTel 可以记录“trace 乱序、完成行非最后、耗时不一致、终态耗时继续增长”等 finding，但这些 finding 只能指向 projector/read model/SSE cursor/timing source 的架构缺陷；不得在 probe analyzer、dashboard 聚合、前端 reducer 或 CSS 文案层做重排、平滑、补零、单调修复或完成行位置修正。

为降低 D601 v0.3 Workbench 高频读路径对远端 durable Postgres 的重复访问压力，hwlab-v03 namespace 内可以部署 Workbench 专用的 Redis 派生读缓存。该缓存只服务 hwlab-workbench-runtime 的 session summary、terminal turn snapshot 和 terminal trace page 等可重建快照；Postgres durable projection 仍是唯一事实源，Redis 命中只影响读路径耗时、cacheStatus 诊断和 DB query avoided 指标，不改变 lifecycle、final response、权限或 projection authority。

相关运维必须按 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 指标。
• hwlab-v03 namespace-local Workbench Redis 派生读缓存的命中、miss、stale、unavailable、operation duration、payload bytes 和 DB query avoided 指标。
• 运行中 Code Agent turn 的无响应空闲时间、最近活动时间和投影刷新活性口径；该口径只衡量“多久没有新事实或可见进展”，不把 turn 总运行时长作为前端超时。
• 前端 RUM 与后端 Prometheus 指标的关联键、脱敏边界、低基数 label、histogram bucket、recording rule 和低样本告警边界。
• 用户可见错误诊断中的 OTel trace_id 与性能观测的关联边界：trace id 可以进入错误诊断、日志、span 和受控 debug payload，不进入 Prometheus label、RUM 默认维度或 /performance 默认表格。
• 权威 observation history 或等价 read model、时间窗口查询、窗口内精确分位、桶化估算标记、样本数、freshness、source family 和数据质量字段。
• UniDesk YAML-first ops 形式的 D601 v0.3 Workbench 监控接入、scrape/render/status/summary CLI、告警/recording rule 配置和受控运维验证。
• D601 v0.3 Cloud Web /performance 性能监控工作台：以同一权威 summary/series 数据源展示中文化概览卡、趋势图、分布图、TopN 排行、数据新鲜度、采集健康和可访问表格 drill-down。
• dashboard 图表、表格、tooltip、legend、空状态、错误状态、加载状态、单位、状态和既有数值的中文化展示；默认 UI 不直接暴露未经产品确认的英文 raw 值。
• SLO、阈值、告警准入和持续治理分流：用户可见 Performance 页只呈现窗口化性能事实和数据质量，内部告警只基于稳定 metric family、足够样本、持续窗口和 YAML 声明阈值触发。

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 为准，不在本规格硬编码。
• 浏览器即时 probe、管理员手工 curl、后端日志 grep、Prometheus raw dump 或 synthetic check 不得作为 /performance 同一展示字段的替代权威；这些只能作为独立 metric family、定位证据或运维检查。
• 长 trace、完整 prompt、assistant 正文、tool 参数、命令输出、Secret、token、DSN 和原始 provider payload 不进入性能指标 label 或默认日志。
• Redis 不承载登录态、权限、OpenFGA、账本、AgentRun command/lease、runner 状态、session lifecycle 或 final response；这些事实分别归用户管理、Agent编排、Workbench实时权威和对应 durable store。

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 的耗时。
Aggregate event stream revision	Workbench实时权威写侧提交序，至少由 eventSeq、aggregateSeq、projectionRevision 或等价字段表达；性能观测只能用它关联业务顺序和可见耗时，不得用本地采样到达顺序重排业务事实。
无响应空闲时间	从最近一次可证明的 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 等后端阶段。
Chart-ready summary	/v1/web-performance/summary 或后续等价公开 summary/series 入口返回的前端图表直用数据结构，包含时间桶、series、histogram bins、TopN rows、freshness、source、observedAt 和 sample window 等字段。
权威观测模型	Performance 页唯一消费的窗口化性能读模型；它由 observation history 或等价持久事实聚合生成，承载 metric family、窗口、样本、分位、近似程度和数据质量。
Observation history	RUM、API timing、Workbench journey、Long Task、Web Vitals、server request metric 或 synthetic check 按 family 归一化后的低基数观测历史。它是窗口查询和 trend/TopN/drill-down 的事实来源。
Metric family	互不覆盖的指标族，例如 rum_web_vitals、rum_api_timing、workbench_journey、server_request、synthetic_check。不同 family 可以关联展示，但不能竞争同一状态字段。
Windowed summary	按 windowFrom/windowTo 和 metric family 从 observation history 聚合出的摘要；同一页面刷新、图表、表格和 drill-down 必须消费同一窗口语义。
数据质量字段	每个 summary、series 或 row 必须携带的可信度字段，至少包括 sampleCount、lowSample、freshness、generatedAt、aggregationKind、approximation 和 sourceFamily。
桶化估算	从 histogram bucket 推导出的近似分位。它必须显式标记 approximation=bucketed 或等价字段，并提供 bucket 边界或估算说明；不得显示成精确耗时。
低样本	当前窗口内样本数量不足以支持健康判断。低样本是可信度状态，不是慢路径根因，也不能被升级为阻塞或正常结论。
采集健康	当前窗口观测是否足够新鲜、是否有样本、是否可聚合的状态；它来自同一权威 summary 的数据质量字段，不是第二套 collectorStatus 事实源。
SLO	面向运维治理的服务目标口径，由 metric family、统计窗口、最低样本、持续时间、阈值、严重级别和处置入口组成；具体数值以 UniDesk owning YAML 为准。
告警准入	指一个指标进入内部告警前必须满足的可信度条件，包括样本数量、freshness、窗口持续性、sourceFamily 和采集健康；低样本或暂无数据默认不能触发性能慢路径告警。
性能监控工作台	Cloud Web /performance 中面向管理员和值守人员的 dashboard 视图，用概览卡、趋势、分布、排行和表格 drill-down 展示 Workbench/RUM/API/Long Task 性能健康。
Workbench Redis派生读缓存	hwlab-v03 namespace 内服务 hwlab-workbench-runtime 的可丢弃 Redis 缓存，只保存从 durable Workbench projection 派生出的短 TTL 读快照；它不是状态源、权限源或 lifecycle authority。
cacheStatus	Workbench read API 和性能观测中的缓存诊断状态，至少区分 hit、miss、stale、unavailable；它只解释读路径性能，不参与业务状态判断。
dbQueryAvoided	因派生读缓存命中而避免的一次 durable read model DB 查询计数；它是性能指标，不表示业务事实变化。
低基数 label	Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。
诊断 trace_id	用户可见错误诊断中的 OTel trace id，用于跳转 trace backend 和关联日志/span；它是高基数排障标识，只能进入 diagnostic、日志、span attribute、exemplar 或受控 debug payload，不得作为 Prometheus/RUM 默认聚合维度。
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 接收入口、权威 observation history、窗口聚合 read model、Cloud API Prometheus metrics、SSE 连接状态、AgentRun adapter timing、recording rule 和性能摘要。
外部输出	Windowed summary、Prometheus histogram/counter/gauge、低噪声性能摘要、Server-Timing header、中文化 Web performance dashboard、issue closeout 可引用的查询结果。
用户接口	D601 v0.3 Cloud Web https://hwlab.pikapython.com/workbench 和 /performance、同源 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/"]
    OBS[(Authority Observation History)]
    AGG[Window Aggregator]
    SUM["/v1/web-performance/summary"]
    TRACE[Trace Store]
    READ[Workbench Read Model]
    CACHE[(hwlab-v03 Redis derived cache)]
    MET[Prometheus Metrics 9100]
    ROUTE --> READ
    ROUTE --> TRACE
    ROUTE --> OBS
    ROUTE --> MET
    READ <--> CACHE
    CACHE --> MET
    PERF --> OBS
    OBS --> AGG
    AGG --> SUM
    OBS --> 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
  SUM -- chart-ready summary --> PERFUI[Performance dashboard]
  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 --> R[cache hit/miss/stale/unavailable]
  C --> E[AgentRun event source metadata]
  D --> F[Trace/read model projection]
  R --> M[server request observation]
  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[server request observation]
  L --> N[/v1/web-performance ingest]
  M --> OH[Authority observation history]
  N --> OH
  OH --> W[Windowed summary/read model]
  W --> DASH[/performance dashboard]
  OH --> P[Prometheus metrics export]
  P --> 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。/performance 的卡片、趋势、TopN、表格和采集健康只能读取同一 windowed summary/read model，不能从 Prometheus raw query、browser probe、localStorage、workspace snapshot 或日志 grep 临时推导展示状态。

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 initial snapshot or Kafka replay SSE
  A->>S: query session/message/turn projection
  A->>T: query trace detail only when explicitly opened
  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 detail pagination、sync replay、rail/detail 投影和后端 read model 的尾部慢路径。性能分析不得把 trace/session/turn 多端点 automatic fan-out 当作合法补洞路径。

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、性能回归
PJ2026-0106050508	Dashboard可视化	本规格 6.8	/performance 中文化图表、chart-ready summary、低基数维度、空态/错误态和表格 drill-down	Web工作台、API契约、运维监控	D601 v0.3 Performance 原入口验收
PJ2026-0106050509	权威观测	本规格 6.9	observation history、metric family、windowed summary 和跨族不可覆盖边界	运维监控、Web工作台、API契约	/performance、告警、审计
PJ2026-0106050510	窗口质量	本规格 6.10	时间窗口、样本数、freshness、aggregationKind、approximation 和 lowSample 语义	运维监控、API契约	dashboard、TopN、drill-down
PJ2026-0106050511	分叉禁令	本规格 6.11	禁止 collectorStatus 旁路、读侧 repair、fallback、bucket 上界冒充精确值和跨族仲裁	Workbench实时权威、Web工作台	后续迁移和回归
PJ2026-0106050512	SLO治理	本规格 6.12	SLO、阈值、告警准入、用户可见页面和内部告警职责分离	运维监控、YAML运维	持续治理和维护 issue
PJ2026-0106050513	Redis读缓存	本规格 6.13	Workbench Redis 派生读缓存的指标、SLO、YAML-first 参数和降级可见性	Workbench实时权威、API契约、YAML运维	D601 v0.3 sessions/turn/trace 高频读降尾延迟
PJ2026-0106050514	Workbench实时运行面	PJ2026-0106050514 Workbench实时运行面	SSE、错误处理、队列、缓存、timeline、storage、scroll、health、OTel 和 Web 哨兵冻结探测的迁移边界	Web工作台、Workbench实时权威、API契约、Web哨兵、YAML运维	JD01 Workbench 多轮卡死和请求风暴治理

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。

Workbench Redis 派生读缓存接入后，还应提供低基数缓存指标，至少包括 workbench_cache_requests_total、workbench_cache_hit_ratio、workbench_cache_operation_duration_seconds、workbench_cache_payload_bytes、workbench_cache_stale_total、workbench_cache_unavailable_total 和 workbench_db_query_avoided_total。这些指标只按 node、lane、service、cache_key_class、route、status 等低基数字段聚合，不包含完整 cache key、actor id、session id、trace id、prompt、stdout/stderr 或敏感值。

指标命名、单位和 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。

用户可见错误的 OTel trace_id 不属于性能指标 label。它可以作为日志与 span 的 correlation 字段，也可以在支持 exemplar 的指标链路中作为受控 exemplar 或 debug payload 关联一次观测，但 /performance 默认 summary、TopN、chart series、problem row 和 RUM 上报维度不得按 trace id、request id、session id、run id 或用户输入聚合。需要从性能页面跳到单次 trace 时，必须通过用户显式点击错误诊断或受控 drill-down，而不是把高基数字段暴露成默认维度。

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、web-probe 和 dashboard 源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-19-p0; PJ2026-010401080313 Workbench实时权威 draft-2026-06-24-p0-aggregate-event-stream，并用一句话说明文件职责。

实现文件不得只写 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 属于旧 compat/diagnostic 读取面，不再是 Workbench 主消息运行态的 poll 权威入口。Workbench 主状态的 live/恢复权威来自 initial snapshot 与 hwlab.event.v1 live/replay SSE；trace/detail 读取只能解释过程或诊断，不能覆盖 message finalResponse、turn terminal 或 session running。

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

Workbench 前端、Cloud API 投影层和性能监控不得维护或展示“运行总时长达到某阈值即超时”的 Code Agent 前端超时状态。运行中的 turn 只允许按无响应空闲时间判断可见性退化：只要 lastActivityAt、lastActivitySeq、AgentRun events/result、trace sourceSeq、SSE typed event、sync replay、initial 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 口径。

Workbench 性能观测必须把“页面可见 timing 是否真实”作为一等指标。web-probe 应采样每个 Code Agent 卡片的 耗时、最近更新、轮次完成行耗时、trace 首尾耗时、terminal sealed duration 和对应 aggregate event stream revision，并输出采样点表与异常 finding。前端、fake-server、CLI renderer、dashboard 和 analyzer 不得为了让曲线更好看而平滑、滤波、补零、限速、单调修复、完成行重排或用多来源仲裁替换页面真实值；发现归零、非单调、跳秒、终态后继续增长、完成行非最后、trace event 顺序和 eventSeq/aggregateSeq 不一致或与 terminal commit 不一致时，应登记为上游 projection/timing 问题并修 event stream、projector、read model、SSE cursor 或权威时间源。

该需求不得削弱功能正确性：terminal result、billing finalize、session owner record、conversation fact 和 trace terminal evidence 仍由最终同步或后续 poll 完成；快速返回只限制单次用户可见 poll 的等待预算，不丢弃 AgentRun 事实、不伪造 final response、不把未完成 turn 标记为完成。

6.8 OPS-WBPERF-REQ-008 Performance dashboard 可视化

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-008	Dashboard可视化	PJ2026-0106050508 Dashboard可视化	Web工作台、API契约、运维监控

D601 v0.3 Cloud Web /performance 应提供 dashboard 级可视化，不得只把 RUM summary 展示成表格或 CSS 比例条。默认视图必须至少包含概览卡、Workbench 体感趋势、Backend event visible 延迟趋势、API timing 趋势或 TopN、Web Vitals 概览、Long Task 分布、问题分布、数据新鲜度和采集健康；表格只作为 drill-down 和可访问 fallback。

图表数据必须来自同一权威 Web performance summary/series 契约。/v1/web-performance/summary 或后续等价公开入口应返回前端可直接渲染的 chart-ready 结构，包括时间桶、series、histogram bins、TopN rows、freshness、source、observedAt、sample window、低样本信息、aggregationKind、approximation 和 sourceFamily。默认 UI 不得依赖未公开的 raw metrics 路径、内部 Prometheus raw dump、workspace snapshot、localStorage 或测试专用后门；当 series 缺失、低样本、采集降级或数据源不可用时，必须显示中文诊断状态而不是用 fallback 推断正常。采集健康只能是同一 summary 的数据质量投影，不得实现为第二套 collectorStatus 事实源。

Performance dashboard 的图表、表格、概览卡、tooltip、legend、空状态、错误状态、加载状态和既有数值必须中文化。单位统一使用 毫秒、秒、次、条、个、%、请求/分钟、样本、序列 等中文语义；状态统一映射为 正常、预警、阻塞、等待数据、低样本、暂无数据、采集降级 或等价中文文案。raw 枚举值可放入 debug tooltip 或复制字段，但默认页面不得直接暴露 Metric、Route、Count、Status、Samples、Problems、Workbench、Web Vitals、API Timing、Long Tasks 等未经产品确认的英文 UI。

Performance 指标展示必须保持低基数和脱敏。默认 label、图表维度、TopN 名称和表格列不得包含 sessionId、traceId、runId、conversationId、userId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret、token、DSN 或账号身份。长 route、event type、problem、outcome、statusClass 等维度必须使用 template、归一化枚举或低基数中文映射；无法确认脱敏的字段只能进入受控诊断证据，不得进入默认 dashboard。

当 /performance 展示 API 错误率、proxy timeout 或 Workbench blocker 相关行时，默认只展示低基数 route template、status class、error code、layer、sample count 和窗口质量。单个 trace_id 只能在用户展开受控诊断或跳转到错误详情时显示，且必须与 PJ2026-010403 API契约 的 HwlabErrorEnvelope 脱敏边界一致。

6.9 OPS-WBPERF-REQ-009 单一权威观测模型

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-009	权威观测	PJ2026-0106050509 权威观测	运维监控、Web工作台、API契约

Performance 页必须以权威 observation history 或等价持久 read model 作为唯一展示事实源。浏览器 RUM、Cloud API route timing、Workbench journey、Web Vitals、Long Task、server request metric 和 synthetic check 进入该模型前必须先归入明确的 metric family；同一 summary row、series point、TopN item 或健康状态只能由一个 family 的窗口聚合生成。

Metric family 可以在同一页面中并列展示和关联 drill-down，但不能互相覆盖。例如直接同源 API probe 可以作为 synthetic_check 或 latest_check 展示，用于说明当前入口可达性；它不能覆盖 rum_api_timing 的 P95，也不能把 RUM 低样本解释成 API 正常。Prometheus histogram 可以作为 metrics export 和告警输入；若 /performance 使用它生成分位，必须保留 aggregationKind=histogram 和近似字段，不得把 bucket 上界当成真实 observation。

权威模型必须支持列表轻量、详情补充的窗口化查询模式：默认 summary 返回当前窗口的主要卡片、趋势和 TopN；详情或 drill-down 继续携带同一 windowFrom/windowTo/sourceFamily/routeTemplate/journey 约束，不能另拉 raw endpoint 形成第二真相。该模式可以借鉴 status page 的 history -> latest/availability/timeline 聚合，但 HWLAB Performance 的事实源必须是自身 observation history，而不是 UI 组件或探针输出。

6.10 OPS-WBPERF-REQ-010 时间窗口和数据质量字段

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-010	窗口质量	PJ2026-0106050510 窗口质量	运维监控、API契约、Web工作台

/performance 必须把时间窗口作为一等输入。summary、series、TopN、分布、问题行和表格 drill-down 都必须返回并展示同一窗口的 windowFrom、windowTo、generatedAt、sampleCount、sourceFamily 和 freshness；用户切换窗口后，页面不得复用旧窗口 summary 冒充新窗口数据。

每个可判定健康的指标行必须携带数据质量字段。sampleCount 低于当前指标族的最低可信阈值时，状态应是 低样本 或 等待数据，而不是 阻塞、正常 或 慢路径。窗口内没有 observation 时，应显示 暂无数据；采集入口失败或聚合不可用时，应显示 采集降级 或等价诊断。低样本、暂无数据和采集降级只能说明可信度或采集状态，不能被当成慢路径根因。

分位数优先从窗口内 observation 精确计算，并返回 aggregationKind=exact 或等价字段。若使用 histogram bucket、Prometheus histogram_quantile 或其他近似聚合，summary 必须返回 aggregationKind=histogram、approximation=bucketed、相关 bucket 边界或误差说明；前端必须用中文标注“桶化估算”或等价文案，禁止显示成精确的 5.0 秒、10 秒、30 秒 结论。

6.11 OPS-WBPERF-REQ-011 防分叉、无 repair 和迁移边界

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-011	分叉禁令	PJ2026-0106050511 分叉禁令	Workbench实时权威、Web工作台、API契约

Performance 页必须吸收 Workbench 唯一投影的失败教训：不得在 Web reducer、summary API、fake-server、probe 脚本或 dashboard 组件中保留多个事实源，再通过“优先级、覆盖、fallback、字段缺失时改走另一端点、刷新后 repair、测试专用后门”等方式决定展示状态。字段缺失、投影滞后、采集失败或样本不足时，必须暴露数据质量或 blocker，并修 observation writer、aggregator、read model 或正式 API 契约。

禁止实现独立 collectorStatus 旁路系统来解释同一批性能指标。采集健康应由 windowed summary 的数据质量字段派生；如果需要展示 synthetic/latest check，它必须有独立 metric family、独立标题和独立说明，不能覆盖 RUM/API/Workbench journey 的窗口聚合。Performance UI、fake-server 和 web-probe 必须使用同一 summary 契约；mock fixture 只按正式 API 契约重放，不访问 live Cloud API、数据库、Prometheus 或 Kubernetes 作为通过条件。

迁移阶段必须删除或改写旧的分叉路径。旧 summary 缺少窗口字段、近似字段或 source family 时，不得由前端补造；旧 bucket 上界显示、二次单位换算、localStorage 真相、raw metrics fallback、hidden probe repair 和 collectorStatus 仲裁都应作为 P1/P4 的负向扫描对象。任何保留的临时兼容都只能作为只读审计输入，不能参与默认 dashboard 展示。

6.12 OPS-WBPERF-REQ-012 SLO 与持续治理

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-012	SLO治理	PJ2026-0106050512 SLO治理	运维监控、YAML运维、Web工作台

Workbench 性能 SLO 只能基于稳定 metric family、明确窗口、足够样本、持续时间和 YAML 声明阈值触发。SLO 配置应至少声明 metricFamily、journey 或 routeTemplate、统计方法、窗口、最低样本、freshness 要求、阈值、持续时间、严重级别、处置入口和 owner；具体数值、窗口长度和告警路由以 UniDesk owning YAML 为准，SPEC 不硬编码数值。

用户可见 /performance 页面和内部告警必须分清职责。Performance 页展示窗口化事实、趋势、TopN、数据质量和中文诊断，允许显示 低样本、暂无数据、采集降级、桶化估算 或 精确窗口分位；内部告警只在告警准入满足时触发，不得把低样本、暂无数据、刚发布后的冷启动窗口或单个 synthetic probe 失败直接升级为“性能阻塞”。采集链路本身持续缺样、stale 或 ingest failure 时，应进入采集健康/观测可用性告警，而不是伪造成某个 API 或 Workbench journey 慢路径。

后续改进 issue 必须按职责分流。用户可感知变慢且满足 SLO 准入时，创建性能退化 issue，正文写清 metric family、窗口、样本、sourceFamily、route/journey、阈值来源和 public origin 复测入口；采集缺失、freshness stale、summary API 错误或 Prometheus target 异常时，创建采集健康 issue；新增 metric family、summary schema、dashboard 合同或告警策略变更时，创建 SPEC/架构治理 issue。大型计划不得只落在已有 issue 评论区；必须创建独立 issue，并在父级治理 issue 中只保留短链接和当前状态。

每次关闭 Workbench 性能实现或维护 issue 时，closeout 必须说明是否影响 SLO 或告警准入：若影响，回写对应 YAML/source branch、SPEC 引用版本、D601 v0.3 public /performance 验收、负向分叉扫描和 rollout 证据；若不影响，说明 SLO impact=none 或等价结论。历史数据和当前窗口必须分开判断，不能用全量历史混合近期修复效果，也不能用短窗口低样本替代稳定窗口结论。

6.13 OPS-WBPERF-REQ-013 Workbench Redis 派生读缓存

编号	短名	主责模块	关联模块
OPS-WBPERF-REQ-013	Redis读缓存	PJ2026-0106050513 Redis读缓存	Workbench实时权威、API契约、YAML运维

D601 v0.3 Workbench 可以在 hwlab-v03 namespace 内使用 Workbench 专用 Redis 作为派生读缓存，用于降低 /v1/workbench/sessions、terminal turn snapshot 和 terminal trace page 等高频读路径的远端 Postgres 重复查询和尾延迟。Redis 只缓存从 durable Workbench projection 派生出的短 TTL 快照；cache key 必须包含 schema version、cache key class、actor visibility input、session/turn/trace/cursor 和 projection revision/seq 或等价 authority input。

缓存配置必须 YAML-first。owning YAML 至少声明 enabled、namespace、serviceName、image、resource request/limit、memory policy、TTL、max key size、max payload bytes、connection timeout、operation timeout、metrics labels 和 disable switch；具体数值以 YAML 为准，SPEC 不硬编码阈值。Redis 不可用时不得让 /health/live 失败，也不得让 Cloud API、Web、web-probe 或前端直接连接 Redis；hwlab-workbench-runtime 应暴露 cacheStatus=unavailable 或等价诊断，并走受控 DB read 或明确 degraded。

缓存响应和观测必须可解释。命中响应应能暴露 cacheStatus、cacheAgeMs、projection revision/seq 或等价低基数字段；OTel span 可以记录 cacheStatus、cacheAgeMs、cacheKeyClass、projectionSeq、dbQueryAvoided、dbQueryDuration 和 payloadBytes，但不得记录完整 cache key、actor id、session id、trace id、prompt、assistant 正文、tool 参数、stdout/stderr、Secret、token 或 DSN。/performance 可以展示缓存命中率、DB avoided、缓存不可用和 sessions API P95 变化，但这些指标不得成为 lifecycle、final response、权限或业务状态的判断条件。

缓存验收必须包含负向边界。实现不得用 Redis stale 值做 read-side lifecycle 推理、final response 推断、session repair、GET read-through repair 或多来源仲裁；不得用缓存掩盖 SQL/schema/nullability bug、row_scan_failed 或 durable projection blocker。若不能精确失效，TTL 与 user-visible freshness SLO 必须匹配，并通过 cacheAgeMs 和 projection revision 让用户可见新鲜度可诊断。

7. 过程控制

本规格的执行 issue 为 #1392，性能问题修复执行 issue 为 #1422，Performance dashboard 中文化可视化执行 issue 为 #1609。单一权威观测模型架构治理 issue 为 #1638，阶段执行 issue 为 P0 #1639、P1 #1641、P2 #1640、P3 #1642、P4 #1643 和 P5 #1644。Workbench Redis 派生读缓存架构执行 issue 为 #1870，P0 SPEC-first 子 issue 为 #1871。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 PJ2026-010605 运维监控、PJ2026-010401 Web工作台、PJ2026-010401080313 Workbench实时权威 和 PJ2026-010403 API契约 的引用关系，再进入后续实现。

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