pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md

PJ2026-0104010803 Workbench唯一投影

修改历史

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

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

正文

PJ2026-0104010803 Workbench唯一投影需求规格

1. 文档控制

字段	内容
编号	PJ2026-0104010803
短名	Workbench唯一投影
层级	L4 专项规格切片
状态	已生效
实现引用版本	draft-2026-06-19-p0-projector-resume
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-010401 Web工作台
关联规格	PJ2026-010403 API契约、PJ2026-010205 HWLAB接入、PJ2026-0102 Agent编排
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Workbench 唯一投影的稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

Workbench唯一投影负责把 AgentRun 执行事实收敛成 HWLAB 自有的 durable Workbench facts，使 Web、CLI、REST、SSE、fake-server 和浏览器回归都消费同一份可恢复、可分页、可诊断的用户态会话事实。

本专项的目标状态是：AgentRun run、command、event 和 result 只作为执行事实输入；HWLAB 只有 WorkbenchProjectionWriter、WorkbenchProjectionFinalizer 写入 Workbench facts；cloud-api boot/background scheduler 是 startup/resume 的 authority，负责扫描 durable open checkpoint 和 running/projecting turn 并恢复追平；所有 GET /v1/workbench/* 和兼容读路径都只通过 WorkbenchReadModel 读取，不在读取时调用 AgentRun、Code Agent manager、trace polling、result polling 或 workspace repair 推进事实。Workbench 必须满足 0repair：页面、GET、SSE、fake-server 和 web-probe 都不得通过 reload、切换 session、sessionRepair、realignFreshSession、localStorage truth 或 read-through repair 把已经分裂的 route/session/message/trace 状态补成看起来正确。

2.2 范围内

• AgentRun facts 到 Workbench facts 的标准映射、幂等写入和 terminal commit 语义。
• session、message、part、turn、trace event、projection checkpoint 和 projection diagnostic 的 durable facts schema。
• WorkbenchFactsStore、WorkbenchProjectionWriter、WorkbenchProjectionFinalizer 和 WorkbenchReadModel 的组件边界。
• cloud-api 进程重启、进程内后台任务丢失、慢任务超过短轮询预算后的 durable finalizer 追平语义。
• GET /v1/workbench/* 纯读、/v1/agent/* compat wrapper 降级和 projection diagnostics 输出要求。
• Web reducer、CLI renderer、fake-server fixture 和 Playwright 回归对同一 durable projection 的消费规则。
• 本专项范围内新增或重构源码文件的 SPEC 头部引用规则。

2.3 范围外

• AgentRun run/command/runner job 的执行生命周期事实归 PJ2026-0102 Agent编排。
• HWLAB 到 AgentRun 的 dispatcher、runtime assembly、manual dispatch 和 provider profile 归 PJ2026-010205 HWLAB接入 及 Agent编排下级规格。
• API path、HTTP schema、错误 envelope 和 route policy 归 PJ2026-010403 API契约。
• Web 布局、组件、浏览器交互和可见 UX 归 PJ2026-010401 Web工作台。
• 用户身份、权限、额度、账本和 owner visibility 归 PJ2026-0105 用户管理。
• CI/CD、GitOps、公开入口、Prometheus 和运行面运维归 PJ2026-0106 平台运维。

3. 术语表

术语	定义
AgentRun facts	AgentRun 产生的 run、command、runner job、event、result、terminalStatus、failureKind、sourceSeq 和 sourceEventId 等执行事实。
Workbench facts	HWLAB 自有的 session、message、part、turn、trace event、checkpoint 和 diagnostic 持久事实，用于用户态 Workbench 展示。
WorkbenchProjectionWriter	唯一把 normalized AgentRun facts 写成 Workbench facts 的组件；它不处理 HTTP route、鉴权、UI transient state 或兼容 API 输出。
WorkbenchProjectionFinalizer	以 checkpoint 为驱动的幂等追平组件；可由 submit 后、event 到达、后台恢复或显式 checkpoint replay/reprojection 触发，但所有入口调用同一 finalization 逻辑。
WorkbenchFactsStore	durable facts 存储接口，负责幂等 upsert、terminal commit、checkpoint、diagnostic、分页查询和 owner visibility 过滤所需的持久化读写。
WorkbenchReadModel	唯一读取 Workbench facts 并组装 session rail、session detail、message page、turn snapshot、trace event page 和 projection diagnostics 的读模型。
checkpoint replay/reprojection	受控管理入口按已持久化 sourceRun/sourceCommand/checkpoint 重放投影逻辑，用于恢复投影 lag 或阻塞；它只能调用同一 finalizer/writer，不由 GET、Web 页面、SSE 订阅或测试 helper 触发，也不得改变 active session 或 route。
projection commit	writer/finalizer 对一组 message、part、turn、trace、session summary 和 checkpoint 的一次幂等持久化提交；terminal commit 必须保持用户可见事实一致。
terminal commit	标记同一 turn 结束的 projection commit，必须原子更新 assistant final text、message/part status、turn terminal、trace terminal event、session running=false、summary 和 SSE cursor。
projectedSeq	HWLAB trace event 和 projection commit 的单调序列，用于 REST 分页、SSE replay、fake-server fixture 和审计；不得与 AgentRun sourceSeq 混用。
sourceSeq/sourceEventId	AgentRun event/result 的来源序列或来源事件标识，只作为映射审计字段和幂等输入，不作为 Workbench trace page cursor。
checkpoint	finalizer 已成功投影到某个 sourceRunId/sourceCommandId/sourceSeq 的 durable 位置记录，用于 cloud-api 重启或后台任务丢失后继续追平。
sourceLatestSeq	finalizer 在本次或最近一次拉取中观察到的 AgentRun command 最新 sourceSeq，用于诊断投影 lag；它不得替代 lastSourceSeq 成为已提交事实。
projection diagnostic	暴露 projection lag、blocker、lastProjectedSeq、sourceRunId、sourceCommandId、updatedAt 和恢复状态的可诊断字段。
projection health	对 projection diagnostic 的只读解释，状态至少区分 projecting、caught-up、degraded 和 stalled；它不推进 facts，也不得把 stale projecting 标为 caught-up。
TraceEventPage	由 WorkbenchReadModel 返回的 trace 分页事实，必须按 projectedSeq 单调排序，并保持 range.fromSeq <= range.toSeq；空页用显式 empty range 表达，不生成非法区间。
compat wrapper	旧 /v1/agent/* 或 conversation path 的兼容包装层；只能调用 WorkbenchReadModel 或正式 mutation，不拥有第二套事实写入或 read-through repair。
read-through repair	GET 路径为了让页面“看起来正确”而同步调用 AgentRun、Code Agent manager、workspace repair、trace/result polling 或 billing finalizer 推进事实；本专项禁止该模式。
读侧推理	REST GET、SSE consumer、compat wrapper、CLI renderer、Web reducer/selectors、Trace renderer、fake-server 或测试断言根据 trace tail、message text、tool event、result cache、session summary、list row、workspace snapshot、localStorage 或 elapsed timeout 推断 turn/session/message lifecycle、terminal、running 或 final response 的行为；本专项禁止该模式。
事后 repair	页面或测试发现 active route/session/message/trace 已经分裂后，再通过 reload、切换 session、sessionRepair、realignFreshSession、workspace selection repair、active tab repair、localStorage truth、GET read-through 或 SSE gap repair 把 UI 补成看起来正确；本专项禁止该模式。

4. 系统边界和接口

本规格把 Workbench唯一投影作为客户端、API契约、HWLAB接入和Agent编排之间的状态边界看待；本章只描述输入、输出和责任边界。

边界项	内容
外部使用者	Cloud Web、HWLAB CLI、Cloud API route、AgentRun adapter、fake-server 回归和运维诊断。
外部输入	AgentRun run/command/event/result facts、turn admission metadata、owner/session visibility、显式 checkpoint replay/reprojection 请求、REST/SSE 查询参数。
受控资源	Workbench facts、projection checkpoint、diagnostic、projectedSeq、session/message/part/turn/trace 查询模型和 SSE projection commit notification。
外部输出	session rail、session detail、message/part page、turn snapshot、trace event page、projection diagnostics、SSE events 和 compat wrapper envelope。
用户接口	Cloud Web /workbench、同源 /v1/workbench/* REST/SSE、HWLAB CLI 的同源 Workbench/API 入口。
系统边界	本专项只定义 Workbench 用户态事实的唯一写入和读取链路；它不定义 AgentRun 执行合同、用户权限策略、Web UI 布局或平台发布机制。

5. 内部分工与规格索引

编号	内部模块	规格文档	主责边界	上游依赖	下游支撑
PJ2026-010401080301	FactsStore	本规格 6.1	durable facts schema、幂等 upsert、terminal commit、checkpoint 和分页读取	数据库/runtimeStore、用户管理 visibility	Writer、Finalizer、ReadModel
PJ2026-010401080302	ProjectionWriter	本规格 6.2	normalized AgentRun facts 到 Workbench facts 的唯一写入	HWLAB接入、Agent编排	ReadModel、SSE、CLI/Web
PJ2026-010401080303	ProjectionFinalizer	本规格 6.3	checkpoint 驱动追平、重启恢复和显式 checkpoint replay/reprojection 的同一幂等入口	FactsStore、AgentRun facts source	Writer、diagnostics
PJ2026-010401080304	ReadModel	本规格 6.4	session/message/turn/trace/projection diagnostics 的唯一读模型	FactsStore、用户管理 visibility	REST GET、compat wrapper、CLI、fake-server
PJ2026-010401080305	CompatWrapper	本规格 6.5	旧 /v1/agent/* 和 conversation path 到 ReadModel 或正式 mutation 的兼容映射	API契约、ReadModel	Web/CLI 迁移期兼容
PJ2026-010401080306	WebServerState	本规格 6.6	Web reducer/selectors 只消费 REST/SSE projection，不补写事实	Web工作台、API契约	session rail、timeline、composer、trace detail
PJ2026-010401080307	Regression	本规格 6.7	后端红灯、fake-server Playwright、D601 web-probe 和分叉清零验收	平台运维、Web工作台	issue 收口和防回归
PJ2026-010401080308	CodeReference	本规格 6.8	源码文件头部 SPEC 引用和实现版本追溯	规格治理	后续实现审计

5.1 目标架构图

flowchart LR
  subgraph AgentRun[AgentRun execution backend]
    RUN[run]
    CMD[command]
    SRC[events / result / sourceSeq]
    RUN --> CMD
    CMD --> SRC
  end
  subgraph CloudAPI[HWLAB Cloud API]
    AD[AgentRun Adapter: normalize facts]
    WR[WorkbenchProjectionWriter]
    FIN[WorkbenchProjectionFinalizer]
    FS[(WorkbenchFactsStore)]
    RM[WorkbenchReadModel]
    SSE[SSE publisher]
    COMP[Compat wrappers]
    AD --> WR
    FIN --> WR
    WR --> FS
    FS --> RM
    FS --> SSE
    RM --> COMP
  end
  subgraph Consumers[Projection consumers]
    REST[GET /v1/workbench/*]
    WEB[Cloud Web reducer/selectors]
    CLI[HWLAB CLI renderer]
    FAKE[fake-server fixture]
    SSEOUT[/v1/workbench/events]
    RM --> REST
    REST --> WEB
    REST --> CLI
    REST --> FAKE
    SSE --> SSEOUT
    SSEOUT --> WEB
  end
  SRC --> AD

目标架构要求 route/auth、adapter、projection writer/finalizer、facts store、read model、SSE publisher 和 compat wrapper 分工清晰。任何 route、GET handler、trace polling、result polling、workspace snapshot 或 front-end reducer 都不能绕过 writer/finalizer 直接改变 Workbench facts。

目标架构还要求彻底禁止读侧推理。turn.status、message.status、session.running、trace terminal、finalResponse 和 projectionStatus 必须是 projection writer/finalizer 已经写入 durable facts 的字段；read model、REST route、SSE consumer、compat wrapper、Web reducer、CLI renderer、fake-server 和测试只能读取和重放这些字段。AgentRun facts、trace events、message parts、result envelope、session summary、list row 和 workspace snapshot 只能作为 writer/finalizer 输入或诊断字段，不得在读取链路中通过优先级、fallback、最后事件、空文本、超时或 UI heuristic 生成生命周期事实。

5.2 目标数据流图

flowchart TD
  USER[用户 prompt/steer/retry/cancel] --> ADMISSION[Turn admission]
  ADMISSION --> IDS[stable turnId traceId userMessageId assistantMessageId]
  ADMISSION --> AR[AgentRun run/command]
  IDS --> WR0[ProjectionWriter: admission facts]
  AR --> EV[AgentRun events/result]
  EV --> NORM[normalize AgentRun facts]
  NORM --> FIN[ProjectionFinalizer]
  FIN --> WR[ProjectionWriter]
  WR0 --> TX[projection commit]
  WR --> TX
  TX --> FACTS[(Workbench facts + checkpoint + diagnostics)]
  FACTS --> RM[WorkbenchReadModel]
  FACTS --> BUS[SSE projection commit]
  RM --> SNAP[REST snapshot / pages]
  BUS --> STREAM[SSE events]
  SNAP --> RED[Web reducer / CLI / fake-server]
  STREAM --> RED

数据流必须保证：admission 只生成稳定标识和初始 facts；AgentRun facts 必须先归一化，再由 writer/finalizer 进入 projection commit；REST snapshot 和 SSE event 只能重放 durable facts；diagnostic 明确表达 lag/blocker，不能让读取路径、页面路径或测试路径隐式修复事实。

5.3 terminal commit 关键时序图

sequenceDiagram
  participant AR as AgentRun
  participant Adapter as AgentRun Adapter
  participant Finalizer as ProjectionFinalizer
  participant Writer as ProjectionWriter
  participant Store as FactsStore
  participant SSE as SSE Publisher
  participant Read as ReadModel
  participant Web as Web/CLI/fake-server
  AR-->>Adapter: terminal result + events + sourceSeq
  Adapter-->>Finalizer: normalized facts
  Finalizer->>Writer: finalize sourceRunId/sourceCommandId
  Writer->>Store: atomic terminal commit
  Store-->>Writer: projectedSeq + checkpoint
  Writer-->>SSE: projection commit notification
  Web->>Read: GET session/messages/turn/trace
  Read->>Store: read only
  Read-->>Web: same terminal facts + diagnostics

terminal commit 必须在同一幂等提交内更新 assistant final text、message/part terminal status、turn terminal、trace terminal event、session running=false、summary updated、projection checkpoint 和 SSE cursor。若提交失败或暂时无法完成，只能暴露 projection lag/blocker；不得让 session rail 显示 completed、message page 显示 running、turn snapshot 显示 failed 或 trace page 缺 terminal 这类互相矛盾状态。

5.4 cloud-api 重启恢复时序图

sequenceDiagram
  participant Boot as cloud-api boot/background scheduler
  participant Store as FactsStore
  participant AR as AgentRun facts source
  participant Finalizer as ProjectionFinalizer
  participant Writer as ProjectionWriter
  participant Read as ReadModel
  Boot->>Store: load open checkpoints / running-projecting turns
  Store-->>Boot: sourceRunId/sourceCommandId/lastSourceSeq/lastProjectedSeq
  Boot->>Finalizer: resume checkpoint
  Finalizer->>AR: fetch events/result after source checkpoint
  AR-->>Finalizer: source facts or still-running status
  Finalizer->>Writer: idempotent catch-up commit
  Writer->>Store: update facts/checkpoint/diagnostic
  Read->>Store: read only snapshots
  Store-->>Read: caught-up facts or explicit lag/blocker

重启恢复要求 finalizer 不依赖进程内 90s 轮询作为唯一推进机制。进程内任务丢失、cloud-api 重启或慢任务超过短轮询预算后，boot/background scheduler 必须能从 durable checkpoint 和 running/projecting turn 找回需要追平的 sourceRun/sourceCommand，并以同一 writer 逻辑提交或记录 blocker。GET、SSE、Web 页面、fake-server 和 probe 只能观察恢复状态，不能触发恢复。

6. 原子需求

6.1 WB-PROJ-REQ-001 durable facts store

编号	短名	主责模块	关联模块
WB-PROJ-REQ-001	FactsStore	PJ2026-010401080301 FactsStore	用户管理、API契约

Workbench facts store 应持久化 session、message、part、turn、trace event、projection checkpoint 和 projection diagnostic，使 Workbench 用户态事实可在 cloud-api 重启、进程内任务丢失或后台 finalizer 重跑后恢复。

Facts schema 至少包含以下事实：

fact	必需字段	职责边界
session	sessionId/conversationId/threadId/projectId/workspaceId/owner/status/running/currentTurnId/summary/updatedAt	会话可见性、rail 摘要和当前 turn 指针；不保存 provider Secret 或完整 prompt 原文之外的敏感负载。
message	messageId/sessionId/role/status/turnId/createdAt/updatedAt	timeline message 事实；assistant final text 通过 part 表达。
part	partId/messageId/type/status/text/tool/error/traceRef/order	文本、工具、错误和 trace 摘要的可组合展示事实。
turn	turnId/sessionId/traceId/status/terminal/failureKind/sourceRunId/sourceCommandId/messageIds/startedAt/finishedAt	一次用户提交、steer、retry 或 cancel 的生命周期事实。
trace event	traceId/projectedSeq/sourceSeq/sourceEventId/type/status/timestamp/redactedPayload	Workbench trace page 的分页事实；projectedSeq 是唯一 cursor。
checkpoint	turnId/traceId/sourceRunId/sourceCommandId/lastSourceSeq/lastProjectedSeq/sourceLatestSeq/status/attempt/lastAttemptAt/lastError/blocker/updatedAt	finalizer 追平位置、幂等边界、恢复状态和退避诊断。
diagnostic	sessionId/turnId/traceId/projectionStatus/health/lag/blocker/sourceRunId/sourceCommandId/lastSourceSeq/lastProjectedSeq/sourceLatestSeq/updatedAt	GET 和运维可见的 projection 状态，不推进事实。

Checkpoint 唯一键必须包含 sourceRunId、sourceCommandId 和对应 turnId/traceId，或等价的 command-scoped 唯一键。同一 AgentRun run 的不同 command 不得共享 cursor；旧 command 的历史事件不得误投到新 turn。lastSourceSeq 表示已经成功投影的来源位置，sourceLatestSeq 只表示最近观察到的来源最新位置；二者差值可用于 lag/health 诊断，但不得让读侧推断 terminal。

Facts store 必须支持幂等 upsert、terminal commit、projection checkpoint、diagnostic update、open checkpoint 扫描、running/projecting turn 扫描和按 owner visibility 过滤的分页查询。agent_sessions.session_json 可作为迁移期 metadata 来源，但不得继续承载业务 projection 真相。

6.2 WB-PROJ-REQ-002 projection writer

编号	短名	主责模块	关联模块
WB-PROJ-REQ-002	Writer	PJ2026-010401080302 ProjectionWriter	HWLAB接入、Agent编排

WorkbenchProjectionWriter 应作为唯一写入口，把 admission facts 和 normalized AgentRun facts 转换为 durable Workbench facts。Writer 不负责 HTTP route、鉴权、AgentRun fetch、UI transient state、旧 API envelope 或测试 fixture。

Writer 必须使用稳定幂等键写入 messageId、partId、turnId、traceId、sourceRunId、sourceCommandId、sourceSeq/sourceEventId 和 projectedSeq。重复 event、重放 result、重启恢复或 checkpoint replay/reprojection 不得创建重复 assistant message、重复 terminal event 或冲突 session summary。

6.3 WB-PROJ-REQ-003 projection finalizer

编号	短名	主责模块	关联模块
WB-PROJ-REQ-003	Finalizer	PJ2026-010401080303 ProjectionFinalizer	HWLAB接入、AgentRun核心

WorkbenchProjectionFinalizer 应以 checkpoint 为驱动追平 AgentRun facts。submit 后、event arrival 后、后台恢复和显式 checkpoint replay/reprojection 可以触发 finalizer，但这些入口必须调用同一幂等 finalization 逻辑。显式 replay/reprojection 是受控投影恢复入口，不是前端、GET、SSE 或 probe 的事后 repair；它不得改变 active session、route、当前消息区或用户显式选择。

Finalizer 不得伪造 terminal、不取消 AgentRun、不用日志尾部推断 completed，也不得让 GET route 临时同步执行 finalization。若 AgentRun 事实暂不可取或映射失败，finalizer 应写入 diagnostic blocker，保留 retry 所需 sourceRun/sourceCommand/checkpoint。

Startup/resume authority 只属于 cloud-api boot/background scheduler。该 scheduler 启动后必须扫描 durable open checkpoint、projectionStatus=projecting 或等价 running/projecting turn，按 bounded concurrency、attempt、lastAttemptAt 和 backoff 推进；它只能调用同一 WorkbenchProjectionFinalizer/Writer，不得新增第二套 result polling、manager shortcut 或 GET repair。恢复任务失败时必须写入 lastError/blocker 和下一次 retry 所需 cursor，不能静默丢弃。

Finalizer 的 cursor 必须以 command 和 checkpoint 为边界追平。对同一 run 的第二个及后续 command，finalizer 必须从该 command 自己的 checkpoint 或 command-scoped event/result window 继续，避免每次从 run head 扫描大量旧事件；当只能获得 run-level event page 时，也必须用 sourceCommandId、稳定幂等键和 source checkpoint 过滤旧 command 事件。result 先到、events 后到、terminal event 缺失但 command result terminal、source event 缺口或 sourceSeq 回退都必须进入 diagnostic/blocker 或补洞路径，不得在读侧修正。

6.4 WB-PROJ-REQ-004 read model and pure GET

编号	短名	主责模块	关联模块
WB-PROJ-REQ-004	ReadModel	PJ2026-010401080304 ReadModel	API契约、Web工作台

WorkbenchReadModel 应作为唯一读模型，从 durable facts 组装 session list、session detail、message page、turn snapshot、trace event page 和 projection diagnostics。Read model 只读 facts store，不调用 AgentRun、Code Agent manager、legacy conversation manager、billing finalizer、workspace repair 或 trace/result polling。

GET /v1/workbench/* 必须纯读。若 projection 滞后，响应应输出 projectionStatus、lastProjectedSeq、sourceRunId、sourceCommandId、blocker 或等价 diagnostic 字段，不能在 GET 内做 read-through repair。

Read model 严禁读侧推理。它不得从 result?.status ?? trace?.status、最后一条 trace event status=completed、message text 是否为空、part/tool row 状态、session list summary、workspace selected state、localStorage mirror、轮询耗时或 elapsed timeout 推断 turn terminal、message terminal、trace terminal、session running、final response 或 projection caught-up。若 durable facts 中唯一投影对象缺少这些字段，Read model 必须返回未知、投影中、degraded 或 blocker 等显式 diagnostic，由 projection writer/finalizer 修复源头；不得在读取时临时合成“看起来正确”的状态。

Projection health 必须只解释 durable diagnostic。projectionStatus=projecting 且 lastProjectedSeq < sourceLatestSeq、checkpoint stale 超过受控阈值、存在 lastError/blocker 或 attempt 正在退避时，不得返回 caught-up；应返回 projecting、degraded 或 stalled，并暴露 blocker、lastProjectedSeq、sourceRunId、sourceCommandId 和更新时间。caught-up 只能表示对应 command checkpoint 已追平可见 source facts，或 source 明确仍 running 且无新可投影 facts。

Trace event page 必须按 projectedSeq 单调返回，响应范围必须合法。非空页满足 range.fromSeq <= range.toSeq；空页必须用明确空集合和空 range/null range 表达，禁止出现 fromSeq=5/toSeq=4 这类非法区间。projectedSeq 是 Workbench 读取 cursor，sourceSeq 只作为来源审计字段；二者不得混用。

6.5 WB-PROJ-REQ-005 compat wrapper

编号	短名	主责模块	关联模块
WB-PROJ-REQ-005	CompatWrapper	PJ2026-010401080305 CompatWrapper	API契约、HWLAB接入

迁移期 /v1/agent/turns/*、/v1/agent/traces/*、conversation detail、result polling 和 legacy conversation path 可以作为 compat wrapper 暂存，但只能调用 WorkbenchReadModel 或正式 mutation。Compat wrapper 不得拥有第二套 session/message/turn/trace 写入逻辑，不得在读取时同步 finalizer，也不得用 result cache 或 trace tail 组装另一份 final response。

旧路径返回的 envelope 可以保留 legacy 字段名，但字段值必须来自同一 Workbench facts。若无法映射，应返回结构化 incompatibility/blocker，而不是回退到旧 manager 或空 stub。

6.6 WB-PROJ-REQ-006 Web server-state single path

编号	短名	主责模块	关联模块
WB-PROJ-REQ-006	Web单路径	PJ2026-010401080306 WebServerState	Web工作台、API契约

Cloud Web 应把 REST snapshot、SSE projection commit、trace event page 和 submit optimistic ids 归一化到同一 server-state/reducer/selectors。UI 组件只消费 selectors；组件、trace polling、result polling、localStorage、workspace snapshot 或 session list summary 不得直接写 final response、message terminal、turn terminal 或 trace authority。

active session 只能由 route sessionId 或用户显式选择产生。REST detail、session list、workspace summary、SSE event、trace page 或 turn snapshot 晚到时，只能更新其声明 sessionId 对应的 server-state bucket；不得重新选择 session、替换 URL、覆盖当前消息区、改变 composer 或把另一个 session 的 running/terminal 状态投射到当前页面。缺少 sessionId 或 session/trace 不匹配的 event 必须进入 authority mismatch diagnostic，不得猜测、fallback 或应用到当前 active session。

SSE 只作为 projection commit 后的通知和加速，不是事实来源。SSE 断线、丢事件或重连后，Web 只能通过同一 REST snapshot 与 trace page 补洞。running trace 在 terminal 前 hasMore=false 只表示当前页追平，不得设置永久 fullTraceLoaded=true。

6.7 WB-PROJ-REQ-007 regression and validation

编号	短名	主责模块	关联模块
WB-PROJ-REQ-007	回归验收	PJ2026-010401080307 Regression	Web工作台、平台运维

Workbench唯一投影必须有后端和浏览器两层回归：后端用 Workbench-only HTTP 用例证明 submit 后不访问旧 /v1/agent/turns 或 result polling 也能自然 completed；durable recovery 用例证明进程内 sync 丢失或 cloud-api 重启后 finalizer 能从 checkpoint 追平；terminal atomicity 用例证明 session rail、session detail、messages、turn snapshot 和 trace event page 不出现 running/completed 组合矛盾。

Durable recovery 红灯必须覆盖长 run、多 command 和大量旧事件场景。fixture 应优先从 D601 v0.3 真实样本脱敏派生，至少覆盖同一 run 中后续 command 已 completed、eventCount 大于 2000、Workbench 只投影早期 seq、GET 保持纯读、随后后台 resume 从 command-scoped checkpoint 追平并展示 final response 的路径。用例还必须断言 GET 没有调用 AgentRun 或 result polling。

回归还必须覆盖读侧推理清零。后端和前端测试应构造最后一条 trace event 为非终态 completed、message text 为空、result/trace/session summary 字段互相矛盾或投影暂时滞后的样本，断言 API 与 DOM 不从这些原始字段推断 terminal/final/running。收口证据应包含负向源码扫描，至少覆盖 result?.status ?? trace?.status、trace.status 终结 turn、last event completed 终结 turn、message/session/list 状态覆盖 turn、elapsed timeout 改写 terminal 和 no-final-response 占位 final text 等读侧推理路径。

fake-server Playwright 应使用目标 node/lane 的真实采集脱敏 fixture，覆盖 session 切换、刷新、SSE 断线重连、REST 补洞、trace 分页和 terminal final response。D601 v0.3 public origin web-probe 应验证不切 session、不刷新页面、fresh deep link 和多观察者场景都通过同一 read model 收敛。

0repair 验收必须先在 fake-server + Playwright 中形成红灯：fresh context 直达 session A、普通点击切到 session B、A 的 delayed detail/turn/trace/SSE 晚到、用户没有提交 B 的新消息时，B 的 URL、active tab、message card、composer 和 trace detail 不得出现 A 的 user/agent 文本、running 状态或 terminal trace。web-probe 必须连续截图观察提交前、running、中间态、terminal 和晚到事件；不得用 reload、切换 session、sessionRepair、realignFreshSession、localStorage 修改或 helper 自动点击修正页面后再判通过。

6.8 WB-PROJ-REQ-008 code reference rule

编号	短名	主责模块	关联模块
WB-PROJ-REQ-008	代码引用	PJ2026-010401080308 CodeReference	规格治理

本专项范围内新增或重构的核心源码文件，文件头部必须标注遵循的 SPEC 编号、短名和实现引用版本，例如：

SPEC: PJ2026-0104010803 Workbench唯一投影 draft-2026-06-19-p0-projector-resume

同一文件同时承载 API契约、HWLAB接入、Web工作台或 Agent编排职责时，应在同一头部追加对应 SPEC 编号与实现引用版本。实现文件不得只写 issue 编号、latest 或 current。自动生成文件、第三方 vendored 文件、纯配置、锁文件和无法承载注释头的二进制产物可例外，但对应生成器、渲染器或配置入口必须能追溯到本 SPEC。

7. 过程控制

本规格的执行证据保留在对应 GitHub 执行 issue、PR、web-probe 报告和 Playwright artifact 中；规格正文不承载长证据、运行日志或一次性排障流水。

本专项关闭前，执行 issue 必须回写以下证据：专项 SPEC commit、后端写点/读点清单、旧路径最终状态、PR、D601 v0.3 发布证据、fake-server Playwright 结果、public origin web-probe 的 script SHA/runDir/report SHA/截图 SHA，以及父级 Web/API/HWLAB接入/Agent编排规格是否仍与实现一致。