pikasTech-unidesk/.agents/skills/unidesk-devlevel/SKILL.md

---
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`。