From 3ae77ee379e7dbce16f1d610072d91a1cce2bd2b Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 15 Jun 2026 07:16:42 +0000 Subject: [PATCH] docs: define HWLAB public entry target state --- .../specs/PJ2026-010401-web-workbench.md | 16 +++++++++++++++- .../specs/PJ2026-010403-api-contract.md | 2 ++ .../specs/PJ2026-010603-yaml-first-ops.md | 4 ++++ 3 files changed, 21 insertions(+), 1 deletion(-) 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 136a6526..afddc4f7 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -66,6 +66,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 共享 trace renderer | Web trace 面板和 HWLAB CLI `trace --render web` 共用的 trace row 转换语义。 | | Trace阅读视图 | 工作台中面向用户阅读 Code Agent trace 的默认视图，只展示用户可理解的助手消息、工具调用、命令输出、最终结果和真实耗时，把运行身份、隐藏统计和原始事件收束到详情入口。 | | 工作态高密度 | 面向持续排障、比较和重复操作的工业化界面密度要求：低圆角、低内边距、正文优先、辅助元信息折叠，避免装饰性卡片和大块留白抢占工作内容。 | +| 正式公开入口 | 目标 node/lane 在 YAML 中声明的 Cloud Web public URL，用作用户访问、Playwright 验收、文档说明和故障复现入口。 | ## 4. 系统边界和接口 @@ -77,7 +78,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 外部输入 | 登录后访问请求、页面导航、会话选择、任务文本、引导/取消/重试操作、诊断查看操作和管理入口点击。 | | 受控资源 | Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航、响应式布局、composer policy 和共享 trace renderer。 | | 外部输出 | 页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示和可继续操作的 UI 状态。 | -| 用户接口 | Cloud Web `/workbench` 及相关登录后页面。 | +| 用户接口 | 目标 node/lane 的正式公开入口、Cloud Web `/workbench` 及相关登录后页面。 | | 系统边界 | Web工作台负责浏览器入口的布局、交互和展示契约；不拥有账号、Agent、硬件、评价或发布事实，只消费这些模块的服务端输出并以一致、低噪声、可操作的方式呈现。 | ## 5. 内部分工与规格索引 @@ -90,6 +91,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | PJ2026-01040104 | 响应布局 | 本规格 6.4 | 桌面多栏、侧栏折叠、移动端主任务区优先和输入区可达 | 全部工作台子模块 | 桌面和移动端用户 | | PJ2026-01040105 | 同源体验 | 本规格 6.5 | Web 与 CLI 共享 composer policy、trace renderer 和同源 API 行为 | HWLAB CLI、API契约、Agent编排 | Web/CLI 排障和内测复现 | | PJ2026-01040106 | Trace阅读 | 本规格 6.6 | Code Agent trace 去噪、详情收纳、耗时、正文优先和单一主按钮状态 | Agent编排、API契约、用户管理 | 用户排障和任务继续操作 | +| PJ2026-01040107 | 公开入口 | 本规格 6.7 | 正式 Cloud Web public URL、history fallback 和旧入口降级边界 | 平台运维、API契约、用户管理 | 用户访问、Playwright 验收、内测说明 | ## 6. 原子需求 @@ -159,6 +161,18 @@ Trace阅读视图属于工作态高密度界面。重复 trace row、message car 命令输入区应提供单一主按钮承载当前 turn 的主要动作：没有运行中 turn 时为发送新 Turn；存在运行中 turn 且输入框为空时为取消；存在运行中 turn 且输入框非空时为 Steer。工作台不得在运行已结束后继续显示独立的“取消运行中 Trace”按钮，也不得让发送、取消和 Steer 以多个并列主动作长期同时出现。 +### 6.7 CLIENT-WB-REQ-007 公开入口 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-WB-REQ-007 | 公开入口 | PJ2026-01040107 公开入口 | [平台运维](PJ2026-0106-platform-ops.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md) | + +Web工作台的正式浏览器入口必须来自目标 node/lane YAML 声明的 public URL。用户文档、内测说明、Playwright 验收和 issue 复现默认使用该正式公开入口，不使用 FRP remote port、节点直连端口、旧 lane 端口或历史临时域名作为正式入口。 + +正式公开入口下，`/`、`/login`、`/workbench` 和登录后页面应由 Cloud Web 提供一致的 SPA history fallback。API path 仍由 API契约定义并返回 JSON 语义；Web工作台不得要求 API/edge 端口对浏览器 history route 返回 HTML fallback。 + +平台运维负责把 YAML 声明的 public URL、FRP、Caddy、TLS 和 health 投递到运行面；Web工作台负责在该入口上完成登录、工作台、导航和错误展示。实现端口可以作为诊断入口暴露给维护者，但不得出现在用户主入口、内测验收入口或客户端默认配置中。 + ## 7. 过程控制 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。 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 1ebdcd8f..816acdef 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -94,6 +94,8 @@ API契约应定义 Cloud Web origin 下的相对 path、JSON-RPC envelope 和 ro 同源路由必须拒绝把绝对 URL、内部服务地址或旧运行面端口作为正式用户入口。平台运维提供公开入口和代理支撑；API契约只规定客户端可依赖的 path 和错误形态。 +API契约必须区分同源 API path 与浏览器 history route：`/auth*`、`/v1*`、`/json-rpc*`、`/health*` 等 API path 返回 JSON 语义，`/workbench`、`/login` 和其他 Cloud Web 页面路由由 Web工作台处理。API/edge 直达入口对页面路由返回 JSON 404 是正确边界，不应被改造成 SPA fallback；反过来，Web正式公开入口必须通过 route policy 把 API path 分流到 API 服务。 + ### 6.2 CLIENT-API-REQ-002 鉴权主体 | 编号 | 短名 | 主责模块 | 关联模块 | diff --git a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md index 2f96a648..da96e837 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md @@ -131,6 +131,10 @@ YAML运维应从 publicExposure 和 target 声明渲染 FRP、Caddy、public URL 公开入口渲染负责入口目标、健康探针和运行面配置的一致性。页面行为、API 契约、用户登录和 Agent 任务语义由关联 L1 定义；YAML运维只保证这些入口被正确投递到声明的目标运行面。 +每个 node/lane 的正式用户入口必须由 YAML 中的 `public.webUrl`、`public.apiUrl` 和 `publicExposure` 共同声明。FRP remote port、Caddy backend、本地 service DNS、旧 direct port、历史 nip.io 域名或仓库 generic deploy 默认值只能作为实现细节、诊断入口或 legacy 对照，不能反向覆盖 node/lane 的正式入口真相。 + +受控 CLI、文档生成和验收提示应优先输出正式 public URL，并把实现端口标注为诊断用途。缺少正式 public URL、DNS 与 `expectedA` 不一致、Caddy/FRP 渲染目标不一致或运行面 health 不匹配时，应暴露为 publicExposure 配置或投递缺口，而不是让调用方回退到旧端口继续验收。 + ### 6.5 OPS-YAML-REQ-005 AgentRun 执行策略配置 | 编号 | 短名 | 主责模块 | 关联模块 |