--- name: unidesk-devlevel description: >- UniDesk 四种开发与部署方式，定义 L0 Function、L1 Native、L2 Development 和 L3 Production 的运行形态。用户提到 devlevel、开发等级、多级调试、 native-first、CLI 直调函数、微服务内部单元测试、native 前后端、开发集群、 生产集群开发方式，或要求问题优先低等级小回环再逐级回归时使用。 --- # UniDesk 开发等级 用 L0-L3 描述四种可以自由选择、反复使用的开发与部署方式。等级只是开发方式的编号，不表示项目成熟度或先后阶段。 ## 四种方式 | 等级 | 名称 | 调用路径 | | --- | --- | --- | | L0 | Function | `CLI -> native function`；单个微服务内部单元测试 | | L1 | Native | `CLI -> native API -> native Worker`；`web-probe -> native Web` | | L2 | Development | `CLI -> dev K8s API -> dev Worker`；`web-probe -> dev Web` | | L3 | Production | `CLI -> prod K8s API -> prod Worker`；`web-probe -> prod Web` | - L0、L1 和 L2 可以自由选择、切换或组合。 - 不要求按 L0、L1、L2 顺序执行；进入 L3 必须先完成对应 L2 回归。 - 已经部署到 L3 的项目仍然经常使用 L0 和 L1 开发新功能、复现问题和快速调试。 - 同一个任务可以按实际需要组合多种方式；不进入 L3 时也可以只使用其中一种。 ## L0 Function - 不启动 API、Worker、Temporal、Web 或 Kubernetes workload。 - 用项目 CLI 直接调用 native function、dispatcher、repository 或本地执行器。 - 单个微服务内部、不启动服务进程且不跨服务通信的单元测试和组件测试属于 L0。 - 适合函数逻辑、配置解析、数据转换、领域服务、微服务内部单元和本地文件操作的快速开发。 - 只加载当前功能需要的本地依赖。 - 测试一旦跨越 API、Worker、网络、独立常驻进程或前后端边界，就使用 L1；native function 同步调用的有界本地 helper 进程仍属于 L0。 - L0 的完成判定以本次变更实际触及的完整逻辑操作为边界： - 变更默认值、控制标志或分支选择时，沿既有调用链核对该值实际控制的结果和副作用，不能只验证参数解析或首个返回值； - 先列出本次实际触及的决策结果、mutation plan、持久状态和清理动作，只保留适用于当前操作的项目； - 最小合同同时覆盖默认保留或无 mutation 分支，以及本次变更允许的显式 mutation 分支； - 文件系统或有界本地 helper 进程副作用无法由纯断言证明时，使用 disposable fixture、dry-run plan 或一次最小本地 smoke，不因此升级到 L1； - 未被本次问题暴露且未被代码改动触及的模块、风险和组合不扩成测试矩阵、门禁或更高等级回归。 ## L1 Native - 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。 - 每个 L1 服务必须使用 owning YAML 或项目规格声明的端口： - 同一服务的旧 L1 进程占用时，通过项目 CLI 停止或重启，再使用 YAML 当前端口； - 其他服务占用时，禁止停止、接管或复用其他服务； - 确认空闲端口后修改本服务 owning YAML，再由 parser/CLI 读取新端口继续； - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。 - 固定端口、bind/probe、固定 HTTPS origin、状态目录和服务组成必须由 YAML-first 配置解析；代码和命令行不得补隐式默认值。 - L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。 - CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。 - Web 使用 `$unidesk-webdev` 的 `web-probe native-readiness` 从 owning YAML 固定 HTTPS origin 访问 native Web。 - 微服务项目只启动当前微服务的前端、API、Worker及必要依赖。 - 前端、API 和 Worker可以分别启动、查看日志、重启和停止。 - 所有 L1 API/Web 用户入口必须是 owning YAML 声明的固定 HTTPS origin： - `0.0.0.0` 只表示进程 bind； - `127.0.0.1` 只用于本机 probe 或进程间代理； - IP、port、bind/probe 地址和临时 URL 不得作为 L1 用户入口返回； - 固定 HTTPS origin 缺失时必须明确失败，不得回退到 IP、localhost、端口拼接或代码默认值； - 内部端口冲突时通过 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` 只读归因，不由 L1 会话补写。 - L1 验收命令必须实际从固定 HTTPS origin 打开页面和 API；本机 `127.0.0.1`/`localhost` 只可作为进程健康 probe，不构成 L1 证据。 - 执行任何 L1 流程时必须扫描当前项目已声明的 L1： - 发现历史 L1 尚未配置固定 HTTPS exposure 时，立即建立可追踪记录； - 发现一例就完成该实例的 YAML-first exposure、受控部署和原入口验收； - 当前实例通过后才继续原 L1 流程，禁止把已发现实例保留为历史遗留。 - HWLAB 的端口退让与公网验收细则以 `docs/reference/hwlab.md#workbench-浏览器回归专项` 为唯一权威，并由 `$unidesk-webdev` 执行。 - 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。 ## L2 Development - 通过项目正常 CI/CD 把目标版本滚动到开发集群。 - 代理可以根据功能和问题是否需要开发集群真实运行面，自行选择并执行 L2。 - CLI 显式使用开发集群 `--over-api`，访问 dev K8s API 和 Worker。 - Web 使用 `$unidesk-webdev` 与 owning YAML 选择的 development semantic origin。 - 适合集群配置、容器运行时、共享依赖、开发域名和多人联调。 - PaC、Tekton、GitOps、Argo 和 rollout 细则使用 `$unidesk-cicd`。 ## L3 Production - 通过项目正式发布方式把目标版本部署到生产集群。 - CLI 使用生产 `--over-api`，访问 prod K8s API 和 Worker。 - Web 使用 `$unidesk-webdev` 与 owning YAML 选择的 production semantic origin。 - 适合生产发布、生产环境问题复现和生产入口检查。 - 生产 branch、tag、target、namespace 和入口只从项目 owning YAML 与领域 skill 读取。 - 执行 L3 前必须先完成目标版本和受影响路径的 L2 回归，并确认 L2 通过。 - L2 未完成或未通过时，不请求 L3 授权，也不执行 L3 滚动。 - L2 通过后，才请求用户对本次 L3 生产操作的明确授权；获得授权后才能滚动到 L3。 - 不得沿用历史授权、其他任务授权、泛化的生产权限或“项目已经部署到生产”的事实。 - 未取得本次明确授权时，只能说明需要 L3 并等待用户决定，不能执行生产写入。 ## 选择方式 - 修改纯函数、解析器或领域逻辑时优先使用 L0。 - 需要 HTTP、Worker、Workflow 或前端联调时使用 L1。 - 需要开发集群真实容器、网络、SecretRef 或共享依赖时使用 L2。 - L2 可由代理根据任务实际需要自行判断和执行。 - L3 只有在对应 L2 回归通过，并获得用户对本次生产操作的明确授权后才能执行。 - 调试 L2/L3 问题时，可以随时回到 L0/L1 做更快的局部实验。 - 不因为项目已经部署到 L2/L3 而跳过日常 L0/L1 开发。 ## 问题处理方式 - 遇到问题时，先选择能够复现根因的最低等级，建立最快的小回环。 - 纯函数、解析、领域逻辑和单个微服务内部单元问题优先降到 L0。 - API、Worker、Workflow、前后端联调问题优先降到 L1。 - 只有依赖开发集群容器、网络、SecretRef 或共享服务时才留在 L2。 - 只有生产环境特有的数据、流量、配置或外部依赖问题才留在 L3。 - 低等级无法复现时，逐级增加真实运行面因素，不在高等级连续滚动试错。 - 修复在低等级稳定后，再逐级回归到问题原来出现的最高等级： - L0 修复的 L3 问题，依次回归 L0、L1、L2、L3； - L1 修复的 L2 问题，依次回归 L1、L2； - 回归只覆盖受影响路径和必要依赖。 - 回归需要进入 L3 时，先完成并确认 L2 回归通过，再停下请求用户对本次生产操作的明确授权。 - 获得当次授权后才滚动到 L3；未获授权时停留在已通过的 L2。 - L3 的 L2 前置与当次授权只约束生产操作，不把等级变成项目成熟度或晋升状态。 ## 项目适配 - 项目仓库的 `AGENTS.md`、owning YAML、正式 CLI 和领域 skill 决定实际命令。 - target、lane、namespace、service、endpoint、SecretRef 和 semantic origin 不得写死在本 skill。 - CLI 与 Web 应继续使用项目同一 dispatcher 和业务路径，不为某个等级复制业务实现。 - 本 skill 不新增 `devlevel` CLI、发布器、测试框架或全局配置。 ## 专项 skill 路由 - 跨 host、临时实验和真实运行面定位使用 `$unidesk-daddev` 与 `$unidesk-trans`。 - L1/L2/L3 的所有浏览器操作使用 `$unidesk-webdev`。 - L2/L3 的 PaC、Tekton、GitOps、Argo、rollout 和事故处理使用 `$unidesk-cicd`。 - target、lane、endpoint、SecretRef 和 semantic origin 归属使用 `$unidesk-ymalops`。 - Temporal workflow、activity、task queue 和 native Worker 使用 `$unidesk-temporal`。 - 项目专属命令继续读取项目领域 skill；例如 SelfMedia 使用 `$unidesk-selfmedia`。