From 10e93f17f9b73424bcf877cf942e952c757f1132 Mon Sep 17 00:00:00 2001 From: pikastech Date: Tue, 21 Jul 2026 01:36:26 +0200 Subject: [PATCH] =?UTF-8?q?docs(devlevel):=20=E5=9B=BA=E5=8C=96=20L1=20nat?= =?UTF-8?q?ive=20=E7=8B=AC=E7=AB=8B=E6=89=A7=E8=A1=8C=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-devlevel/SKILL.md | 55 +++++++++++------------- docs/reference/dev-environment.md | 17 ++++++++ docs/reference/hwlab.md | 32 +++++++++----- 3 files changed, 64 insertions(+), 40 deletions(-) diff --git a/.agents/skills/unidesk-devlevel/SKILL.md b/.agents/skills/unidesk-devlevel/SKILL.md index 56f195ad..097e7068 100644 --- a/.agents/skills/unidesk-devlevel/SKILL.md +++ b/.agents/skills/unidesk-devlevel/SKILL.md @@ -43,12 +43,23 @@ description: >- ## L1 Native - 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。 +- L1 的执行面在任何情况下都固定为本机 native 进程，不依赖 CI/CD、GitOps、 + Kubernetes、集群 rollout 或运行时镜像： + - API、Worker 和 Web 必须由 owning YAML 选中的 host workspace 与项目受控 + lifecycle CLI 拉起； + - CLI `--over-api` 回归可以直接访问 owning YAML 固定端口上的 native API； + - 本机调用可使用 YAML 解析出的 probe host，跨主机或用户入口使用 YAML + 声明的固定 native 地址； + - 正常启动、首次拉起、配置变更、合并后复测和故障处理都不得等待或调用 + PipelineRun、Argo、Deployment、ConfigMap 或镜像交付； + - 需要上述集群对象才能复现或验收时，该部分已经属于 L2，不得继续标为 L1。 - 每个 L1 服务必须使用 owning YAML 或项目规格声明的端口： - 同一服务的旧 L1 进程占用时，通过项目 CLI 停止或重启，再使用 YAML 当前端口； - 其他服务占用时，禁止停止、接管或复用其他服务； - 确认空闲端口后修改本服务 owning YAML，再由 parser/CLI 读取新端口继续； - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。 -- 固定端口、bind/probe、首选 HTTPS origin、固定公网 HTTP 降级入口、状态目录和服务组成必须由 YAML-first 配置解析；代码和命令行不得补隐式默认值。 +- 固定端口、bind/probe、状态目录和服务组成必须由 YAML-first 配置解析； + 代码和命令行不得补隐式默认值。 - L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。 - L1 开发、诊断或验收中发现受控 CLI 问题时，可以在当前任务内即时修改并完成最小验证： - 问题范围包括 parser、lifecycle、transport、输出、错误码、可见性和帮助； @@ -61,37 +72,23 @@ description: >- - 一次性 disposable smoke 可以按自身隔离合同清理，但不能替代可持续访问的 L1 服务； - 任务结束前必须重新读取 lifecycle status，不能凭启动返回值推断服务仍在运行。 - CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。 -- Web 使用 `$unidesk-webdev` 的受控入口，从 owning YAML 当前选中的首选 HTTPS origin 或固定公网 HTTP 降级入口访问 native Web。 +- Web 使用 `$unidesk-webdev` 的受控入口访问 owning YAML 固定端口上的 native Web。 - 微服务项目只启动当前微服务的前端、API、Worker及必要依赖。 - 前端、API 和 Worker可以分别启动、查看日志、重启和停止。 -- 所有 L1 API/Web 用户入口必须由 owning YAML 声明和选择： - - 固定 HTTPS origin 是首选入口； - - 共享 public-edge、TLS、DNS 或出网故障导致 HTTPS 不可用时，必须立即降级到 owning YAML 解析出的固定公网 HTTP IP 与 port，不能因公共面故障停止 L1 业务调试或验收； +- L1 API/Web 入口必须由 owning YAML 声明和选择： - `0.0.0.0` 只表示进程 bind； - - `127.0.0.1` 只用于本机 probe 或进程间代理； - - 固定公网 HTTP 入口的 IP 与 port 必须由 owning YAML 显式声明或从其中的公网地址和服务固定端口确定，禁止随机端口、localhost、命令行拼接或代码默认值； - - HTTP 降级不得关闭或绕过业务认证，不得新增第二 Caddy、FRP、代理或业务路径； - - 降级后先验证公网 HTTP readiness，再通过同一 API、Worker、SSE 和页面业务路径继续原 L1 验收；仅探测到端口或 HTTP 200 不构成业务通过； - - 内部端口冲突时通过 owning YAML 退让到空闲端口，固定 HTTPS origin 保持不变。 -- L1 使用共享 public-edge 时： - - 只允许修改本服务 owning YAML 的 `publicExposure` 与聚合 YAML 的 `configRef/path`； - - 只允许执行 `platform-infra public-edge plan|status` 或 `apply --dry-run`； - - 禁止执行、提示或恢复 `public-edge apply --confirm`、内部 `reconcile`、Caddyfile 写入或容器重建； - - 公网配置随正常 `master` merge 由唯一 PaC authority 自动收敛； - - 自动链未收敛时使用 `$unidesk-cicd` 只读归因并登记独立公共面 issue，不由 L1 会话补写； - - 公共面 issue 不得阻塞业务主线，确认固定公网 HTTP 降级入口可用后必须立即继续 L1； - - HTTPS 恢复后从正式 origin 复测并撤回 HTTP 降级状态。 -- L1 验收命令必须实际从当前选中的公网 HTTPS 或固定 HTTP 入口打开页面和 API；本机 `127.0.0.1`/`localhost` 只可作为进程健康 probe，不构成 L1 证据。 -- 涉及 L1 的任务在结束时必须报告公网入口： - - 报告 owning YAML 声明的固定 HTTP/HTTPS origin 和当前可用状态； - - 存在页面路径时同时报告可直接访问的完整 URL； - - HTTPS 未就绪但固定公网 HTTP 已通过时，明确报告 `degraded`、公共面 issue 和固定 HTTP URL，并继续交付； - - 两种公网入口都不可用时才报告 L1 公网 blocker，禁止用 localhost、bind 地址、随机 IP 或随机端口冒充公网入口。 -- 执行任何 L1 流程时必须扫描当前项目已声明的 L1： - - 发现历史 L1 尚未配置固定 HTTPS exposure 时，立即建立可追踪记录； - - 发现一例就完成该实例的 YAML-first exposure、受控部署和原入口验收； - - HTTPS 未收敛但固定公网 HTTP 降级入口已通过时，公共面问题独立跟踪，当前 L1 流程继续；禁止把公共面问题变成核心业务门禁。 -- HWLAB 的端口退让与公网验收细则以 `docs/reference/hwlab.md#workbench-浏览器回归专项` 为唯一权威，并由 `$unidesk-webdev` 执行。 + - 同 host 的 CLI、服务间调用和浏览器回归可以使用 YAML probe host 与固定端口； + - 跨 host 调用使用 YAML 声明的固定 native host 与端口； + - 禁止随机端口、临时 URL、命令行覆盖和代码默认值。 +- L1 验收以 native 服务为准： + - lifecycle status 必须证明 API、Worker 和 Web 进程仍在运行且 health ready； + - CLI 必须通过 native `--over-api` 完成真实业务操作； + - Web 必须通过 native Web 完成受影响页面和交互； + - localhost 或 probe host 只要来自 owning YAML，就可以作为同 host L1 证据。 +- 公网域名、TLS、public-edge 和固定公网入口属于独立暴露检查： + - 不进入 L1 启动、执行、回归和完成条件； + - L1 任务不得调查、等待或操作其 CI/CD、GitOps、Argo 或 Kubernetes； + - 用户明确要求 L2 或独立公共面运维时，才进入对应专项流程。 - 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。 ## L2 Development diff --git a/docs/reference/dev-environment.md b/docs/reference/dev-environment.md index 7e22b8ec..a09afc19 100644 --- a/docs/reference/dev-environment.md +++ b/docs/reference/dev-environment.md @@ -101,6 +101,23 @@ trans D601:/home/ubuntu/workspace/unidesk-dev git remote -v - 使用目标 provider、pod 或 Windows route 的最小闭环证明； - 只有证据显示 client 侧无法规避边界时，才进入 provider-gateway 变更流程。 +## L1 Native 执行边界 + +- L1 只使用 host 上的 native API、Worker、Web 和必要基础依赖： + - 服务从 owning YAML 解析固定 workspace、端口、状态目录和依赖； + - 启动、停止、重启、状态和日志统一走项目受控 lifecycle CLI； + - `--over-api` 直接调用该 native API，不经过 Kubernetes Service 或集群 workload。 +- L1 在任何情况下都不依赖 CI/CD、GitOps、Argo、Kubernetes、镜像发布或 + 集群 rollout： + - 正常启动、首次拉起、配置变更、合并后复测和故障处理都不等待这些系统； + - 不用这些系统更新、修复或验收 L1 运行面； + - 必须依赖集群对象的验证属于 L2。 +- L1 始终使用本机小回环： + - 通过 owning YAML 固定 native 端口完成 API、Worker、Workflow 和 Web 回归； + - 同 host 可使用 YAML probe host，跨 host 使用 YAML 固定 native host； + - 公共入口状态独立记录，不能成为 L1 业务门禁； + - L1 任务不进入 CI/CD、Kubernetes 和 public-edge 调查或操作。 + ## L1 受控 CLI 即时修复 - 执行 L1 开发、诊断或验收时，发现项目受控 CLI 存在问题即可在当前任务内即时修改： diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 23bab113..f9bf7ed4 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -102,9 +102,18 @@ HWLAB v0.2/v0.3 仓库内 `docs/reference/spec-*`，以及已收编的 `cloud-wo - development `NC01/v03` 前端/API 入口为 `https://lab-dev.hwpod.com`； - production release lane `NC01/production` 的正式入口为 `https://lab.hwpod.com`。 - HWPOD L1 Native 是独立于 Cloud Web 的运行面： - - API、Temporal worker、Web、固定端口和公网入口必须从 `config/hwlab-node-lanes.yaml#lanes..targets..nativeDevelopment.hwpod` 读取； + - API、Temporal worker、Web 和固定端口必须从 owning YAML 读取： + - `config/hwlab-node-lanes.yaml#lanes..targets..nativeDevelopment.hwpod`； - 启停和状态统一使用 `hwlab nodes native-development hwpod api|worker|web`； - - 公网验收统一使用 `web-probe native-readiness --node --lane --profile hwpod`； + - L1 API、worker 和 Web 是 NC01 host 上的 native 进程： + - 任何情况下都不依赖 CI/CD、GitOps、Argo、Kubernetes 或集群 rollout； + - 正常启动、首次拉起、配置变更、合并后复测和故障处理均适用； + - CLI `--over-api` 直接调用 owning YAML 固定端口上的 native API： + - 同 host 回归使用 YAML probe host； + - 禁止改走 Cloud API 或 Kubernetes Service； + - L1 只验收本机 API、worker、Web 小回环： + - 公网入口与 public-edge 是独立可选检查； + - 不得成为 L1 启动、执行或完成条件； - HWPOD Web 无业务登录页时，由 owning YAML profile 声明 `authentication: none`，不得改用临时 Playwright 脚本或弱化浏览器错误断言。 - Windows HWPOD-NODE 的连接入口和制品入口属于不同合同： - WebSocket 注册入口来自节点 YAML 的桌面连接配置； @@ -196,16 +205,17 @@ Workbench 浏览器回归需求以 UniDesk OA [PJ2026-010401 Web工作台](../.. - 端口被同一 L1 服务的旧进程占用时，只能通过项目 CLI 停止或重启该服务； - 端口被其他服务占用时，禁止停止、接管或复用其他服务； - 必须先确认空闲端口，再修改 `config/hwlab-node-lanes.yaml#lanes..targets..nativeDevelopment.workbench` 中本服务的端口； - - API、Worker、Web 的启动、状态和固定 HTTPS 入口继续由同一 YAML 与 `hwlab nodes native-development workbench` 解析； + - API、Worker、Web 的启动和状态继续由同一 YAML 与 `hwlab nodes native-development workbench` 解析； - 禁止用命令行参数、临时环境变量或代码 fallback 形成第二端口真相； - - 端口退让后固定 HTTPS 域名保持不变，并从该域名执行 `web-probe native-readiness`，确认页面、DOM、交互和浏览器错误均通过后再向用户披露入口。 -- L1 Native 公网暴露与降级： - - `nativeDevelopment..publicExposure` 声明首选固定 HTTPS origin； - - HTTPS 因 public-edge、TLS、DNS 或出网故障不可用时，必须降级到同一 owning YAML 解析出的固定公网 HTTP IP:port，并继续 L1； - - 固定 HTTP 降级入口必须保持业务认证，禁止随机端口、localhost、临时 URL、第二代理或第二业务路径； - - 降级后先验证公网 readiness，再通过同一 Workbench API、Worker、Kafka SSE 与 Web 路径完成原验收；端口监听或 HTTP 200 不能替代业务验收； - - HTTPS 故障独立登记为非阻塞公共面 issue，不得等待回复或恢复后才继续业务； - - 公共面恢复后从固定 HTTPS origin 复测，并撤回 HTTP 降级状态。 + - 端口退让后从 owning YAML 的 native probe host 和固定端口执行 + `web-probe native-readiness`，确认页面、DOM、交互和浏览器错误均通过。 +- L1 Native 暴露边界： + - `nativeDevelopment..publicExposure` 只描述独立公共入口； + - 公网域名、TLS、public-edge 和固定公网入口不进入 L1 启动、执行、回归和 + 完成条件； + - L1 不调查、等待或操作公共面的 CI/CD、GitOps、Argo、Kubernetes、镜像或 + rollout； + - 只有用户明确要求 L2 或独立公共面运维时，才进入对应专项流程。 - Workbench L1 API 与 Kafka SSE 验收： - API 进程存活入口固定为 `/health/live`；