From 6bf9a49f6dcf30cb5ad3250d3d7d5418eda36bfd Mon Sep 17 00:00:00 2001 From: UniDesk Codex Date: Tue, 30 Jun 2026 13:43:25 +0800 Subject: [PATCH] docs: record workbench rollout guardrails --- docs/reference/cloud-workbench.md | 4 ++++ docs/reference/node-gitops-cicd.md | 8 ++++++++ docs/reference/opencode-integration.md | 2 ++ 3 files changed, 14 insertions(+) diff --git a/docs/reference/cloud-workbench.md b/docs/reference/cloud-workbench.md index ad46eae4..592fee03 100644 --- a/docs/reference/cloud-workbench.md +++ b/docs/reference/cloud-workbench.md @@ -27,6 +27,8 @@ Cloud Web 的通用加载态使用 `web/hwlab-cloud-web/src/components/common/Lo Session rail 是该规则的高频区域。`/v1/agent/conversations` 还未返回时，即使 workspace 中已有 `selectedConversationId`、sessionId、traceId 或 selected conversation snapshot，也不能把选中 session stub 渲染成单条 `.session-tab`，更不能让它占满整个 session 列表高度。加载窗口应只显示 `LoadingState`，并隐藏当前 trace 元信息、复制/删除等依赖真实 active tab 的动作；待 conversations ready 后再渲染真实 session tabs，或在真实空集合时显示空态。 +Session rail 的后台恢复刷新必须有硬边界。显式用户动作或强一致操作（例如选择会话、删除当前会话）可以立即刷新会话列表；SSE error、active trace REST gap-fill、terminal refresh、trace hydration 等后台补偿路径不得绕过 session list 的冷却/合并机制去强制刷新完整列表。后台路径应优先补当前 trace、turn status、message projection 和必要的 trace events；需要刷新 session rail 时走统一的 scheduled refresh，并按 session/list key 合并已有 timer，避免网络抖动或 EventSource error storm 把 `/v1/workbench/sessions` 放大成浏览器内存和 CDP responsiveness 红灯。 + Workbench 只能维护一条会话恢复与提交路径。首次打开、新建后继续、从左侧 session rail 切换、直接进入 `/workbench/sessions/` 恢复时，都必须以当前 route/active conversation id 作为会话真相，并通过同一条 conversation detail hydration 路径得到 messages、turn state、trace/status 和 markdown 渲染输入；不得另写只消费列表 snapshot、workspace stub 或 localStorage selected id 的恢复分支。 Workbench 的 URL 反射必须服从用户当前导航和组件生命周期。`activeConversationId`、hydrate、select conversation 或列表刷新等异步状态只能在当前 route 仍属于 Workbench section、路径仍是 `/workbench`/`/workspace` 系列且 Workbench 组件仍 active 时，才允许把 URL 反射到 `/workbench/sessions/`；用户已经点击 Dashboard、API Keys、Admin、Settings 或其他非 Workbench 导航后，晚到的 Workbench 响应只能更新 store，不得再调用 `router.replace`/`router.push` 把全局 route 拉回 Workbench。新增 session 恢复或 URL 反射入口时必须复用共享路由守卫，例如 `web/hwlab-cloud-web/src/router/workbench-navigation.ts`，不要在业务组件里各自手写跳转判断。 @@ -38,3 +40,5 @@ Workspace 中的 `selectedConversationId`、`selectedAgentSessionId` 和 selecte Session rail 的运行中状态以目标 conversation 的真实 in-flight turn 为准。某个会话正在执行 Code Agent 请求时，对应 `.session-tab` 保持原有单行标题和最近用户消息时间，但必须暴露 `data-running="true"` 并显示执行中动效；turn 进入 completed、failed 或 canceled 后清除动效并回到 `data-running="false"`。切换会话、恢复会话或取消请求不能改变 session tab 的标题来源：左侧只展示用户第一句话和以最后一条用户消息发送时间计算的更新时间。 关闭 Workbench 加载态问题时，浏览器验收应从当前 node/lane 的 public origin 进入，并在同源会话中对目标列表 API 施加短暂延迟，观察 in-flight DOM 和恢复 DOM。延迟窗口应能看到 `#session-tabs[data-loading="true"]`、`.session-tab` 数量为 0、`.loading-state` 和 `.loading-spinner` 存在、`#session-status` 为“加载中”；延迟结束后应恢复为真实数据或真实空态。延迟时间应低于前端请求超时，避免把接口 timeout 后的降级状态误判为恢复态。 + +关闭 Workbench 多轮卡死或刷新风暴问题时，浏览器验收必须从新的 Workbench session 开始，并显式选择目标 provider；不要复用未知状态的旧 session，否则旧 in-flight turn、失败 trace 或投影滞后可能把验收误判为 HTTP 409 或会话漂移。验收至少核对两层证据：turn-summary 中用户复现步骤全部 terminal 且 final response 可见；observe analyze 中没有 browser memory、Playwright responsiveness、CDP metrics timeout 这类红灯。若只有 amber 的 requestfailed、console 或 DOM lag，要结合 turn-summary 和 archive red 判断是否仍影响多轮连续工作，不得把非阻塞噪声当作卡死复发。 diff --git a/docs/reference/node-gitops-cicd.md b/docs/reference/node-gitops-cicd.md index 01eeaf35..f7a0d4b2 100644 --- a/docs/reference/node-gitops-cicd.md +++ b/docs/reference/node-gitops-cicd.md @@ -12,3 +12,11 @@ - [PJ2026-010605 运维监控](https://github.com/pikasTech/unidesk/blob/master/project-management/PJ2026-01/specs/PJ2026-010605-observability-monitoring.md) 目标 node/lane 的具体实现、PipelineRun 观察和运行命令仍按本仓 `AGENTS.md` 与受控 CLI 执行；需求边界、node/lane 规则和运维职责只更新 UniDesk OA。 + +## 运行参考 + +node/lane rollout 的 120 秒阈值是性能告警和诊断分界，不是继续盲等的理由。`trigger-current --wait` 超过阈值或返回 pending 时，先用定点 `hwlab nodes control-plane status --node --lane --pipeline-run `、`git-mirror status` 和 runtime workload 摘要确认卡在哪一层：PipelineRun task、Argo sync、runtime-ready、public probe 或 git mirror flush。 + +PR 合并后如果目标分支被并行 PR 推进，closeout 要同时记录本 PR merge commit、当前 source head 和 ancestry 证据；只要当前 head 包含本 PR merge commit，后续 rollout 应按当前 head 收敛，避免回滚到旧 source。定点 status 可证明某个旧 PipelineRun 是否 succeeded，但最终用户入口验收必须以当前 node/lane source、GitOps revision、Argo 和 runtime 状态为准。 + +runtime-ready 卡住时先看 `STATUS` 输出里的 notReady workload，再按 workload 日志和事件定位；修复应回到 source truth、PR、GitOps 和受控 sync/refresh，不把手工 patch Deployment、裸删 Pod 或临时容器改动作为交付路径。若 runtime 已 ready 但 Argo 仍 OutOfSync/Progressing，先走受控 `hwlab nodes control-plane sync|refresh --node --lane --confirm` 收敛控制面，再复查 bounded status。 diff --git a/docs/reference/opencode-integration.md b/docs/reference/opencode-integration.md index 1d9c27f7..10e3d10e 100644 --- a/docs/reference/opencode-integration.md +++ b/docs/reference/opencode-integration.md @@ -7,6 +7,7 @@ - OpenCode UI/后端作为独立运行面接入 HWLAB，不与 `hwlab-cloud-web` 共享 Pod 或进程；Cloud Web 只负责导航入口、同源鉴权换票和代理守卫。 - OpenCode 公开 URL、upstream URL、provider profile、SecretRef 和 namespace 选择必须来自 node/lane 的受控 YAML 与 GitOps 渲染，不在前端或 runtime 代码里写隐藏默认。 - Cloud Web 的 OpenCode iframe 只能在拿到同源签名 URL 后加载。前端不得直接把裸 `HWLAB_CLOUD_WEB_OPENCODE_URL` 作为 iframe `src`，否则用户可能看到代理拒绝 JSON 而不是 HWLAB 页面状态。 +- OpenCode runtime 启动路径不得把外部包仓库访问作为 readiness 前置条件。`opencode-server` 容器启动时只启动服务本身；git、npm、provider adapter 或其他运行依赖必须通过镜像、env-reuse 环境或受控 boot sidecar 预置/校验。禁止在主容器启动脚本中临时 `apk add` / `apt install` 后再进入服务，否则 node DNS、egress proxy 或上游仓库抖动会把 OpenCode 变成 lane rollout blocker。 ## 鉴权与换票 @@ -25,3 +26,4 @@ - rollout 后先用受控 `hwlab nodes control-plane status --node --lane ` 确认 PipelineRun、Argo revision、runtime workload 和 public entry 全部收敛。 - Web 验收从 HWLAB public origin 打开 `/opencode`，确认 iframe 存在、frame URL 带 redacted ticket、顶层页面和 iframe body 都没有 `opencode_auth_required`。 - OTel 验收至少覆盖一条成功 frame-url trace 和一条未认证直连 OpenCode host 的 401 trace；两者都应能在 Tempo 中查到 Cloud API `/auth/session` span。 +- 如果 rollout 卡在 `opencode-server` not-ready，先用受控 node/lane status 确认是否只是 OpenCode workload 阻塞，再查 Pod 日志区分 `ImagePull`、CrashLoop、探针失败和 provider sidecar 失败。发现启动期包安装或外部仓库访问失败时，应修 GitOps 渲染或镜像/env-reuse source truth 后重新 rollout；不要手工 patch Deployment 或删除 Pod 作为长期解法。