From 5863a51188334162cdb9cbfff46d520ef2daba00 Mon Sep 17 00:00:00 2001 From: UniDesk Codex Date: Tue, 30 Jun 2026 10:31:56 +0800 Subject: [PATCH] docs: document opencode integration boundary --- AGENTS.md | 1 + docs/reference/opencode-integration.md | 27 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 docs/reference/opencode-integration.md diff --git a/AGENTS.md b/AGENTS.md index d97f2611..ec0db56c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文件只作为低噪 - DEV/runtime 边界与禁止误判：[docs/reference/dev-runtime-boundary.md](docs/reference/dev-runtime-boundary.md) - Cloud Workbench 默认首页与 UX 约束：[docs/reference/cloud-workbench.md](docs/reference/cloud-workbench.md) - Code Agent 真实回复、provider blocker 与 readiness：[docs/reference/code-agent-chat-readiness.md](docs/reference/code-agent-chat-readiness.md) +- OpenCode 独立 UI 接入、iframe 鉴权换票与 OTel 追踪：[docs/reference/opencode-integration.md](docs/reference/opencode-integration.md) - AgentRun 手动调度与 UniDesk SSH passthrough：[docs/reference/agentrun-code-agent-dispatch.md](docs/reference/agentrun-code-agent-dispatch.md) - 文档治理与 docs-spec 本地权威：[docs/reference/documentation-governance.md](docs/reference/documentation-governance.md) - 中文优先规则：[docs/reference/chinese-first-documentation.md](docs/reference/chinese-first-documentation.md) diff --git a/docs/reference/opencode-integration.md b/docs/reference/opencode-integration.md new file mode 100644 index 00000000..1d9c27f7 --- /dev/null +++ b/docs/reference/opencode-integration.md @@ -0,0 +1,27 @@ +# 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 页面状态。 + +## 鉴权与换票 + +- 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` 主入口的用户体验。 + +## OTel 可追踪性 + +- 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 --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。