docs: 固化 Workbench Kafka-only 与 L1 端口规则

This commit is contained in:
pikastech
2026-07-18 07:23:28 +02:00
parent 06fea2e3c3
commit 3deaff1746
5 changed files with 76 additions and 4 deletions
+6 -2
View File
@@ -43,8 +43,11 @@ description: >-
## L1 Native
- 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。
- 每个 L1 服务必须使用 owning YAML 或项目规格声明的固定本地端口;启动前只识别同一服务的旧 L1 进程,若该固定端口已被它占用,先停止旧进程,再在同一端口启动新进程。
- 不得因为端口冲突改用临时端口,也不得停止其他 L1、其他 worktree 或无关服务;无法确认端口占用者属于当前服务时先报告冲突。
- 每个 L1 服务必须使用 owning YAML 或项目规格声明的端口:
- 同一服务的旧 L1 进程占用时,通过项目 CLI 停止或重启,再使用 YAML 当前端口;
- 其他服务占用时,禁止停止、接管或复用其他服务;
- 确认空闲端口后修改本服务 owning YAML,再由 parser/CLI 读取新端口继续;
- 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。
- 固定端口、bind/probe/public host、状态目录和服务组成必须由 YAML-first 配置解析;代码和命令行不得补隐式端口默认值。
- L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理;`npm run``bun run``vite` 或裸脚本只允许作为 CLI 的内部实现,不是用户操作入口。
- CLI 显式使用项目 native `--over-api` transport,经 native API 调用 Worker。
@@ -57,6 +60,7 @@ description: >-
- bind/probe 地址不得作为 L1 用户入口返回;
- 公网 IP、API port 和 Web port 缺失时必须明确失败,不得回退到 localhost 或代码默认值。
- L1 验收命令必须实际从该公网 IP 打开页面和 API;本机 `127.0.0.1`/`localhost` 只可作为进程健康 probe,不构成 L1 证据。
- HWLAB 的端口退让与公网验收细则以 `docs/reference/hwlab.md#workbench-浏览器回归专项` 为唯一权威,并由 `$unidesk-webdev` 执行。
- 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。
## L2 Development