docs: update workbench performance dashboard spec
This commit is contained in:
Codex
@@ -47,6 +47,8 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
|
||||
- 运行中 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 配置和受控运维验证。
|
||||
- D601 v0.3 Cloud Web `/performance` 性能监控工作台：以同一权威 summary/series 数据源展示中文化概览卡、趋势图、分布图、TopN 排行、数据新鲜度、采集健康和可访问表格 drill-down。
|
||||
- dashboard 图表、表格、tooltip、legend、空状态、错误状态、加载状态、单位、状态和既有数值的中文化展示；默认 UI 不直接暴露未经产品确认的英文 raw 值。
|
||||
|
||||
### 2.3 范围外
|
||||
|
||||
@@ -68,6 +70,8 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
|
||||
| 无响应空闲时间 | 从最近一次可证明的 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 等字段。 |
|
||||
| 性能监控工作台 | Cloud Web `/performance` 中面向管理员和值守人员的 dashboard 视图，用概览卡、趋势、分布、排行和表格 drill-down 展示 Workbench/RUM/API/Long Task 性能健康。 |
|
||||
| 低基数 label | Prometheus label 只能取有限稳定集合，例如 route template、journey、phase、eventKind、status，不包含 traceId、sessionId、runId 或用户输入。 |
|
||||
| YAML-first UniDesk ops | UniDesk 自有运维事实先进入 YAML，再由受控 CLI 渲染、校验和下发；运行面对象只作为观测面，不反推配置真相。 |
|
||||
|
||||
@@ -78,8 +82,8 @@ Workbench性能负责把 HWLAB Cloud Web 工作台中用户直接感知的等待
|
||||
| 外部使用者 | 平台管理员、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。 |
|
||||
| 外部输出 | 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 目标架构图
|
||||
@@ -250,6 +254,7 @@ session 切换必须分别记录 `first_visible` 和 `full_load`。first visible
|
||||
| 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 原入口验收 |
|
||||
|
||||
## 6. 原子需求
|
||||
|
||||
@@ -335,8 +340,22 @@ Workbench 前端、Cloud API 投影层和性能监控不得维护或展示“运
|
||||
|
||||
该需求不得削弱功能正确性：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工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md)、[运维监控](PJ2026-010605-observability-monitoring.md) |
|
||||
|
||||
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 和低样本信息。默认 UI 不得依赖未公开的 raw metrics 路径、内部 Prometheus raw dump、workspace snapshot、localStorage 或测试专用后门；当 series 缺失、低样本、采集降级或数据源不可用时，必须显示中文诊断状态而不是用 fallback 推断正常。
|
||||
|
||||
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。
|
||||
|
||||
## 7. 过程控制
|
||||
|
||||
本规格的执行 issue 为 [HWLAB #1392](https://github.com/pikasTech/HWLAB/issues/1392)，性能问题修复执行 issue 为 [HWLAB #1422](https://github.com/pikasTech/HWLAB/issues/1422)。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。
|
||||
本规格的执行 issue 为 [#1392](https://github.com/pikasTech/HWLAB/issues/1392)，性能问题修复执行 issue 为 [#1422](https://github.com/pikasTech/HWLAB/issues/1422)，Performance dashboard 中文化可视化执行 issue 为 [#1609](https://github.com/pikasTech/HWLAB/issues/1609)。该类 issue 的 P0 阶段必须以本 SPEC 为前置：先确认本规格、父级 [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 的引用关系，再进入后续实现。
|
||||
|
||||
后续实现 issue 或 PR 收口时必须回写：使用的 SPEC 编号和实现引用版本、触达的源码文件头部标注情况、Prometheus 指标/label 审查结果、D601 v0.3 public origin 的原入口验证结果，以及是否需要继续修订本规格。
|
||||
|
||||
Reference in New Issue
Block a user