docs: record workbench terminal triad invariant

2026-07-01 17:57:21 +08:00
parent 511810e8ee
commit 9fc4671478
1 changed files with 2 additions and 0 deletions
@@ -21,6 +21,8 @@ Workbench 投影写路径必须做到 0 隐式 fallback。Admission、projection

 Workbench 的 trace/message/projection 运行时必须是独立模块边界。`workbench.ts` 只保留 session/route authority 校验、Pinia state commit、刷新调度和用户动作编排；trace snapshot、terminal result、message timing/status patch、agent error normalize、projection diagnostic 裁剪和 final response 文本提取等纯算法统一由 `web/hwlab-cloud-web/src/stores/workbench-message-projection-runtime.ts` 提供。新增或修复浏览器 smoke 时不得把这些 helper 重新散写回 store 或组件，也不得通过 reload、repair、localStorage truth、GET read-through、测试专用后门或删除 guard 来绕过真实投影问题。web-probe origin、视口、采样、命令超时、provider/lane 和报警阈值只从选中 node/lane 的受控 YAML/source-of-truth 进入验证命令，不在 SPEC 或前端 runtime 中写第二份数值。

+Workbench terminal 三态必须作为一个不可拆分的投影不变量维护：session rail 状态、turn 卡片状态和 final response object 要么同时表现为完成且 final response 存在，要么同时表现为运行且 final response 不存在。持久 read model 是 session、messages、turn、trace tuple 的 source of truth；前端 `workbench-server-state` 只能做归一化缓存和单调合并，不能把 stale running 刷新覆盖到同一 trace 的 terminal authority 上。`session.status`、`turn.status`、`session.list/detail/messages`、`message.snapshot`、projection page merge、REST trace hydration 和 SSE trace snapshot 都必须保留已 sealed terminal 的 `status`、`traceAutoLifecycle`、`text`、`finalResponse` 和 terminal timing；新 trace 的 running 可以让同一 session 进入下一轮运行，但同 trace 的 running/non-terminal 只能作为旧事件丢弃或合并为 runnerTrace 证据。判断 final response 是否存在时不得只看 `text`，`finalResponse` 对象本体也属于 Workbench read model 合同；新增修复应优先补 `workbench-message-projection-runtime` 或 `workbench-server-state` 的最小单元测试，而不是用 UI 特判、reload 或额外 fallback 掩盖投影分叉。
+
 MDTODO 发起 Workbench 执行时，HWPOD 执行上下文的唯一权威来源是 Project Management source registry。Workbench Launch 服务端必须通过 `taskRef -> sourceId/fileRef -> source` 解析 `launchContext.executionContext`，并把同一份 `contextFingerprint` 写入 session owner、Workbench facts、project-management link 和 OTel span；浏览器传入的 HWPOD 字段只能作为任务元数据，不能作为权威执行上下文。`sourceKind=hwpod-workspace` 但缺少 `hwpodId`、`nodeId` 或 `workspaceRootRef` 时，launch 必须显式失败，不能创建“看似成功但无法执行”的空 session。

 MDTODO 首轮 Code Agent prompt 必须包含 `hwpodId`、`mdtodoRootRef` 和 `hwpodWorkspaceArgs`，并要求所有 `hwpod/hwpod-ctl` 命令携带该参数。Agent 不得猜测容器本地路径，不得创建、复制或修补本地 `.hwlab/hwpod-spec.yaml` fallback。Workbench session header 可以显示 source、HWPOD 和 MDTODO root 的只读短标识；workspace host path 的长期可观测性默认使用 basename/label、hash 或 redacted 形态。