docs: add HWLAB workbench performance SPEC

2026-06-17 09:11:25 +00:00
parent 6e5b50a221
commit 6b4501980b
7 changed files with 401 additions and 2 deletions
@@ -26,6 +26,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
 - 当任务缺少上级方向、验收标准或原始验证入口时，先归类为规划/调查，不要直接变成实现任务。
 - L1 方向必须是直接服务 L0 使命的能力域。文档整理、阶段报告、项目管理机制、看板维护、技能维护、仓库名、工具名和临时执行路径都不能作为 L1 方向。
 - L1 是验收主责，不是宽泛标签。跨方向 issue 可以列关联 L1，但必须且只能有一个主责 L1，选择依据是哪个方向定义完成标准。
+- 重大规划型 issue 必须 P0 SPEC-first：P0 阶段先在 `project-management/PJ2026-01/specs/` 维护对应 SPEC，明确 SPEC 编号、上级/关联规格、架构图、数据流图、关键时序图和代码引用规则，再进入后续实现。issue 正文只能承载执行计划和证据，不能替代 SPEC 正文。

 ## 需求规格写作规则

@@ -33,6 +34,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
 - 文档控制表只保留规格自身必要字段；状态只能写 `已生效`、`已废弃` 或 `未生效`。不要在文档控制表里写长期面板、阶段规格、L1 划分、规格来源或迁移来源。
 - 修改历史只记录已经定稿的版本。用户未明确说“可以定稿”前，不新增 `待提交` 版本号，也不把每次小编辑拆成一个版本。
 - L0、L1、L2 需求规格正文固定使用裁剪后的 1-7 章结构：文档控制、目的和范围、术语表、系统边界和接口、内部分工与规格索引、原子需求、过程控制。第 7 章只索引阶段验证、内测、灰度或用户反馈分流 issue；不要在 SPEC 正文追加假设和风险、变更控制、开放缺口、验收标准或执行过程流水。
+- 涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的 SPEC，必须在正文中包含目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`，并和原子需求编号互相对应。
 - L0 系统边界必须把 HWLAB 作为完整系统看待，描述外部使用者、外部输入、受控资源、外部输出、用户接口和系统责任边界，不写内部治理材料。
 - 稳定概念用术语表表达；不要写没有判定价值的“运行概念”流水。
 - L0 的 L1 方向树和项目规格索引合并为内部模块分工与规格索引，用相对路径索引到每个内部模块规格文档。
@@ -42,6 +44,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
 - 单一主责、关闭验收、规格沉淀、回写和偏离判定是治理规则，不得伪装成 L0 原子需求。
 - L2 是稳定能力域，不是仓库文件名或原始 spec 文档一比一搬运目录。单个 L1 下的 L2 通常不超过 6 个；从仓库参考文档迁移过来的大量细项应合并到少量 L2，并把更细的服务、lane、source truth、验证切片放到 L3 或正文分工中。
 - 运维交付内容必须按职责归位：通用 CI/CD、发布判定、镜像 promotion 放到平台运维的发布流水；通用 Git mirror、source truth、GitOps branch、artifact catalog 放到源码同步；Secret/YAML/sourceRef/targetKey/fingerprint 放到 YAML运维。只有能抽象到多服务共用的规则才放通用 L2；AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等专项细节放到这些通用规格下的 AgentRun 专项 L3，`PJ2026-0102 Agent编排` 只引用这些支撑规格，不把运维后勤 L2 塞进 Agent编排。
+- 大规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0`；不得只写 issue 编号、`latest` 或 `current`。自动生成文件、第三方 vendored 文件、纯配置、锁文件和无法承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须可追溯到 SPEC。

 ## HWLAB 标准 issue 锚点

@@ -59,6 +62,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
 3. 写入 GitHub issue/PR 评论时，同时使用 `unidesk-gh`；所有写入必须从 `/root/unidesk` 通过 `bun scripts/cli.ts gh ...` 完成。
 4. 修改长期项目管理文档时，把稳定规划内容放到 `project-management/PJ2026-01` 的总规格/规格文件，阶段报告只保留带日期的总结。
 5. 修订 L1/L2 层级时，先按完成标准判断主责，再看实现表面。工具、CLI、Web、API 形态可以形成关联 L1，但主责 L1 必须是定义完成标准的能力域。
+6. 更新重大规划型 issue 时，先把 P0 SPEC 文件和图维护到位，再用 `unidesk-gh` 回写 issue；后续代码任务必须在 issue 中引用 SPEC 编号和实现引用版本。

 ## 必需层级和职责

@@ -71,3 +75,4 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管
 - L4：执行任务 / PR / CaseRun / smoke / 文档收口。负责具体执行和证据收集，不能重新定义父级范围。

 每个非平凡 issue 都应写明上级链接、目标分支/lane、验收标准、验证入口和收口回写目标。
+重大规划型 issue 还必须把“更新并确认 SPEC”列为 P0，且 P0 未完成前不得推进代码实现。
@@ -38,6 +38,19 @@ HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏
 - 规格文件引用其他规格时，使用同目录相对路径 Markdown 链接，例如 `[PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md)`；不要引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#<number>`。
 - GitHub issue/PR 正文和评论中的 issue/PR 引用必须写成 `[#<number>](https://github.com/<owner>/<repo>/issues/<number>)` 或 `[#<number>](https://github.com/<owner>/<repo>/pull/<number>)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。`owner/repo#number` 只允许作为 CLI 命令参数 shorthand。

+## 重大规划型 issue 的 P0 SPEC-first 规则
+
+涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的大规划型 issue，P0 必须先维护对应 SPEC，再继续实现。issue 只能记录执行状态、讨论和证据，不能成为稳定需求、架构、数据流、时序或验收口径的唯一正文。
+
+P0 SPEC 必须完成：
+
+- 分配或确认 SPEC 编号、短名、层级、主责 L1/L2、上级规格和关联规格。
+- 按模板写清文档控制、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。
+- 为涉及实现架构的数据面补齐目标架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`。
+- 在 SPEC 中写明后续代码文件头部应标注的 SPEC 编号、短名和实现引用版本。
+
+后续代码阶段只能在 P0 SPEC 明确后开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本；自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。
+
 ## 当前 HWLAB issue 锚点

 - L0 总规格：`project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md`。该规格文档本身承担索引职责；历史 issue 为 `[#1194](https://github.com/pikasTech/HWLAB/issues/1194)`。
@@ -219,6 +219,70 @@
 - [ ] 如稳定规则变化，更新 `project-management/PJ2026-01` 中的对应规格文件
 ```

+## 重大规划型 issue P0 SPEC 先行块
+
+```markdown
+## P0 SPEC 先行
+
+- SPEC 编号: PJ2026-010N0M
+- SPEC 文档: project-management/PJ2026-01/specs/<对应规格文件>.md
+- 上级规格: project-management/PJ2026-01/specs/<父级规格>.md
+- 关联规格: <Web/API/AgentRun/平台运维等相关 SPEC>
+- 实现引用版本: draft-YYYY-MM-DD-p0
+- 目标图:
+  - [ ] 架构图已写入 SPEC
+  - [ ] 数据流图已写入 SPEC
+  - [ ] 关键时序图已写入 SPEC
+- 代码引用规则:
+  - [ ] 本 issue 范围内新增或修改源码文件头部必须标注 `SPEC: <编号> <短名> <实现引用版本>`
+  - [ ] 自动生成、vendored、纯配置、锁文件或二进制产物如不能加头部，必须能从生成器/渲染器/配置入口追溯到 SPEC
+
+后续实现只能在 P0 SPEC 编号、目标图和代码引用规则确认后开始。若后续讨论改变稳定需求、数据流、接口或验收口径，先更新 SPEC，再更新本 issue 计划。
+```
+
+## SPEC 图与代码引用章节片段
+
+````markdown
+### 5.1 目标架构图
+
+```mermaid
+flowchart LR
+  A[入口] --> B[服务边界]
+  B --> C[持久化或运行事实]
+  C --> D[用户/运维可见输出]
+```
+
+### 5.2 目标数据流图
+
+```mermaid
+flowchart TD
+  A[外部输入] --> B[校验/归一化]
+  B --> C[权威状态]
+  C --> D[投影/查询]
+  D --> E[外部输出]
+```
+
+### 5.3 关键时序图
+
+```mermaid
+sequenceDiagram
+  participant U as 用户或调用方
+  participant C as 客户端
+  participant S as 服务端
+  participant R as 运行事实
+  U->>C: 发起动作
+  C->>S: 受控请求
+  S->>R: 读取或写入事实
+  R-->>S: 事实结果
+  S-->>C: 稳定响应
+  C-->>U: 用户可见结果
+```
+
+### 6.N <REQ> SPEC-first 与代码引用
+
+本能力的实现必须先引用本规格，再进入代码变更。该规划型 issue 范围内新增或修改的源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-010N0M <短名> draft-YYYY-MM-DD-p0`，并用一句话说明文件职责。实现文件不得只写 issue 编号、`latest` 或 `current` 作为规格引用。
+````
+
 ## 阶段报告章节

 ```markdown
@@ -33,6 +33,8 @@ HWLAB v0.2/v0.3 仓库内 `docs/reference/spec-*`，以及已收编的 `cloud-wo

 公开入口、FRP/Caddy/域名和 Web/API 可达性需求以 [PJ2026-010604 公开入口](../../project-management/PJ2026-01/specs/PJ2026-010604-public-entry.md) 为权威；Prometheus、日志、trace、health、status 和运维监控需求以 [PJ2026-010605 可观测监控](../../project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md) 为权威。运行配置数值仍以 UniDesk YAML 和目标 HWLAB repo 的受控配置为准，长期 reference 只记录解析与验证方法。

+重大规划型 issue 必须执行 P0 SPEC-first：P0 阶段先在 UniDesk OA `project-management/PJ2026-01/specs/` 维护对应 SPEC，确认 SPEC 编号、上级/关联规格、架构图、数据流图、关键时序图和代码引用规则，再进入后续实现。该 issue 范围内新增或修改的源码文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本；自动生成、vendored、纯配置、锁文件或不能承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。issue 正文和评论只承载执行计划、讨论和证据，不替代长期 SPEC。
+
 ## DEV 入口

 - 退役 G14 DEV/PROD 前端/API 入口曾使用 `http://74.48.78.17:17666/`、`http://74.48.78.17:17667/health/live`、`http://74.48.78.17:18666/` 和 `http://74.48.78.17:18667/health/live`；这些端口不再作为当前 HWLAB runtime 证据。
@@ -23,7 +23,7 @@
 | 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
 | 规格治理索引 | [规格治理](spec-governance.md) |

-本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB Prometheus 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB Prometheus 运维监控的稳定使命、范围、术语、系统边界、内部分工和原子需求。Workbench 用户可感知性能监控的架构图、数据流图、时序图和实现引用要求由 [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) 细化。

 ## 2. 目的和范围

@@ -36,7 +36,7 @@
 ### 2.2 范围内

 - Prometheus scrape target、metrics endpoint、alert rule 和服务健康指标接入。
- Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态和公开入口健康观测。
+- Web/API/AgentRun/HWPOD/Harness/用户管理等服务的运行面健康、资源状态、公开入口健康和用户可感知性能观测。
 - 发布后 runtime readiness、resource usage、error rate、queue depth、target availability 和 alert 状态摘要。
 - 监控数据的受控查询、低噪声摘要、失败归因和敏感输出约束。

@@ -52,6 +52,7 @@
 | 术语 | 定义 |
 | --- | --- |
 | Prometheus 运维监控 | 通过 Prometheus 采集、查询和告警 HWLAB 运行面 metrics 的运维能力。 |
+| 用户可感知性能 | 用户在 Web、CLI 或 API 入口中直接感受到的等待时间、加载时间、首个可读内容出现时间和完整可用状态。 |
 | scrape target | Prometheus 抓取 metrics 的目标服务、path 和 label 集合。 |
 | metrics endpoint | 服务暴露运行状态、资源状态和业务健康指标的 HTTP 端点。 |
 | alert rule | 对 metrics 表达告警条件的规则，具体阈值来自配置。 |
@@ -77,6 +78,7 @@
 | PJ2026-01060502 | 告警规则 | 本规格 6.2 | alert rule、状态分类和配置来源 | Metrics接入、YAML运维 | 平台值守、发布判定 |
 | PJ2026-01060503 | 运行摘要 | 本规格 6.3 | health、readiness、resource、error rate 和入口健康摘要 | 公开入口、发布流水 | 管理员和各 L1 owner |
 | PJ2026-01060504 | 边界约束 | 本规格 6.4 | 监控与业务通过、长证据、敏感输出的边界 | 全部 L1 | 用户反馈和排障 |
+| PJ2026-01060505 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | Web 工作台用户可感知性能、RUM、AgentRun event visible latency 和 Prometheus 指标口径 | Web工作台、Agent编排、API契约 | 平台运维、客户端和性能回归调查 |

 ## 6. 原子需求

@@ -120,6 +122,16 @@

 缺失业务能力时，监控只能报告 blocker 或 health 降级，不能通过新增告警、证据采样或诊断文案伪装成能力完成。

+### 6.5 OPS-MON-REQ-005 Workbench 用户可感知性能
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-MON-REQ-005 | Workbench性能 | [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | [Web工作台](PJ2026-010401-web-workbench.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[API契约](PJ2026-010403-api-contract.md) |
+
+运维监控应把 Web 工作台的用户可感知性能纳入 Prometheus 与 RUM 口径，使用户发消息到首个可见 Code Agent 输出、AgentRun backend event 到 Web 可见、session 切换加载和首屏打开等路径可以被持续观测。
+
+Workbench 性能监控只记录低基数指标、阶段耗时、状态分类和脱敏 correlation；不得把 traceId、sessionId、runId、prompt、assistant 正文、tool 参数、stdout/stderr、Secret 或用户个人信息写入 Prometheus label。具体架构、数据流、时序和代码引用规则由 [PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) 定义。
+
 ## 7. 过程控制

 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
@@ -0,0 +1,295 @@
+# PJ2026-01060505 Workbench性能
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01060505 Workbench性能需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01060505 |
+| 短名 | Workbench性能 |
+| 层级 | L3 子课题 |
+| 状态 | 已生效 |
+| 实现引用版本 | draft-2026-06-17-p0 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-010605 运维监控](PJ2026-010605-observability-monitoring.md) |
+| 关联规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 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 的脱敏诊断继续定位，但监控本身不替代业务功能闭环。
+
+### 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 指标。
+- 前端 RUM 与后端 Prometheus 指标的关联键、脱敏边界、低基数 label、histogram bucket、recording rule 和低样本告警边界。
+
+### 2.3 范围外
+
+- 工作台布局、消息投影、Trace阅读视图和会话权威 API 的功能正确性仍由 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 和 [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) 定义。
+- AgentRun run、command、runner、backend profile 和 provider 事件事实归 [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) 与 [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md)。
+- 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 的耗时。 |
+| 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 或用户输入。 |
+
+## 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 目标架构图
+
+```mermaid
+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 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
+  MET --> PROM[Prometheus / Rules / Dashboard]
+```
+
+### 4.2 目标数据流图
+
+```mermaid
+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 用户消息到首个可见事件时序图
+
+```mermaid
+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 可见时序图
+
+```mermaid
+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 切换和首屏打开时序图
+
+```mermaid
+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 | 代码引用 | 本规格 6.5 | SPEC-first、代码文件头部 SPEC 标注和 issue 回写要求 | 规格治理、全部实现模块 | 后续实现和 review |
+
+## 6. 原子需求
+
+### 6.1 OPS-WBPERF-REQ-001 Journey 口径
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-WBPERF-REQ-001 | Journey口径 | PJ2026-0106050501 Journey口径 | [Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md) |
+
+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工作台](PJ2026-010401-web-workbench.md) |
+
+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编排](PJ2026-0102-agent-orchestration.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[Web工作台](PJ2026-010401-web-workbench.md) |
+
+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指标 | [运维监控](PJ2026-010605-observability-monitoring.md)、[API契约](PJ2026-010403-api-contract.md) |
+
+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 SPEC-first 与代码引用
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-WBPERF-REQ-005 | 代码引用 | PJ2026-0106050505 代码引用 | [规格治理](spec-governance.md)、[Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md) |
+
+本性能监控能力的实现必须先引用本规格，再进入代码变更。新增或修改的前端、后端、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。
+
+## 7. 过程控制
+
+本规格的执行 issue 为 [HWLAB #1392](https://github.com/pikasTech/HWLAB/issues/1392)。该 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 的原入口验证结果，以及是否需要继续修订本规格。
@@ -23,6 +23,14 @@
 - 不在本文档 中记录阶段进展、CaseRun 日志、PR 流水或具体实现方案。
 - 治理规则变化需要回写 [L0 总规格](PJ2026-01-HWLAB.md) 的引用关系，并同步更新 UniDesk `$unidesk-oa`。

+## 重大规划型 issue 的 P0 SPEC-first 规则
+
+- 涉及新能力、跨模块架构、用户可见工作流、长期 API/数据模型、平台运维能力或多阶段实施的大规划型 issue，P0 阶段必须先维护 `project-management/PJ2026-01/specs/` 中的对应 SPEC；不得只把稳定需求、架构或验收标准写在 issue 正文里。
+- P0 SPEC 必须按模板明确编号、短名、层级、状态、上级规格、关联规格、目的和范围、术语表、系统边界、内部分工、原子需求和过程控制。涉及实现架构的数据面必须在 SPEC 中包含架构图、数据流图和关键时序图；图形优先使用 Markdown 内嵌 `mermaid`。
+- issue 正文的 P0 必须链接到对应 SPEC 文件和 SPEC 编号，并声明后续代码工作只有在 SPEC 编号、目标图和代码引用规则确认后才能开始。后续讨论改变稳定需求、数据流、接口或验收口径时，先更新 SPEC，再更新 issue 计划。
+- 该规划型 issue 范围内新增或修改的源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如 `SPEC: PJ2026-01060505 Workbench性能 draft-2026-06-17-p0`。自动生成文件、第三方 vendored 文件、纯配置、锁文件和不能承载注释头的二进制产物不要求加源码头部，但对应生成器、渲染器或配置入口必须能追溯到 SPEC。
+- PR/issue 收口必须回写实际遵循的 SPEC 编号、实现引用版本、触达源码文件头部标注情况，以及是否需要修订 SPEC。发现代码实现偏离 SPEC 时，先修 SPEC 或修代码，不能用 issue 评论替代长期规格。
+
 ## 编号与命名规则

 - 编号格式：`PJ<立项年份>-<层级路径>`。