diff --git a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md index b4f42f31..70013dc0 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -19,7 +19,7 @@ | 短名 | Web工作台 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery | +| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -89,6 +89,12 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 初发刷新一致性 | 同一 prompt 在初次发送、切换 session 后回到该 session、刷新页面和 SSE 重连后，都以同一 userMessageId、assistantMessageId、turnId 和 traceId 还原同一语义结果。 | | 浏览器回归验证 | 使用 Playwright 在真实浏览器中验证 Workbench 用户可见行为、状态投影和 Trace 阅读正确性的前端端到端单元测试；测试过程使用本地 mock server，不依赖实时 Cloud API、AgentRun、HWPOD 或其他运行组件。 | | 真实采集 fixture | 从目标 node/lane 的受控样本采集 Workbench REST、SSE、conversation、session、turn 和 trace 响应，经稳定伪 ID 映射与敏感字段脱敏后，用于浏览器回归验证的数据集。 | +| 长程 Web Observer | 在目标 node/lane 正式公开入口上启动真实浏览器并持续观测同一页面的客户端程序，用于发现长 Trace、session 切换、刷新恢复、滚动跟随和瞬态状态竞态。 | +| 纯客户端 web-probe | 只作为本地或目标 host 上的浏览器客户端进程运行的 web-probe 形态；它没有入站 HTTP/WebSocket/gRPC API、监听端口、数据库、队列、平台服务身份或业务状态写权。 | +| 被动采样 | 采样器不主动调用 Workbench 业务 API、不 reload、不自动点击、不修复 session、不拦截或重放网络请求，只读取 DOM、浏览器性能条目、控制台、页面错误和页面自然产生的网络事件。 | +| 命令文件 | `trans` 或受控 CLI 写入目标 host 文件系统的控制请求，例如登录、打开页面、发送 prompt、截图或停止；命令文件本身必须进入观测时间线。 | +| 页面权威 | 同一长程观测 job 中唯一拥有 Playwright browser/context/page 的客户端进程；控制循环和采样循环必须共享同一个 `page` 对象，页面重建必须记录连续性中断。 | +| JSONL 采样流 | 长程观测产物使用追加式 `.jsonl` 文件保存，每行一条带时间戳、单调序号、来源和脱敏标记的采样记录，便于长时间写入、局部复制和后处理分析。 | ## 4. 系统边界和接口 @@ -117,6 +123,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | PJ2026-01040108 | 状态投影 | 本规格 6.8 | server-state、reducer、selectors、timeline projection 和初发刷新一致性 | API契约、Agent编排 | Web timeline、session rail、trace detail | | PJ2026-01040109 | 前端模块 | 本规格 6.9 | API client、event client、server-state、UI state 和组件职责拆分 | API契约、公开入口 | 可维护前端实现 | | PJ2026-01040110 | 浏览器回归 | 本规格 6.10 | Playwright 独立测试、真实采集 fixture、mock server、截图 artifact 和状态投影断言 | API契约、平台运维 | Workbench 功能回归、防止刷新和会话切换退化 | +| PJ2026-01040111 | 长程观测 | 本规格 6.11 | 纯客户端 web-probe observer、命令文件控制、无副作用采样、JSONL artifact 和后处理分析 | 平台运维、公开入口 | Workbench 长程稳定性、瞬态竞态复现 | ### 5.1 目标数据流程图 @@ -211,7 +218,39 @@ flowchart LR 浏览器回归验证的数据流必须保证：fixture 优先来自目标 node/lane 的真实受控样本；脱敏后保留 conversationId、sessionId、turnId、traceId、messageId 和 sourceSeq 之间的关系；mock server 只重放和变形这些事实，不成为新的业务事实来源；D601 远程 Playwright route 只负责执行与截图 artifact 回传，功能正确性仍由 Web工作台规格定义。 -### 5.4 PJ2026-0104010803 Workbench唯一投影专项 +### 5.4 长程 web-probe observer 数据流图 + +```mermaid +flowchart LR + subgraph Host[D601 或目标 node host] + TRANS[trans 短连接控制] + CMD[commands/*.json] + OBS[web-probe observer 客户端进程] + ART[.state/web-observe artifacts] + ANALYZE[离线分析 job] + TRANS --> CMD + CMD --> OBS + OBS --> ART + ART --> ANALYZE + end + subgraph Browser[同一个 Playwright Browser/Context/Page] + PAGE[Workbench page] + DOM[DOM/scroll/performance 只读采样] + NET[自然 request/response/requestfailed 事件] + CONSOLE[console/pageerror] + PAGE --> DOM + PAGE --> NET + PAGE --> CONSOLE + end + OBS --> PAGE + DOM --> ART + NET --> ART + CONSOLE --> ART +``` + +长程 observer 的数据流必须保证：`trans` 只写命令文件和读取产物，不打开入站控制端口；observer 是目标 host 上的客户端进程，不是 Web 服务、daemon API、数据库消费者或平台状态源。控制命令、采样器和后处理分析共享同一份时间戳化 artifact；控制命令改变页面时必须记录为用户意图来源，采样器本身不得通过主动 API 请求、reload、自动点击、session repair 或网络拦截制造新业务事件。 + +### 5.5 PJ2026-0104010803 Workbench唯一投影专项 [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 是 Workbench 状态投影的唯一专项规格，集中定义 durable facts schema、`WorkbenchProjectionWriter`、`WorkbenchProjectionFinalizer`、`WorkbenchFactsStore`、`WorkbenchReadModel`、terminal commit、sealed final response、cloud-api 重启恢复、GET 纯读和代码引用规则。 @@ -410,6 +449,28 @@ mock 数据应优先来自目标 node/lane 的真实受控样本，而不是从 测试实现应优先使用用户可见文本、ARIA role 和稳定 DOM 标识断言，不通过内部 store、localStorage 或后端数据库直接判定通过。失败时必须保留 Playwright screenshot、trace 或等价 artifact；关键路径可以生成命名截图用于人工审阅。远程执行默认在目标 node/lane 上通过 UniDesk Playwright route 运行，截图和报告应回传到调用端，但这些 artifact 只是验证证据，不进入业务事实或监控指标。 +### 6.11 CLIENT-WB-REQ-011 长程观测 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-WB-REQ-011 | 长程观测 | PJ2026-01040111 长程观测 | [PJ2026-010604 公开入口](PJ2026-010604-public-entry.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +Web 工作台应具备长程 web-probe observer 能力，用真实浏览器在目标 node/lane 的正式公开入口上持续观察同一页面，用于复现和分析长 Trace、session 切换、刷新恢复、滚动跟随、final response 闪烁和无用户新消息时状态变化等瞬态问题。该能力只提供观察和证据，不拥有 Workbench 业务状态、身份鉴权、session lifecycle、projection、监控指标或修复权。 + +web-probe observer 必须保持纯客户端形态。它可以作为目标 host 上的长时间本地进程运行，但不得暴露入站 HTTP/WebSocket/gRPC API、监听控制端口、数据库 schema、消息队列消费者、Kubernetes 常驻服务、平台 daemon 或 Web 管理面。启动、停止、状态查看、命令投递和 artifact 回收只能通过受控 CLI、`trans` 短连接和目标 host 文件系统完成。任何需要长期保留的默认参数必须按 YAML-first 进入 UniDesk 自有配置；一次性控制命令使用命令文件，不得演变为新服务协议。 + +同一个 observer job 内必须只有一个页面权威。Playwright browser/context/page 由 observer 客户端进程持有；控制循环、采样循环、截图逻辑和网络事件监听共享同一个 `page` 对象。登录、打开 URL、发送 prompt、点击会话、截图和停止等控制动作以命令文件进入 `commands/pending`，处理结果追加到 `control.jsonl`，并带上命令 id、时间戳、操作者来源、执行前后 URL 和页面标识。若浏览器或页面崩溃后必须重建，observer 必须记录 oldPageId/newPageId、原因和连续性中断，不能把重建后的页面当作同一段无缝采样。 + +采样默认必须无副作用。采样器不得主动 `fetch` Workbench 业务 API、不得 reload 页面、不得自动点击、不得切换 session、不得调用 session repair helper、不得通过 `page.route()` 拦截或改写请求，也不得用 GET 触发 read-through repair。允许采集的默认输入只包括 DOM 快照摘要、可见文本摘要、当前 URL、scroll metrics、focus/selection、`performance` 条目、console/pageerror、Playwright 自然产生的 `request`/`response`/`requestfailed` 事件和用户控制命令造成的页面自然网络事件。网络记录必须标明 `observerInitiated=false`；若未来确需主动 API 探针，必须作为显式非默认模式记录 `observerInitiated=true`，并从被动证据分析中排除。 + +长程采样产物必须使用时间戳化目录和 JSONL 追加文件。推荐目录形态为 `.state/web-observe/////
/__/`，其中 `manifest.json` 记录目标 origin、node、lane、browser 版本、observer 版本、启动参数和脱敏策略；`heartbeat.json` 保存最近心跳；`control.jsonl`、`samples/*.jsonl`、`network/*.jsonl`、`console/*.jsonl`、`pageerrors/*.jsonl`、`anomalies/*.jsonl` 分别承载控制、采样、网络、控制台、页面错误和异常。每条 JSONL 记录必须包含 ISO 时间、单调序号、pageId、url、recordType、source、valuesRedacted 和 schemaVersion，避免长程文件被一次性整块读取或写坏。 + +截图策略应受预算控制。默认不做高频全页截图；常规 checkpoint 可使用 viewport 或关键区域 JPEG，并配置质量、间隔、最大张数和总字节预算；异常、失败、布局错乱和人工标记证据使用 PNG 或等价无损格式保存。每张截图必须记录触发原因、文件 SHA、字节数、viewport、deviceScaleFactor、关联 sample seq 和脱敏状态。重复截图应通过内容 hash 或视觉 hash 去重；超过预算时优先保留异常、状态切换和人工命令附近的证据。 + +离线分析 job 只能读取 artifact，不访问 Workbench 业务 API，也不修改浏览器页面。分析至少应覆盖：active session 是否跳转、route/session/message/trace 是否不一致、没有用户命令时是否出现新 agent 消息、final response 是否从 sealed 正文闪回错误态、Trace 是否长时间无 terminal、Trace 窗口和主工作区滚动是否跳顶、运行中“最近/耗时”是否停止刷新、自然网络响应与 DOM 可见状态之间的延迟。分析结果写入 `analysis/report.md` 和结构化 `analysis/report.json`，作为 issue 和回归修复证据，不成为产品业务状态。 + +长程 observer 不替代 fake-server Playwright 回归。fake-server Playwright 负责确定性功能红灯和修复后回归；observer 负责在线 public origin 的长时间、无副作用、瞬态观测。observer 发现的 bug 必须沉淀成可复现 fixture 或 fake-server 用例后再作为 Web 工作台功能回归闭环；不得用 observer 的自动切换、reload、repair 或人工观察代替功能修复。 + ## 7. 过程控制 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。