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

name, description

name	description
unidesk-devlevel	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。