From 380f7bc08c524a9b25fa85d6db8ed2250d75f5c6 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 17 Jul 2026 04:37:42 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=B0=86=E5=BC=80=E5=8F=91=E7=AD=89?= =?UTF-8?q?=E7=BA=A7=E6=94=B9=E4=B8=BA=E7=8B=AC=E7=AB=8B=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-cicd/SKILL.md | 7 +- .agents/skills/unidesk-daddev/SKILL.md | 4 +- .agents/skills/unidesk-devlevel/SKILL.md | 139 ++++++------------ .../unidesk-devlevel/agents/openai.yaml | 4 +- .agents/skills/unidesk-selfmedia/SKILL.md | 2 +- .agents/skills/unidesk-temporal/SKILL.md | 5 +- .agents/skills/unidesk-webdev/SKILL.md | 4 +- 7 files changed, 62 insertions(+), 103 deletions(-) diff --git a/.agents/skills/unidesk-cicd/SKILL.md b/.agents/skills/unidesk-cicd/SKILL.md index ec1b8377..46e0ae06 100644 --- a/.agents/skills/unidesk-cicd/SKILL.md +++ b/.agents/skills/unidesk-cicd/SKILL.md @@ -14,10 +14,9 @@ description: >- HWLAB G14 和 AgentRun CI/CD 的受控入口。任何 PR 监控、Tekton/Argo、git-mirror、Secret、observability、CI tools image、PipelineRun 清理或 AgentRun 部署都必须走 `bun scripts/cli.ts`。 -- 当任务按 `$unidesk-devlevel` 分级执行时： - - 本 skill 负责 L2 Development 与 L3 Production 的自动交付、运行面证据和事故回退； - - 不负责 L0 Function 或 L1 Native； - - 不自行决定从 L2 晋升 L3。 +- `$unidesk-devlevel` 用 L2 Development 和 L3 Production 描述两种集群部署方式： + - 本 skill 负责这两种方式的自动交付、运行面操作和事故处理； + - L0 Function 与 L1 Native 不使用 CI/CD。 ## 高频入口 diff --git a/.agents/skills/unidesk-daddev/SKILL.md b/.agents/skills/unidesk-daddev/SKILL.md index f081cfa2..5f5d48bc 100644 --- a/.agents/skills/unidesk-daddev/SKILL.md +++ b/.agents/skills/unidesk-daddev/SKILL.md @@ -8,9 +8,9 @@ description: UniDesk 分布式敏捷开发流程，覆盖真实运行面探测 > 遵循规范: 本 Skill 遵循 [Skill(cli-spec)](file:///root/.agents/skills/cli-spec/SKILL.md) 规范（精简版，仅保留与流程相关的硬约束）。 -- `$unidesk-devlevel` 定义正常开发的 L0-L3 等级和晋升证据： +- `$unidesk-devlevel` 定义 L0-L3 四种可反复使用的开发方式： - 本 skill 只在某一级需要跨 host 观察、最小可逆实验、故障收敛或真实入口复测时接管现场闭环； - - 不替代等级定义。 + - 不把现场修复过程解释成等级变化。 ## DAD-DEV SPEC diff --git a/.agents/skills/unidesk-devlevel/SKILL.md b/.agents/skills/unidesk-devlevel/SKILL.md index 561dcf11..5cadf25a 100644 --- a/.agents/skills/unidesk-devlevel/SKILL.md +++ b/.agents/skills/unidesk-devlevel/SKILL.md @@ -1,124 +1,83 @@ --- name: unidesk-devlevel description: >- - UniDesk 四级开发、调试与部署晋升技能，统一编排 L0 Function、L1 Native、 - L2 Development 和 L3 Production。用户提到 devlevel、开发等级、多级调试、 - native-first、从本地到开发集群、从开发集群到生产集群、L0/L1/L2/L3、 - 逐级验证或版本晋升时使用。 + UniDesk 四种开发与部署方式，定义 L0 Function、L1 Native、L2 Development + 和 L3 Production 的运行形态。用户提到 devlevel、开发等级、多级调试、 + native-first、CLI 直调函数、native 前后端、开发集群或生产集群开发方式时使用。 --- # UniDesk 开发等级 -把同一功能从函数级验证逐级晋升到 native、开发集群和生产集群。只编排等级、证据和专项 skill，不建立新的测试框架、发布器或配置真相。 +用 L0-L3 描述四种可以自由选择、反复使用的开发与部署方式。等级只是开发方式的编号，不表示项目成熟度或先后阶段。 -## 等级合同 +## 四种方式 -| 等级 | 名称 | 调用路径 | 运行面写入 | -| --- | --- | --- | --- | -| L0 | Function | `CLI -> native function` | 无 | -| L1 | Native | `CLI -> native API -> native Worker`；`web-probe -> native Web` | 仅 native 进程与任务工作区 | -| 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 | 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 -> L3`。 -- 不定义隐藏等级、Package 等级或 L2.5 门禁。 -- 可以按用户要求单独执行某一级；未执行的级别必须显示为 `not-run`，不能伪装成通过。 -- 晋升只能复用同一 source commit 或可证明内容等价的不可变制品证据。 - -## 通用原则 - -- 保持同一验证意图： - - 领域输入、预期结果和业务断言在各级保持一致； - - 只替换 function、native transport、development transport 或 production transport； - - CLI 与 Web 必须访问同一 dispatcher 和业务状态，不建立第二业务路径。 -- 使用项目适配器： - - 项目仓库的 `AGENTS.md`、owning YAML、正式 CLI 和领域 skill 决定实际命令； - - target、lane、namespace、service、endpoint、SecretRef、semantic origin 和 release source 不得写死在本 skill； - - 一个项目只启动或发布本次受影响的微服务及其必要依赖。 -- 复用已成立证据： - - 证据必须绑定项目、source commit、等级、target 和测试身份； - - 相同身份的成功证据仍有效时不重复执行； - - 代码、配置、制品或目标发生变化时，只失效受影响等级及其后续等级。 -- 控制晋升： - - 当前级的目标功能失败时停止向后晋升，先在当前或更低等级修复； - - 非选中对象、全局一致性和版本漂移只作为 `blocking=false` warning； - - 缺少目标唯一性、权限或不可变版本身份时，在运行面写入前 fail-closed； - - 未明确要求生产发布时，不从 L2 自动进入 L3。 +- 四种方式相互独立，可以随时切换或组合。 +- 不要求按 L0、L1、L2、L3 顺序执行。 +- 已经部署到 L3 的项目仍然经常使用 L0 和 L1 开发新功能、复现问题和快速调试。 +- 同一个任务可以按实际需要组合多种方式，也可以只使用其中一种。 ## L0 Function - 不启动 API、Worker、Temporal、Web 或 Kubernetes workload。 - 用项目 CLI 直接调用 native function、dispatcher、repository 或本地执行器。 -- 只运行与修改相关的最小语法、函数或组件 smoke。 -- 长任务可以使用本地 submit-and-poll，但不得为了 L0 启动 HTTP 服务。 -- 通过条件：目标函数返回预期结果，且未依赖未声明的远端服务路径。 +- 适合函数逻辑、配置解析、数据转换、领域服务和本地文件操作的快速开发。 +- 只加载当前功能需要的本地依赖。 ## L1 Native -- 独立启动受影响微服务的 native API、Worker、基础依赖和 HMR Web。 -- CLI 显式使用项目 native `--over-api` transport，经 native API 调用同一 dispatcher 和 Worker。 -- Web 只通过 `$unidesk-webdev` 的 `web-probe` custom/local 入口访问 native Web。 -- 前端、API 和 Worker 必须可分别启动、查看状态与日志、重启和停止。 -- 优先复用仍在运行的 native 服务，不为每轮修改重复安装依赖或重启无关组件。 -- 通过条件：CLI native API 链路、Worker 终态和目标 Web DOM/交互均满足同一业务断言。 +- 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。 +- CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。 +- Web 使用 `$unidesk-webdev` 的 `web-probe` custom/local 入口访问 native Web。 +- 微服务项目只启动当前微服务的前端、API、Worker及必要依赖。 +- 前端、API 和 Worker可以分别启动、查看日志、重启和停止。 +- 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。 ## L2 Development -- 只通过项目 source PR merge 和 `$unidesk-cicd` 声明的正常自动链滚动开发集群。 -- 禁止人工创建 PipelineRun、直接推送镜像、Argo sync、GitOps patch 或运行面补链。 -- CLI 显式使用开发集群 `--over-api`，验证 dev K8s API、Worker 和真实作业。 -- Web 通过 `$unidesk-webdev` 和 owning YAML 选择的 development semantic origin 验证。 -- 运行面故障或证据冲突时使用 `$unidesk-daddev` 分层定位，不用反复 rollout 试错。 -- 通过条件：自动链成功、不可变 source/artifact identity 对齐、开发 workload ready，且 CLI/Web 原入口通过。 +- 通过项目正常 CI/CD 把目标版本滚动到开发集群。 +- CLI 显式使用开发集群 `--over-api`，访问 dev K8s API 和 Worker。 +- Web 使用 `$unidesk-webdev` 与 owning YAML 选择的 development semantic origin。 +- 适合集群配置、容器运行时、共享依赖、开发域名和多人联调。 +- PaC、Tekton、GitOps、Argo 和 rollout 细则使用 `$unidesk-cicd`。 ## L3 Production -- 只晋升已经通过 L2 的同一不可变版本；不得在 L3 临时重建或替换源码。 -- 生产 branch、tag、target、namespace、入口和晋升方式只从项目 owning YAML 与发布 skill 读取。 -- 生产写入必须来自用户明确的 L3/生产发布要求，不从普通修复或 L2 验收推断授权。 -- CLI 使用生产 `--over-api`；Web 使用 production semantic origin。 -- 默认执行只读或专用生产安全 smoke，不生成无法清理的正式业务数据。 -- 生产事故遵循 `$unidesk-cicd` 的优先回退规则，不在失败版本上连续叠加试修。 -- 通过条件：生产自动链、不可变版本、runtime health 和生产 CLI/Web 原入口全部成立。 +- 通过项目正式发布方式把目标版本部署到生产集群。 +- CLI 使用生产 `--over-api`，访问 prod K8s API 和 Worker。 +- Web 使用 `$unidesk-webdev` 与 owning YAML 选择的 production semantic origin。 +- 适合生产发布、生产环境问题复现和生产入口检查。 +- 生产 branch、tag、target、namespace 和入口只从项目 owning YAML 与领域 skill 读取。 +- 生产写入仍需用户明确要求；选择 L3 不改变现有生产权限和安全边界。 -## 执行流程 +## 选择方式 -1. 识别项目、source commit、当前等级、目标等级和受影响微服务。 -2. 从项目 owning YAML 和领域 skill 解析每一级的 adapter 与运行目标。 -3. 输出等级计划： - - 每级的调用路径； - - 必要依赖和运行面写入； - - 可复用证据； - - 通过条件与停止条件。 -4. 从最低必要等级开始执行；已有同身份证据时复用，不机械重跑前级。 -5. 每级完成后记录有界证据，再决定继续、停止或请求生产授权。 -6. 最终报告每级 `passed|failed|blocked|not-run`，不得只给整体成功。 +- 修改纯函数、解析器或领域逻辑时优先使用 L0。 +- 需要 HTTP、Worker、Workflow 或前端联调时使用 L1。 +- 需要开发集群真实容器、网络、SecretRef 或共享依赖时使用 L2。 +- 用户明确要求生产部署或生产问题只能在生产环境复现时使用 L3。 +- 调试 L2/L3 问题时，可以随时回到 L0/L1 做更快的局部实验。 +- 不因为项目已经部署到 L2/L3 而跳过日常 L0/L1 开发。 -## 证据合同 +## 项目适配 -- 每一级至少记录： - - `level`、`project`、`sourceCommit`； - - target/lane 或 native workspace； - - CLI/Web 入口与同路径证明； - - job/workflow/trace、artifact 或 screenshot identity； - - 开始时间、结束时间和墙钟耗时； - - `passed|failed|blocked|not-run` 与首个失败层。 -- 统计 native 加速时同时记录 native 迭代次数和正式 delivery 次数。 -- 没有同类基线时只报告减少的构建、rollout 和等待步骤，不虚构提速比例或费用。 +- 项目仓库的 `AGENTS.md`、owning YAML、正式 CLI 和领域 skill 决定实际命令。 +- target、lane、namespace、service、endpoint、SecretRef 和 semantic origin 不得写死在本 skill。 +- CLI 与 Web 应继续使用项目同一 dispatcher 和业务路径，不为某个等级复制业务实现。 +- 本 skill 不新增 `devlevel` CLI、发布器、测试框架或全局配置。 ## 专项 skill 路由 -- L0/L1 的跨 host、临时实验和真实运行面定位使用 `$unidesk-daddev` 与 `$unidesk-trans`。 +- 跨 host、临时实验和真实运行面定位使用 `$unidesk-daddev` 与 `$unidesk-trans`。 - L1/L2/L3 的所有浏览器操作使用 `$unidesk-webdev`。 -- L2/L3 的 PaC、Tekton、GitOps、Argo、rollout 和版本回退使用 `$unidesk-cicd`。 -- 等级 adapter 的 target、lane、endpoint、SecretRef 和 semantic origin 归属使用 `$unidesk-ymalops`。 +- 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`。 - -## 禁止事项 - -- 不把 `$unidesk-devlevel` 实现成新的全局发布 orchestrator。 -- 不复制专项 skill 的完整命令或维护第二份 target 配置。 -- 不用 L0/L1 结果替代 L2/L3 的 revision、runtime 和公网证据。 -- 不用 L2 结果冒充 L3，也不把生产验证结果反向证明开发等级已经执行。 -- 不新增阻塞交付的全局配置一致性、合同或版本门禁。 diff --git a/.agents/skills/unidesk-devlevel/agents/openai.yaml b/.agents/skills/unidesk-devlevel/agents/openai.yaml index e0fc968b..451ec2a8 100644 --- a/.agents/skills/unidesk-devlevel/agents/openai.yaml +++ b/.agents/skills/unidesk-devlevel/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "UniDesk 开发等级" - short_description: "按 L0 到 L3 编排 native、开发与生产晋升" - default_prompt: "使用 $unidesk-devlevel 规划并执行当前功能从 L0 到目标等级的最短验证与晋升流程。" + short_description: "区分函数、native、开发集群和生产集群开发方式" + default_prompt: "使用 $unidesk-devlevel 为当前任务选择合适的开发或部署方式。" diff --git a/.agents/skills/unidesk-selfmedia/SKILL.md b/.agents/skills/unidesk-selfmedia/SKILL.md index 84c42ba8..9bed8761 100644 --- a/.agents/skills/unidesk-selfmedia/SKILL.md +++ b/.agents/skills/unidesk-selfmedia/SKILL.md @@ -41,7 +41,7 @@ description: UniDesk SelfMedia 工厂的 YAML-first 运维技能，覆盖 NC01 ## 相关技能 -- SelfMedia 的 L0 Function、L1 Native、L2 Development 和 L3 Production 晋升使用 `$unidesk-devlevel`；本 skill 继续提供项目 adapter 和验收命令。 +- SelfMedia 使用 `$unidesk-devlevel` 区分 L0 Function、L1 Native、L2 Development 和 L3 Production 四种开发方式；本 skill 继续提供项目 adapter 和验收命令。 - Secret/YAML 归属或 renderer 修改同时使用 `$unidesk-ymalops`。 - PaC、Tekton、GitOps、Argo 或自动交付排障同时使用 `$unidesk-cicd`。 - 跨节点现场闭环同时使用 `$unidesk-daddev` 与 `$unidesk-trans`。 diff --git a/.agents/skills/unidesk-temporal/SKILL.md b/.agents/skills/unidesk-temporal/SKILL.md index 20ddd802..a8dfc988 100644 --- a/.agents/skills/unidesk-temporal/SKILL.md +++ b/.agents/skills/unidesk-temporal/SKILL.md @@ -126,11 +126,12 @@ trans NC01:k3s kubectl -n temporal get service temporal-frontend \ ## Temporal 应用的 Native-first 闭环 -- 使用 `$unidesk-devlevel` 表达应用晋升等级： +- 使用 `$unidesk-devlevel` 表达应用当前采用的开发方式： - dispatcher/function 属于 L0； - native API、Worker 和 Web 属于 L1； - 开发集群 API/Worker/Web 属于 L2； - - 同一不可变版本的生产晋升属于 L3。 + - 生产集群 API/Worker/Web 属于 L3； + - 已部署到 L2/L3 的应用仍然可以反复使用 L0/L1 开发和调试。 - 应用必须共享 contracts、repository、application dispatcher 和 Temporal contracts： - 本地 CLI 默认直接调用 dispatcher； - REST adapter 只处理 HTTP envelope、状态码、鉴权和 correlation； diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 4e4d908b..22c19d6b 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -7,11 +7,11 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web 本技能是 UniDesk/HWLAB Web 开发和受控浏览器复测的唯一入口，并遵循 Skill(cli-spec)。需求真相源仍是 `project-management/PJ2026-01/specs/`；本技能只规定如何开发、采集、复现和验收。 -- 当任务按 `$unidesk-devlevel` 分级执行时： +- 当任务使用 `$unidesk-devlevel` 描述开发方式时： - L1 使用 custom/local 受控入口验证 native Web； - L2 使用 development semantic origin； - L3 使用 production semantic origin； - - 本 skill 负责浏览器证据，不决定等级晋升。 + - 本 skill 负责各运行面的浏览器操作，不解释项目处于哪个等级。 ## 快速规则