---
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 只访问当前 host 可见的本地文件系统和进程：
  - `--local` 不提供跨 host 路由，也不把 owning spec 中的远端绝对路径映射到
    当前 host；
  - 跨 host spec 在 L0 只验证 compiler/plan 合同，真实 workspace、build 和硬件
    操作使用目标 host 的 L1 native API；
  - L0 文件副作用使用当前 host 的 disposable fixture 或本地 workspace 验证。
- 单个微服务内部、不启动服务进程且不跨服务通信的单元测试和组件测试属于 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 的执行面在任何情况下都固定为本机 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、状态目录和服务组成必须由 YAML-first 配置解析；
  代码和命令行不得补隐式默认值。
- L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。
- L1 开发、诊断或验收中发现受控 CLI 问题时，可以在当前任务内即时修改并完成最小验证：
  - 问题范围包括 parser、lifecycle、transport、输出、错误码、可见性和帮助；
  - 不等待独立 issue 或额外授权；
  - 不把 CLI 缺陷当作只读 blocker；
  - 不改用裸脚本绕过原产品入口；
  - 修改范围和执行面边界以 `docs/reference/dev-environment.md#l1-受控-cli-即时修复` 为准。
- 通过项目 lifecycle 启动的 L1 服务在测试和验收后默认保持运行：
  - 只有用户明确要求停止或清理时才执行 stop；
  - 一次性 disposable smoke 可以按自身隔离合同清理，但不能替代可持续访问的 L1 服务；
  - 任务结束前必须重新读取 lifecycle status，不能凭启动返回值推断服务仍在运行；
  - 多服务 L1 必须优先使用项目 CLI 的聚合 status，一次返回 API、Worker 和 Web 状态，禁止由调用方逐个查询后人工拼接结论；
  - 项目暂缺聚合 status 时，应在当前任务内补齐该 CLI 能力，不能把逐服务查询固化为长期验收流程。
- 多轮 session 的 L1 复用验收也必须使用项目 CLI 聚合查询：
  - 一个 session 只允许一个 run 和一个 runner Job；
  - N 个 turn 只允许首轮 source fetch 和物化资源；
  - 后续 turn 必须复用 backend process 并完成 thread resume；
  - 禁止逐条查询 run、command、runner 和 event 后人工拼接结论。
- CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。
- Web 使用 `$unidesk-webdev` 的受控入口访问 owning YAML 固定端口上的 native Web。
- 微服务项目只启动当前微服务的前端、API、Worker及必要依赖。
- 前端、API 和 Worker可以分别启动、查看日志、重启和停止。
- L1 API/Web 入口必须由 owning YAML 声明和选择：
  - `0.0.0.0` 只表示进程 bind；
  - 同 host 的 CLI、服务间调用和浏览器回归可以使用 YAML probe host 与固定端口；
  - 跨 host 调用使用 YAML 声明的固定 native host 与端口；
  - 禁止随机端口、临时 URL、命令行覆盖和代码默认值。
- L1 验收以 native 服务为准：
  - lifecycle status 必须证明 API、Worker 和 Web 进程仍在运行且 health ready；
  - 任务 worktree 可以承载短反馈迭代，但不得成为 L1 完成运行面；
  - 宣称 L1 完成前，已验收语义必须以边界明确的提交合入 owning YAML 选定的固定 L1 workspace；
  - 合入后必须通过项目 lifecycle CLI 重载受影响进程，并从固定端口重新回归；
  - lifecycle status 必须披露运行进程选中的源码 workspace、runtime commit
    和远端可获取的 runner source commit；
  - runtime workspace 与 runner source commit 的 provenance 漂移只记录
    非阻塞 warning，不得阻断核心业务；
  - runner source Git 对象不存在或无法获取时仍是业务 blocker，必须从
    owning YAML 声明的 remote/source branch 修正，禁止改用本地独有 `HEAD`；
  - 仍有已验收语义只存在于任务 worktree、未提交 diff 或临时产物时，L1 必须保持未完成；
  - 详细收口合同以 `docs/reference/dev-environment.md#l1-固定工作区收口` 为唯一权威；
  - 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

- 通过项目受控手动 CI/CD 把目标版本滚动到开发集群。
- PR merge、push 和 branch update 不自动进入 L2；先通过 `$unidesk-cicd` 的 release plan 审阅 env reuse、镜像构建数和范围，再手动发送 PaC webhook。
- 代理可以根据功能和问题是否需要开发集群真实运行面，自行选择并执行 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

- 通过项目受控手动发布方式把目标版本部署到生产集群。
- L3 同样先 plan 后手动发送 PaC webhook，禁止 PR merge 自动发布。
- 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`。
