# PJ2026-010401080313 Workbench实时权威

## 修改历史

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

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

## 正文

## PJ2026-010401080313 Workbench实时权威需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010401080313 |
| 短名 | Workbench实时权威 |
| 层级 | L4 专项规格切片 |
| 状态 | 草稿 |
| 实现引用版本 | draft-2026-07-08-p0-workbench-realtime-authority-v2; draft-2026-07-09-p1-single-step-debug |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
| 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-0106050514 Workbench实时运行面](PJ2026-0106050514-workbench-realtime-runtime.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文承载 Workbench Realtime Authority v2 的长期裁决。GitHub issue 记录阶段执行和证据；本文定义长期稳定的实时权威、禁止路径、回归和调试工作台边界。

## 2. 目的和范围

### 2.1 目的

Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card、Final Response、Trace detail 和 transport diagnostic 的实时输入收敛到同一 durable projection 语义。当前目标不是“永远不用 REST”，而是禁止前端多端点补洞成为 correctness path：SSE typed event 是 live 主路径，`/v1/workbench/sync` 只能作为与 SSE 同语义的统一 replay/delta，initial snapshot 只负责页面初始水位，detail/history 只服务用户显式查看。

本规格同时定义单步调试工作台。调试工作台必须能在不接触真实运行面、不触发 automatic recovery 和不污染生产 Workbench store 的前提下，用 fake SSE 数据逐条驱动同一 reducer，暴露每一步的 authority decision、entity version、state diff、DOM triad 和禁止请求。

### 2.2 范围内

- `/v1/workbench/events` typed event 的 authority metadata、cursor、entity family/id/version、projectionRevision 和 terminal seal 语义。
- `/v1/workbench/sync` replay/delta 的语义边界：它是 SSE replay 等价物，不是第二套 REST repair 事实源。
- initial snapshot、explicit detail/history、trace-detail-only payload、session list/detail/messages read model 和主状态投影之间的合并边界。
- 前端 reducer/adapter 的 authority gate、sealed guard、detail-only rejection、late stale rejection 和 diagnostic 输出。
- 自动恢复、SSE error、cursor gap、cross-tab projection signal 和 refresh/reconnect 的允许动作与禁止动作。
- fake SSE 单步调试页、fixture 来源、调试子标签页、请求禁用规则、可视化证据和 Playwright 回归口径。
- web-probe/OTel/analyzer 对 legacy fan-out、sync/replay authority、cross-page convergence 和 fresh submit terminal/final 的判定口径。

### 2.3 范围外

- AgentRun run/command/runner job、provider stream 和 Code Agent 执行事实仍由 Agent编排定义。
- Durable event stream、projection writer/finalizer、facts store、read model 的写侧事务细节由 [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义。
- 浏览器内存、freeze blocker、RUM 和 web-probe 运行策略由 [PJ2026-0106050514 Workbench实时运行面](PJ2026-0106050514-workbench-realtime-runtime.md) 和 Web哨兵规格定义。
- 调试工作台不是用户业务入口，不拥有 session lifecycle、权限、Secret、真实 mutation 或运行面修复权。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| Realtime Authority v2 | Workbench 主状态只能由 initial snapshot、SSE typed event、统一 `/v1/workbench/sync` replay/delta 和显式 detail/history 中各自被授权的 projection 输入更新的规则集合。 |
| 高纯度 SSE | Workbench live correctness 优先由 SSE typed event 驱动；断线、重复、乱序和缺口通过同一 durable cursor/replay 语义处理，不回退到多个业务 REST endpoint 自行补事实。 |
| sync replay | `/v1/workbench/sync` 或等价入口按 session/trace scope 与 cursor 返回的 typed delta。它必须能被转换为与 SSE 相同的 reducer event，并携带同一 authority metadata。 |
| 多源补洞 | 前端在 automatic recovery 中同时或顺序调用 `/turns`、`/sessions/:id/messages`、`/traces/:id/events`、旧 `/v1/agent/*` 等端点来推断 terminal/final/message/session 主状态。该模式禁止。 |
| detail-only | 只服务 Trace detail、历史页、诊断和审计的 payload。它可以展示过程，不能覆盖主 message/finalResponse/turn/session authority。 |
| terminal seal | 同一 durable projection revision 内写入的 message/part terminal status、turn terminal、Final Response、timing、session running=false 和 cursor checkpoint。 |
| cross-page convergence | control page、observer page、刷新页和多标签页在同一 durable event/sync 输入下收敛到同一 message count、trace ids、turn status 和 Final Response digest。 |
| 单步调试工作台 | Cloud Web 内的独立调试路由，用 fake fixture 逐条喂入 snapshot/SSE/sync/detail 输入，展示 reducer 决策和 UI 投影，不访问真实 Workbench mutation。 |

## 4. 权威输入和禁止路径

Workbench 主状态只接受以下输入：

- `initial snapshot`：页面初始加载或 explicit user refresh 的水位输入，只能写入其声明的 session/message/turn/trace bucket。
- `SSE typed event`：live delivery 主路径，必须携带 `contractVersion`、`realtimeAuthority`、`entity.family/id/version`、cursor 和 `projectionRevision`。
- `sync replay/delta`：与 SSE 同语义的 replay 输入，必须先转换为 typed event 或同等 reducer action，再进入主 reducer。
- `explicit detail/history`：用户显式打开的 trace detail、历史分页或详情读取，只能写 detail bucket 或 diagnostic bucket；声明 `detailProjection=true` 或 `authority=trace-detail-only` 时必须拒绝写主状态。
- `optimistic local echo`：submit admission 前后的本地临时投影，必须有 stable id，对账后由 durable event/sync 覆盖；不得成为跨页面或刷新后的事实源。

禁止路径：

- automatic recovery、SSE error、cursor gap、submit reattach、terminal projection 或 cross-tab signal 直接调用 `/v1/workbench/turns/:id`、`/v1/workbench/sessions/:id/messages`、`/v1/workbench/traces/:id/events` 或旧 `/v1/agent/turns|traces|chat/result` 写主状态。
- 用 trace tail、trace detail 末行、message text、session list preview、elapsed timeout、localStorage、DOM active card 或 analyzer fallback 推断 `running`、terminal、Final Response 或 session active。
- 让 late session list/detail/messages、detail-only trace payload、transport diagnostic、requestfailed 或 stale running snapshot 覆盖 sealed entity version。
- 用 reload、切换 session、自动 repair helper、测试后门或 probe analyzer suppress 把已经分裂的页面补成通过。

## 5. 单步调试工作台

Cloud Web 应新增独立根导航入口，例如 `/workbench/debug`，navId 可为 `workbench.debug`。该入口面向开发和验收，不是普通用户任务入口。它必须使用隔离的 debug store 或 reducer harness，默认不复用生产 Workbench store，不写真实 session，不调用真实 mutation，不读取 Secret，不通过 localStorage 伪造权威。

调试页应采用左侧 fixture/场景栏、顶部子标签页、右侧 evidence 面板的工作态布局。根侧边栏入口是合理方案，因为单步调试需要独立路由、深链恢复、Playwright 直达和与真实 Workbench 页面并列观察；不应继续塞进现有 topbar 诊断弹窗。

建议子标签页如下：

| 子标签页 | 目标 | 必备能力 |
| --- | --- | --- |
| 纯 SSE 单步 | 单独测试 fake SSE 数据且禁用补洞 | 加载事件序列，`Next`/`Back`/`Run`/`Reset`，每步只调用 reducer，禁止 `/sync` 和 detail REST，显示 state diff、message order、turn status、Final Response digest。 |
| Authority Gate | 验证 authority metadata | 输入缺 `realtimeAuthority`、缺 entity、旧 version、detail-only、乱序 cursor 等样本，展示 accept/reject reason 和 diagnostic。 |
| Terminal Seal | 验证 sealed guard | 先写 completed/final，再喂 late running、trace error、detail-only、transport error，断言主正文、status、duration 不回退。 |
| Reconnect/Cursor | 验证重复、断线和 replay | 模拟 duplicate、missing seq、out-of-order、reconnect afterSeq；默认只标 diagnostic，不自动补洞；显式打开 sync 模式时只允许 `/workbench/sync` 等价 replay。 |
| Cross Page | 验证 control/observer 收敛 | 两个隔离 reducer/page model 接收同一 durable SSE/sync 输入或不同到达顺序，比较 message count、trace ids、turn status、Final Response digest。 |
| Detail Only | 验证 Trace detail 隔离 | 显式展开 trace detail，喂 `trace-detail-only` payload，证明只更新 detail/diagnostic，不写主 message/final/turn/session。 |
| Snapshot Merge | 验证 initial snapshot 与 late read model | 构造 initial snapshot、late list/detail/messages 与 SSE interleave，证明 bucket 合并、stale rejection 和 active session 不变。 |
| Fake Provider | 验证 fake-echo/fake model 场景 | 使用 redacted fixture 或 fake provider 生成事件序列，检查 submit -> event -> terminal 的高纯度 SSE 路径，不以真实 provider 成败作为通过条件。 |
| Request Ledger | 验证禁止请求 | 记录 debug harness 中所有网络意图；纯 SSE 模式下任何 `/sync`、`/turns`、`/messages`、`/traces` 自动请求都必须红灯。 |

### 5.1 fake 数据来源

fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture 只能补足边界条件，例如 authority 字段缺失、version 回退、duplicate cursor、late running snapshot、detail-only payload、cross-page 到达顺序差异和 provider stream disconnect。每个 fixture 必须记录 `fixtureId`、`schemaVersion`、`capturedFrom` 或 `derivedFrom`、`syntheticReason`、redaction 状态和 expected verdict。

纯 SSE 调试的 fixture 应使用 typed event 数组作为第一等输入，不要求启动 fake server。需要浏览器级验证时，可以用 fake EventSource adapter 或 Playwright route 提供 `text/event-stream`，但调试页 reducer 必须能脱离真实 Cloud API 独立运行。

### 5.2 判定输出

每个单步场景必须至少输出：

- event header：eventName、type、sessionId、traceId、entity family/id/version、cursor、projectionRevision、detail-only 状态。
- authority decision：accepted/rejected、reason、diagnostic code、是否写主状态。
- state diff：session rail、message list、turn status、Final Response digest、trace detail rows、transport diagnostics。
- request ledger：本步允许和实际发生的网络请求族；纯 SSE 模式必须显示 no-sync/no-backfill。
- triad verdict：DOM-like projection、server-state projection、expected fixture verdict 三者是否一致。
- export：可复制为 Playwright fixture 或 issue closeout 的 bounded JSON/Markdown 摘要，不输出 Secret 或完整敏感 prompt。

## 6. 验收标准

静态验收：

- 自动恢复路径只允许 `SSE typed event`、`/v1/workbench/sync` replay 或 diagnostic；不得出现旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
- `traceHydration*` 命名和运行时口径必须收敛为 `traceDetail*` 或显式 detail read；旧配置字段如保留，只能作为 deprecated alias。
- `detailProjection=true`、`authority=trace-detail-only` 和缺 authority metadata 的输入必须被 reducer gate 拒绝写主状态，并产生可见 diagnostic。

行为验收：

- fresh submit 能在真实入口中自然 terminal/final 收敛，或明确暴露 provider/adapter blocker；不能靠旧补洞掩盖。
- refresh/reconnect/cross-tab signal 后，control/observer/fresh page 不出现 persistent `cross-page-projection-divergence`。
- `workbench-automatic-recovery-fanout-authority`、旧 agent read-through 和旧 Workbench detail fan-out 不回归。
- fake SSE 单步调试可以在无真实 API、无 `/sync`、无补洞的模式下完成 terminal seal、late stale rejection、detail-only rejection 和两页收敛测试。

## 7. 过程控制

本规格由 pikasTech/unidesk#1582 承载架构裁决入口，阶段 issue 包括 #1583 后端合同、#1584 前端接入、#1585 Colada key、#1586 web-probe/OTel 判定、#1587 原入口验收，以及后续 #1591/#1592/#1600/#1606/#1608 等 blocker 和残余收敛。后续代码实现和 closeout 必须引用本 SPEC 编号与实现引用版本，不得只写 issue 编号或“按最新方案”。
