OpenCode 接入运行参考

本文记录 HWLAB Cloud Web 接入 OpenCode 独立 UI/后端的长期运行约束；需求边界仍以 UniDesk OA 客户端、平台运维和公开入口规格为准。

运行边界

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。

Cloud Web 入口使用同源 GET /opencode/frame-url 读取当前 hwlab_session，通过 Cloud API /auth/session 确认登录态后签发短生命周期 hwlab_opencode_ticket。
hwlab_opencode_ticket 只用于 OpenCode iframe 首跳和后续代理 cookie 绑定；日志、issue、probe 报告和命令输出只能记录 ticket presence、redacted URL 或 fingerprint，不能打印 ticket 值。
OpenCode proxy 在没有有效 HWLAB session、ticket 缺失、ticket 过期或 upstream 配置缺失时必须返回结构化 JSON，并由 Cloud Web 页面展示受控状态；不得让裸 JSON 成为 /opencode 主入口的用户体验。

HWLAB 的 OpenCode 默认工作区由 Cloud Web runtime 配置进入运行面。OpenCode 左侧 session 列表依赖浏览器端 OpenCode project store 能看到 /workspace；如果只把 iframe 路由带到 /workspace/session，但没有让 OpenCode 前端 store 打开该 project，左侧仍可能表现为空 project 或只剩 Load more。
默认 project bootstrap 必须满足 OpenCode 上游 CSP。不要向 OpenCode HTML 注入 inline localStorage script；Cloud Web 应提供同源外部脚本资源，并由 HTML 只引用 script-src 'self' 允许的 src。
Cloud Web 代理改写 OpenCode HTML 时，如果通过运行时 fetch() 读取 upstream body，必须按已解码/已重写的新 body 重建实体 header。至少不得继续透传 upstream 的 content-encoding、content-md5 和 etag；content-length 以改写后 body 为准。
Web 验收不要只看 OpenCode /project API。最终口径应从用户入口 /opencode 验证 iframe 自然进入 /workspace 相关 route，OpenCode browser storage 中 project store 包含 /workspace，左侧 DOM 出现真实 session 节点或标题，且页面没有 No projects open / Open a project to get started。
临时 probe 可以读取 storage/API 帮助定位，但不得把手工写 localStorage、点击 Recent project 或 reload repair 当成通过条件；这些只能作为 P2 方向验证，不能替代用户入口自然收敛。

OpenCode frame-url 和 proxy 拒绝分支必须返回 traceparent、x-hwlab-otel-trace-id、x-request-id，响应 body 的 diagnostic 可以包含同一组 id 和 valuesPrinted=false。
Cloud Web 在调用 Cloud API /auth/session 时必须传播同一 trace context 和 request id，使 Tempo 能通过返回给浏览器的 trace id 查到 GET /auth/session 与 auth.session spans。
opencode_auth_required 不是最终根因；排障时先用响应里的 trace id 查询 OTel，再结合 Cloud API /auth/session 状态、ticket presence 和 Cloud Web runtime event 判断是登录态缺失、ticket 未签发、ticket 失效还是代理配置问题。

rollout 后先用受控 hwlab nodes control-plane status --node <node> --lane <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 作为长期解法。