pikastech
13 KiB
13 KiB
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 只访问当前 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-apitransport，经 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 不新增
devlevelCLI、发布器、测试框架或全局配置。
专项 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。