From 00c97b7f37f09f8478ca50af73fcce7cade43e0e Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 03:11:45 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E5=8A=9F=E8=83=BD=20?= =?UTF-8?q?schema=20=E9=9D=9E=E9=98=BB=E5=A1=9E=E4=BA=A4=E4=BB=98=E5=90=88?= =?UTF-8?q?=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-cicd/SKILL.md | 8 +++ docs/MDTODO/hwlab-web-product-experience.md | 4 ++ .../MDTODO/observability-trace-reliability.md | 52 ++++++++++++++++++- .../pr-merge-driven-automatic-delivery.md | 4 ++ 4 files changed, 66 insertions(+), 2 deletions(-) diff --git a/.agents/skills/unidesk-cicd/SKILL.md b/.agents/skills/unidesk-cicd/SKILL.md index a38bd660..a9e5906b 100644 --- a/.agents/skills/unidesk-cicd/SKILL.md +++ b/.agents/skills/unidesk-cicd/SKILL.md @@ -119,6 +119,14 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help - 未迁移的 legacy CI/CD 若仍保留人工入口，必须由单一受控命令完成 source sync、构建、发布、GitOps/Argo 收敛、runtime provenance 校验和 `/health` 端点验证。PaC migrated consumer 不得使用该人工入口，其唯一交付触发是 GitHub PR merge。 - CI/CD 端到端 wall-clock 目标及预算只由 owning YAML 声明；PaC migrated consumer 从 GitHub PR merge 事件计时，legacy lane 才从操作者触发受控命令计时，均到 runtime ready 且 `/health` 端点验证完成为止。 - CI/CD validation 阶段只能验证部署对象的 `/health` 端点和必要 provenance；禁止在 CI/CD gate 中运行 web-probe、Playwright、远程浏览器截图、用户路径 E2E 或等价重型业务探针。业务/用户入口验证只能作为发布后的独立 post-deploy validation 证据，不得阻塞 CI/CD 一键交付。 +- 产品功能配置 schema 的 CI/CD 合同： + - repo 内唯一约定路径固定为 `config/feature-config.schema.json`； + - schema 只描述产品功能配置，不得承载数据 authority、事件路径、投影实现或交付路径选择； + - 一个产品功能只允许一个规范配置变量，禁止在 schema、renderer、Deployment env 或应用解析器中保留别名、反向变量或重复开关； + - CI/CD 必须检查 schema 语法、配置值匹配和功能到配置变量的一对一关系，并输出有界 typed warning； + - schema 缺失、非法、配置不匹配或发现重复变量时，只允许记录 warning；PipelineRun、artifact、GitOps promote、Argo reconcile、runtime rollout 和 `/health` closeout 必须继续； + - schema 校验器只读，禁止写回配置、注入默认值、删除变量、关闭功能、切换架构路径或执行任何补救操作；运行时必须原样接收本次待发布配置； + - schema warning 必须进入 CI/CD OTel span 与 `status|history|debug-step` 的同构有界投影，但不得改变成功/失败终态。 - 任一 CI/CD 阶段或总耗时超过 owning YAML 预算时，不要继续死等或把超长等待视为正常；先输出阶段耗时分解，并优先从 env reuse、git mirror、BuildKit/cache、GitOps/Argo watch 和 runtime readiness 探测方向优化后再继续交付。 - 仅 legacy lane 的 node-scoped `trigger-current --wait` 可以把 source sync、pre/post flush、PipelineRun、GitOps/Argo、runtime readiness 和 `/health` closeout 放进同一端到端 YAML 预算；超预算时由 CLI 输出阶段分解、Argo target revision、runtime/public 状态和 TaskRun/Pod drill-down。PaC migrated consumer 禁止执行 `trigger-current`，也禁止手动串联状态、sync 或 flush 命令补齐交付。 - node-scoped `control-plane status` 可见性规则： diff --git a/docs/MDTODO/hwlab-web-product-experience.md b/docs/MDTODO/hwlab-web-product-experience.md index ce9e8b81..51b2f7b0 100644 --- a/docs/MDTODO/hwlab-web-product-experience.md +++ b/docs/MDTODO/hwlab-web-product-experience.md @@ -73,3 +73,7 @@ ### R1.14 [completed] 依据用户最新反馈全量重写 HWLAB v0.3 管理域导航、授权、密钥、用户、账务与 MDTODO 页面代码（子 issue [pikasTech/HWLAB#2522](https://github.com/pikasTech/HWLAB/issues/2522)）：禁止以换色、圆角、字母方块、薄包装组件或局部 CSS 冒充重写；先抽取工业运营台通用工作区、状态轨、实体索引、权限矩阵、密钥流向、审计/账本时间线、真实线性图标与 Markdown/报告 Viewer，再重建五页组件树、状态组合和样式并删除旧私有实现。MDTODO 只保留成熟的有界三栏、任务树→正文→报告、Source/File、inline edit、报告调宽/关闭/全屏和深链思想；保留 typed API、稳定 ID、revision/fingerprint、ACL、Secret 脱敏与公共 Workbench Launch 合同，完成 1920/960/390 原入口验收，完成任务后将详细报告写入[任务报告](./details/hwlab-web-product-experience/R1.14_Task_Report.md)。 + +## R2 [in_progress] + +执行 [HWLAB #2537](https://github.com/pikasTech/HWLAB/issues/2537)：纠正此前名义完成但真实效果不达标的问题，依据 OA SPEC 和 R1_Context 全量重写 HWLAB v0.3 非 Workbench 页面代码；先抽取工业风高信息密度通用表格、卡片、弹窗、日志/Markdown/JSON/Trace Viewer、Inspector 和图标/列表/密度切换，再重写 AC/SK/UR/AB、MDTODO、HWPOD 与 HWPOD Node，补 Python 单文件节点下载及分阶段接入引导；保留 MDTODO 三栏布局思想、typed API、权限/Secret/硬件/账务 authority 和 Workbench 主路径，完成 1920/960/390、ARIA、reduced-motion 与完整异步状态验收，完成任务后将详细报告写入[任务报告](./details/hwlab-web-product-experience/R2_Task_Report.md)。 diff --git a/docs/MDTODO/observability-trace-reliability.md b/docs/MDTODO/observability-trace-reliability.md index b1cb50be..8e651631 100644 --- a/docs/MDTODO/observability-trace-reliability.md +++ b/docs/MDTODO/observability-trace-reliability.md @@ -57,8 +57,56 @@ ### R4.3 [in_progress] -执行 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949)：由 config/hwlab-node-lanes.yaml 选择 transactionalProjector、projectionOutboxRelay、projectionRealtime 单一产品 authority，关闭 live-only direct authority，保持 renderer/status/preflight YAML-first，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.3_Task_Report.md)。 +执行 [UniDesk #1949](https://github.com/pikasTech/unidesk/issues/1949) 与 [UniDesk #1981](https://github.com/pikasTech/unidesk/issues/1981)：删除 config/hwlab-node-lanes.yaml、renderer、runtime GitOps 和 CI/CD 中对 Workbench 数据 authority、direct/live/refresh、projector/outbox/realtime 的架构选择与六个布尔 env 硬门禁；HWLAB v0.3 固定纯 Kafka transactional projector→outbox→实时/回放 SSE，YAML 只保留 broker/topic/group/tuning 与产品功能配置，schema 校验仅 warning 且不阻塞滚动上线，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.3_Task_Report.md)。 -### R4.4 +### R4.4 [in_progress] 依赖 R4.1-R4.3，主代理完成 PR 架构审核、顺序合并、自动 CI/CD 和 NC01/v03 原 Workbench 新 hi turn 验收；核对 command/run 实际耗时、Kafka backlog/lag、运行中增量、terminal/final、刷新 replay、公开 result 与 OTel 一致后收口，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4_Task_Report.md)。 + +#### R4.4.1 [in_progress] + +执行 [HWLAB #2527](https://github.com/pikasTech/HWLAB/issues/2527)：修复 HWLAB PaC source artifact 未吸收 UniDesk owning YAML transactional projection authority 的漂移，以新的正常 PR merge 自动生成 direct/live/replay=false、projector/outbox/realtime=true 的 GitOps manifest；禁止手工 PipelineRun、mirror sync、Argo refresh 和运行面 patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.1_Task_Report.md)。 + +#### R4.4.2 [in_progress] + +执行 [UniDesk #1959](https://github.com/pikasTech/unidesk/issues/1959) 及其后续解阻任务：修复 HWLAB PaC source artifact 的 runtime GitOps helper、ARG_MAX、marker 与 overlay 投影问题，并按最新 R4.4.2.10/R6 合同删除六个架构 env 及其 CI 硬门禁；大段逻辑继续使用 repo-native 文件或等价受管制品，产品 schema 失败只 warning 并继续滚动上线，禁止手改生成物、HTTP 补链、页面轮询、第二 authority 和人工 PipelineRun/同步/刷新/patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2_Task_Report.md)。 + +##### R4.4.2.1 [in_progress] + +执行 [UniDesk #1963](https://github.com/pikasTech/unidesk/issues/1963)：修复 HWLAB runtime GitOps scripts ConfigMap 的 Git-backed 自动 ownership/交付漂移，只由正常 PR merge 自动事件验收；保持 `UNIDESK_RUNTIME_GITOPS_OVERLAY_FILE`、纯 Kafka transactional projector 与实时/回放 SSE，禁止 B64 回退、HTTP 补链、轮询、第二 authority、人工 PipelineRun/ConfigMap apply/运行面 patch及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.1_Task_Report.md)。 + +##### R4.4.2.2 [in_progress] + +执行 [HWLAB #2530](https://github.com/pikasTech/HWLAB/issues/2530)：增加 repo-owned PaC 回归验证 `UNIDESK_RUNTIME_GITOPS_OVERLAY_FILE`、禁止 B64 内联并校对 ConfigMap mount/helper 合同，以正常 v0.3 PR merge 触发真实自动交付；保持纯 Kafka transactional projector 与实时/回放 SSE，禁止空提交、人工 PipelineRun/同步/刷新/运行面 patch及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.2_Task_Report.md)。 + +##### R4.4.2.3 [in_progress] + +执行 [UniDesk #1967](https://github.com/pikasTech/unidesk/issues/1967)：修复 runtime GitOps postprocess 仅 JSON.parse 而跳过真实 YAML workload，使用结构化 YAML API 覆盖普通、多文档与 List 并显式写入六项 `false,false,false,true,true,true` 能力 env；只由正常 PR merge 自动交付和新 HWLAB merge 验收，禁止放宽 required boolean、手工 patch/补跑/同步/刷新及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.3_Task_Report.md)。 + +##### R4.4.2.4 [in_progress] + +执行 [UniDesk #1968](https://github.com/pikasTech/unidesk/issues/1968)：对齐 runtime GitOps guard 的 typed `continuing/no-build-no-rollout-plan-gitops-verify` 与 PaC terminal evaluator，保持普通 skip 与 verify 模式显式分离且缺证据 fail closed，使 status/history/debug-step 同构；禁止按 TaskRun 成功启发式放宽、人工补跑/同步/刷新/patch及额外状态库锁租约，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.4_Task_Report.md)。 + +##### R4.4.2.5 [in_progress] + +执行 [HWLAB #2532](https://github.com/pikasTech/HWLAB/issues/2532)：修复 prepare-source 仍期待 `require.resolve("yaml")` 的过期测试，结构化验证 CI node dependency bootstrap、renderer dependency-install-disabled 与 runtime GitOps helper 的 YAML 模块可解析合同，跑通全文件测试并以正常 v0.3 PR merge触发最终自动验收；禁止运行时 npm install、B64、手改生成物、空提交及人工补跑/patch，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.5_Task_Report.md)。 + +##### R4.4.2.6 [in_progress] + +执行 [UniDesk #1971](https://github.com/pikasTech/unidesk/issues/1971)：修复 runtime GitOps verify guard 保留旧 `!willRunGitopsPromote` 条件导致 typed continuing marker 永不发出的合同缺口，使无 build/rollout plan 与继续 verify 正交并让 status/history/debug-step 精确返回 runtime-gitops-verify/valid=true；禁止放宽 evaluator、人工补跑/同步/刷新/patch、第二 authority及额外锁租约状态库，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.6_Task_Report.md)。 + +##### R4.4.2.7 [in_progress] + +执行 [HWLAB #2534](https://github.com/pikasTech/HWLAB/issues/2534)：在 UniDesk #1972 自动交付后用受控 source-artifact renderer 重新生成 HWLAB NC01/v03 PaC artifact，使无 build/rollout plan 的 typed continuing marker 与 `willRunGitopsPromote` 解耦，并以正常 v0.3 PR merge 验证 runtime-gitops-verify/valid=true；禁止手改生成物、空提交、人工补跑/同步/刷新/patch、放宽 evaluator及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.7_Task_Report.md)。 + +##### R4.4.2.8 [in_progress] + +执行 [UniDesk #1973](https://github.com/pikasTech/unidesk/issues/1973)：修复 PaC evaluator 对 runtime GitOps verify 真实 marker 组合的误判，允许零运行时变更 plan 下 collect-artifacts skip 与 gitops-promote continuing 共存，同时继续拒绝 promote skipped/continuing 冲突、非零 plan 与终态证据缺失；由正常 PR merge 自动交付后只读复核 `runtime-gitops-verify/valid=true`，禁止人工补跑、同步、刷新、patch及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.8_Task_Report.md)。 + +##### R4.4.2.9 [in_progress] + +执行 [UniDesk #1975](https://github.com/pikasTech/unidesk/issues/1975)：修复 runtime GitOps scripts ConfigMap 丢失 owning YAML `codeAgentRuntime` overlay 导致 postprocess 静默未写纯 Kafka capability env、cloud-api CrashLoop 的问题，并让 verify 在工作负载未命中或 transactional projection capability/env 不完整时 fail closed；以正常 PR merge 自动链和新的 HWLAB source merge 验证 Pod ready、Argo `Synced/Healthy`、projector/outbox/realtime health 归零，禁止人工补跑、同步、刷新、patch及第二 authority，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.9_Task_Report.md)。 + +##### R4.4.2.10 [in_progress] + +执行 [HWLAB #2538](https://github.com/pikasTech/HWLAB/issues/2538)：删除六个架构 capability env 及 direct/live/refresh 分支，把 agentrun.event.v1→transactional projector→PostgreSQL facts/outbox→hwlab.event.v1→实时/回放 SSE 固定为代码不变量；新增 config/feature-config.schema.json 只描述 Trace、原始事件、调试重放和视图等产品功能，一个功能只用一个规范变量；保持 canonical duration、同 cursor/reducer 和纯 Kafka，禁止 HTTP 补链、页面轮询、双 authority、额外锁租约状态库，schema warning 不关闭功能、不改配置且不阻塞滚动上线，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.10_Task_Report.md)。 diff --git a/docs/MDTODO/pr-merge-driven-automatic-delivery.md b/docs/MDTODO/pr-merge-driven-automatic-delivery.md index 7508ba6b..3f107843 100644 --- a/docs/MDTODO/pr-merge-driven-automatic-delivery.md +++ b/docs/MDTODO/pr-merge-driven-automatic-delivery.md @@ -82,3 +82,7 @@ ### R5.3 合并修复 PR 后只观察新的 GitHub webhook→Gitea mirror→PaC→Tekton→GitOps/Argo 自动事件，验证 watcher Ready、TaskRun 创建及 AgentRun/Monitor runtime 收敛，不人工补齐既有 queued run，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R5.3_Task_Report.md)。 + +## R6 [in_progress] + +执行 [UniDesk #1981](https://github.com/pikasTech/unidesk/issues/1981)：固定仓库产品功能 schema 路径为 config/feature-config.schema.json，CI/CD 只读校验 schema 语法、值匹配和功能到唯一配置变量的一对一关系；缺失、非法、不匹配或重复仅输出 typed warning 并投影到 OTel/status/history/debug-step，必须继续 artifact、GitOps/Argo 和滚动上线，禁止写回、默认值、变量删除、功能关闭、架构切换及其他补救操作，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R6_Task_Report.md)。