diff --git a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md index 84883d38..9c56e465 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md +++ b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md @@ -22,7 +22,7 @@ | 短名 | Agent编排 | | 层级 | L1 方向 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e | +| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-serve-session-aggregate-authority | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -146,4 +146,6 @@ HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有 [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 要求 Agent编排只把 AgentRun run、command、event、terminal status、failureKind 和 result envelope 交给 HWLAB接入的 projection writer/finalizer。Agent编排不得让 Web、CLI、Workbench GET、trace polling 或 legacy conversation path 分别读取 AgentRun 并各自推断 session running、assistant final response、turn terminal 或 trace terminal；同一 AgentRun 事实只能形成一份 HWLAB Workbench durable projection。 +Serve/session aggregate authority 要求职责进一步分离：AgentRun 拥有 run、command、runner job、cancel delivery、terminal report 和 execution diagnostic；HWLAB Workbench 拥有用户态 session aggregate、input/command fact、message/part、trace/timing、sealed final response 和 projection diagnostic。AgentRun 应暴露稳定 runId、commandId、event/result id、terminal status、failureKind、cancel/no-op 和 stale/blocked diagnostic，使 Workbench input/command fact 能回绑执行事实；AgentRun 不拥有 Workbench message/final/timing 显示权，也不通过旧 conversation/session 路径覆盖 Workbench read model。 + Web CaseRun 的 Agent 执行部分同样遵守该合同边界。CaseRun service 可以引用 AgentRun runId、commandId、traceId、terminal status、diff 和 final response，但不得通过 stdout 尾部、partial assistant、runner pod phase 或用户手工 steer 推断 CaseRun 成功。硬件动作、operation result 和 aggregate 仍由硬件池与 HarnessRL 生产，Agent编排只交付可引用的执行事实。 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 b16470a4..e5494747 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-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; 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-24-p0-aggregate-event-stream | +| 实现引用版本 | 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; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; 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-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -36,6 +36,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 长程可靠 Workbench 是本课题的黄金用例：用户在同一 public origin 内新建或选择 session，发送 `hi` 或等价最小任务，等待真实 Agent turn 运行，看到主消息区 final response 和 Trace terminal，随后刷新页面、切换到其他 session、再回到原 session、多标签页打开同一 deep link，仍看到同一组 sessionId、turnId、traceId、messageId、sealed final response 和 trace page。主 timeline 不等待完整长 Trace 全量拉完；Trace detail、projection diagnostic、transport diagnostic 和性能指标只解释可见性，不拥有主消息 lifecycle 或 final response 写权。trace/timeline 顺序、完成行位置、terminal sealed duration 和 SSE replay 必须来自唯一投影的 aggregate event stream revision，不能由浏览器 arrival order、trace hydration 顺序、session list 刷新或 probe 后处理重排。 +命令输入区的 prompt、steer、cancel 和 retry 都必须先成为唯一投影的 serve/session aggregate control command。Web 可以展示 optimistic placeholder，但不得从 DOM active card、session list、trace tail、localStorage 或 request timeout 推断 active turn、final response、running、duration 或 cancel 结果。 + ### 2.2 范围内 - 登录后 Cloud Web shell、topbar、导航、工作台路由、页面切换反馈和同源 API 状态展示。 @@ -87,6 +89,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | Aggregate event stream revision | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的 `eventSeq`、`aggregateSeq` 或等价 projection revision；Web reducer 只能用它判断新旧和补洞，不得用网络到达顺序或本地时间重排 terminal/final/timing。 | | 显示层本地 now | 浏览器组件为了展示“最近 X 秒前”和运行中“耗时 X 秒”而读取的当前时间；它只能作为直接渲染输入，不能写回 Server State、投影、session/message/turn lifecycle 或诊断事实，也不能通过平滑、滤波、单调 floor、跳变 cap 或二次缓存伪造一个更好看的时间事实。 | | 唯一投影 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的状态链路：AgentRun 执行事实只经 HWLAB projection writer/finalizer 写入 durable Workbench facts，REST、SSE、CLI、fake-server 和 Web 前端只消费该投影。 | +| Serve Session Aggregate Authority | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的会话级权威链路；Web 的 prompt、steer、cancel、retry、run-state、message/part、trace/timing 和 final response 只能消费该 aggregate read model。 | | sealed final response | 唯一投影 terminal commit 写入的 assistant 主正文、finalResponse、message/turn terminal status 和 sealed 标记；它是主消息区用户结果的唯一权威，不被后续读侧诊断、trace hydration 失败、turn polling 失败或 SSE gap 覆盖。 | | 破坏性投影权 | 删除 session、清空 active session、清空当前消息页、把 composer 改为无 session 或把 session lifecycle 改写为 not-found/archived/deleted 的权力。Web 前端 reducer、selectors、route hydrate、GET/list/detail/messages/SSE consumer 和测试 helper 没有破坏性投影权；只有显式用户 mutation 成功或后端 canonical lifecycle projection 可以改变这些事实。 | | 读侧推理 | Web、API、CLI、fake-server 或测试根据 trace tail、message text、tool event、result cache、session summary、list row、workspace snapshot、localStorage 或 elapsed timeout 推断 lifecycle、terminal、running 或 final response 的行为；Web工作台禁止该模式。 | diff --git a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md index 76cf54bc..90d2a32c 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md +++ b/project-management/PJ2026-01/specs/PJ2026-0104010803-workbench-unique-projection.md @@ -19,7 +19,7 @@ | 短名 | Workbench唯一投影 | | 层级 | L4 专项规格切片 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-24-p1-opencode-message-part-authority | +| 实现引用版本 | draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-24-p1-opencode-message-part-authority; draft-2026-06-25-p0-serve-session-aggregate-authority | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | | 关联规格 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md)、[PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | @@ -113,6 +113,8 @@ D601 v0.3 可以在 `hwlab-v03` namespace 内为 `hwlab-workbench-runtime` 使 | cache authority input | 构成缓存 key 与有效性判断的权威输入，至少包含 schema version、actor visibility input、session/turn/trace/cursor、projection revision/seq 或等价字段；这些输入必须来自 durable facts/read model。 | | cache diagnostic | `cacheStatus`、`cacheAgeMs`、cache key class、projection revision/seq、dbQueryAvoided 和 Redis unavailable/stale 等读路径诊断；它只能解释性能和新鲜度，不拥有主 timeline 写权。 | | CLI trace 视图 | `web-probe analyze` 从采样事实渲染的文字版 trace 视图，包含多 turn 的 `turn-summary` 和单 turn/单 frame 的 `trace-frame` 两层；它用于人工复核自动 finding，不保存新事实，不从 DOM 重新推断。 | +| Serve Session Aggregate Authority | Workbench 会话级聚合根，统一接收 prompt admission、steer、cancel、retry、run-state、message/part、trace/timing 和 terminal/final response 的写入序列；它是 Web、REST、SSE、CLI 和 web-probe 可见状态的上游 authority。 | +| durable input/command fact | 用户输入或控制命令进入执行前写入的持久事实，至少绑定 `sessionId`、`turnId`、`messageId`、`commandId`、action、target、admittedSeq、status 和 no-op/blocker；它先于 AgentRun dispatch 或 Kubernetes job 创建。 | ## 4. 系统边界和接口 @@ -142,6 +144,7 @@ D601 v0.3 可以在 `hwlab-v03` namespace 内为 `hwlab-workbench-runtime` 使 | PJ2026-010401080309 | DerivedReadCache | 本规格 6.9 | ReadModel 内部 Redis 派生缓存的 authority input、payload、失效和降级边界 | Workbench性能、API契约 | 高频读降尾延迟 | | PJ2026-010401080310 | AggregateEventStream | 本规格 6.10 | Workbench append-only aggregate event stream、cursor replay、projector revision 和顺序权威 | ProjectionWriter、ProjectionFinalizer、FactsStore | ReadModel、SSE、Web、CLI、fake-server、web-probe | | PJ2026-010401080311 | CliTraceView | 本规格 6.11 | web-probe 采样事实的 turn-summary/trace-frame 渲染、final response 展示和 analyzer 判据 | ReadModel、AggregateEventStream | 工测复核、自动 finding、issue 证据 | +| PJ2026-010401080312 | ServeSessionAggregate | 本规格 6.12 | prompt admission、steer/cancel、run-state、message/part、trace/timing 的 session aggregate authority | API契约、Agent编排、HWLAB接入 | Web、CLI、web-probe、fake-server | ### 5.1 OpenCode serve 对照原则 @@ -584,6 +587,24 @@ Trace-frame 行顺序必须来自 Workbench projectedSeq、aggregateSeq、part o prompt、steer、cancel 和 retry 必须在 CLI 视图中保留 control command boundary。普通 prompt 的 POST `/v1/agent/chat`、运行中 steer 的 `/v1/agent/chat/steer`、cancel 的 `/v1/agent/chat/cancel`、以及 terminal/no-active no-op 必须分别显示 action、target turn/run/command、HTTP status、accepted/no-op/blocker 和相关 ids；analyzer 不得因为同一时间窗内出现 steer 请求就把此前 prompt 判定成 `prompt-routed-to-steer`。 +### 6.12 WB-PROJ-REQ-012 serve/session aggregate authority + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| WB-PROJ-REQ-012 | 会话聚合权威 | PJ2026-010401080312 ServeSessionAggregate | [API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[Web工作台](PJ2026-010401-web-workbench.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | + +Workbench session 必须是用户可见执行状态的 aggregate root。prompt、steer、cancel 和 retry 先写成 durable input/command fact，再进入 AgentRun run/command、runner job 创建、steer delivery 或 cancel delivery；admission route 只能返回 durable accepted、structured conflict、structured no-op 或 blocker，不得让浏览器请求等待 Kubernetes Job 创建、runner 启动、result polling 或 trace hydration。 + +每个 input/command fact 必须至少绑定 `sessionId`、`turnId`、`traceId`、`userMessageId`、`assistantMessageId`、`commandId`、action、target run/command、`admittedSeq`、`promotedSeq`、status、no-op reason 或 blocker。`turnId/traceId/messageId/partId` 必须在 dispatch 前或首次 projection commit 前稳定分配；后续 AgentRun event/result、steer accepted、cancel requested、terminal result 和 diagnostic 都必须回绑这些身份。提交 HTTP 500、AgentRun dispatch failure 或 delivery timeout 也必须绑定到本次 input fact，不得回落到旧 trace、旧 final response 或旧 active card。 + +同一 session 必须有一条受控 execution lane。wake、interrupt、steer、cancel、retry 和 runner terminal 之间必须按 session aggregate seq 判定新旧；stale wake、late runner event、旧 turn polling、DOM active card、session list summary、last trace row 或浏览器 local state 都不能覆盖更新 turn 的状态。没有 active turn 的 cancel/steer 必须返回结构化 no-op 或 error；已 terminal 的 cancel 必须返回 already-terminal/no-op 或触发 terminal projection catch-up，不能重新打开 sealed turn 或覆盖 terminal facts。 + +Message/part 是用户结果的显示权威。assistant final response 只能来自 sealed assistant final/text part，diagnostic、stdout/stderr、transport error、steer/cancel accepted 文案和 analyzer summary 必须分仓展示。trace rows、turn timing、session running、completion row 和 duration 必须从同一 session aggregate/event stream/read model 派生；`trace-frame --trace-id newTrace` 不得显示旧 trace 行。若缺少 order、缺少 terminal 或存在 projection 矛盾，CLI/API/Web 必须暴露 projection blocker 或 warning，而不是读侧补齐。 + +兼容 `/v1/agent/*`、conversation path、旧 Web route、CLI renderer、SSE 和 fake-server 都只能调用同一个 mutation/read model。保留 wrapper 时，它只能做鉴权、schema 映射和旧字段降级，不拥有第二套 prompt admission、status、final response、timing 或 trace authority。 + +本要求参考 OpenCode serve 的职责边界，但不复制其技术栈。HWLAB 应学习其 `SessionInput` admitted/promoted、session run coordinator、run-state、message/part event 和 abort route 分工：输入先成为可审计事件，run-state 集中仲裁 busy/idle/cancel/retry，message/part 按顺序追加并 sealed，读取路径只消费 page/cursor/read model。后续实现不得继续沿用 trace tail、result envelope、DOM、session list 或 analyzer fallback 作为架构补丁。 + ## 7. 过程控制 本规格的执行证据保留在对应 GitHub 执行 issue、PR、web-probe 报告和 Playwright artifact 中；规格正文不承载长证据、运行日志或一次性排障流水。 @@ -593,3 +614,5 @@ prompt、steer、cancel 和 retry 必须在 CLI 视图中保留 control command web-probe 历史窗口 trace 乱序、完成行非最后、耗时不一致和红色 finding 的架构修复执行 issue 为 [#2055](https://github.com/pikasTech/HWLAB/issues/2055)。阶段跟踪必须以子 issue 为准：P0 SPEC-first [#2057](https://github.com/pikasTech/HWLAB/issues/2057)、P1 event schema/projector [#2058](https://github.com/pikasTech/HWLAB/issues/2058)、P2 read/SSE seq replay [#2059](https://github.com/pikasTech/HWLAB/issues/2059)、P3 Cloud Web trace/timing 补偿清理 [#2060](https://github.com/pikasTech/HWLAB/issues/2060)、P4 web-probe/OTel 验收固化 [#2061](https://github.com/pikasTech/HWLAB/issues/2061)、P5 D601/v03 长程验收与旧路径删除 [#2062](https://github.com/pikasTech/HWLAB/issues/2062)。后续实现必须引用 `draft-2026-06-24-p0-aggregate-event-stream`，并在关闭各阶段 issue 时说明是否仍存在读侧 repair、到达顺序排序、UI timing fabrication 或 probe 侧补偿。 Workbench turn/message/trace 投影 authority 与 CLI trace 视图收敛的架构修复执行 issue 为 [#2079](https://github.com/pikasTech/HWLAB/issues/2079)，正式 20 轮长程采样父 issue 为 [#2072](https://github.com/pikasTech/HWLAB/issues/2072)，运行中 steer 与前 1-5 轮采样子 issue 为 [#2078](https://github.com/pikasTech/HWLAB/issues/2078)。后续实现必须引用 `draft-2026-06-24-p1-opencode-message-part-authority`，并在各阶段子 issue 中说明是否已经消除 final response 误选、turn-summary/trace-frame traceId 误归因、completion row 非最后、duration 不一致、prompt/steer/cancel 边界误判和 analyzer-only 误判。 + +Workbench serve/session aggregate authority 架构修复执行 issue 为 [#2125](https://github.com/pikasTech/HWLAB/issues/2125)。阶段跟踪必须以子 issue 为准：P0 SPEC-first [#2128](https://github.com/pikasTech/HWLAB/issues/2128)、P1 durable input/command 与 session aggregate seq [#2127](https://github.com/pikasTech/HWLAB/issues/2127)、P2 message/part/turn/trace read model 与 terminal atomic commit [#2126](https://github.com/pikasTech/HWLAB/issues/2126)、P3 prompt/steer/cancel run-state authority [#2129](https://github.com/pikasTech/HWLAB/issues/2129)、P4 REST/SSE/CLI/Web 单源消费与 legacy wrapper 降级 [#2131](https://github.com/pikasTech/HWLAB/issues/2131)、P5 删除 fallback/repair/renderer 补丁路径 [#2130](https://github.com/pikasTech/HWLAB/issues/2130)、P6 fake-server 与 D601/v03 20轮原入口验收 [#2132](https://github.com/pikasTech/HWLAB/issues/2132)。后续实现必须引用 `draft-2026-06-25-p0-serve-session-aggregate-authority`，并在关闭各阶段 issue 时说明 prompt admission、steer/cancel、run-state、message/part、trace/timing、final response 是否已经共享同一 session aggregate authority。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md index 902376e1..6234e816 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -19,7 +19,7 @@ | 短名 | API契约 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-25-p0-web-caserun-e2e; 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-24-p0-aggregate-event-stream; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | +| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-25-p0-web-caserun-e2e; 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-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | @@ -81,6 +81,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | WorkbenchProjectionWriter | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的唯一写入组件，把 AgentRun run、command、event 和 result 转换为 HWLAB durable Workbench facts。 | | WorkbenchReadModel | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的唯一读模型，从 durable Workbench facts 组装 session detail、message page、turn snapshot、trace event page 和 session rail summary。 | | Aggregate event stream | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的 Workbench append-only event stream；API 只能暴露其 projection revision、cursor 和 replay envelope，不得把 source event array 或 result envelope 作为第二 API 事实源。 | +| Serve Session Aggregate Authority | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 定义的会话聚合权威；API mutation 先写 durable input/command fact，GET/SSE/compat wrapper 只读同一 aggregate projection。 | | eventSeq/aggregateSeq | Workbench event stream 的全局 cursor 与 aggregate 内 cursor，用于 SSE replay、projection revision、新鲜度和乱序检测；它们与 AgentRun `sourceSeq` 分离。 | | Derived read cache | WorkbenchReadModel 内部可选的 Redis 派生读缓存；它只缓存 durable projection 派生快照，不改变 API 资源、权限、lifecycle 或 final response 语义。 | | CacheDiagnostic | Workbench pure-read 响应或 OTel span 中用于解释缓存行为的诊断字段集合，至少包含 `cacheStatus`、`cacheAgeMs`、cacheKeyClass、projectionSeq 或等价字段；它不参与业务状态判断。 | @@ -120,6 +121,8 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md) 集中定义 AgentRun facts 到 Workbench durable facts 的目标架构、aggregate event stream、数据流、terminal commit 时序和 cloud-api 重启恢复时序。API契约在本文只保留接口边界：`GET /v1/workbench/*` 只读取 `WorkbenchReadModel`；SSE 只发布 projection commit notification；compat wrapper 只能调用同一 read model 或正式 mutation。 +Workbench mutation API 必须接入 serve/session aggregate authority。`POST /v1/agent/chat`、steer、cancel、retry 或未来 `/v1/workbench/sessions/{sessionId}/turns` 等入口，应先写入 durable input/command fact 并短返回 `202 Accepted`、structured conflict、structured no-op 或 blocker；响应中必须包含可继续查询的 `sessionId`、`turnId`、`traceId`、`commandId` 或 no-op reason。API 不得把浏览器请求阻塞到 Kubernetes Job 创建、runner 启动、result polling、trace hydration 或 finalizer catch-up，也不得在失败时把新提交回落到旧 session/trace/final。旧 `/v1/agent/*` wrapper 只能调用同一 mutation/read model 并做字段降级。 + Workbench SSE/event API 必须按 aggregate event stream/outbox cursor replay。`GET /v1/workbench/events?afterSeq=N` 或等价入口返回的每条 envelope 至少应携带 `eventSeq` 或 `outboxSeq`、`aggregateId`、`aggregateSeq`、`sessionId`、`turnId`、`traceId`、`projectionRevision`、`commitType` 和脱敏 payload 摘要。API 不承诺按网络到达顺序、trace hydration 完成顺序、result polling 返回顺序或 session list 更新时间排序；客户端必须按 cursor/revision 应用，缺口进入 transport diagnostic 和 REST 补洞。 若 AgentRun 事实已经 terminal 但 Workbench projection 尚未追平，GET 响应应暴露 `projectionStatus`、`lastProjectedSeq`、`sourceRunId`、`sourceCommandId`、`blocker` 或等价诊断字段；不得在 GET 中同步调用 AgentRun、Code Agent manager、legacy conversation manager、billing finalizer、workspace repair、trace polling 或 result polling 来推进事实。读模型、SSE publisher、compat wrapper 和 CLI render 都不能各自解释 terminal、running、final response 或 trace pagination；它们只能重放 durable projection。